Jetpack Compose UI组件封装(一)

202 阅读8分钟

项目地址:github.com/Peakmain/Co…

文档地址:www.yuque.com/peakmain/al… 《Compose UI组件封装》

1. 添加依赖

How To

  • Step 1. Add the JitPack repository to your build file
    • gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
    • gradle.kts
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
  }
}
  • Step 2. Add the dependency
dependencies {
    implementation("com.github.Peakmain:ComposeUI:+")
}

2. 基础组件

2.1. 顶部应用栏(AppBar)组件

2.1.1. 介绍

TopAppBarCenter 是一个高度定制的顶部应用栏(App Bar)组件,基于 Jetpack Compose 实现。主要特性包括:

  • 标题居中显示,支持自定义标题内容
  • 可配置左侧导航图标(如返回按钮)和右侧操作图标组
  • 支持沉浸式状态栏(透明状态栏,内容延伸到状态栏下方)
  • 动态控制状态栏图标颜色(深色或浅色)
  • 无缝集成 Scaffold,可直接作为其 TopBar 参数使用

2.1.2. 参数

参数名参数类型是否必填默认值说明
title@Composable () -> Unit标题内容(支持任意 Composable 内容,默认居中显示)
modifierModifierModifier布局修饰符,会与组件内部修饰符合并
navigationIcon@Composable (() -> Unit)?null左侧导航图标(如返回按钮),若为 null则不显示
backgroundColorColorMaterialTheme.colors.primarySurface应用栏背景颜色
actions@Composable RowScope.() -> Unit{}右侧操作图标组(可包含多个图标按钮)
isImmersiveBooleanfalse是否启用沉浸式状态栏(透明状态栏,内容向上延伸)
darkIconsBooleanfalse状态栏图标颜色是否为深色(true为黑色,false为白色),仅在 isImmersive=true时生效
content@Composable (PaddingValues) -> Unit页面主体内容(通过 Scaffold插入到应用栏下方)

2.2. 标题组件

2.2.1. 介绍

  • 用于快速实现设计规范中的标题和内文样式。通过预定义的 PkTitleType 密封类(包含大标题、标题、小标题、内文等多种样式),开发者可以快速选择字体大小、字重等属性,保证 UI 一致性。
  • 组件支持自定义颜色、对齐方式、溢出处理等常见文本属性,同时保留与原生 Text 组件的兼容性

2.2.2. 参数说明

