Compose
要添加对 Compose UI 的支持,请导入扩展库:
implementation("io.coil-kt.coil3:coil-compose:3.6.3")然后使用 AsyncImage 可组合项来加载并显示图片:
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
)model 既可以是 ImageRequest.data 的值,也可以是 ImageRequest 本身。contentDescription 用于设置无障碍服务所使用的文本,以描述该图片所呈现的内容。
AsyncImage
AsyncImage 是一个以异步方式执行图片请求并渲染结果的可组合项。它支持与标准 Image 可组合项相同的实参,并且还支持设置 placeholder/error/fallback painter 以及 onLoading/onSuccess/onError 回调。以下是一个加载图片时应用圆形裁剪、淡入淡出(crossfade)并设置占位符的示例:
AsyncImage(
model = ImageRequest.Builder(LocalContext.current)
.data("https://example.com/image.jpg")
.crossfade(true)
.build(),
placeholder = painterResource(R.drawable.placeholder),
contentDescription = stringResource(R.string.description),
contentScale = ContentScale.Crop,
modifier = Modifier.clip(CircleShape),
)何时使用此函数:
在大多数情况下首选 AsyncImage。它会根据可组合项的约束条件以及所提供的 ContentScale 正确确定加载图片应采用的尺寸。
rememberAsyncImagePainter
在内部,AsyncImage 和 SubcomposeAsyncImage 使用 rememberAsyncImagePainter 来加载 model。如果你需要的是 Painter 而非可组合项,可以使用 rememberAsyncImagePainter 来加载图片:
val painter = rememberAsyncImagePainter("https://example.com/image.jpg")rememberAsyncImagePainter 比 AsyncImage 和 SubcomposeAsyncImage 更灵活,但有一些缺点(见下文)。
何时使用此函数:
适用于需要 Painter 而非可组合项的情况——或者需要观察 AsyncImagePainter.state 并根据其绘制不同的可组合项——亦或需要使用 AsyncImagePainter.restart 手动重启图片请求的情况。
此函数的主要缺点在于它不会检测图片在屏幕上加载时的尺寸,并且始终按其原始尺寸加载图片。你可以传入自定义的 SizeResolver 或使用 rememberConstraintsSizeResolver(这也是 AsyncImage 内部所使用的)来解决此问题。示例:
val sizeResolver = rememberConstraintsSizeResolver()
val painter = rememberAsyncImagePainter(
model = ImageRequest.Builder(LocalPlatformContext.current)
.data("https://example.com/image.jpg")
.size(sizeResolver)
.build(),
)
Image(
painter = painter,
contentDescription = null,
modifier = Modifier.then(sizeResolver),
)另一个缺点是,使用 rememberAsyncImagePainter 时,在首次组合中 AsyncImagePainter.state 将始终为 AsyncImagePainter.State.Empty——即使图片已存在于内存缓存中且会在第一帧绘制。
SubcomposeAsyncImage
SubcomposeAsyncImage 是 AsyncImage 的变体,它利用子组合(subcomposition)为 AsyncImagePainter 的各种状态提供插槽 API,而不是使用 Painter。示例如下:
SubcomposeAsyncImage(
model = "https://example.com/image.jpg",
loading = {
CircularProgressIndicator()
},
contentDescription = stringResource(R.string.description),
)此外,你可以利用其 content 实参和用于渲染当前状态的 SubcomposeAsyncImageContent 来实现更复杂的逻辑:
SubcomposeAsyncImage(
model = "https://example.com/image.jpg",
contentDescription = stringResource(R.string.description)
) {
val state by painter.state.collectAsState()
if (state is AsyncImagePainter.State.Success) {
SubcomposeAsyncImageContent()
} else {
CircularProgressIndicator()
}
}注意
子组合比常规组合更慢,因此该可组合项可能不适合用于 UI 中对性能要求极高的部分(例如 LazyList)。
何时使用此函数:
如果你需要观察 AsyncImagePainter.state,通常首选使用 rememberAsyncImagePainter 而非此函数,因为它不使用子组合。
具体而言,仅当你需要观察 AsyncImagePainter.state,且不能像 rememberAsyncImagePainter 那样在首次组合和第一帧中为 Empty 时,此函数才有用。SubcomposeAsyncImage 使用子组合来获取图片的约束,因此其 AsyncImagePainter.state 可以立即更新。
观察 AsyncImagePainter.state
val painter = rememberAsyncImagePainter("https://example.com/image.jpg")
val state by painter.state.collectAsState()
when (state) {
is AsyncImagePainter.State.Empty,
is AsyncImagePainter.State.Loading -> {
CircularProgressIndicator()
}
is AsyncImagePainter.State.Success -> {
Image(
painter = painter,
contentDescription = stringResource(R.string.description)
)
}
is AsyncImagePainter.State.Error -> {
// 展示错误 UI。
}
}过渡
你可以使用 ImageRequest.Builder.crossfade 启用内置的淡入淡出过渡:
AsyncImage(
model = ImageRequest.Builder(LocalContext.current)
.data("https://example.com/image.jpg")
.crossfade(true)
.build(),
contentDescription = null,
)自定义 Transition 无法与 AsyncImage、SubcomposeAsyncImage 或 rememberAsyncImagePainter 配合使用,因为它们需要 View 引用。而 CrossfadeTransition 可以正常工作是因为内部提供了特殊支持。
话虽如此,在 Compose 中可以通过观察 AsyncImagePainter.state 来创建自定义过渡:
val painter = rememberAsyncImagePainter("https://example.com/image.jpg")
val state = painter.state.collectAsState().value
if (state is AsyncImagePainter.State.Success && state.result.dataSource != DataSource.MEMORY_CACHE) {
// 执行过渡动画。
}
Image(
painter = painter,
contentDescription = stringResource(R.string.description),
)完整的 AnimatedContent 示例请参阅 Compose AnimatedContent。
预览
AsyncImage/rememberAsyncImagePainter/SubcomposeAsyncImage 在 Android Studio 中的预览行为由 LocalAsyncImagePreviewHandler 控制。默认情况下,它会在预览环境中尝试正常执行请求。由于预览环境中禁用了网络访问,因此网络 URL 请求将始终失败。
你可以像这样重写预览行为:
val previewHandler = AsyncImagePreviewHandler {
ColorImage(Color.Red.toArgb())
}
CompositionLocalProvider(LocalAsyncImagePreviewHandler provides previewHandler) {
AsyncImage(
model = "https://example.com/image.jpg",
contentDescription = null,
)
}这对于在相同预览环境中运行的 AndroidX 的 Compose Preview 屏幕截图测试库 也非常有用。
Compose Multiplatform 资源
Coil 支持通过将 Res.getUri 作为 model 形参来加载 Compose Multiplatform Resources。示例:
AsyncImage(
model = Res.getUri("drawable/sample.jpg"),
contentDescription = null,
)注意
Coil 不支持 Res.drawable.image 和其他编译期安全的引用。你必须改用 Res.getUri("drawable/image")。关注此问题获取更新。
