Skip to content

网络图片 ​

默认情况下,Coil 3.x 不包含从网络加载图片的支持。这是为了避免向希望使用自己的网络解决方案或不需要网络 URL 支持(例如仅从磁盘加载图片)的用户强加庞大的网络依赖项。

要添加从网络获取图片的支持,仅需导入以下依赖项之一:

kotlin
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 引擎。以下是一组快速入门引擎:

kotlin
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:

kotlin
val imageLoader = ImageLoader.Builder(context)
    .components {
        add(
            OkHttpNetworkFetcherFactory(
                callFactory = {
                    OkHttpClient()
                }
            )
        )
    }
    .build()

注意

如果你已经有一个构建好的 OkHttpClient,请使用 newBuilder() 来构建一个与原始客户端共享资源的新客户端。

在 ImageLoader 中使用 HttpEngine ​

要在 Android API 34 及更高版本上使用 HttpEngine,请添加 coil-network-httpengine 并在你的 ImageLoader 中注册其 fetcher:

kotlin
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:

kotlin
OkHttpNetworkFetcherFactory(
    cacheStrategy = { CacheControlCacheStrategy() },
)

注意

要支持 Android API 级别 25 或更低版本,你需要启用 coreLibraryDesugaring。请遵循此处的文档进行启用。

标头 ​

可以通过以下两种方式之一为你的图片请求添加标头。你可以为单个请求设置标头:

kotlin
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 执行的每个请求设置标头:

kotlin
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()