参数名参数类型是否必填说明
textString需要显示的文本内容
typePkTitleType标题类型(默认为 BigTitle1),支持选择预定义的标题样式(如大标题、小标题、内文等)
modifierModifier布局修饰符(默认 Modifier),用于调整文本的布局、尺寸、间距等
colorColor文本颜色(默认 0xFF333333
fontStyleFontStyle?字体风格(如斜体 FontStyle.Italic),默认 null表示不设置
textAlignTextAlign?文本对齐方式(如居中 TextAlign.Center),默认 null表示继承父布局对齐
overflowTextOverflow文本溢出处理方式(默认 TextOverflow.Clip),支持 Ellipsis等效果
maxLinesInt文本最大行数(默认无限制 Int.MAX_VALUE
styleTextStyle自定义文本样式(默认 LocalTextStyle.current),可覆盖 type中的部分属性

2.2.3. PkTitleType 类型说明

PkTitleType 是一个密封类,定义了以下预置样式:

类型名称字体大小字重说明
BigTitle124.spW500大标题1(默认类型)
BigTitle222.spW500大标题2
BigTitle318.spW500大标题3
TitleBold116.spW500标题1(加粗)
TitleNormal116.spW400标题1(常规)
TitleBold215.spW500标题2(加粗)
TitleNormal215.spW400标题2(常规)
SmallTitleBold14.spW500小标题(加粗)
SmallTitleNormal14.spW400小标题(常规)
TextBold112.spW500内文1(加粗)
TextNormal112.spW400内文1(常规)
TextBold211.spW500内文2(加粗)
TextNormal211.spW400内文2(常规)

2.2.4. 示例代码

Column(verticalArrangement = Arrangement.spacedBy(8.dp), horizontalAlignment = Alignment.CenterHorizontally) {
    PkTitle("大标题1", PkTitleType.BigTitle1())
    PkTitle("大标题2", PkTitleType.BigTitle2())
    PkTitle("大标题3", PkTitleType.BigTitle3())
    PkDivider(modifier = Modifier.padding(vertical = 10.dp), isHorizontal = true)
    PkTitle("标题1加粗", PkTitleType.TitleBold1())
    PkTitle("标题1常规", PkTitleType.TitleNormal1())
    PkTitle("标题2加粗", PkTitleType.TitleBold2())
    PkTitle("标题2常规", PkTitleType.TitleNormal2())
    PkDivider(modifier = Modifier.padding(vertical = 10.dp), isHorizontal = true)
    PkTitle("小标题加粗", PkTitleType.SmallTitleBold())
    PkTitle("小标题常规", PkTitleType.SmallTitleNormal())
    PkDivider(modifier = Modifier.padding(vertical = 10.dp), isHorizontal = true)
    PkTitle("内文1加粗", PkTitleType.TextBold1())
    PkTitle("内文1正常", PkTitleType.TextNormal1())
    PkTitle("内文2加粗", PkTitleType.TextBold2())
    PkTitle("内文2正常", PkTitleType.TextNormal2())
}

3. 展示组件

3.1. 网格布局

3.1.1. 介绍

GridLayout 是一个基于 Jetpack Compose 的网格布局组件,支持动态生成多行多列的布局结构。通过指定列数 columns,组件会自动计算行数并按顺序填充数据。支持以下特性:

  • 自动填充数据项,不足一行的位置用空白占位
  • 可自定义水平分割线(默认或自定义样式)
  • 灵活的内容渲染逻辑,开发者可完全控制每个网格项的 UI

3.1.2. 参数

参数名参数类型是否必填默认值说明
columnsInt(取值范围 ≥1)每行显示的列数
dataMutableList<E>数据源列表,泛型 E表示数据项类型
isShowHorizontalDividerBooleanfalse是否显示水平分割线(仅在行之间显示)
divider@Composable (() -> Unit)?null自定义分割线组件,若未提供且 isShowHorizontalDivider=true,则使用默认 Divider
content@Composable (Int, E) -> Unit定义每个网格项的内容,参数为数据项索引和对应的数据项 E

3.1.3. 示例代码

GridLayout(
    2,
    data = arrayListOf("111","222","333","444","555"),
) { index,item->
    Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.Center) {
        Text(item, modifier = Modifier.padding(10.dp))
    }
}

3.2. 分割线

3.2.1. PkDivider分割线

3.2.1.1. 介绍
  • 支持设置水平/垂直 虚线或实线分割线
  • PkDashDivider(虚线)和 PkFullDivider(实线)整合类

3.2.1.2. 导入依赖
import com.peakmain.compose.ui.divier.PkDivider
3.2.1.3. 参数
参数名参数类型说明
modifierModifier用于添加额外修饰符的 Modifier。
colorColor分隔线的颜色,默认为 0xFFF1EFE9。
heightDp分隔线的高度,仅在垂直分隔线生效,默认为 28.dp。
thicknessDp分隔线的厚度,仅在非虚线时生效,默认为 1.dp。
startIndentDp分隔线的起始缩进,仅在非虚线时生效,默认为 0.dp。
isHorizontalBoolean是否为水平分隔线,默认为 false。
isDashBoolean是否绘制虚线分隔线,默认为 false。
strokeWidthDp虚线的宽度,仅在绘制虚线时生效,默认为 0.5.dp。
dashLengthDp虚线的线段长度,仅在绘制虚线时生效,默认为 2.dp。
gapLengthDp虚线的间隔长度,仅在绘制虚线时生效,默认为 2.dp。
3.2.1.4. 示例代码
//默认垂直实线
PkDivider()
//水平实线
PkDivider(modifier = Modifier.padding(top = 10.dp), isHorizontal = true)
//垂直虚线
PkDivider(isDash=true)
//水平虚线
PkDivider(modifier = Modifier.padding(top = 10.dp), isHorizontal = true, isDash = true)

3.2.2. PkFullDivider实线分割线

3.2.2.1. 介绍
  • 创建一个水平/垂直实线分隔线组件
3.2.2.2. 导入依赖
import com.peakmain.compose.ui.divier.PkFullDivider
3.2.2.3. 参数
参数名参数类型说明
modifierModifier用于添加额外修饰符的 Modifier。
colorColor分隔线的颜色,默认为 0xFFF1EFE9。
heightDp分隔线的高度,垂直方向生效默认为 28.dp。
thicknessDp分隔线的厚度,默认为 1.dp。
startIndentDp分隔线的起始缩进,默认为 0.dp。
isHorizontalBoolean水平分割线 (true)/ 垂直分割线 (false),默认是 false
3.2.2.4. 示例代码
PkFullDivider(modifier = Modifier.padding(top = 10.dp), isHorizontal = true)

3.2.3. PkDashDivider虚线分割线

3.2.3.1. 介绍
  • 创建一个水平/垂直虚线分隔线组件
3.2.3.2. 导入依赖
import com.peakmain.compose.ui.divier.PkDashDivider
3.2.3.3. 参数
参数名参数类型说明
modifierModifier用于添加额外修饰符的 Modifier。
colorColor分隔线的颜色,默认为 0xFFF1EFE9。
heightDp分隔线的高度,垂直方向生效,默认为 28.dp。
strokeWidthDp虚线的宽度,默认为 0.5.dp。
dashLengthDp虚线的长度,默认为 2.dp。
gapLengthDp虚线之间的间隔长度,默认为 2.dp。
isHorizontalBoolean水平分割线 (true)/ 垂直分割线 (false),默认是 false
3.2.3.4. 示例代码
 PkDashDivider(modifier = Modifier.padding(top = 10.dp), isHorizontal = true)

3.3. 流式布局PkFlow

3.3.1. 介绍

PkFlowRow 是一个定制化的流式布局组件,基于 Jetpack Compose 的 FlowRow 扩展而来。核心功能如下:

  • 支持子项水平排列,自动换行
  • 限制最大行数(超出部分自动隐藏)
  • 可自定义子项间水平/垂直间距
  • 自动裁剪超出最大高度的内容(通过 clipToBounds 实现)
  • 适用于标签组、动态分类展示等需要紧凑布局的场景

3.3.2. 参数

参数名参数类型是否必填默认值说明
modifierModifierModifier布局修饰符(如尺寸、背景等),会与内部修饰符合并
horizontalSpacingDp0.dp子项之间的水平间距
verticalSpacingDp0.dp行之间的垂直间距
maxLineInt(取值范围 ≥1)2最大显示行数,超出部分将被隐藏
content@Composable () -> Unit子项内容,支持任意Composable 组件

3.3.3. 示例代码

@Preview
@Composable
fun PkFlowRowPreview() {
    val tags = listOf("Android", "Kotlin", "Jetpack Compose", "KMP","Material Design", "UI", "Development")

    PkFlowRow(
        horizontalSpacing = 8.dp,
        verticalSpacing = 12.dp,
        maxLine = 1
    ) {
        tags.forEach { tag ->
            Text(
                text = tag,
                modifier = Modifier
                    .background(Color.LightGray, RoundedCornerShape(16.dp))
                    .padding(horizontal = 12.dp, vertical = 8.dp)
            )
        }
    }
}

4. 工具类

4.1. ImagePainterUtils工具类

4.1.1. 介绍

  • 根据图片 URL 获取 AsyncImagePainter 对象

4.1.2. 导入依赖

import com.peakmain.compose.utils.ImagePainterUtils

4.1.3. 参数

参数名参数类型说明
imageUrlString图片的 URL,如果为空则显示占位图。
errorDrawableResIdInt图片加载失败时显示的 Drawable 资源 ID,默认为 R.drawable.icon_loading。
placeDrawableResIdInt图片加载过程中显示的占位图 Drawable 资源 ID,默认为 R.drawable.icon_loading。

4.1.4. 示例代码

Image(
    painter = ImagePainterUtils.getPainter(it.imageUrl),
    contentDescription = null,
    modifier = Modifier
        .clip(RoundedCornerShape(8.dp))
        .weight(1f)
        .height(75.dp),
    contentScale = ContentScale.Crop
)

5. 扩展类

5.1. List扩展类

5.1.1. 介绍

可空List的扩展类,作用如下

  • 可空List的大小
  • 可空List的大小是否大于0
  • 可空List大小是否为0

5.1.2. 导入依赖

import com.peakmain.compose.ext.orSize

5.1.3. 方法

方法名返回值说明
orSizeInt获取 List 的大小。若 List 为 null,则返回 0;若 List 不为 null,则返回其 size。
sizeBigZeroBoolean判断 List 大小是否大于 0。若 List 为 null,则返回 false;若 List 不为 null,则判断其大小是否大于 0。
sizeEqualZeroBoolean判断 List 的大小是否为 0。若 List 为 null,则返回 true;若 List 不为 null,则判断其大小是否等于 0。

5.1.4. 示例代码

params?.imageList.orSize() > 0
params?.imageList.sizeBigZero()