android-compose

android-compose

用途

此技能可帮助 AI 使用 Jetpack Compose 生成和操作 Android UI 代码，重点关注声明式语法，以高效构建响应式界面。可用于处理 Android 应用中的 UI 组件、状态管理和导航。

适用场景

在构建或重构需要现代 UI 模式的 Android 应用时使用此技能，例如动态列表、适配主题的设计或屏幕导航。新建采用 Material 3 的项目时，或将 XML 布局迁移到 Compose 以提升性能并简化代码时，也可使用此技能。

主要功能

• 使用 @Composable 注解定义可复用的 UI 元素。
• 通过状态提升管理状态，避免重组时出现错误。
• 使用 LazyColumn 高效渲染大型数据集中的列表。
• 使用 Button 和 Scaffold 等 Material 3 组件，实现一致的主题样式。
• 使用 CompositionLocal 访问全局上下文，以便在多个可组合项之间共享数据。
• 使用 navigation-compose 处理多屏应用的导航。

使用模式

构建 UI 时，先在 Activity 或 Fragment 中创建顶层 @Composable 函数。始终将状态提升到父级可组合项，以实现正确的重组。对于列表，将条目放在 LazyColumn 中，以便按需加载内容。使用 MaterialTheme 设置样式，并使用 CompositionLocalProvider 注入值。进行导航时，设置包含可组合目标的 NavHost。

常用命令/API

• 使用 @Composable 注解：导入 androidx.compose.runtime.Composable；使用 @Composable fun MyScreen() { Text("Hello") } 这样的形式标注函数
• 管理状态：使用 remember 和 mutableStateOf，例如 val count by remember { mutableStateOf(0) }
• 懒加载列表：导入 androidx.compose.foundation.lazy.LazyColumn；使用 LazyColumn { items(list) { ItemRow(it) } }
• Material 3：导入 androidx.compose.material3.MaterialTheme；使用 MaterialTheme { Surface { MyContent() } } 包裹 UI
• CompositionLocal：使用 compositionLocalOf 定义，例如 val LocalUser = compositionLocalOf { null }；通过 LocalUser.current 访问
• 导航：在 build.gradle 中添加依赖：implementation "androidx.navigation:navigation-compose:2.5.3"；使用 NavHost(navController) { composable("route") { Screen() } } 进行设置

集成说明

将 Compose 集成到 Android 项目时，在 build.gradle 中添加 Compose BOM：dependencies { implementation platform('androidx.compose:compose-bom:2023.10.01') implementation 'androidx.compose.ui:ui' implementation 'androidx.compose.material3:material3' }。在模块的 build.gradle 中通过 composeOptions { kotlinCompilerExtensionVersion '1.4.7' } 启用 Compose。对于导航，可通过 hilt 或手动依赖注入的方式与 ViewModel 配合使用。如有需要，可使用 $ANDROID_HOME 环境变量设置 SDK 路径，并在脚本中设置 $COMPOSE_VERSION 以使用自定义版本。

错误处理

通过确保状态已提升来处理重组错误；例如，如果可组合项因状态过时而崩溃，可将其包装在一个通过参数传递状态的函数中。常见问题：组合期间进行无效更改——对回调使用 rememberUpdatedState。对于 LazyColumn 中的 IndexOutOfBounds 等错误，请确保在渲染前已加载数据。使用 Log.e("ComposeError", "Message") 记录错误，并在非 UI 代码中使用 try-catch。如果导航失败，请检查 navController 设置和路由；可使用 Android Studio 的 Compose 预览进行调试。

具体使用示例

1. 带状态的简单可组合项：通过编写 @Composable fun Counter() { var count by remember { mutableStateOf(0) } Button(onClick = { count++ }) { Text("$count") } } 创建计数器 UI。然后，从 Activity 中调用它：setContent { Counter() }
2. 使用 LazyColumn 实现导航：设置一个带列表的屏幕：@Composable fun HomeScreen(navController: NavController) { LazyColumn { items(10) { Text("Item $it"); if (it == 5) Button(onClick = { navController.navigate("detail") }) { Text("Go") } } } } 在应用中：NavHost { composable("home") { HomeScreen(navController) } }

图关系

• 相关集群：mobile
• 通过标签关联：compose（例如，链接到其他 UI 技能）、android（例如，与 Android 核心技能集成）、ui（例如，与 Web UI 技能共享模式）、material（例如，与设计系统技能保持一致）
• 依赖项：navigation-compose（用于路由）、material3（用于主题设置）