compose-multiplatform-patterns

Patrones de Compose Multiplatform

Patrones para construir UI compartida en Android, iOS, Escritorio y Web usando Compose Multiplatform y Jetpack Compose. Cubre gestión de estado, navegación, tematización y rendimiento.

Cuándo activarlo

• Al construir UI con Compose (Jetpack Compose o Compose Multiplatform)
• Al gestionar estado de UI con ViewModels y estado de Compose
• Al implementar navegación en proyectos KMP o Android
• Al diseñar composables reutilizables y sistemas de diseño
• Al optimizar la recomposición y el rendimiento de renderizado

Gestión de Estado

ViewModel + Objeto de Estado Único

Usa una sola clase de datos para el estado de la pantalla. Exponla como StateFlow y recógela en 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) } }
            )
        }
    }
}

Recolectando Estado en 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
) {
    // Composable sin estado — fácil de previsualizar y probar
}

Patrón de Sumidero de Eventos

Para pantallas complejas, usa una interfaz sellada para eventos en lugar de múltiples lambdas de callback:

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

// En el 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)
    }
}

// En el Composable — una sola lambda en lugar de muchas
ItemListContent(
    state = state,
    onEvent = viewModel::onEvent
)

Navegación

Navegación con Tipos Seguros (Compose Navigation 2.8+)

Define las rutas como objetos @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() }
    }
}

Navegación con Diálogos y Hojas Inferiores

Usa dialog() y patrones de superposición en lugar de mostrar/ocultar imperativo:

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

Diseño de Componibles

APIs Basadas en Slots

Diseña componibles con parámetros de slot para mayor flexibilidad:

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

Orden de los Modifiers

El orden de los modificadores importa — aplícalos en esta secuencia:

Text(
    text = "Hola",
    modifier = Modifier
        .padding(16.dp)          // 1. Diseño (padding, tamaño)
        .clip(RoundedCornerShape(8.dp))  // 2. Forma
        .background(Color.White) // 3. Dibujo (fondo, borde)
        .clickable { }           // 4. Interacción
)

UI Específica de Plataforma en KMP

expect/actual para Componibles de Plataforma

// 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 maneja esto mediante interoperabilidad UIKit o Info.plist
}

Rendimiento

Tipos Estables para Recomposición Omitible

Marca las clases como @Stable o @Immutable cuando todas sus propiedades sean estables:

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

Usa key() y Listas Perezosas Correctamente

LazyColumn {
    items(
        items = items,
        key = { it.id }  // Claves estables permiten reutilización de elementos y animaciones
    ) { item ->
        ItemRow(item = item)
    }
}

Diferir Lecturas con derivedStateOf

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

Evitar Asignaciones en Recomposición

// MAL — nueva lambda y lista en cada recomposición
items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }

// BIEN — asigna cada elemento para que los callbacks permanezcan vinculados a la fila correcta
val activeItems = remember(items) { items.filter { it.isActive } }
activeItems.forEach { item ->
    key(item.id) {
        ActiveItem(item, onClick = { handle(item) })
    }
}

Tematización

Tematización Dinámica con 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)
}

Anti-patrones a Evitar

• Usar mutableStateOf en ViewModels cuando MutableStateFlow con collectAsStateWithLifecycle es más seguro para el ciclo de vida
• Pasar NavController profundamente en los componibles — en su lugar pasa lambdas de callback
• Cómputo pesado dentro de funciones @Composable — muévelo al ViewModel o a remember {}
• Usar LaunchedEffect(Unit) como sustituto de la inicialización del ViewModel — se re-ejecuta en cambios de configuración en algunos contextos
• Crear nuevas instancias de objetos en parámetros de componibles — provoca recomposición innecesaria

Referencias

Consulta el skill: android-clean-architecture para estructura de módulos y capas. Consulta el skill: kotlin-coroutines-flows para patrones de corrutinas y Flows.