图像

本文档整理了 Jetpack Compose 中与图像显示、处理相关的常用 API、painter、常用库（如 Coil/Accompanist/Coil-Compose）和实用示例，覆盖本地资源与网络加载、占位与错误处理、裁剪/圆形/阴影、ContentScale、颜色过滤与性能注意事项。

核心组件与类型

• Image（androidx.compose.foundation.Image）：基础显示组件，接受 painter、contentDescription、contentScale、alignment、colorFilter 等参数。
• Painter：抽象的绘制接口。常见实现：painterResource（本地资源）、rememberImagePainter（旧的 Coil helper）、rememberAsyncImagePainter / AsyncImage（Coil-Compose/Accompanist 提供）或 rememberVectorPainter。
• ImageBitmap / ImageVector：位图与矢量图，分别用于位图资源和矢量资源。

常用参数说明

• painter: Painter：用于绘制的 painter，如 painterResource(id) 或 Coil 的 AsyncImage 提供的 painter。
• contentDescription: String?：无障碍说明（若为装饰性图像可设为 null）。
• contentScale: ContentScale：如何缩放图片以适应容器，常用值：Crop、Fit、FillBounds、Inside、None。
• alignment: Alignment：图片在容器内的定位（如 Alignment.Center、Alignment.TopStart）。
• modifier: Modifier：常用于 size、clip、border、background、clickable 等。
• colorFilter: ColorFilter?：对图片着色（例如为图标加 tint）。
• alpha: Float：透明度。

本地资源示例

@Composable
fun LocalImageExample() {
	Image(
		painter = painterResource(id = R.drawable.sample),
		contentDescription = "示例图片",
		modifier = Modifier
			.size(120.dp)
			.clip(RoundedCornerShape(8.dp)),
		contentScale = ContentScale.Crop
	)
}

网络图片（推荐使用 Coil-Compose）

说明：推荐使用 Coil 的 Compose 适配（io.coil-kt:coil-compose）或 Accompanist 的 coil（早期），以便方便的占位、错误与缓存控制。

Gradle 依赖示例（Coil-Compose）：

implementation "io.coil-kt:coil-compose:2.2.2"

基本网络加载示例（使用 Coil 提供的 AsyncImage）：

@Composable
fun NetworkImageExample(url: String) {
	AsyncImage(
		model = url,
		contentDescription = "网络图片",
		placeholder = painterResource(R.drawable.placeholder),
		error = painterResource(R.drawable.error),
		contentScale = ContentScale.Crop,
		modifier = Modifier
			.fillMaxWidth()
			.height(200.dp)
	)
}

占位与加载反馈可使用 SubcomposeAsyncImage（Coil 提供）显示加载中的进度或自定义占位。

@Composable
fun SubcomposeImage(url: String) {
	SubcomposeAsyncImage(
		model = url,
		contentDescription = null,
		modifier = Modifier.size(160.dp),
		contentScale = ContentScale.Crop
	) {
		val state = painter.state
		if (state is AsyncImagePainter.State.Loading || state is AsyncImagePainter.State.Empty) {
			Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
				CircularProgressIndicator()
			}
		} else if (state is AsyncImagePainter.State.Error) {
			Image(painter = painterResource(R.drawable.error), contentDescription = "错误")
		} else {
			SubcomposeAsyncImageContent()
		}
	}
}

圆形头像与裁剪

@Composable
fun Avatar(url: String) {
	AsyncImage(
		model = url,
		contentDescription = "头像",
		modifier = Modifier
			.size(64.dp)
			.clip(CircleShape)
			.border(2.dp, Color.White, CircleShape),
		contentScale = ContentScale.Crop
	)
}

GIF / 动图与 SVG 支持

• Coil 支持 GIF 与动画图像（需要相应的依赖）；SVG 支持可通过 coil-svg 扩展或使用 accompanist 的 SVG loader。
• 在 Compose 中显示 GIF 时依然使用 AsyncImage，Coil 会处理动画帧。

图片转换（Crop / CircleCrop / RoundedCorners）

• Coil 支持在请求时传入 ImageRequest.Builder，并使用 transformations（例如 RoundedCornersTransformation、CircleCropTransformation）。

示例：带变换的请求

val imageLoader = ImageLoader.Builder(context)
	.build()

val request = ImageRequest.Builder(context)
	.data(url)
	.transformations(CircleCropTransformation())
	.build()

val painter = rememberAsyncImagePainter(request)
Image(painter = painter, contentDescription = null)

（注意：API 名称随 Coil 版本变化，参考当前 Coil 文档。）

使用 Painter 的高级用法

• rememberDrawablePainter / rememberVectorPainter：用于矢量或 Drawable 转换为 painter。
• ImageBitmap.imageResource()：将资源转为 ImageBitmap（更低层操作）。

颜色过滤与着色

Image(
	painter = painterResource(R.drawable.ic_icon),
	contentDescription = null,
	colorFilter = ColorFilter.tint(Color.Red)
)

用于把图标着色为主题色。

性能与缓存建议

• 使用 Coil/Glide 等库处理网络图片以获得磁盘与内存缓存、解码优化与占位支持。
• 对列表中的图片使用合适的 size 或 scale，避免加载过大位图。
• 使用 remember / rememberAsyncImagePainter 缓存 painter，避免在每次组合时重新创建。
• 在 Recycler/List 中使用 LazyColumn + AsyncImage，避免不必要的重组。

可访问性

• contentDescription：为非纯装饰图像提供描述；纯装饰图像设为 null。
• 提示文本或语义（Modifier.semantics{}）来补充额外信息（例如图片代表的状态）。

小结（速查）

• 基础显示：Image(painter, contentDescription, contentScale, modifier)
• 本地资源：painterResource(R.drawable.xxx)、rememberVectorPainter
• 网络加载：AsyncImage / rememberAsyncImagePainter（Coil-Compose）或 Accompanist
• 裁剪与形状：Modifier.clip()、CircleShape、RoundedCornerShape
• 缓存与性能：使用 Coil/Glide、指定尺寸、使用 remember
• 变换：在 ImageRequest 中使用 transformations

如果你需要，我可以把上面的示例拆成带 @Preview 的 Kotlin 文件并放入 src/androidTest 或 sample 模块，或为你的项目生成一个最小示例工程配置（包含 Coil 依赖与演示屏幕）。