compose-multiplatform-patterns

Compose Multiplatform 模式

使用 Compose Multiplatform 和 Jetpack Compose 在 Android、iOS、Desktop 和 Web 上建構共用 UI 的模式。涵蓋狀態管理、導航、主題設定和效能。

何時啟用

• 建構 Compose UI（Jetpack Compose 或 Compose Multiplatform）
• 使用 ViewModel 和 Compose 狀態管理 UI 狀態
• 在 KMP 或 Android 專案中實作導航
• 設計可重複使用的可組合項和設計系統
• 最佳化重組和渲染效能

狀態管理

ViewModel + 單一狀態物件

使用單一 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)
    }

    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) } }
            )
        }
    }
}

在 Compose 中收集狀態

@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
) {
    // 無狀態的可組合項 — 易於預覽和測試
}

Event Sink 模式

對於複雜的螢幕，使用 sealed interface 來表示事件，而不是多個回呼 lambda：

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)
    }
}

// 在可組合項中 — 使用單一 lambda 取代多個
ItemListContent(
    state = state,
    onEvent = viewModel::onEvent
)

導航

型別安全導航（Compose Navigation 2.8+）

將路由定義為 @Serializable 物件：

@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() 和疊加模式，而不是命令式顯示/隱藏：

NavHost(navController, startDestination = HomeRoute) {
    composable<HomeRoute> { /* ... */ }
    dialog<ConfirmDeleteRoute> { backStackEntry ->
        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
        ConfirmDeleteDialog(
            itemId = route.itemId,
            onConfirm = { navController.popBackStack() },
            onDismiss = { navController.popBackStack() }
        )
    }
}

可組合項設計

基於插槽的 API

使用插槽參數設計可組合項以獲得靈活性：

@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 順序

Modifier 的順序很重要 — 按以下順序套用：

Text(
    text = "Hello",
    modifier = Modifier
        .padding(16.dp)          // 1. 佈局 (padding, size)
        .clip(RoundedCornerShape(8.dp))  // 2. 形狀
        .background(Color.White) // 3. 繪製 (background, border)
        .clickable { }           // 4. 互動
)

KMP 平台特定 UI

expect/actual 用於平台可組合項

// 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 處理
}

效能

穩定型別以實現可跳過重組

當所有屬性都穩定時，將類別標記為 @Stable 或 @Immutable：

@Immutable
data class ItemUiModel(
    val id: String,
    val title: String,
    val description: String,
    val progress: Float
)

正確使用 key() 和 Lazy List

LazyColumn {
    items(
        items = items,
        key = { it.id }  // 穩定的鍵啟用項目重用和動畫
    ) { item ->
        ItemRow(item = item)
    }
}

使用 derivedStateOf 延遲讀取

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

避免在重組中分配記憶體

// 不好 — 每次重組都會建立新的 lambda 和 list
items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }

// 好 — 為每個項目設定鍵值，以便回呼始終附加到正確的行
val activeItems = remember(items) { items.filter { it.isActive } }
activeItems.forEach { item ->
    key(item.id) {
        ActiveItem(item, onClick = { handle(item) })
    }
}

主題設定

Material 3 動態主題

@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)
}

應避免的反模式

• 在 ViewModel 中使用 mutableStateOf，而 MutableStateFlow 搭配 collectAsStateWithLifecycle 對生命週期更安全
• 將 NavController 深入傳遞給可組合項 — 改為傳遞 lambda 回呼
• 在 @Composable 函式中進行大量計算 — 移至 ViewModel 或 remember {}
• 使用 LaunchedEffect(Unit) 作為 ViewModel 初始化的替代方案 — 在某些設定中，它會在配置變更時重新執行
• 在可組合項參數中建立新的物件實例 — 會導致不必要的重組

參考資料

請參閱技能：android-clean-architecture 以了解模組結構和分層。 請參閱技能：kotlin-coroutines-flows 以了解協程和 Flow 模式。