compose-multiplatform-patterns Skill 为 KMP（Kotlin Multiplatform）项目提供了一套标准化的 Compose UI 架构模式，涵盖状态管理、类型安全导航、平台特定 UI 适配与性能优化等关键环节。通过本指南，你将掌握如何在实际项目中高效激活和运用该 Skill，系统性提升多端 UI 代码的可维护性、可测试性与一致性，充分发挥 AI 编程助手在跨平台开发中的生产力优势。

Everything Claude Code Compose Multiplatform Patterns：KMP 状态管理、导航与平台特定 UI 跨平台最佳实践

在多端（Android/iOS/Desktop/Web）UI 开发中，Compose Multiplatform 已成为主流的跨平台方案。而在 AI 编程助手（如 Claude Code、Codex、Cursor）辅助下，如何让生成的 Compose 代码既具备工程规范、又兼容多端特性？这正是 compose-multiplatform-patterns Skill 解决的核心问题。

本 Skill 集成于 Everything Claude Code 完全指南 体系，专为 KMP 项目打造，涵盖状态管理、导航、主题、性能优化与平台特定 UI 等全流程最佳实践。相比传统“直接生成 Compose 代码”，它通过标准化模式和结构化输出，显著降低多端协作与维护成本，并与 AI Agent/Skill 体系深度协作。

1. 适用场景与激活时机

compose-multiplatform-patterns Skill 通常在以下场景自动激活：

• 你让 Claude 生成或重构 Compose Multiplatform/Jetpack Compose UI 代码
• 需要统一 Android/iOS/Web/Desktop UI 架构，避免平台分叉
• 希望实现高可测、可预览、可复用的 Composable 组件
• 需要类型安全的导航、生命周期安全的状态管理
• 面临性能瓶颈、主题适配或平台特定 UI 问题

Skill 激活后，Claude 会自动采用以下模式输出：

• ViewModel + StateFlow 单一状态对象
• 事件下沉（Event Sink）与 sealed interface 事件流
• 类型安全的 Compose Navigation 路由
• Slot-based 组件 API 设计
• expect/actual 平台适配与性能优化建议

2. 使用流程 Step by Step

Step 1：声明单一状态对象与 ViewModel

Skill 推荐每个界面只维护一个 data class 状态对象，并通过 StateFlow 暴露，保证 Compose 层的可测试性和可预测性。

data class ItemListState(
    val items: List<Item> = emptyList(),
    val isLoading: Boolean = false,
    val error: String? = null,
    val searchQuery: String = ""
)

class ItemListViewModel(
    private val getItems: GetItemsUseCase
) : ViewModel() {
    private val _state = MutableStateFlow(ItemListState())
    val state: StateFlow<ItemListState> = _state.asStateFlow()

    fun onSearch(query: String) {
        _state.update { it.copy(searchQuery = query) }
        loadItems(query)
    }
    // ...省略
}

对比不用该 Skill 的常见问题：

• 多 mutableStateOf 变量导致状态分散、难以追踪
• ViewModel 生命周期不安全，易内存泄漏

Step 2：Compose 层收集状态并解耦 UI

使用 collectAsStateWithLifecycle() 自动感知生命周期，防止内存泄漏和重复渲染。

@Composable
fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
    val state by viewModel.state.collectAsStateWithLifecycle()
    ItemListContent(
        state = state,
        onSearch = viewModel::onSearch
    )
}

优势：

• UI 纯函数化，易于预览和单元测试
• 业务逻辑与 UI 解耦

Step 3：事件下沉（Event Sink Pattern）

对于复杂交互，Skill 推荐用 sealed interface 事件流代替多个 callback，提升可维护性和扩展性。

sealed interface ItemListEvent {
    data class Search(val query: String) : ItemListEvent
    data class Delete(val itemId: String) : ItemListEvent
    data object Refresh : ItemListEvent
}

fun onEvent(event: ItemListEvent) { /* ... */ }

ItemListContent(
    state = state,
    onEvent = viewModel::onEvent
)

效果：

• 所有事件归一，易于追踪和测试
• 支持复杂交互和 Undo/Redo 扩展

Step 4：类型安全导航与对话框路由

Skill 自动生成 @Serializable 路由对象，避免字符串拼接和参数遗漏，支持 Compose Navigation 2.8+。

