Skip to content

实用指南 ​

本页提供了关于如何使用 Coil 处理一些常见用例的指导。你可能需要修改这些代码以满足你的具体需求,但希望它能为你指明正确的方向!

发现了未涵盖的常见用例?欢迎提交拉取请求 (PR) 添加新小节。

Palette ​

Palette 允许你从图像中提取出主要颜色。要创建 Palette,你需要访问图像的 Bitmap。这可以通过多种方式实现:

你可以通过设置 ImageRequest.Listener 并将 ImageRequest 加入队列来获取对图像位图的访问权限:

kotlin
imageView.load("https://example.com/image.jpg") {
    // 禁用硬件位图,因为 Palette 需要读取图像的像素。
    allowHardware(false)
    listener(
        onSuccess = { _, result ->
            // 在后台线程上创建 palette。
            Palette.Builder(result.image.toBitmap()).generate { palette ->
                // 使用 palette。
            }
        }
    )
}

将内存缓存键用作占位符 ​

如果两张图像相同但加载尺寸不同,将先前请求的 MemoryCache.Key 用作后续请求的占位符会非常有用。例如,如果第一个请求以 100x100 加载图像,而第二个请求以 500x500 加载图像,我们就可以将第一张图像用作第二个请求的同步占位符。

以下是该效果在示例应用中的呈现效果:

列表中的图像特意以极低的细节加载,并且放慢了交叉淡入淡出(crossfade)速度,以突出视觉效果。

要实现此效果,请将第一个请求的 MemoryCache.Key 用作第二个请求的 ImageRequest.placeholderMemoryCacheKey。示例如下:

kotlin
// 第一个请求
listImageView.load("https://example.com/image.jpg")

// 第二个请求(在第一个请求完成后)
detailImageView.load("https://example.com/image.jpg") {
    placeholderMemoryCacheKey((listImageView.result as? SuccessResult)?.memoryCacheKey)
}

Compose AnimatedContent ​

使用 rememberAsyncImagePainter 和 AnimatedContent 在占位符与已加载图像之间添加动画过渡:

kotlin
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 -> {
            // 在 model 变更后旧图像退出动画期间保持其可见。
            Image(
                painter = targetState.painter,
                contentDescription = stringResource(R.string.description),
            )
        }
        is AsyncImagePainter.State.Error -> ErrorContent()
    }
}

将 targetState.painter 传递给 Image,以便在 model 变更后旧图像退出动画期间保持其可见。

在加载完成之前,最终的图像尺寸是未知的。请使用固定约束或已知宽高比来预留空间。

即使图像已在内存缓存中,rememberAsyncImagePainter 也会从 State.Empty 开始。如有需要,可以使用 state.result.dataSource 为内存缓存中的图像跳过动画。

注意:AnimatedContent 的开销远高于 painter 交叉淡入淡出,并且在动画结束之前会将旧图像保留在内存中。在惰性列表中或仅需要简单的淡入淡出时,建议优先使用 ImageRequest.Builder.crossfade。

共享元素转换 (Shared Element Transitions) ​

共享元素转换允许你在 Activities 与 Fragments 之间实现动画过渡。以下是使其与 Coil 协同工作的一些建议:

  • 共享元素转换与硬件位图不兼容。你应该设置 allowHardware(false),为动画起始的 ImageView 和动画目标的视图同时禁用硬件位图。否则,过渡转换将抛出 java.lang.IllegalArgumentException: Software rendering doesn't support hardware bitmaps 异常。

  • 将起始图像的 MemoryCache.Key 用作结束图像的 placeholderMemoryCacheKey。这可确保将起始图像用作结束图像的占位符;若图像已在内存缓存中,则会实现平滑过渡且不会出现白闪。

  • 同时使用 ChangeImageTransform 与 ChangeBounds 可获得最佳效果。

正在使用 Compose?阅读此文章了解如何结合 AsyncImage 执行共享元素转换。

Remote Views ​

Coil 没有开箱即用地为 RemoteViews 提供 Target,但你可以像这样自行创建一个:

kotlin
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 请求即可:

kotlin
val request = ImageRequest.Builder(context)
    .data("https://example.com/image.jpg")
    .target(RemoteViewsTarget(context, componentName, remoteViews, imageViewResId))
    .build()
imageLoader.enqueue(request)

变换 Painter ​

AsyncImage 与 AsyncImagePainter 都具有接收 Painter 的 placeholder/error/fallback 实参。Painter 虽然不如可组合项灵活,但运行速度更快,因为 Coil 不需要使用子组合(subcomposition)。即便如此,为了获得预期的 UI,可能仍需要对 Painter 进行内嵌缩进(inset)、拉伸、着色或变换。为此,将此代码片段 (gist) 复制到你的项目中,并像这样包装 Painter:

kotlin
AsyncImage(
    model = "https://example.com/image.jpg",
    contentDescription = null,
    placeholder = forwardingPainter(
        painter = painterResource(R.drawable.placeholder),
        colorFilter = ColorFilter(Color.Red),
        alpha = 0.5f,
    ),
)

可以使用尾随 lambda 重写 onDraw:

kotlin
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 查询参数。

kotlin
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 {
            // width 和 height 不可用,例如由于存在无限约束。
            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 中!

kotlin
ImageLoader.Builder(context)
    .components {
        add(UrlSizeInterceptor())
    }
    .build()