Back to Details

compose-multiplatform-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Compose Multiplatform Patterns

Compose Multiplatform 模式

Patterns for building shared UI across Android, iOS, Desktop, and Web using Compose Multiplatform and Jetpack Compose. Covers state management, navigation, theming, and performance.
本内容介绍如何使用Compose Multiplatform和Jetpack Compose为Android、iOS、桌面端及Web端构建共享UI的模式，涵盖状态管理、导航、主题设置与性能优化。

When to Activate

适用场景

  • Building Compose UI (Jetpack Compose or Compose Multiplatform)
  • Managing UI state with ViewModels and Compose state
  • Implementing navigation in KMP or Android projects
  • Designing reusable composables and design systems
  • Optimizing recomposition and rendering performance
  • 构建Compose UI（Jetpack Compose或Compose Multiplatform）
  • 使用ViewModel与Compose state管理UI状态
  • 在KMP或Android项目中实现导航功能
  • 设计可复用的composable组件与设计系统
  • 优化重组与渲染性能

State Management

状态管理

ViewModel + Single State Object

ViewModel + 单一状态对象

Use a single data class for screen state. Expose it as 
StateFlow
and collect in Compose:
kotlin
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)
    }

    private fun loadItems(query: String) {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }
            getItems(query).fold(
                onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } },
                onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } }
            )
        }
    }
}
使用单个数据类存储屏幕状态，以
StateFlow
暴露并在Compose中收集：
kotlin
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)
    }

    private fun loadItems(query: String) {
        viewModelScope.launch {
            _state.update { it.copy(isLoading = true) }
            getItems(query).fold(
                onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } },
                onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } }
            )
        }
    }
}

Collecting State in Compose

在Compose中收集状态

kotlin
@Composable
fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    ItemListContent(
        state = state,
        onSearch = viewModel::onSearch
    )
}

@Composable
private fun ItemListContent(
    state: ItemListState,
    onSearch: (String) -> Unit
) {
    // Stateless composable — easy to preview and test
}
kotlin
@Composable
fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    ItemListContent(
        state = state,
        onSearch = viewModel::onSearch
    )
}

@Composable
private fun ItemListContent(
    state: ItemListState,
    onSearch: (String) -> Unit
) {
    // 无状态composable组件——便于预览与测试
}

Event Sink Pattern

事件接收器模式

For complex screens, use a sealed interface for events instead of multiple callback lambdas:
kotlin
sealed interface ItemListEvent {
    data class Search(val query: String) : ItemListEvent
    data class Delete(val itemId: String) : ItemListEvent
    data object Refresh : ItemListEvent
}

// In ViewModel
fun onEvent(event: ItemListEvent) {
    when (event) {
        is ItemListEvent.Search -> onSearch(event.query)
        is ItemListEvent.Delete -> deleteItem(event.itemId)
        is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery)
    }
}

// In Composable — single lambda instead of many
ItemListContent(
    state = state,
    onEvent = viewModel::onEvent
)
对于复杂屏幕，使用密封接口定义事件，替代多个回调lambda：
kotlin
sealed interface ItemListEvent {
    data class Search(val query: String) : ItemListEvent
    data class Delete(val itemId: String) : ItemListEvent
    data object Refresh : ItemListEvent
}

// 在ViewModel中
fun onEvent(event: ItemListEvent) {
    when (event) {
        is ItemListEvent.Search -> onSearch(event.query)
        is ItemListEvent.Delete -> deleteItem(event.itemId)
        is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery)
    }
}

// 在Composable中——用单个lambda替代多个回调
ItemListContent(
    state = state,
    onEvent = viewModel::onEvent
)

Navigation

导航

Type-Safe Navigation (Compose Navigation 2.8+)

类型安全导航（Compose Navigation 2.8+）

Define routes as 
@Serializable
objects:
kotlin
@Serializable data object HomeRoute
@Serializable data class DetailRoute(val id: String)
@Serializable data object SettingsRoute

