android-coil-compose

Android Coil Compose

适用场景

• 当请求涉及以下内容时使用此技能：Coil Compose 图像加载、Android Compose 中的 asyncimage、Android 中的 rememberasyncimagepainter。
• 主要目标：在 Jetpack Compose 中使用 Coil，采用 AsyncImage、绘制器变体、尺寸设置和无障碍图像加载模式。
• 如果工作专门涉及 Compose 中的图像加载、占位符、错误状态、尺寸设置或列表性能，请使用此技能。
• 阅读 references/patterns.md，了解 AsyncImage、绘制器和子组合之间的选择指南。
• 阅读 references/scenarios.md，了解列表性能和截图稳定性验证路径。
• 如果工作范围扩大，请移交给以下技能：
• android-compose-foundations
• android-compose-performance

工作流

1. 判断 UI 需要的是简单的图像表面、低级绘制器访问，还是基于插槽的自定义加载状态。
2. 优先使用 AsyncImage，只有当组件确实需要时才改用绘制器 API。
3. 限制尺寸，设置占位符和内容描述，确保图像行为兼具性能与无障碍性；对于绘制器 API，在需要时提供显式尺寸解析器。
4. 在认为实现已完成之前，检查列表渲染、状态变化和视觉回退效果；如果源类型有要求，还要确认远程数据或解码器模块确实存在。
5. 图像管线稳定后，将通用 Compose 布局或更广泛的性能问题移交给相关技能。

注意事项

• 对大多数 Compose 图像表面，优先使用 AsyncImage。
• 尽可能让图像请求的尺寸与实际渲染的 UI 表面相符。
• 提供有意义的无障碍行为：信息性图像使用描述性的 contentDescription，装饰性图像使用 null。
• 除非用户体验确实需要，否则避免在大量滚动的列表中使用依赖大量子组合的图像模式。
• 如果需要直接访问绘制器状态，请记住 rememberAsyncImagePainter 不会自行推断屏幕上的尺寸。

反模式

• 在微小的列表项中加载完整尺寸的远程资源。
• 明明简单的占位符就足够，却到处使用 SubcomposeAsyncImage。
• 将图像加载失败当作无声忽略，不提供任何错误回退。
• 忘记为可操作或信息性图像设置无障碍语义。

审查重点

• API 选择：AsyncImage、rememberAsyncImagePainter 或 SubcomposeAsyncImage。
• 渲染表面的尺寸设置和请求构造是否正确。
• 远程加载的前提条件，例如是否使用了正确的 Coil 网络模块。
• 列表、测试和截图中占位符及错误状态是否稳定。

示例

正常流程

• 场景：构建 Compose 测试夹具，并确认任务看板中能够稳定渲染 AsyncImage 图像表面。
• 命令：bash skills/android-coil-compose/scripts/run_examples.sh

边界情况

• 场景：检查列表单元格，其中占位符、尺寸设置和惰性列表性能都很重要。
• 命令：cd examples/orbittasks-compose && ./gradlew :app:testDebugUnitTest

故障恢复

• 场景：更改占位符或错误状态后，使用适合截图的验证方式重新检查图像表面。
• 命令：cd examples/orbittasks-compose && ./gradlew verifyRoborazziDebug

完成清单

• 默认使用 AsyncImage，除非有充分理由使用更底层的绘制器 API。
• 明确设置尺寸、占位符和错误状态。
• 有意设计无障碍行为。
• 已在 Compose 测试夹具中验证列表和截图行为。

Official References

• https://coil-kt.github.io/coil/compose/
• https://coil-kt.github.io/coil/image_requests/
• https://coil-kt.github.io/coil/network/
• https://developer.android.com/develop/ui/compose/graphics/images/loading
• https://developer.android.com/develop/ui/compose/accessibility