Coil 3.x へのアップグレード
Coil 3 は、多くの主要な改善点を含む Coil の次のメジャーバージョンです:
- すべての主要ターゲット(Android、iOS、JVM、JS、および WASM)を含む Compose Multiplatform の完全サポート。
- 複数のネットワークライブラリ(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 になります。
Coroutines、Ktor、AndroidX で使用されている命名規則に合わせるため、coil-base アーティファクトと coil-compose-base アーティファクトは、それぞれ coil-core と coil-compose-core に名前が変更されました。
ネットワーク画像
coil-core は、デフォルトでネットワークからの画像読み込みをサポートしなくなりました。 Coil のネットワークアーティファクトのいずれかへの依存関係を追加する必要があります。詳細はこちらを参照してください。。この変更により、ユーザーは異なるネットワークライブラリを選択したり、アプリで不要な場合にネットワーク依存関係を排除したりできるようになりました。
さらに、Cache-Control ヘッダーはデフォルトでは考慮されなくなりました。詳細についてはこちらを参照してください。
マルチプラットフォーム
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クラスに置き換えられました。ImageRequest.dataとしてandroid.net.Uriを渡している呼び出し元は影響を受けません。android.net.Uriを受け取ることに依存しているカスタムFetcherは、coil3.Uriを使用するように更新する必要があります。 Contextの使用箇所はPlatformContextに置き換えられました。PlatformContextは Android ではContextの型エイリアスであり、Android 以外のプラットフォームではPlatformContext.INSTANCEを使用してアクセスできます。Compose Multiplatform で参照を取得するには、LocalPlatformContext.currentを使用します。CoilクラスはSingletonImageLoaderに名前が変更されました。- カスタムの Android
ApplicationクラスでImageLoaderFactoryを実装している場合は、ImageLoaderFactoryの代替としてSingletonImageLoader.Factoryの実装に切り替える必要があります。SingletonImageLoader.Factoryを実装すると、必要に応じてnewImageLoader()をオーバーライドできるようになります。
coil-svg アーティファクトはマルチプラットフォームでサポートされていますが、coil-gif および coil-video アーティファクトは、特定の Android デコーダーやライブラリに依存しているため、(現時点では)引き続き Android 専用です。
Compose
coil-compose アーティファクトの API はほぼ変更されていません。Coil 2 と同様に、AsyncImage、SubcomposeAsyncImage、rememberAsyncImagePainter を引き続き使用できます。さらに、これらのメソッドは再起動可能(restartable)かつスキップ可能(skippable)になるよう更新されており、パフォーマンスが向上するはずです。
AsyncImagePainter.stateはStateFlowになりました。val state = painter.state.collectAsState()を使用して監視する必要があります。AsyncImagePainterのデフォルトのSizeResolverは、キャンバスのサイズを取得するために最初のonDraw呼び出しを待機しなくなりました。代わりに、AsyncImagePainterはデフォルトでSize.ORIGINALになります。- Compose の
modelEqualityDelegateは、AsyncImage/SubcomposeAsyncImage/rememberAsyncImagePainterへのパラメーターではなく、CompositionLocal であるLocalAsyncImageModelEqualityDelegateを介して設定されるようになりました。
全般
その他の重要な動作変更は以下のとおりです:
- ファーストパーティの
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)で再度有効にできます。 - 予期しない OOM(メモリ不足)を防ぐため、出力画像のサイズは 4096x4096 未満に制限されるようになりました。これは
ImageLoader/ImageRequest.Builder.maxBitmapSizeで設定できます。この動作を無効にするには、maxBitmapSizeをSize.ORIGINALに設定します。 - Coil 2 の
ParametersAPI はExtrasに置き換えられました。Extrasは文字列のキーを必要とせず、参照の等価性に依存します。Extrasはメモリキャッシュキーの変更をサポートしていません。extra がメモリキャッシュキーに影響を与える場合は、代わりにImageRequest.memoryCacheKeyExtraを使用してください。 - マルチプラットフォームをより容易にサポートするため、多くの
ImageRequest.Builder関数が拡張関数に移行しました。
