レシピ
このページでは、Coilを使用した一般的なユースケースの処理方法について案内します。要件に合わせてコードを変更する必要があるかもしれませんが、実装の足がかりとして役立つはずです。
カバーされていない一般的なユースケースにお気づきですか?新しいセクションを追加するPRをぜひ気軽に送信してください。
Palette
Palette を使用すると、画像から主要な色を抽出できます。Palette を作成するには、画像の Bitmap にアクセスする必要があります。これにはいくつかの方法があります。
ImageRequest.Listener を設定し、ImageRequest をエンキューすることで、画像のビットマップにアクセスできます。
imageView.load("https://example.com/image.jpg") {
// Paletteが画像のピクセルを読み取る必要があるため、ハードウェアビットマップを無効化します。
allowHardware(false)
listener(
onSuccess = { _, result ->
// バックグラウンドスレッドでパレットを作成します。
Palette.Builder(result.image.toBitmap()).generate { palette ->
// パレットを使用します。
}
}
)
}メモリキャッシュキーをプレースホルダーとして使用する
以前のリクエストの MemoryCache.Key を後続のリクエストのプレースホルダーとして使用することは、サイズが異なるだけで同じ2つの画像を読み込む場合に役立ちます。例えば、最初のリクエストが画像を 100x100 で読み込み、2番目のリクエストが画像を 500x500 で読み込む場合、最初の画像を2番目のリクエストの同期的なプレースホルダーとして使用できます。
サンプルアプリでは、この効果は次のようになります。
視覚効果を強調するため、リスト内の画像は意図的に非常に低いディテールで読み込まれ、クロスフェードは遅く設定されています。
この効果を実現するには、最初のリクエストの MemoryCache.Key を2番目のリクエストの ImageRequest.placeholderMemoryCacheKey として使用します。以下に例を示します。
// 最初のリクエスト
listImageView.load("https://example.com/image.jpg")
// 2番目のリクエスト(最初のリクエストが完了した後)
detailImageView.load("https://example.com/image.jpg") {
placeholderMemoryCacheKey((listImageView.result as? SuccessResult)?.memoryCacheKey)
}Compose AnimatedContent
プレースホルダーと読み込まれた画像の間をアニメーションさせるには、rememberAsyncImagePainter と AnimatedContent を使用します。
val sizeResolver = rememberConstraintsSizeResolver()
val painter = rememberAsyncImagePainter(
model = ImageRequest.Builder(LocalPlatformContext.current)
.data("https://example.com/image.jpg")
.size(sizeResolver)
.build(),
)
val state by painter.state.collectAsState()
AnimatedContent(
modifier = Modifier.then(sizeResolver),
targetState = state,
contentKey = { it::class },
transitionSpec = { fadeIn() togetherWith fadeOut() },
) { targetState ->
when (targetState) {
is AsyncImagePainter.State.Empty,
is AsyncImagePainter.State.Loading -> PlaceholderContent()
is AsyncImagePainter.State.Success -> {
// モデルが変更された後、古い画像がアニメーションしながら消える間も表示を維持します。
Image(
painter = targetState.painter,
contentDescription = stringResource(R.string.description),
)
}
is AsyncImagePainter.State.Error -> ErrorContent()
}
}モデル変更後に古い画像がアニメーションしながら消える間も表示が維持されるよう、targetState.painter を Image に渡します。
最終的な画像サイズは読み込みが完了するまで不明です。スペースを確保するには、固定の制約(constraints)または既知のアスペクト比を使用してください。
rememberAsyncImagePainter は、画像がメモリキャッシュにある場合でも State.Empty から開始します。必要に応じて、state.result.dataSource を使用してメモリキャッシュされた画像のアニメーションをスキップしてください。
注意: AnimatedContent はペインターのクロスフェードよりもはるかに負荷が高く、アニメーションが終了するまで古い画像をメモリに保持します。Lazy リストや単純なフェードの場合は、ImageRequest.Builder.crossfade を優先して使用してください。
共有要素遷移(Shared Element Transitions)
共有要素遷移(Shared element transitions) を使用すると、Activities と Fragments の間をアニメーション化できます。Coilでこれらを適切に機能させるための推奨事項は以下のとおりです。
共有要素遷移はハードウェアビットマップと互換性がありません。 アニメーション元の
ImageViewとアニメーション先のビューの両方でallowHardware(false)を設定し、ハードウェアビットマップを無効にする必要があります。設定しない場合、遷移時にjava.lang.IllegalArgumentException: Software rendering doesn't support hardware bitmaps例外がスローされます。開始画像の
MemoryCache.Keyを、終了画像のplaceholderMemoryCacheKeyとして使用します。これにより、開始画像が終了画像のプレースホルダーとして使用され、画像がメモリキャッシュにある場合に白いちらつき(フラッシュ)のないスムーズな遷移が実現します。最適な結果を得るには、
ChangeImageTransformとChangeBoundsを組み合わせて使用してください。
Composeを使用していますか?AsyncImage で共有要素遷移を実行する方法については、こちらの記事を確認してください。
Remote Views
Coilは RemoteViews 用の Target を標準では提供していませんが、次のように作成できます。
class RemoteViewsTarget(
private val context: Context,
private val componentName: ComponentName,
private val remoteViews: RemoteViews,
@IdRes private val imageViewResId: Int
) : Target {
override fun onStart(placeholder: Image?) = setImage(placeholder)
override fun onError(error: Image?) = setImage(error)
override fun onSuccess(result: Image) = setImage(result)
private fun setImage(image: Image?) {
remoteViews.setImageViewBitmap(imageViewResId, image?.toBitmap())
AppWidgetManager.getInstance(context).updateAppWidget(componentName, remoteViews)
}
}その後、通常どおりリクエストを enqueue / execute します。
val request = ImageRequest.Builder(context)
.data("https://example.com/image.jpg")
.target(RemoteViewsTarget(context, componentName, remoteViews, imageViewResId))
.build()
imageLoader.enqueue(request)Painterの変形(Transforming Painters)
AsyncImage と AsyncImagePainter の両方に、Painter を受け取る placeholder / error / fallback 引数があります。Painterはコンポーザブルを使用するよりも柔軟性に欠けますが、Coilがサブコンポジション(subcomposition)を使用する必要がないため高速です。とはいえ、目的のUIを実現するために、Painterのインセット、拡大・縮小、色合い変更(tint)、または変形が必要になる場合があります。これを実現するには、このGistをプロジェクトにコピーし、次のようにPainterをラップします。
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
placeholder = forwardingPainter(
painter = painterResource(R.drawable.placeholder),
colorFilter = ColorFilter(Color.Red),
alpha = 0.5f,
),
)末尾のラムダを使用して onDraw を上書きできます。
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
placeholder = forwardingPainter(painterResource(R.drawable.placeholder)) { info ->
inset(50f, 50f) {
with(info.painter) {
draw(size, info.alpha, info.colorFilter)
}
}
},
)リクエストの変換
画像の取得に使用されるHTTPリクエストを変換(変更)する必要がある場合があります。この例では、Interceptor を使用してリクエストURLに width と height のクエリパラメータを追加します。
class UrlSizeInterceptor : Interceptor {
override suspend fun intercept(chain: Chain): ImageResult {
val request = chain.request
val uri = request.uri
if (uri == null || uri.scheme !in setOf("https", "http")) {
// HTTP以外のリクエストは無視します。
return chain.proceed()
}
val (width, height) = chain.size
return if (width is Pixels && height is Pixels) {
val transformUri = uri.newBuilder()
.query("width=${width.px}&height=${height.px}")
.build()
val transformedRequest = request.newBuilder()
.data(transformUri)
.build()
return chain.withRequest(transformedRequest).proceed()
} else {
// 幅と高さが利用できません(例: 無限の制約によるものなど)。
chain.proceed()
}
}
private val ImageRequest.uri: Uri?
get() = when (val data = data) {
is Uri -> data
is coil3.Uri -> data.toAndroidUri()
is String -> data.toUri()
else -> null
}
}作成したインターセプターを ImageLoader に追加して登録することを忘れないでください。
ImageLoader.Builder(context)
.components {
add(UrlSizeInterceptor())
}
.build()