@Composable
fun AppNavHost(navController: NavHostController = rememberNavController()) {
    NavHost(navController, startDestination = HomeRoute) {
        composable<HomeRoute> {
            HomeScreen(onNavigateToDetail = { id -> navController.navigate(DetailRoute(id)) })
        }
        composable<DetailRoute> { backStackEntry ->
            val route = backStackEntry.toRoute<DetailRoute>()
            DetailScreen(id = route.id)
        }
        composable<SettingsRoute> { SettingsScreen() }
    }
}
将路由定义为
@Serializable
对象：
kotlin
@Serializable data object HomeRoute
@Serializable data class DetailRoute(val id: String)
@Serializable data object SettingsRoute

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

Dialog and Bottom Sheet Navigation

对话框与底部弹窗导航

Use 
dialog()
and overlay patterns instead of imperative show/hide:
kotlin
NavHost(navController, startDestination = HomeRoute) {
    composable<HomeRoute> { /* ... */ }
    dialog<ConfirmDeleteRoute> { backStackEntry ->
        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
        ConfirmDeleteDialog(
            itemId = route.itemId,
            onConfirm = { navController.popBackStack() },
            onDismiss = { navController.popBackStack() }
        )
    }
}
使用
dialog()
和覆盖模式替代命令式的显示/隐藏：
kotlin
NavHost(navController, startDestination = HomeRoute) {
    composable<HomeRoute> { /* ... */ }
    dialog<ConfirmDeleteRoute> { backStackEntry ->
        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
        ConfirmDeleteDialog(
            itemId = route.itemId,
            onConfirm = { navController.popBackStack() },
            onDismiss = { navController.popBackStack() }
        )
    }
}

Composable Design

Composable组件设计

Slot-Based APIs

基于插槽的API

Design composables with slot parameters for flexibility:
kotlin
@Composable
fun AppCard(
    modifier: Modifier = Modifier,
    header: @Composable () -> Unit = {},
    content: @Composable ColumnScope.() -> Unit,
    actions: @Composable RowScope.() -> Unit = {}
) {
    Card(modifier = modifier) {
        Column {
            header()
            Column(content = content)
            Row(horizontalArrangement = Arrangement.End, content = actions)
        }
    }
}
为composable组件设计插槽参数以提升灵活性：
kotlin
@Composable
fun AppCard(
    modifier: Modifier = Modifier,
    header: @Composable () -> Unit = {},
    content: @Composable ColumnScope.() -> Unit,
    actions: @Composable RowScope.() -> Unit = {}
) {
    Card(modifier = modifier) {
        Column {
            header()
            Column(content = content)
            Row(horizontalArrangement = Arrangement.End, content = actions)
        }
    }
}

Modifier Ordering

Modifier顺序

Modifier order matters — apply in this sequence:
kotlin
Text(
    text = "Hello",
    modifier = Modifier
        .padding(16.dp)          // 1. Layout (padding, size)
        .clip(RoundedCornerShape(8.dp))  // 2. Shape
        .background(Color.White) // 3. Drawing (background, border)
        .clickable { }           // 4. Interaction
)
Modifier的顺序至关重要——请按以下顺序应用：
kotlin
Text(
    text = "Hello",
    modifier = Modifier
        .padding(16.dp)          // 1. 布局（内边距、尺寸）
        .clip(RoundedCornerShape(8.dp))  // 2. 形状
        .background(Color.White) // 3. 绘制（背景、边框）
        .clickable { }           // 4. 交互
)

KMP Platform-Specific UI

KMP平台专属UI

expect/actual for Platform Composables

平台Composable组件的expect/actual用法

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

// androidMain
@Composable
actual fun PlatformStatusBar(darkIcons: Boolean) {
    val systemUiController = rememberSystemUiController()
    SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) }
}

// iosMain
@Composable
actual fun PlatformStatusBar(darkIcons: Boolean) {
    // iOS handles this via UIKit interop or Info.plist
}
kotlin
// commonMain
@Composable
expect fun PlatformStatusBar(darkIcons: Boolean)

// androidMain
@Composable
actual fun PlatformStatusBar(darkIcons: Boolean) {
    val systemUiController = rememberSystemUiController()
    SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) }
}

// iosMain
@Composable
actual fun PlatformStatusBar(darkIcons: Boolean) {
    // iOS通过UIKit交互或Info.plist处理此逻辑
}

Performance

性能优化

