android-coil-compose

Android Coil Compose

使用する場面

• リクエストの内容が次のいずれかに関する場合に、このスキルを使用します：Coil による画像読み込み、Compose for Android の AsyncImage、Android の rememberasyncimagepainter。
• 主な目的：Jetpack Compose で Coil を使用し、AsyncImage、ペインターのバリエーション、サイズ指定、アクセシブルな画像読み込みパターンを活用します。
• Compose での画像読み込み、プレースホルダー、エラー状態、サイズ指定、リストのパフォーマンスに特化した作業で、このスキルを使用します。
• AsyncImage とペインター、サブコンポジションの選択ガイドについては、references/patterns.md を確認してください。
• リストのパフォーマンスとスクリーンショットの安定性を検証する方法については、references/scenarios.md を確認してください。
• 対象範囲が広がる場合は、次のスキルに引き継いでください：
• android-compose-foundations
• android-compose-performance

ワークフロー

1. UI にシンプルな画像表示領域、低レベルのペインターアクセス、カスタムのスロットベースの読み込み状態のどれが必要かを特定します。
2. まず AsyncImage を優先し、コンポーネントが本当に必要とする場合にのみペインター API に切り替えます。
3. 画像の動作が高パフォーマンスでアクセシブルになるよう、サイズ、プレースホルダー、コンテンツ説明を適切に設定します。ペインター API では、必要に応じて明示的なサイズリゾルバーを指定します。
4. 実装を完了と判断する前に、リストのレンダリング、状態の変化、視覚的なフォールバックを確認します。また、ソースの種類にリモートデータやデコーダーモジュールが必要な場合、それらが実際に含まれていることを確認します。
5. 画像パイプラインが安定したら、Compose の一般的なレイアウトや広範なパフォーマンスの問題を、関連するスキルに引き継ぎます。

ガードレール

• Compose のほとんどの表示領域では AsyncImage を優先します。
• 可能な限り、画像リクエストのサイズを UI 上の表示サイズに合わせます。
• アクセシビリティの動作を適切に設定します：内容のある画像には意味のある contentDescription を指定し、装飾用画像には null を指定します。
• UX 上どうしても必要な場合を除き、スクロールの多いリストでサブコンポジションを多用する画像パターンは避けます。
• ペインターの状態を直接扱う必要がある場合は、rememberAsyncImagePainter 自体では画面上のサイズが推測されないことに注意してください。

アンチパターン

• 小さなリスト項目に、サイズの大きなリモートアセットを読み込む。
• シンプルなプレースホルダーで十分な場合にも、あらゆる場面で SubcomposeAsyncImage を使用する。
• エラー時のフォールバックを用意せず、画像読み込みの失敗を何も起きなかったかのように扱う。
• 操作可能な画像や内容のある画像に、アクセシビリティのセマンティクスを設定し忘れる。

レビューの重点項目

• API の選択：AsyncImage、rememberAsyncImagePainter、SubcomposeAsyncImage。
• 表示領域に適したサイズ指定とリクエストの構築。
• 適切な Coil ネットワークモジュールなど、リモート読み込みの前提条件。
• リスト、テスト、スクリーンショットで安定して表示されるプレースホルダーとエラー状態。

例

期待どおりのケース

• シナリオ：Compose のフィクスチャをビルドし、タスクボードに安定した AsyncImage 表示領域が描画されることを確認します。
• コマンド：bash skills/android-coil-compose/scripts/run_examples.sh

エッジケース

• シナリオ：プレースホルダー、サイズ指定、Lazy リストのパフォーマンスがすべて重要となるリストセルをレビューします。
• コマンド：cd examples/orbittasks-compose && ./gradlew :app:testDebugUnitTest

失敗からの復旧

• シナリオ：プレースホルダーまたはエラー状態の変更後、スクリーンショットに適した検証方法で画像表示領域を再確認します。
• コマンド：cd examples/orbittasks-compose && ./gradlew verifyRoborazziDebug

完了チェックリスト

• より低レベルのペインター API を使う理由がある場合を除き、AsyncImage をデフォルトとして使用しています。
• サイズ、プレースホルダー、エラー状態を明示しています。
• アクセシビリティの動作を意図的に設定しています。
• Compose のフィクスチャでリストとスクリーンショットの動作を検証しています。

Official References

• https://coil-kt.github.io/coil/compose/
• https://coil-kt.github.io/coil/image_requests/
• https://coil-kt.github.io/coil/network/
• https://developer.android.com/develop/ui/compose/graphics/images/loading
• https://developer.android.com/develop/ui/compose/accessibility