快速入門
Compose UI
一個典型的 Compose UI 專案通常會需要匯入:
implementation("io.coil-kt.coil3:coil-compose:3.6.3")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3")匯入之後,你可以使用 AsyncImage 從網路載入圖片:
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
)注意
OkHttp 支援 Android 與桌面端 JVM。若共用的網路程式碼同時以 iOS 或 Web 為目標,請參閱 Ktor 網路引擎。
Android Views
如果你使用的是 Android View 而非 Compose UI,請匯入:
implementation("io.coil-kt.coil3:coil:3.6.3")
implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3")匯入之後,你可以使用 ImageView.load 擴充函式從網路載入圖片:
imageView.load("https://example.com/image.jpg")設定單例 ImageLoader
預設情況下,Coil 包含一個單例 ImageLoader。ImageLoader 透過擷取、解碼、快取並傳回結果來執行傳入的 ImageRequest。你不需要特別設定你的 ImageLoader;如果沒有設定,Coil 將以預設設定建立單例 ImageLoader。
你可以透過多種方式進行設定(請僅選擇其中一種):
- 在應用程式的進入點附近(應用程式的根
@Composable)呼叫setSingletonImageLoaderFactory。這最適合 Compose Multiplatform 應用程式。
setSingletonImageLoaderFactory { context ->
ImageLoader.Builder(context)
.crossfade(true)
.build()
}- 在 Android 的
Application上實作SingletonImageLoader.Factory。這最適合 Android 應用程式。
class CustomApplication : Application(), SingletonImageLoader.Factory {
override fun newImageLoader(context: Context): ImageLoader {
return ImageLoader.Builder(context)
.crossfade(true)
.build()
}
}- 在應用程式的進入點附近(例如 Android 中的
Application.onCreate)呼叫SingletonImageLoader.setSafe。這是最具彈性的方式。
SingletonImageLoader.setSafe { context ->
ImageLoader.Builder(context)
.crossfade(true)
.build()
}注意
如果你正在編寫相依於 Coil 的程式庫,請切勿取得/設定單例 ImageLoader。相反地,你應該相依於 io.coil-kt.coil3:coil-core,建立專屬的 ImageLoader 並手動傳遞。若在程式庫中設定了單例 ImageLoader,當使用該程式庫的應用程式也使用了 Coil 時,可能會覆蓋掉該應用程式所設定的 ImageLoader。
圖片
為了支援多平台算繪,Coil 3.x 使用了自訂的 coil3.Image 類別。它取代了 Android 的 Drawable,但與其完全互通:
val drawable = image.asDrawable(resources)
val image = drawable.asImage()Coil 也定義了一個 coil3.Bitmap 類別,它是 Android 上 android.graphics.Bitmap 或非 Android 平台上 org.jetbrains.skia.Bitmap 的型別別名:
val bitmap = image.toBitmap()
val image = bitmap.asImage()它也與 Compose UI 的 Painter 類別互通。此擴充函式需要匯入 coil-compose-core 構件:
val painter = image.asPainter(LocalPlatformContext.current)注意
Painter 無法轉換為 Image,因為 Painter 只能在 Composition 內部算繪,而 Image 必須能夠在任何 Canvas 上算繪。
構件
以下是 Coil 發佈至 mavenCentral() 的主要構件清單:
io.coil-kt.coil3:coil:預設構件,相依於io.coil-kt.coil3:coil-core。包含單例ImageLoader及相關的擴充函式。io.coil-kt.coil3:coil-core:io.coil-kt.coil3:coil的子集,不包含單例ImageLoader及相關的擴充函式。io.coil-kt.coil3:coil-compose:預設的 Compose UI 構件,相依於io.coil-kt.coil3:coil與io.coil-kt.coil3:coil-compose-core。包含使用單例ImageLoader的AsyncImage、rememberAsyncImagePainter與SubcomposeAsyncImage的多載。io.coil-kt.coil3:coil-compose-core:io.coil-kt.coil3:coil-compose的子集,不包含相依於單例ImageLoader的函式。io.coil-kt.coil3:coil-network-okhttp:包含使用 OkHttp 從網路擷取圖片的支援。io.coil-kt.coil3:coil-network-ktor2:包含使用 Ktor 2 從網路擷取圖片的支援。io.coil-kt.coil3:coil-network-ktor3:包含使用 Ktor 3 從網路擷取圖片的支援。io.coil-kt.coil3:coil-network-httpengine:包含使用 Android 的 HttpEngine 從網路擷取圖片的支援。需要 Android API >= 34。io.coil-kt.coil3:coil-network-cache-control:包含在從網路擷取圖片時遵循Cache-Control標頭 的支援。io.coil-kt.coil3:coil-gif:包含兩個解碼器以支援 GIF 解碼。詳情請參閱 GIF。io.coil-kt.coil3:coil-svg:包含一個解碼器以支援 SVG 解碼。詳情請參閱 SVG。io.coil-kt.coil3:coil-video:包含一個解碼器以支援從任何 Android 支援的影片格式中解碼影格。詳情請參閱影片。io.coil-kt.coil3:coil-test:包含支援測試的類別。詳情請參閱測試。io.coil-kt.coil3:coil-bom:包含一個物料清單 (Bill of Materials)。匯入coil-bom可讓你相依於其他 Coil 構件而無需指定版本。
