android-native-ui

Android 原生 UI

围绕平台约定构建和审查 Android 界面：Compose 语义、感知生命周期的状态、自适应窗口、Material/系统集成、返回导航和无障碍功能，而不是 Web ARIA 或仅追求像素级一致。

确定 UI 边界

梳理 Android Views 与 Compose、Material 3/自定义设计系统、最低 SDK、导航库、状态持有者，以及项目是仅面向 Android 还是使用 Compose Multiplatform。

对于 Compose Multiplatform，将可移植 UI 放在 commonMain 中；将 Context、权限、返回处理和窗口 API 等 Android API 隔离在平台边界处。分别验证每个已发布目标平台。

获取最新的平台指南

在提供或实现可能因 Android/Compose/Kotlin 版本而异的 API、行为、Material 约定、工具或验证方案之前，先搜索当前的 Android 一手资料：developer.android.com、AndroidX 发行说明，以及相关的 Kotlin 文档。建议 API 之前，先检查项目的 SDK、Compose BOM/库版本，以及已发布的 Compose Multiplatform 目标平台。此处示例阐述的是持久适用的约定，不能替代针对具体版本的文档。

状态、副作用和组件 API

仅在需要控制状态的调用方层级提升状态。将持久的屏幕状态与一次性事件分开建模。在 Android 上使用生命周期感知方式收集 flow，并使用 LaunchedEffect、DisposableEffect 或其他显式副作用来执行命令式操作，而不是在可组合函数体内执行。

@Composable
fun SaveButton(
    enabled: Boolean,
    onSave: () -> Unit,
    modifier: Modifier = Modifier,
) {
    Button(
        onClick = onSave,
        enabled = enabled,
        modifier = modifier,
    ) {
        Text("Save")
    }
}

可复用的可组合函数应在最外层提供 Modifier，保留原生控件语义；如果状态模型或插槽表达得更清楚，就避免不断增加布尔值/基本类型参数。谨慎检查修饰符顺序：命中区域、裁剪、内边距、视觉反馈和语义都可能随顺序变化。

Compose 性能和动效

组合、布局和绘制是不同阶段。除非能证明反馈循环安全，否则不要编写由布局推导出的状态并让同级节点在组合期间读取。避免在频繁执行的可组合函数体内进行开销大的分配或集合操作；在惰性集合中使用稳定键。在能够实现预期效果的前提下，尽可能晚地读取动画、滚动和手势状态。

动画应由状态驱动，在交互需要时可取消，并且在 Android 的动画时长缩放被调低或关闭时仍可使用。统计动画或读取最终状态前，应先等待可见完成条件或语义完成条件。

无障碍和自适应

Compose 使用语义树，而非 ARIA。测试内容描述、角色、状态描述、自定义操作、遍历顺序、合并语义、焦点、TalkBack、触控目标和禁用状态。只有在内容纯属装饰时，contentDescription = null 才是正确的。

根据窗口大小类别和可用空间进行适配，而不是依赖设备标签。在相关场景下测试紧凑和展开窗口、大字体缩放、深色主题、屏幕挖孔/内边距、键盘、布局方向，以及预测性/系统返回。

Icon(
    imageVector = Icons.Default.Star,
    contentDescription = null, // decorative beside visible text
)

在对渲染后的 Android 界面作出判断前，请先阅读 references/android-verification.md。其中包含最低证据流程和基于语义的示例。

推荐 / 不推荐

推荐	不推荐
采用 Material/原生控件语义，并进行有意识的主题定制	使用会丢失角色、状态或键盘/无障碍行为的可点击布局
使用不可变 UI 状态和生命周期感知的状态收集	在组合期间执行副作用或可变事件处理
使用稳定的惰性集合键，并在合适的阶段读取状态	使用索引作为键，以及组合/布局反馈循环
结合语义测试与渲染检查	仅凭截图判断无障碍功能或状态
根据窗口大小进行适配	将仅适用于手机的布局拉伸到平板、折叠设备和桌面设备上