Accompanist组件库中文指南 - Coil篇

这是我参与更文挑战的第6天，活动详情查看：更文挑战
本文翻译自 Accompanist 官方文档 - Coil

目前有一个正在进行的 Jetpack Compose中文手册项目，旨在帮助开发者更好的理解和掌握Compose框架，目前仍还在开荒中，欢迎大家进行关注与加入！

这篇文章由 @易冬同学翻译撰写，目前已经发布到该手册中，欢迎进行查阅。

请关注微信公众号 Jetpack Compose 博物馆 获取更多Compose技术信息。

概述

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

`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 参数来自定义 Coil 的ImageRequest。通过这种方式开发者可以实现如CircleCropTransformation、BlurTransformation、GrayscaleTransformation、RoundedCornersTransformation 等 transformations 之类的效果：

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 有四种状态：Empty、Loading、Success 和 Error，分别对应着初始状态、加载状态、加载成功和加载失败。开发者可以根据需要显示不同的内容：

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 的信息，请参见此处。

下载

repositories {
    mavenCentral()
}

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

Sonatype's snapshots repository中提供了开发版本的快照。每一次提交，快照都会更新。