網路圖片
預設情況下,Coil 3.x 不包含從網路載入圖片的支援。這是為了避免對想要使用自訂網路解決方案或不需要網路 URL 支援(例如僅從磁碟載入圖片)的使用者強加龐大的網路相依性。
若要新增從網路擷取圖片的支援,請僅匯入以下其中一項:
implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3") // 僅適用於 Android/JVM。
implementation("io.coil-kt.coil3:coil-network-ktor2:3.6.3")
implementation("io.coil-kt.coil3:coil-network-ktor3:3.6.3")
implementation("io.coil-kt.coil3:coil-network-httpengine:3.6.3") // 僅適用於 Android API 34+。如果你使用 OkHttp 或 HttpEngine,這樣就完成了。匯入之後,便會自動支援像是 https://example.com/image.jpg 的網路 URL。如果你使用 Ktor,則需要為每個平台新增支援的引擎(請參閱下方內容)。
Ktor 網路引擎
如果你依賴 coil-network-ktor2 或 coil-network-ktor3,你需要為每個平台(Javascript 除外)匯入一個 Ktor 引擎。以下是一組快速入門的引擎配置:
androidMain {
dependencies {
implementation("io.ktor:ktor-client-android:<ktor-version>")
}
}
appleMain {
dependencies {
implementation("io.ktor:ktor-client-darwin:<ktor-version>")
}
}
jvmMain {
dependencies {
implementation("io.ktor:ktor-client-java:<ktor-version>")
}
}如果你想使用自訂網路程式庫,可以匯入 io.coil-kt.coil3:coil-network-core,實作 NetworkClient,並在你的 ImageLoader 中將自訂的 NetworkClient 註冊至 NetworkFetcher。
使用自訂的 OkHttpClient
如果你使用 io.coil-kt.coil3:coil-network-okhttp,可以在建立 ImageLoader 時指定自訂的 OkHttpClient:
val imageLoader = ImageLoader.Builder(context)
.components {
add(
OkHttpNetworkFetcherFactory(
callFactory = {
OkHttpClient()
}
)
)
}
.build()注意
如果你已經建構了 OkHttpClient,請使用 newBuilder() 來建置一個與原始用戶端共享資源的新用戶端。
在 ImageLoader 中使用 HttpEngine
若要在 Android API 34 及更新版本上使用 HttpEngine,請新增 coil-network-httpengine 並在你的 ImageLoader 中註冊其 fetcher:
import android.os.Build.VERSION.SDK_INT
import coil3.ImageLoader
import coil3.network.httpengine.HttpEngineNetworkFetcherFactory
val imageLoader = ImageLoader.Builder(context)
.components {
if (SDK_INT >= 34) {
add(HttpEngineNetworkFetcherFactory())
}
}
.build()如果你沒有手動註冊網路 fetcher,Coil 的 service loader 將依序從 OkHttp、Ktor 3、Ktor 2 和 HttpEngine 中挑選第一個可用的網路用戶端。
Cache-Control 支援
預設情況下,Coil 3.x 不會遵循 Cache-Control 標頭,且一律將回應儲存至其磁碟快取中。
io.coil-kt.coil3:coil-network-cache-control 包含一個 CacheStrategy 實作,可確保 NetworkFetcher 遵循網路回應的 Cache-Control 標頭。
將 CacheControlCacheStrategy 傳遞給你的 NetworkFetcher,然後在你的 ImageLoader 中註冊該自訂的 NetworkFetcher:
OkHttpNetworkFetcherFactory(
cacheStrategy = { CacheControlCacheStrategy() },
)注意
若要支援 Android API 等級 25 或以下版本,你需要啟用 coreLibraryDesugaring。請遵循此處的文件進行啟用。
標頭
可以透過以下兩種方式之一將標頭新增至圖片請求中。你可以為單一請求設定標頭:
val headers = NetworkHeaders.Builder()
.set("Cache-Control", "no-cache")
.build()
val request = ImageRequest.Builder(context)
.data("https://example.com/image.jpg")
.httpHeaders(headers)
.target(imageView)
.build()
imageLoader.execute(request)或者你可以建立一個 OkHttp Interceptor,為你的 ImageLoader 所執行的每個請求設定標頭:
class RequestHeaderInterceptor(
private val name: String,
private val value: String,
) : Interceptor {
override fun intercept(chain: Interceptor.Chain): Response {
val request = chain.request().newBuilder()
.header(name, value)
.build()
return chain.proceed(request)
}
}
val imageLoader = ImageLoader.Builder(context)
.components {
add(
OkHttpNetworkFetcherFactory(
callFactory = {
OkHttpClient.Builder()
.addNetworkInterceptor(RequestHeaderInterceptor("Cache-Control", "no-cache"))
.build()
},
)
)
}
.build()