coil-compose

Jetpack Compose 向け Coil

手順

Jetpack Compose で画像を読み込む場合は、Coil（Coroutines Image Loader）を使用してください。効率性とシームレスな統合により、Compose に推奨されるライブラリです。

1. 主要なコンポーザブル：AsyncImage

ほとんどのユースケースでは、AsyncImage を使用してください。サイズを自動的に解決し、標準の Image パラメーターをサポートします。

AsyncImage(
    model = ImageRequest.Builder(LocalContext.current)
        .data("https://example.com/image.jpg")
        .crossfade(true)
        .build(),
    placeholder = painterResource(R.drawable.placeholder),
    error = painterResource(R.drawable.error),
    contentDescription = stringResource(R.string.description),
    contentScale = ContentScale.Crop,
    modifier = Modifier.clip(CircleShape)
)

2. 低レベルの制御：rememberAsyncImagePainter

コンポーザブルではなく Painter が必要な場合（例：Canvas や Icon で使用する場合）、または読み込み状態を手動で監視する場合に限り、rememberAsyncImagePainter を使用してください。

警告

rememberAsyncImagePainter は、画面上で画像がどのサイズで読み込まれるかを検出せず、デフォルトでは常に元のサイズで画像を読み込みます。Painter がどうしても必要な場合を除き、AsyncImage を使用してください。

val painter = rememberAsyncImagePainter(
    model = ImageRequest.Builder(LocalContext.current)
        .data("https://example.com/image.jpg")
        .size(Size.ORIGINAL) // Explicitly define size if needed
        .build()
)

3. スロット API：SubcomposeAsyncImage

状態（読み込み中、成功、エラー）ごとにカスタムのスロット API が必要な場合は、SubcomposeAsyncImage を使用してください。

注意

サブコンポジションは通常のコンポジションより低速です。LazyColumn や LazyRow など、パフォーマンスが重要な箇所での SubcomposeAsyncImage の使用は避けてください。

SubcomposeAsyncImage(
    model = "https://example.com/image.jpg",
    contentDescription = null,
    loading = {
        CircularProgressIndicator()
    },
    error = {
        Icon(Icons.Default.Error, contentDescription = null)
    }
)

4. パフォーマンスとベストプラクティス

• シングルトンの ImageLoader：ディスク／メモリーキャッシュを共有できるよう、アプリ全体で単一の ImageLoader インスタンスを使用してください。
• メインスレッドセーフ：Coil は画像リクエストを自動的にバックグラウンドスレッドで実行します。
• クロスフェード：プレースホルダーから成功状態への遷移を滑らかにするため、ImageRequest で常に crossfade(true) を有効にしてください。
• サイズ指定：必要以上に大きな画像を読み込まないよう、contentScale を適切に設定してください。

5. 実装チェックリスト

• 他のバリエーションより AsyncImage を優先してください。
• 意味のある contentDescription を必ず指定するか、装飾用画像の場合は null に設定してください。
• UX を向上させるため、crossfade(true) を使用してください。
• リスト内での SubcomposeAsyncImage の使用は避けてください。
• 変換（例：CircleCropTransformation）など、特定の要件に合わせて ImageRequest を設定してください。