升級至 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 headers)。詳情請參閱此處。
多平台
Coil 3 現在是一個支援 Android、JVM、iOS、macOS、JavaScript 和 WASM 的 Kotlin Multiplatform 程式庫。
在 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等)現在會透過 service loader 自動新增至每個新的ImageLoader。可以使用ImageLoader.Builder.serviceLoaderEnabled(false)停用此行為。 - 移除了對
android.resource://example.package.name/drawable/imageURI 的支援,因為這會阻礙資源縮減(resource shrinking)最佳化。建議直接傳入R.drawable.image的值。傳入資源 ID 而非資源名稱依然可行:android.resource://example.package.name/12345678。如果你仍然需要此功能,可以在你的組件註冊表(component registry)中手動包含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函式已移為擴充函式,以便更輕鬆地支援多平台。
