网络图片
默认情况下,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 的服务加载器(ServiceLoader)会按 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()