Jetpack Compose 自定义组件完全指南

news2025/4/12 9:27:39

Jetpack Compose 自定义组件完全指南

Compose 的声明式 UI 范式为创建自定义组件提供了前所未有的灵活性。本指南将带你从基础到高级全面掌握 Compose 自定义组件的开发技巧。

一、自定义组件基础

1.1 基本结构

一个最简单的自定义组件：

@Composable
fun Greeting(name: String) {
    Text(text = "Hello, $name!")
}

1.2 组件参数设计原则

明确职责：每个组件应只做一件事
合理的默认值：为非必要参数提供默认值
命名规范：使用描述性名称，遵循 Kotlin 惯例

@Composable
fun CustomButton(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    icon: @Composable (() -> Unit)? = null
) {
    // 实现
}

二、布局与样式

2.1 自定义布局

使用 Layout 可创建完全自定义的布局：

@Composable
fun CustomLayout(
    modifier: Modifier = Modifier,
    content: @Composable () -> Unit
) {
    Layout(
        modifier = modifier,
        content = content
    ) { measurables, constraints ->
        // 测量和布局逻辑
        val placeables = measurables.map { it.measure(constraints) }
        layout(constraints.maxWidth, constraints.maxHeight) {
            var yPos = 0
            placeables.forEach { placeable ->
                placeable.placeRelative(x = 0, y = yPos)
                yPos += placeable.height
            }
        }
    }
}

2.2 样式与主题

使用 MaterialTheme 实现主题化：

@Composable
fun ThemedComponent() {
    val colors = MaterialTheme.colorScheme
    Box(
        modifier = Modifier
            .background(colors.primary)
            .padding(16.dp)
    ) {
        Text("主题化组件", color = colors.onPrimary)
    }
}

创建自定义主题系统：

object CustomTheme {
    val colors: CustomColors
        @Composable
        get() = LocalCustomColors.current
}

@Composable
fun CustomTheme(
    colors: CustomColors = lightCustomColors(),
    content: @Composable () -> Unit
) {
    CompositionLocalProvider(
        LocalCustomColors provides colors,
        content = content
    )
}

三、状态管理

3.1 组件内部状态

@Composable
fun Counter() {
    var count by remember { mutableStateOf(0) }
    Button(onClick = { count++ }) {
        Text("Clicked $count times")
    }
}

3.2 状态提升

@Composable
fun Counter(
    count: Int,
    onIncrement: () -> Unit,
    modifier: Modifier = Modifier
) {
    Button(
        onClick = onIncrement,
        modifier = modifier
    ) {
        Text("Clicked $count times")
    }
}

3.3 高级状态管理

@Stable
class CustomState(
    initialValue: Int
) {
    var value by mutableStateOf(initialValue)
    fun increment() { value++ }
}

@Composable
fun rememberCustomState(initial: Int = 0) = remember {
    CustomState(initial)
}

四、交互与动画

4.1 手势交互

@Composable
fun DraggableBox() {
    var offsetX by remember { mutableStateOf(0f) }
    Box(
        modifier = Modifier
            .offset { IntOffset(offsetX.roundToInt(), 0) }
            .pointerInput(Unit) {
                detectDragGestures { change, dragAmount ->
                    offsetX += dragAmount.x
                }
            }
            .size(100.dp)
            .background(Color.Blue)
    )
}

4.2 动画效果

@Composable
fun AnimatedComponent(visible: Boolean) {
    val alpha by animateFloatAsState(
        targetValue = if (visible) 1f else 0f,
        animationSpec = tween(durationMillis = 300)
    )
    
    Box(
        modifier = Modifier
            .alpha(alpha)
            .size(100.dp)
            .background(Color.Red)
    )
}

五、高级技巧

5.1 性能优化

@Composable
fun OptimizedList(items: List<String>) {
    LazyColumn {
        items(items, key = { it }) { item ->
            Text(item)
        }
    }
}

5.2 跨平台适配

@Composable
fun PlatformSpecificComponent() {
    val configuration = LocalConfiguration.current
    val isWideScreen = configuration.screenWidthDp >= 600
    
    if (isWideScreen) {
        WideScreenLayout()
    } else {
        MobileLayout()
    }
}

5.3 测试策略

@Test
fun testCustomComponent() {
    composeTestRule.setContent {
        CustomButton(text = "Test", onClick = {})
    }
    
    composeTestRule.onNodeWithText("Test").assertIsDisplayed()
}

六、实战案例

6.1 自定义下拉刷新

@Composable
fun PullToRefreshLayout(
    refreshing: Boolean,
    onRefresh: () -> Unit,
    content: @Composable () -> Unit
) {
    Box(modifier = Modifier.pointerInput(Unit) {
        // 手势检测逻辑
    }) {
        content()
        if (refreshing) {
            CircularProgressIndicator()
        }
    }
}

6.2 复杂图表组件

@Composable
fun LineChart(
    dataPoints: List<Float>,
    modifier: Modifier = Modifier
) {
    Canvas(modifier = modifier) {
        // 自定义绘制逻辑
    }
}