Jetpack Compose UI组件封装（一）

项目地址：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 内容，默认居中显示）
modifier	Modifier	否	Modifier	布局修饰符，会与组件内部修饰符合并
navigationIcon	@Composable (() -> Unit)?	否	null	左侧导航图标（如返回按钮），若为 null则不显示
backgroundColor	Color	否	MaterialTheme.colors.primarySurface	应用栏背景颜色
actions	@Composable RowScope.() -> Unit	否	{}	右侧操作图标组（可包含多个图标按钮）
isImmersive	Boolean	否	false	是否启用沉浸式状态栏（透明状态栏，内容向上延伸）
darkIcons	Boolean	否	false	状态栏图标颜色是否为深色（true为黑色，false为白色），仅在 isImmersive=true时生效
content	@Composable (PaddingValues) -> Unit	是	无	页面主体内容（通过 Scaffold插入到应用栏下方）

2.2. 标题组件

2.2.1. 介绍

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

2.2.2. 参数说明

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

---

2.2.3. PkTitleType 类型说明

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

类型名称	字体大小	字重	说明
BigTitle1	24.sp	W500	大标题1（默认类型）
BigTitle2	22.sp	W500	大标题2
BigTitle3	18.sp	W500	大标题3
TitleBold1	16.sp	W500	标题1（加粗）
TitleNormal1	16.sp	W400	标题1（常规）
TitleBold2	15.sp	W500	标题2（加粗）
TitleNormal2	15.sp	W400	标题2（常规）
SmallTitleBold	14.sp	W500	小标题（加粗）
SmallTitleNormal	14.sp	W400	小标题（常规）
TextBold1	12.sp	W500	内文1（加粗）
TextNormal1	12.sp	W400	内文1（常规）
TextBold2	11.sp	W500	内文2（加粗）
TextNormal2	11.sp	W400	内文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. 参数

参数名	参数类型	是否必填	默认值	说明
columns	Int（取值范围 ≥1）	是	无	每行显示的列数
data	MutableList<E>	是	无	数据源列表，泛型 E表示数据项类型
isShowHorizontalDivider	Boolean	否	false	是否显示水平分割线（仅在行之间显示）
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. 参数

参数名	参数类型	说明
modifier	Modifier	用于添加额外修饰符的 Modifier。
color	Color	分隔线的颜色，默认为 0xFFF1EFE9。
height	Dp	分隔线的高度，仅在垂直分隔线生效，默认为 28.dp。
thickness	Dp	分隔线的厚度，仅在非虚线时生效，默认为 1.dp。
startIndent	Dp	分隔线的起始缩进，仅在非虚线时生效，默认为 0.dp。
isHorizontal	Boolean	是否为水平分隔线，默认为 false。
isDash	Boolean	是否绘制虚线分隔线，默认为 false。
strokeWidth	Dp	虚线的宽度，仅在绘制虚线时生效，默认为 0.5.dp。
dashLength	Dp	虚线的线段长度，仅在绘制虚线时生效，默认为 2.dp。
gapLength	Dp	虚线的间隔长度，仅在绘制虚线时生效，默认为 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. 参数

参数名	参数类型	说明
modifier	Modifier	用于添加额外修饰符的 Modifier。
color	Color	分隔线的颜色，默认为 0xFFF1EFE9。
height	Dp	分隔线的高度，垂直方向生效默认为 28.dp。
thickness	Dp	分隔线的厚度，默认为 1.dp。
startIndent	Dp	分隔线的起始缩进，默认为 0.dp。
isHorizontal	Boolean	水平分割线 (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. 参数

参数名	参数类型	说明
modifier	Modifier	用于添加额外修饰符的 Modifier。
color	Color	分隔线的颜色，默认为 0xFFF1EFE9。
height	Dp	分隔线的高度，垂直方向生效，默认为 28.dp。
strokeWidth	Dp	虚线的宽度，默认为 0.5.dp。
dashLength	Dp	虚线的长度，默认为 2.dp。
gapLength	Dp	虚线之间的间隔长度，默认为 2.dp。
isHorizontal	Boolean	水平分割线 (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. 参数

参数名	参数类型	是否必填	默认值	说明
modifier	Modifier	否	Modifier	布局修饰符（如尺寸、背景等），会与内部修饰符合并
horizontalSpacing	Dp	否	0.dp	子项之间的水平间距
verticalSpacing	Dp	否	0.dp	行之间的垂直间距
maxLine	Int（取值范围 ≥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. 参数

参数名	参数类型	说明
imageUrl	String	图片的 URL，如果为空则显示占位图。
errorDrawableResId	Int	图片加载失败时显示的 Drawable 资源 ID，默认为 R.drawable.icon_loading。
placeDrawableResId	Int	图片加载过程中显示的占位图 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. 方法

方法名	返回值	说明
orSize	Int	获取 List 的大小。若 List 为 null，则返回 0；若 List 不为 null，则返回其 size。
sizeBigZero	Boolean	判断 List 大小是否大于 0。若 List 为 null，则返回 false；若 List 不为 null，则判断其大小是否大于 0。
sizeEqualZero	Boolean	判断 List 的大小是否为 0。若 List 为 null，则返回 true；若 List 不为 null，则判断其大小是否等于 0。

5.1.4. 示例代码

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