HarmonyOS6半年磨一剑 - RcText组件核心架构与类型系统设计
文章目录
前言
各位开发者,大家好!我是若城。
在鸿蒙应用开发过程中,我发现许多组件样式和工具方法具有高度的复用性,但每次新项目都需要重复编写,这极大地降低了开发效率。因此,我决定投入半年时间,打造一款专为鸿蒙生态设计的 UI 组件库 —— rchoui。
项目简介
rchoui 是一个面向 HarmonyOS6 的企业级 UI 组件库,旨在提供开箱即用的高质量组件,让开发者告别"重复造轮子"。
rchoui官网
目前暂定 rchoui 官网地址：http://rchoui.ruocheng.site/
需要注意的是 当前官网还在完善当中, 会在后续更新中逐步完善。届时可以为大家提供更加完善的说明文档
### 开源计划
项目预计于 2026 年 7 月中旬正式开源,届时可通过三方库直接下载使用。在此期间,我会通过系列文章逐一介绍每个模块的设计思路与实现细节。
一、概述
RcText是一个功能强大的文本展示组件,采用ComponentV2装饰器实现,支持多种主题样式、尺寸规格、特殊显示模式以及灵活的样式定制。本文将深入解析RcText组件的核心架构设计、类型系统以及设计思想。
二、组件架构设计
2.1 装饰器体系
RcText组件采用HarmonyOS6最新的@ComponentV2装饰器,这是ArkUI框架的新一代组件定义方式:
@ComponentV2export struct RcText {// 组件实现}核心优势:
- 提供更优秀的性能表现
- 支持更精细的状态管理
- 具备更强的类型推断能力
- 优化渲染效率和响应速度
2.2 参数状态管理
组件使用@Param装饰器定义所有可配置属性,实现清晰的参数管理:
核心内容参数
@Param text:string|number=''@Param type: RcTextType ='default'@Param textSize: RcTextSize ='default'这三个参数构成文本组件的核心:
- text: 支持字符串和数字类型,满足各种显示需求
- type: 定义文本的主题语义
- textSize: 控制文本尺寸规格
样式定制参数
@Param color:string| Resource =''@Param fontSize: RcStringNumber =0@Param fontWeight: RcTextWeight ='normal'@Param textAlign: RcTextAlign ='left'@Param textDecoration: RcTextDecoration ='none'@Param lineHeight: RcStringNumber =0设计亮点:
- 所有样式参数都提供合理默认值
- 自定义参数优先级高于预设配置
- 参数命名清晰,语义明确
- 支持渐进式定制,基础用法简单,高级用法灵活
高级功能参数
@Param maxLines:number=0@Param truncated:boolean=false@Param mode: RcTextMode ='text'@Param href:string=''@Param selectable:boolean=false这些参数提供了文本组件的高级能力:
- maxLines: 多行文本截断控制
- truncated: 单行截断快捷开关
- mode: 特殊显示模式(价格、手机号、链接)
- selectable: 文本可选中复制功能
2.3 类型系统设计
RcText组件建立了完善的类型定义体系,确保类型安全和开发体验。
文本主题类型
exporttypeRcTextType='default'|'primary'|'success'|'warning'|'danger'|'info'设计思路:
- 涵盖6种常见的UI语义类型
- 每种类型对应特定的视觉风格
- 与设计规范中的色彩体系一致
颜色映射关系:
| 类型 | 颜色值 | 使用场景 |
|---|---|---|
| default | #303133 | 常规文本内容 |
| primary | #409eff | 强调信息、链接 |
| success | #67c23a | 成功提示、正向状态 |
| warning | #e6a23c | 警告信息、注意事项 |
| danger | #f56c6c | 错误提示、危险操作 |
| info | #909399 | 次要信息、辅助说明 |
尺寸规格类型
exporttypeRcTextSize='large'|'default'|'small'尺寸预设规范:
| 尺寸 | 字体大小 | 使用场景 |
|---|---|---|
| large | 18vp | 标题文字、重要信息 |
| default | 14vp | 正文内容、常规显示 |
| small | 12vp | 辅助文字、次要信息 |
设计考量:
- 提供3档常用尺寸,覆盖90%使用场景
- 采用vp单位,适配不同屏幕密度
- 保持字号阶梯合理,视觉层级清晰
对齐方式类型
exporttypeRcTextAlign='left'|'center'|'right'|'start'|'end'类型说明:
- left/center/right: 传统的左中右对齐
- start/end: 支持国际化的开始/结束对齐
- 在RTL(从右到左)语言环境下,start/end会自动适配
文本装饰类型
exporttypeRcTextDecoration='none'|'underline'|'line-through'装饰效果:
- none: 无装饰,默认状态
- underline: 下划线,常用于链接
- line-through: 删除线,表示作废或优惠前价格
字体粗细类型
exporttypeRcTextWeight='normal'|'bold'|'lighter'|'bolder'|number灵活设计:
- 提供4种预设字重关键字
- 支持数值类型(100-900),满足精确控制需求
- 兼顾易用性和灵活性
显示模式类型
exporttypeRcTextMode='text'|'price'|'phone'|'link'这是RcText的创新设计,内置了常见的业务场景:
模式详解:
- text模式(默认)
- 普通文本显示
- 不做任何格式化处理
- price模式
- 自动添加货币符号(¥)
- 保留两位小数
- 添加千分位分隔符
- 示例:
1234.56→¥1,234.56
- phone模式
- 手机号脱敏显示
- 中间4位替换为星号
- 示例:
13888888888→138****8888
- link模式
- 链接文本模式
- 配合href参数使用
- 支持点击跳转逻辑
三、核心设计模式
3.1 策略模式 - 主题颜色管理
组件采用策略模式管理不同主题的颜色配置:
privategetTypeColor():string| Resource {if(this.color){returnthis.color }switch(this.type){case'primary':return'#409eff'case'success':return'#67c23a'case'warning':return'#e6a23c'case'danger':return'#f56c6c'case'info':return'#909399'case'default':default:return'#303133'}}设计亮点:
- 优先级机制: 自定义color优先级最高,提供完全覆盖能力
- 默认兜底: default分支确保任何情况都有颜色返回
- 类型安全: 返回类型支持Resource,兼容系统资源引用
- 集中管理: 所有颜色配置集中在一处,便于维护和主题扩展
3.2 计算属性模式 - 尺寸计算
使用私有方法实现计算属性,处理尺寸的优先级逻辑:
privategetSizeValue():string{if(this.fontSize){returngetSizeByUnit(this.fontSize)}switch(this.textSize){case'large':return'18vp'case'small':return'12vp'case'default':default:return'14vp'}}优先级规则:
- 自定义fontSize: 最高优先级,提供像素级精确控制
- 预设textSize: 次级优先级,提供快捷配置
- 默认值: 兜底逻辑,确保组件始终可用
工具函数集成:
getSizeByUnit函数统一处理数值单位- 支持数字、字符串、带单位字符串等多种输入
- 自动补充单位,保证输出格式统一
3.3 适配器模式 - 对齐方式转换
将自定义的对齐类型转换为系统TextAlign枚举:
privategetTextAlign(): TextAlign {switch(this.textAlign){case'left':return TextAlign.Start case'center':return TextAlign.Center case'right':return TextAlign.End case'start':return TextAlign.Start case'end':return TextAlign.End default:return TextAlign.Start }}设计意图:
- 隔离系统API,组件对外提供更语义化的类型
- 便于未来扩展,不受系统API变更影响
- 提供默认值保护,增强健壮性
3.4 装饰器模式 - 文本装饰转换
转换文本装饰类型为系统枚举:
privategetDecoration(): TextDecorationType {switch(this.textDecoration){case'underline':return TextDecorationType.Underline case'line-through':return TextDecorationType.LineThrough case'none':default:return TextDecorationType.None }}配合使用示例:
.decoration({ type:this.getDecoration(), color:this.getTypeColor()})装饰线颜色自动跟随文本颜色,保持视觉一致性。
3.5 模板方法模式 - 文本格式化
getFormattedText方法定义了文本格式化的算法骨架:
privategetFormattedText():string{const textValue =String(this.text)switch(this.mode){case'price':const num =parseFloat(textValue)if(isNaN(num))return textValue return'¥'+ num.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g,',')case'phone':if(textValue.length ===11){return textValue.replace(/(\d{3})\d{4}(\d{4})/,'$1****$2')}return textValue case'link':return textValue case'text':default:return textValue }}实现细节:
toFixed(2): 保留两位小数- 正则表达式: 每3位数字前添加逗号
\B: 非单词边界,避免开头添加逗号(?=(\d{3})+(?!\d)): 正向预查,匹配3的倍数位置- 使用正则分组捕获前3位和后4位
- 中间4位替换为星号
- 仅处理11位手机号,其他长度保持原样
- 容错处理
- 价格格式化失败时返回原文本
- 手机号长度不符时返回原文本
- 确保在任何输入下不会崩溃
手机号脱敏算法
textValue.replace(/(\d{3})\d{4}(\d{4})/,'$1****$2')价格格式化算法
num.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g,',')四、组件布局架构
4.1 Row布局结构
RcText使用Row布局实现横向排列:
build(){Row(){// 前置元素// 文本内容// 后置元素}.margin(this.rcMargin).padding(this.rcPadding).onClick(()=>this.handleClick())}布局优势:
- 自然的水平流式布局
- 支持前后元素扩展
- 响应点击事件
- 统一的外边距和内边距控制
4.2 条件渲染
组件支持可选的前后置元素:
// 前置部分if(this.prefixIcon){RcIcon({ name:this.prefixIcon, iconSize:this.iconSize, color:this.iconColor ||this.getTypeColor()}).margin({ right:4})}// 文本部分(核心)Text(this.getFormattedText()).fontSize(this.getSizeValue()).fontColor(this.getTypeColor())// ...更多样式配置// 后置部分if(this.suffixIcon){RcIcon({ name:this.suffixIcon, iconSize:this.iconSize, color:this.iconColor ||this.getTypeColor()}).margin({ left:4})}设计考量:
- 条件渲染避免空节点
- 间距自动适配(有文本时才添加间距)
- 颜色自动联动(未设置时跟随文本颜色)
4.3 文本属性配置
核心Text组件的属性配置体现了组件的灵活性:
Text(this.getFormattedText()).fontSize(this.getSizeValue()).fontColor(this.getTypeColor()).fontWeight(this.getFontWeight()).textAlign(this.getTextAlign()).decoration({ type:this.getDecoration(), color:this.getTypeColor()}).lineHeight(this.lineHeight ?getSizeByUnit(this.lineHeight):undefined).maxLines(this.maxLines >0?this.maxLines :(this.truncated ?1:undefined)).textOverflow(this.maxLines >0||this.truncated ?{ overflow: TextOverflow.Ellipsis }:undefined).copyOption(this.selectable ? CopyOptions.InApp : CopyOptions.None).layoutWeight(1)属性解析:
- 基础样式: 字号、颜色、字重、对齐、装饰
- 行高控制: 可选配置,未设置时使用默认行高
- 截断逻辑:
- maxLines优先级更高
- truncated快捷设置单行截断
- 同时控制textOverflow为省略号
- 选中功能: 通过copyOption控制是否可选中复制
- 弹性布局: layoutWeight(1)使文本占据剩余空间
五、交互处理机制
5.1 点击事件处理
组件提供了统一的点击事件处理机制:
privatehandleClick(){if(this.mode ==='link'&&this.href){console.log('Open link:',this.href)}if(this.onTextClick){this.onTextClick()}}处理流程:
- 检查是否为链接模式
- 链接模式下处理跳转逻辑(预留扩展点)
- 执行用户自定义的点击回调
扩展性设计:
- 链接跳转逻辑可后续扩展为真实的页面跳转
- 回调函数可选,不影响基础功能
- 支持链式处理,先处理内部逻辑再执行回调
5.2 事件冒泡
Row容器的onClick绑定确保整个组件区域可点击:
Row(){// 内容}.onClick(()=>this.handleClick())这种设计使得不仅文本可点击,整个组件区域都可以响应点击。
六、设计原则体现
6.1 单一职责原则
每个私有方法都有明确的单一职责:
getTypeColor(): 专注于颜色获取getSizeValue(): 专注于尺寸计算getFormattedText(): 专注于文本格式化getTextAlign(): 专注于对齐方式转换
6.2 开闭原则
组件对扩展开放,对修改封闭:
- 通过添加新的type值扩展主题色
- 通过添加新的mode扩展格式化方式
- 通过自定义属性覆盖默认行为
- 无需修改核心代码
6.3 里氏替换原则
Text组件可以被RcText无缝替换:
- 兼容基础Text的所有功能
- 提供更丰富的扩展能力
- 保持API的一致性和可预测性
6.4 接口隔离原则
组件的Props接口定义清晰:
- 每个属性都有明确的用途
- 没有冗余或强制不需要的属性
- 使用可选类型提供灵活性
6.5 依赖倒置原则
组件依赖抽象而非具体实现:
- 依赖自定义类型而非系统枚举
- 通过适配器模式转换类型
- 便于测试和扩展
七、类型安全保障
7.1 泛型工具类型
组件使用了RcStringNumber工具类型:
exporttypeRcStringNumber=string|number这个类型在rchoui组件库中广泛使用,统一处理尺寸参数的多种输入格式。
7.2 联合类型
大量使用联合类型提供类型约束:
@Param type: RcTextType ='default'@Param textSize: RcTextSize ='default'优势:
- IDE自动补全
- 编译期类型检查
- 减少运行时错误
- 提升开发体验
7.3 可选类型
使用可选类型提供灵活性:
@Param color:string| Resource =''空字符串作为默认值,未设置时使用type对应的颜色。
八、总结
RcText组件通过精心的架构设计实现了:6种主题、3种尺寸、多种对齐和装饰方式，支持预设配置和自定义样式的完美结合，预留扩展点,支持主题定制和功能增强，遵循设计原则,易于理解和维护。
组件的成功在于找到了"简单易用"和"功能强大"之间的平衡点,既满足快速开发需求,又提供深度定制能力。 希望Rchoui可以帮助到各位开发者
