用途:把 Jetpack Compose 的 @Preview 作为最廉价的验证回路(编辑后约 1 秒渲染,无需构建、安装、导航),通过结构化 composable 让预览长期可用。
主要能力与用法:预览组件而非整个屏幕;将状态提升,使可预览的 composable 只接收普通参数,把 ViewModel 留在调用点;预览体用应用主题(如 AppTheme { … })包裹;对 fillMaxWidth/fillMaxSize 的组件加 widthDp/heightDp;用 @PreviewParameter 与 PreviewParameterProvider 从单个函数覆盖 loading/content/empty/error/溢出等状态;用可重复的 @Preview 叠加深色模式、字体放大、RTL 等配置,并把标准集合抽取为一个被 @Preview 注解的注解类(multipreview);对图片加载等环境依赖,用 LocalInspectionMode.current 分支绘制占位符。
规则与限制:可预览 composable 不得带 ViewModel、repository、NavController 或 Context 绑定参数;读取 MaterialTheme 的预览体必须包主题;状态必须用 @PreviewParameter 覆盖;填充型组件必须给 widthDp;示例数据要贴近生产模型,模型变更导致预览编译失败是预期行为;禁止在预览体中放 Mockito/MockK 模拟对象,也不要用 LocalInspectionMode 替代状态提升。前置条件:主 classpath 上有 androidx.compose.ui:ui-tooling-preview,debugImplementation("androidx.compose.ui:ui-tooling"),以及启用 Compose 的模块。本技能不覆盖在设备或 CI 中截图(含 HotSwan captureAllPreviews、GitHub Pages 目录)、Paparazzi/Roborazzi 像素差分金图测试和行为 UI 测试,这些属于其他技能。