1. Jetpack Compose组件开发背景与需求解析在移动端UI开发领域Material Design组件库一直是Android开发者的重要工具。随着Jetpack Compose的普及传统View体系下的组件正在被重新设计和实现。ChipItemWithTwoLinesCard这种复合组件在实际业务场景中非常常见——它结合了Chip的紧凑性和卡片容器的信息承载能力特别适合用于展示带有分类标签的多行信息项。我在多个电商类App项目中都遇到过类似需求商品列表项需要同时展示商品标签如新品、促销、主标题、副标题以及辅助信息。传统方案要么使用多个View组合要么自定义View实现都存在维护成本高、样式不统一的问题。Compose的声明式特性让这类复合组件的开发变得直观且高效。2. 组件API设计规范与实现思路2.1 组件属性定义原则一个规范的Compose组件API应该遵循以下设计原则原子性每个属性只控制一个视觉或行为特征可组合性属性之间应该尽可能解耦默认值合理提供业务场景中最常用的默认配置类型安全充分利用Kotlin的类型系统对于ChipItemWithTwoLinesCard我们定义的核心属性包括Composable fun ChipItemWithTwoLinesCard( chipText: String, chipIcon: Painter? null, primaryText: String, secondaryText: String? null, onClick: () - Unit {}, modifier: Modifier Modifier, colors: ChipItemColors ChipItemColors.default(), elevation: CardElevation CardDefaults.elevatedCardElevation(), shape: Shape MaterialTheme.shapes.medium )2.2 状态管理与交互设计组件需要处理多种交互状态点击效果Ripple悬停/聚焦状态桌面端场景禁用状态我们通过组合Material现有的交互修饰符来实现Modifier .clickable( interactionSource remember { MutableInteractionSource() }, indication LocalIndication.current, onClick onClick ) .hoverable(interactionSource interactionSource)3. 样式系统与主题适配实现3.1 颜色系统封装为保持样式一致性我们封装颜色配置类class ChipItemColors( val chipBackgroundColor: Color, val chipContentColor: Color, val textPrimaryColor: Color, val textSecondaryColor: Color, val containerColor: Color ) { companion object { Composable fun default() ChipItemColors( chipBackgroundColor MaterialTheme.colorScheme.primaryContainer, chipContentColor MaterialTheme.colorScheme.onPrimaryContainer, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surface ) } }3.2 文字样式配置遵循Material Typography系统但提供适配合适的文本样式val primaryTextStyle MaterialTheme.typography.titleMedium.copy( color colors.textPrimaryColor ) val secondaryTextStyle MaterialTheme.typography.bodyMedium.copy( color colors.textSecondaryColor )4. 布局结构与测量优化4.1 组件层级结构组件的整体布局采用以下结构Card ├─ Column (主内容区域) │ ├─ Row (Chip 主文本) │ └─ Text (副文本) └─ Ripple效果层具体实现使用Compose的基础布局Card( modifier modifier, elevation elevation, shape shape, colors CardDefaults.cardColors( containerColor colors.containerColor ) ) { Column( modifier Modifier.padding(16.dp) ) { Row(verticalAlignment Alignment.CenterVertically) { Chip( text chipText, icon chipIcon, colors ChipDefaults.assistChipColors( containerColor colors.chipBackgroundColor, labelColor colors.chipContentColor, iconContentColor colors.chipContentColor ) ) Spacer(Modifier.width(8.dp)) Text( text primaryText, style primaryTextStyle, modifier Modifier.weight(1f) ) } secondaryText?.let { Text( text it, style secondaryTextStyle, modifier Modifier.padding(top 4.dp) ) } } }4.2 性能优化要点避免重组使用derivedStateOf处理依赖多个状态的计算合理使用remember缓存计算结果和对象实例内容测量优化对动态内容使用SubcomposeLayout延迟测量5. 完整实现与API文档5.1 组件完整代码/** * 带分类标签的双行卡片项 * * param chipText 标签文本 * param chipIcon 标签图标可选 * param primaryText 主文本 * param secondaryText 副文本可选 * param onClick 点击回调 * param modifier 修饰符 * param colors 颜色配置 * param elevation 卡片阴影 * param shape 卡片形状 */ Composable fun ChipItemWithTwoLinesCard( chipText: String, chipIcon: Painter? null, primaryText: String, secondaryText: String? null, onClick: () - Unit {}, modifier: Modifier Modifier, colors: ChipItemColors ChipItemColors.default(), elevation: CardElevation CardDefaults.elevatedCardElevation(), shape: Shape MaterialTheme.shapes.medium ) { val interactionSource remember { MutableInteractionSource() } Card( modifier modifier .clickable( interactionSource interactionSource, indication LocalIndication.current, onClick onClick ) .hoverable(interactionSource), elevation elevation, shape shape, colors CardDefaults.cardColors( containerColor colors.containerColor ) ) { Column( modifier Modifier.padding(16.dp) ) { Row( verticalAlignment Alignment.CenterVertically, modifier Modifier.fillMaxWidth() ) { Chip( text chipText, icon chipIcon, colors ChipDefaults.assistChipColors( containerColor colors.chipBackgroundColor, labelColor colors.chipContentColor, iconContentColor colors.chipContentColor ) ) Spacer(Modifier.width(8.dp)) Text( text primaryText, style MaterialTheme.typography.titleMedium.copy( color colors.textPrimaryColor ), modifier Modifier.weight(1f) ) } secondaryText?.let { Text( text it, style MaterialTheme.typography.bodyMedium.copy( color colors.textSecondaryColor ), modifier Modifier.padding(top 4.dp) ) } } } } /** * 卡片项颜色配置 */ class ChipItemColors( val chipBackgroundColor: Color, val chipContentColor: Color, val textPrimaryColor: Color, val textSecondaryColor: Color, val containerColor: Color ) { companion object { Composable fun default() ChipItemColors( chipBackgroundColor MaterialTheme.colorScheme.primaryContainer, chipContentColor MaterialTheme.colorScheme.onPrimaryContainer, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surface ) } }5.2 使用示例基础用法ChipItemWithTwoLinesCard( chipText 新品, primaryText 高端无线耳机, secondaryText 限时特惠 ¥399, onClick { navigateToDetail() } )完整配置ChipItemWithTwoLinesCard( chipText 热销, chipIcon painterResource(R.drawable.ic_hot), primaryText 智能手表Pro, secondaryText 累计销量10万, colors ChipItemColors( chipBackgroundColor Color.Red.copy(alpha 0.2f), chipContentColor Color.Red, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surfaceVariant ), elevation CardDefaults.cardElevation(defaultElevation 8.dp), modifier Modifier.padding(8.dp) )6. 测试与问题排查6.1 单元测试要点内容断言验证文本是否正确显示交互测试模拟点击事件样式测试验证不同主题下的颜色应用Test fun displaysPrimaryText() { composeTestRule.setContent { ChipItemWithTwoLinesCard( chipText 标签, primaryText 主标题 ) } composeTestRule.onNodeWithText(主标题).assertExists() }6.2 常见问题解决文本溢出方案为Text添加maxLines和overflow参数建议主文本1行副文本2行性能问题现象列表滚动卡顿解决确保没有在组合函数中进行耗时操作主题不生效检查是否在正确的MaterialTheme上下文中使用验证使用LocalContext.current.theme调试7. 组件扩展与变体7.1 支持尾部操作按钮扩展API添加trailingContent参数fun ChipItemWithTwoLinesCard( // 原有参数... trailingContent: Composable (() - Unit)? null ) { // 在Row布局中添加 trailingContent?.invoke() }7.2 加载状态处理添加加载状态UIfun ChipItemWithTwoLinesCard( // 原有参数... isLoading: Boolean false, loadingPlaceholder: Composable (() - Unit)? null ) { if (isLoading) { loadingPlaceholder?.invoke() ?: DefaultLoadingPlaceholder() } else { // 正常内容 } }在实际项目中使用时建议根据具体业务需求对组件进行适当扩展。我在电商项目中的经验是这类组件通常会演化出多个变体最好的做法是保持核心功能稳定通过Slot API内容插槽来支持扩展需求。 Jetpack Compose实现Material Design双行卡片组件开发
1. Jetpack Compose组件开发背景与需求解析在移动端UI开发领域Material Design组件库一直是Android开发者的重要工具。随着Jetpack Compose的普及传统View体系下的组件正在被重新设计和实现。ChipItemWithTwoLinesCard这种复合组件在实际业务场景中非常常见——它结合了Chip的紧凑性和卡片容器的信息承载能力特别适合用于展示带有分类标签的多行信息项。我在多个电商类App项目中都遇到过类似需求商品列表项需要同时展示商品标签如新品、促销、主标题、副标题以及辅助信息。传统方案要么使用多个View组合要么自定义View实现都存在维护成本高、样式不统一的问题。Compose的声明式特性让这类复合组件的开发变得直观且高效。2. 组件API设计规范与实现思路2.1 组件属性定义原则一个规范的Compose组件API应该遵循以下设计原则原子性每个属性只控制一个视觉或行为特征可组合性属性之间应该尽可能解耦默认值合理提供业务场景中最常用的默认配置类型安全充分利用Kotlin的类型系统对于ChipItemWithTwoLinesCard我们定义的核心属性包括Composable fun ChipItemWithTwoLinesCard( chipText: String, chipIcon: Painter? null, primaryText: String, secondaryText: String? null, onClick: () - Unit {}, modifier: Modifier Modifier, colors: ChipItemColors ChipItemColors.default(), elevation: CardElevation CardDefaults.elevatedCardElevation(), shape: Shape MaterialTheme.shapes.medium )2.2 状态管理与交互设计组件需要处理多种交互状态点击效果Ripple悬停/聚焦状态桌面端场景禁用状态我们通过组合Material现有的交互修饰符来实现Modifier .clickable( interactionSource remember { MutableInteractionSource() }, indication LocalIndication.current, onClick onClick ) .hoverable(interactionSource interactionSource)3. 样式系统与主题适配实现3.1 颜色系统封装为保持样式一致性我们封装颜色配置类class ChipItemColors( val chipBackgroundColor: Color, val chipContentColor: Color, val textPrimaryColor: Color, val textSecondaryColor: Color, val containerColor: Color ) { companion object { Composable fun default() ChipItemColors( chipBackgroundColor MaterialTheme.colorScheme.primaryContainer, chipContentColor MaterialTheme.colorScheme.onPrimaryContainer, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surface ) } }3.2 文字样式配置遵循Material Typography系统但提供适配合适的文本样式val primaryTextStyle MaterialTheme.typography.titleMedium.copy( color colors.textPrimaryColor ) val secondaryTextStyle MaterialTheme.typography.bodyMedium.copy( color colors.textSecondaryColor )4. 布局结构与测量优化4.1 组件层级结构组件的整体布局采用以下结构Card ├─ Column (主内容区域) │ ├─ Row (Chip 主文本) │ └─ Text (副文本) └─ Ripple效果层具体实现使用Compose的基础布局Card( modifier modifier, elevation elevation, shape shape, colors CardDefaults.cardColors( containerColor colors.containerColor ) ) { Column( modifier Modifier.padding(16.dp) ) { Row(verticalAlignment Alignment.CenterVertically) { Chip( text chipText, icon chipIcon, colors ChipDefaults.assistChipColors( containerColor colors.chipBackgroundColor, labelColor colors.chipContentColor, iconContentColor colors.chipContentColor ) ) Spacer(Modifier.width(8.dp)) Text( text primaryText, style primaryTextStyle, modifier Modifier.weight(1f) ) } secondaryText?.let { Text( text it, style secondaryTextStyle, modifier Modifier.padding(top 4.dp) ) } } }4.2 性能优化要点避免重组使用derivedStateOf处理依赖多个状态的计算合理使用remember缓存计算结果和对象实例内容测量优化对动态内容使用SubcomposeLayout延迟测量5. 完整实现与API文档5.1 组件完整代码/** * 带分类标签的双行卡片项 * * param chipText 标签文本 * param chipIcon 标签图标可选 * param primaryText 主文本 * param secondaryText 副文本可选 * param onClick 点击回调 * param modifier 修饰符 * param colors 颜色配置 * param elevation 卡片阴影 * param shape 卡片形状 */ Composable fun ChipItemWithTwoLinesCard( chipText: String, chipIcon: Painter? null, primaryText: String, secondaryText: String? null, onClick: () - Unit {}, modifier: Modifier Modifier, colors: ChipItemColors ChipItemColors.default(), elevation: CardElevation CardDefaults.elevatedCardElevation(), shape: Shape MaterialTheme.shapes.medium ) { val interactionSource remember { MutableInteractionSource() } Card( modifier modifier .clickable( interactionSource interactionSource, indication LocalIndication.current, onClick onClick ) .hoverable(interactionSource), elevation elevation, shape shape, colors CardDefaults.cardColors( containerColor colors.containerColor ) ) { Column( modifier Modifier.padding(16.dp) ) { Row( verticalAlignment Alignment.CenterVertically, modifier Modifier.fillMaxWidth() ) { Chip( text chipText, icon chipIcon, colors ChipDefaults.assistChipColors( containerColor colors.chipBackgroundColor, labelColor colors.chipContentColor, iconContentColor colors.chipContentColor ) ) Spacer(Modifier.width(8.dp)) Text( text primaryText, style MaterialTheme.typography.titleMedium.copy( color colors.textPrimaryColor ), modifier Modifier.weight(1f) ) } secondaryText?.let { Text( text it, style MaterialTheme.typography.bodyMedium.copy( color colors.textSecondaryColor ), modifier Modifier.padding(top 4.dp) ) } } } } /** * 卡片项颜色配置 */ class ChipItemColors( val chipBackgroundColor: Color, val chipContentColor: Color, val textPrimaryColor: Color, val textSecondaryColor: Color, val containerColor: Color ) { companion object { Composable fun default() ChipItemColors( chipBackgroundColor MaterialTheme.colorScheme.primaryContainer, chipContentColor MaterialTheme.colorScheme.onPrimaryContainer, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surface ) } }5.2 使用示例基础用法ChipItemWithTwoLinesCard( chipText 新品, primaryText 高端无线耳机, secondaryText 限时特惠 ¥399, onClick { navigateToDetail() } )完整配置ChipItemWithTwoLinesCard( chipText 热销, chipIcon painterResource(R.drawable.ic_hot), primaryText 智能手表Pro, secondaryText 累计销量10万, colors ChipItemColors( chipBackgroundColor Color.Red.copy(alpha 0.2f), chipContentColor Color.Red, textPrimaryColor MaterialTheme.colorScheme.onSurface, textSecondaryColor MaterialTheme.colorScheme.onSurfaceVariant, containerColor MaterialTheme.colorScheme.surfaceVariant ), elevation CardDefaults.cardElevation(defaultElevation 8.dp), modifier Modifier.padding(8.dp) )6. 测试与问题排查6.1 单元测试要点内容断言验证文本是否正确显示交互测试模拟点击事件样式测试验证不同主题下的颜色应用Test fun displaysPrimaryText() { composeTestRule.setContent { ChipItemWithTwoLinesCard( chipText 标签, primaryText 主标题 ) } composeTestRule.onNodeWithText(主标题).assertExists() }6.2 常见问题解决文本溢出方案为Text添加maxLines和overflow参数建议主文本1行副文本2行性能问题现象列表滚动卡顿解决确保没有在组合函数中进行耗时操作主题不生效检查是否在正确的MaterialTheme上下文中使用验证使用LocalContext.current.theme调试7. 组件扩展与变体7.1 支持尾部操作按钮扩展API添加trailingContent参数fun ChipItemWithTwoLinesCard( // 原有参数... trailingContent: Composable (() - Unit)? null ) { // 在Row布局中添加 trailingContent?.invoke() }7.2 加载状态处理添加加载状态UIfun ChipItemWithTwoLinesCard( // 原有参数... isLoading: Boolean false, loadingPlaceholder: Composable (() - Unit)? null ) { if (isLoading) { loadingPlaceholder?.invoke() ?: DefaultLoadingPlaceholder() } else { // 正常内容 } }在实际项目中使用时建议根据具体业务需求对组件进行适当扩展。我在电商项目中的经验是这类组件通常会演化出多个变体最好的做法是保持核心功能稳定通过Slot API内容插槽来支持扩展需求。