跳转至

注意,此库已被迁移至 Coil 官网库中,这里不再维护

详情请看:

Coil 官网

本手册

————————————————————————————————————————————————

Coil for Jetpack Compose

Maven Central

该库提供了简单易用的 Painter,它可以使用 Coil 图像加载库获取并显示外部图像(例如网络图像等)。

Coil logo

rememberCoilPainter()

主要 API rememberCoilPainter() 的最简单用法如下:

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter("https://picsum.photos/300/300"),
    contentDescription = stringResource(R.string.image_content_desc),
)

painter使用 Coil 加载传入的数据,然后绘制结果图像。

开发者也可以通过 requestBuilder 参数来自定义 CoilImageRequest。通过这种方式开发者可以实现如CircleCropTransformationBlurTransformationGrayscaleTransformationRoundedCornersTransformationtransformations 之类的效果:

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter(
        request = "https://picsum.photos/300/300",
        requestBuilder = {
            transformations(CircleCropTransformation())
        },
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

淡入动画

该库内置支持图像加载过程中的淡入动画

rememberCoilPainter 的函数参数 fadeIn:Boolean 默认为 false,当 fadeIn = true 时,一个默认的淡入动画将出现在图片成功加载过程中。

import androidx.compose.foundation.Image
import com.google.accompanist.coil.rememberCoilPainter

Image(
    painter = rememberCoilPainter(
        "https://picsum.photos/300/300",
        fadeIn = true
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

自定义内容

有时开发者可能希望在图片加载时显示占位图片或者在图片加载失败时显示失败提示图片,rememberCoilPainter()返回的painter是 的一个LoadPainter实例,ImageLoadState 有四种状态:EmptyLoadingSuccessError,分别对应着初始状态、加载状态、加载成功和加载失败。开发者可以根据需要显示不同的内容:

val painter = rememberCoilPainter("https://picsum.photos/300/300")

Box {
    Image(
        painter = painter,
        contentDescription = stringResource(R.string.image_content_desc),
    )

    when (painter.loadState) {
        is ImageLoadState.Loading -> {
            // Display a circular progress indicator whilst loading
            CircularProgressIndicator(Modifier.align(Alignment.Center))
        }
        is ImageLoadState.Error -> {
            // If you wish to display some content if the request fails
        }
    }
}

预览

为了支持 Android Studio 的 Composable Previews 功能,开发者可以通过 previewPlaceholder 参数传入一个图片资源 ID ,以便 Android Studio 预览布局时有图片展示:

Image(
    painter = rememberCoilPainter(
        request = "https://picsum.photos/300/300",
        previewPlaceholder = R.drawable.placeholder,
    ),
    contentDescription = stringResource(R.string.image_content_desc),
)

如果引用的 drawable 仅用于 previewPlaceholder,则可以将其放置在 debug 构建变体的资源中,例如:app/debug/res/drawable/,通过这种操作将 drawable 捆绑在调试版本中,同时也将其排除至发布版本外。

GIF

Accompanist Coil 通过 Coil 内置 GIF 支持实现 GIF 图片加载。具体配置参考 Coil 库的配置说明

观察加载状态变化

开发者可以使用snapshotFlow()来观察 painter.loadState的变化情况,以此实现对图片加载状态的监听,然后根据需要调整代码逻辑:

val painter = rememberCoilPainter("https://image.url")

LaunchedEffect(painter) {
    snapshotFlow { painter.loadState }
        .filter { it.isFinalState() }
        .collect { result ->
            // TODO do something with result
        }
}

Image(painter = painter)

自定义 ImageLoader

如果开发者希望在所有rememberCoilPainter() 调用中使用同一个默认的ImageLoader,就请使用 LocalImageLoader

示例如下:

val imageLoader = ImageLoader.Builder(context)
    // customize the ImageLoader as needed
    .build()

CompositionLocalProvider(LocalImageLoader provides imageLoader) {
    // This will automatically use the value of LocalImageLoader
    Image(
        painter = rememberCoilPainter(...)
    )
}

更多有关 CompositionLocal 的信息,请参见此处

下载

Maven Central

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.google.accompanist:accompanist-coil:<version>"
}

每个版本可以在 快照仓库 中被找到,每次提交时都会更新。


最后更新: September 17, 2021