在 Jetpack Compose 中用 Coil…

在 Jetpack Compose 中从 URL 加载图片、处理加载/错误状态或优化图片性能时使用。

适用场景

解决思路

1. 在 Jetpack Compose 中实现图片加载时使用 Coil（Coroutines Image Loader），它是 Compose 的推荐库，效率高且集成无缝。
2. 大多数场景优先使用 AsyncImage：它会自动解析尺寸，并支持标准的 Image 参数。
3. 通过 ImageRequest.Builder(LocalContext.current).data("https://example.com/image.jpg").crossfade(true).build() 构造 model 传入。
4. 给 AsyncImage 设置 placeholder = painterResource(R.drawable.placeholder)、error = painterResource(R.drawable.error)、contentDescription = stringResource(R.string.description)、contentScale = ContentScale.Crop、modifier = Modifier.clip(CircleShape) 等参数。
5. 只有在需要一个 Painter（例如用于 Canvas 或 Icon）或需要手动观察加载状态时，才使用 rememberAsyncImagePainter。
6. 使用 rememberAsyncImagePainter 时要注意它不会检测图片在屏幕上的实际加载尺寸，默认总按原始尺寸加载；如需要就显式指定尺寸，例如 .size(Size.ORIGINAL)。
7. 当需要为不同状态（Loading、Success、Error）提供自定义 slot API 时使用 SubcomposeAsyncImage，并在其中传入 loading = { CircularProgressIndicator() }、error = { Icon(Icons.Default.Error, contentDescription = null) } 等槽位。
8. 避免在 LazyColumn、LazyRow 等性能敏感区域使用 SubcomposeAsyncImage，因为 subcomposition 比普通 composition 更慢。
9. 为整个 App 使用单一的 ImageLoader 单例，以共享磁盘缓存和内存缓存。
10. 放心在主线程发起请求：Coil 会自动在后台线程执行图片请求。
11. 始终在 ImageRequest 中启用 crossfade(true)，让 placeholder 到成功加载的过渡更平滑。
12. 设置合适的 contentScale，避免加载比实际需要更大的图片。
13. 实现前检查清单：优先用 AsyncImage 而不是其它变体。
14. 始终提供有意义的 contentDescription，装饰性图片则设为 null。
15. 使用 crossfade(true) 改善体验。
16. 列表中避免使用 SubcomposeAsyncImage。
17. 按具体需求配置 ImageRequest，例如使用转换（如 CircleCropTransformation）。

适用边界 · 注意事项

• 性能敏感区域（如 LazyColumn / LazyRow）不要用 SubcomposeAsyncImage。
• 除非确实需要一个 Painter（Canvas、Icon 等）或需手动观察加载状态，否则不要用 rememberAsyncImagePainter，它会默认按原始尺寸加载。