@Serializable data object HomeRoute
@Serializable data class DetailRoute(val id: String)

@Composable
fun AppNavHost(navController: NavHostController = rememberNavController()) {
    NavHost(navController, startDestination = HomeRoute) {
        composable<HomeRoute> { /* ... */ }
        composable<DetailRoute> { backStackEntry ->
            val route = backStackEntry.toRoute<DetailRoute>()
            DetailScreen(id = route.id)
        }
    }
}

对比不用该 Skill：

• 字符串路由易出错，参数传递混乱
• 对话框/底部弹窗用 imperative show/hide，难以统一管理

Step 5：设计 Slot-based 组件与 Modifier 顺序

Skill 推荐所有可复用组件用 slot 参数（header/content/actions），提升灵活性，并规范 Modifier 顺序，避免布局/交互 bug。

@Composable
fun AppCard(
    header: @Composable () -> Unit = {},
    content: @Composable ColumnScope.() -> Unit,
    actions: @Composable RowScope.() -> Unit = {}
) { /* ... */ }

Modifier 顺序建议：

Text(
    text = "Hello",
    modifier = Modifier
        .padding(16.dp)          // 1. Layout
        .clip(RoundedCornerShape(8.dp))  // 2. Shape
        .background(Color.White) // 3. Drawing
        .clickable { }           // 4. Interaction
)

Step 6：平台特定 UI 适配（expect/actual）

Skill 自动生成 expect/actual 结构，保证平台差异最小化，Android/iOS/Web 共享主逻辑，仅在必要时分支。

// commonMain
@Composable
expect fun PlatformStatusBar(darkIcons: Boolean)

// androidMain
@Composable
actual fun PlatformStatusBar(darkIcons: Boolean) { /* ... */ }

Step 7：性能优化与主题适配

• 推荐用 @Stable/@Immutable 标记数据类型，减少不必要的重组
• 列表渲染强制要求 key，避免动画和状态错乱
• 动态主题适配 Material 3，自动检测系统暗色/亮色

@Immutable
data class ItemUiModel(/* ... */)

3. 输出示例与预期结果

Skill 触发后，AI 输出将自动包含：

• 完整的 ViewModel + 状态对象 + 事件流代码
• 类型安全的导航与对话框路由
• Slot-based 组件与 Modifier 顺序注释
• 平台 expect/actual 适配代码
• 性能与主题优化建议

示例输出片段：

// ViewModel + StateFlow
class ItemListViewModel : ViewModel() { /* ... */ }

// Composable 层
@Composable
fun ItemListScreen(/* ... */) { /* ... */ }

// 类型安全路由
@Serializable data object HomeRoute

4. 常见配套 Agent 与 Skill 协作

• 与 android-clean-architecture Skill 协作，自动生成分层结构（domain/data/ui）
• 配合 kotlin-coroutines-flows Skill，提升异步流处理与生命周期安全
• 可与 kotlin-reviewer Agent 联动，自动审查生成代码的架构与协程安全性
• 结合 code-reviewer Agent 做跨端 UI 质量审查

5. 反模式与注意事项

• 避免在 ViewModel 直接用 mutableStateOf，统一用 StateFlow 并在 Compose 层用 collectAsStateWithLifecycle
• 不要把 NavController 传递到深层 composable，统一用事件回调
• 重计算/重分配操作放到 ViewModel 或 remember {}，避免在 Composable 直接执行
• 避免在 Composable 参数中创建新对象，防止无谓重组

更多跨平台架构与协作模式可参考 Everything Claude Code 快速上手指南。

---

FAQ

Q: compose-multiplatform-patterns Skill 适合哪些项目？
A: 适用于所有基于 Compose Multiplatform 或 Jetpack Compose 的 KMP 项目，尤其是需要统一多端 UI 架构和提升可维护性的团队。

Q: Skill 输出和普通 AI 代码生成有何区别？
A: Skill 输出严格遵循最佳实践模板，自动覆盖状态管理、导航、平台适配与性能优化，保证代码结构一致、易维护，远优于零散的 AI 代码片段。

Q: 如何与其他 Claude Code Agent/Skill 组合使用？
A: 推荐与 android-clean-architecture、kotlin-coroutines-flows 等 Skill 及 kotlin-reviewer、code-reviewer Agent 协作，实现从架构设计到代码审查的全流程自动化。

---