Stable Types for Skippable Recomposition

稳定类型实现可跳过重组

Mark classes as 
@Stable
or 
@Immutable
when all properties are stable:
kotlin
@Immutable
data class ItemUiModel(
    val id: String,
    val title: String,
    val description: String,
    val progress: Float
)
当类的所有属性均稳定时，将类标记为
@Stable
或
@Immutable
：
kotlin
@Immutable
data class ItemUiModel(
    val id: String,
    val title: String,
    val description: String,
    val progress: Float
)

Use 
key()
and Lazy Lists Correctly

正确使用
key()
与懒加载列表

kotlin
LazyColumn {
    items(
        items = items,
        key = { it.id }  // Stable keys enable item reuse and animations
    ) { item ->
        ItemRow(item = item)
    }
}
kotlin
LazyColumn {
    items(
        items = items,
        key = { it.id }  // 稳定的key可实现项复用与动画效果
    ) { item ->
        ItemRow(item = item)
    }
}

Defer Reads with 
derivedStateOf

使用
derivedStateOf
延迟读取

kotlin
val listState = rememberLazyListState()
val showScrollToTop by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 5 }
}
kotlin
val listState = rememberLazyListState()
val showScrollToTop by remember {
    derivedStateOf { listState.firstVisibleItemIndex > 5 }
}

Avoid Allocations in Recomposition

避免在重组中分配对象

kotlin
// BAD — new lambda and list every recomposition
items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }

// GOOD — key each item so callbacks stay attached to the right row
val activeItems = remember(items) { items.filter { it.isActive } }
activeItems.forEach { item ->
    key(item.id) {
        ActiveItem(item, onClick = { handle(item) })
    }
}
kotlin
// 不良写法——每次重组都会创建新的lambda与列表
items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }

// 推荐写法——为每个项设置key，使回调与正确的行绑定
val activeItems = remember(items) { items.filter { it.isActive } }
activeItems.forEach { item ->
    key(item.id) {
        ActiveItem(item, onClick = { handle(item) })
    }
}

Theming

主题设置

Material 3 Dynamic Theming

Material 3 动态主题

kotlin
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            if (darkTheme) dynamicDarkColorScheme(LocalContext.current)
            else dynamicLightColorScheme(LocalContext.current)
        }
        darkTheme -> darkColorScheme()
        else -> lightColorScheme()
    }

    MaterialTheme(colorScheme = colorScheme, content = content)
}
kotlin
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            if (darkTheme) dynamicDarkColorScheme(LocalContext.current)
            else dynamicLightColorScheme(LocalContext.current)
        }
        darkTheme -> darkColorScheme()
        else -> lightColorScheme()
    }

    MaterialTheme(colorScheme = colorScheme, content = content)
}

Anti-Patterns to Avoid

需避免的反模式

  • Using 
    mutableStateOf
    in ViewModels when 
    MutableStateFlow
    with 
    collectAsStateWithLifecycle
    is safer for lifecycle
  • Passing 
    NavController
    deep into composables — pass lambda callbacks instead
  • Heavy computation inside 
    @Composable
    functions — move to ViewModel or 
    remember {}
  • Using 
    LaunchedEffect(Unit)
    as a substitute for ViewModel init — it re-runs on configuration change in some setups
  • Creating new object instances in composable parameters — causes unnecessary recomposition
  • 当使用
    MutableStateFlow
    配合
    collectAsStateWithLifecycle
    在生命周期管理上更安全时，仍在ViewModel中使用
    mutableStateOf
  • 将
    NavController
    深层传递到composable组件中——应传递lambda回调替代
  • 在
    @Composable
    函数内执行大量计算——应移至ViewModel或
    remember {}
    中
  • 使用
    LaunchedEffect(Unit)
    替代ViewModel初始化——在某些配置下，它会在配置变更时重新运行
  • 在composable参数中创建新的对象实例——会导致不必要的重组

References

参考资料

See skill: 
android-clean-architecture
for module structure and layering. See skill: 
kotlin-coroutines-flows
for coroutine and Flow patterns.
查看技能：
android-clean-architecture
了解模块结构与分层设计。 查看技能：
kotlin-coroutines-flows
了解协程与Flow模式。