升级到 Coil 3.x
Coil 3 是 Coil 的下一个主要版本,包含多项重大改进:
- 完整支持 Compose Multiplatform,包括所有主要目标平台(Android、iOS、JVM、JS 以及 WASM)。
- 支持多个网络库(Ktor 和 OkHttp)。或者,如果你只需要加载本地/静态文件,也可以在不依赖网络库的情况下使用 Coil。
- 改进了 Compose
@Preview渲染,并通过LocalAsyncImagePreviewHandler支持自定义预览行为。 - 对部分需要破坏现有行为的错误进行了重要修复(详情见下文)。
本文档简要概述了从 Coil 2 到 Coil 3 的主要变更,并重点说明了所有破坏性或重要改动。本文档未涵盖所有的二进制不兼容变更或细微的行为变化。
有关示例项目,请参阅 Compose Multiplatform 示例。
Maven 坐标与包名
Coil 的 Maven 坐标已从 io.coil-kt 更新为 io.coil-kt.coil3,其包名也已从 coil 更新为 coil3。这使得 Coil 3 可以与 Coil 2 并行运行,而不会发生二进制兼容性问题。例如,io.coil-kt:coil:2.7.0 现在变更为 io.coil-kt.coil3:coil:3.0.0。
构件 coil-base 和 coil-compose-base 分别重命名为 coil-core 和 coil-compose-core,以与 Coroutines、Ktor 和 AndroidX 所使用的命名约定保持一致。
网络图片
coil-core 默认不再支持从网络加载图片。你必须添加对 Coil 网络构件之一的依赖项。详细了解请参阅此处。。进行此更改是为了让使用者能够使用不同的网络库,或者在应用不需要时避免引入网络依赖项。
此外,默认不再遵循 Cache-Control 标头。详细了解请参阅此处。
多平台
Coil 3 现已成为一个 Kotlin Multiplatform 库,支持 Android、JVM、iOS、macOS、JavaScript 和 WASM。
在 Android 上,Coil 使用标准图形类来渲染图片。在非 Android 平台上,Coil 使用 Skiko 渲染图片。Skiko 是一套包装了 Google 开发的 Skia 图形引擎的 Kotlin 绑定。
作为脱离 Android SDK 解耦的一部分,API 进行了多项更改。值得注意的有:
Drawable已替换为自定义的Image接口。在 Android 上,使用Drawable.asImage()和Image.asDrawable(resources)在类之间进行转换。在非 Android 平台上,使用Bitmap.asImage()和Image.toBitmap()。- Android 的
android.net.Uri类的使用已被多平台的coil3.Uri类取代。将android.net.Uri作为ImageRequest.data传递的所有调用站点均不受影响。依赖接收android.net.Uri的自定义Fetcher需要更新为使用coil3.Uri。 Context的使用已被替换为PlatformContext。PlatformContext在 Android 上是Context的类型别名,在非 Android 平台上可以使用PlatformContext.INSTANCE进行访问。在 Compose Multiplatform 中,请使用LocalPlatformContext.current获取引用。Coil类已重命名为SingletonImageLoader。- 如果你在自定义的 Android
Application类中实现了ImageLoaderFactory,则需要改为实现SingletonImageLoader.Factory来替代ImageLoaderFactory。实现SingletonImageLoader.Factory后,如果你需要或希望重写newImageLoader(),即可对其进行重写。
coil-svg 构件已支持多平台,但 coil-gif 和 coil-video 构件(目前)仍然仅限 Android,因为它们依赖特定的 Android 解码器与库。
Compose
构件 coil-compose 的 API 大部分保持不变。你可以像在 Coil 2 中一样继续使用 AsyncImage、SubcomposeAsyncImage 和 rememberAsyncImagePainter。此外,这些方法已更新为可重启与可跳过 (restartable and skippable),这有助于提升其性能。
AsyncImagePainter.state现在是一个StateFlow。应当使用val state = painter.state.collectAsState()来进行观察。AsyncImagePainter的默认SizeResolver不再等待第一次onDraw调用来获取画布的大小。取而代之的是,AsyncImagePainter默认使用Size.ORIGINAL。- Compose 的
modelEqualityDelegate委托现在通过 CompositionLocalLocalAsyncImageModelEqualityDelegate设置,而不是作为AsyncImage/SubcomposeAsyncImage/rememberAsyncImagePainter的形参传入。
常规变更
其他重要的行为变更包括:
- 官方第一方的
Fetcher和Decoder(例如NetworkFetcher.Factory、SvgDecoder等)现在会通过 ServiceLoader 自动添加到每个新建的ImageLoader中。可以通过ImageLoader.Builder.serviceLoaderEnabled(false)禁用此行为。 - 移除对
android.resource://example.package.name/drawable/imageURI 的支持,因为这会阻碍资源缩减优化。建议直接传递R.drawable.image值。传递资源 ID 而不是资源名称仍然有效:android.resource://example.package.name/12345678。如果你仍然需要此功能,可以在组件注册表中手动引入ResourceUriMapper。 - 默认不再将文件的最后修改时间戳添加到其缓存键中。这是为了避免在主线程上读取磁盘(哪怕耗时极短)。可以通过
ImageRequest.Builder.addLastModifiedToFileCacheKey(true)或ImageLoader.Builder.addLastModifiedToFileCacheKey(true)重新启用该功能。 - 输出图片尺寸现在强制要求小于 4096x4096,以防止意外的 OOM。可以通过
ImageLoader/ImageRequest.Builder.maxBitmapSize进行配置。若要禁用此行为,请将maxBitmapSize设置为Size.ORIGINAL。 - Coil 2 的
ParametersAPI 已被Extras替代。Extras不需要字符串键,而是依赖标识相等性(identity equality)。Extras不支持修改内存缓存键。如果你的 extra 会影响内存缓存键,请改用ImageRequest.memoryCacheKeyExtra。 - 许多
ImageRequest.Builder函数已变更为扩展函数,以便更轻松地支持多平台。
