HarmonyOS6半年磨一剑 - RcText组件核心架构与类型系统设计

文章目录

• 前言
• 项目简介
  • rchoui官网
• 一、概述
• 二、组件架构设计
  • 2.1 装饰器体系
  • 2.2 参数状态管理
    • 核心内容参数
    • 样式定制参数
    • 高级功能参数
  • 2.3 类型系统设计
    • 文本主题类型
    • 尺寸规格类型
    • 对齐方式类型
    • 文本装饰类型
    • 字体粗细类型
    • 显示模式类型
• 三、核心设计模式
  • 3.1 策略模式 - 主题颜色管理
  • 3.2 计算属性模式 - 尺寸计算
  • 3.3 适配器模式 - 对齐方式转换
  • 3.4 装饰器模式 - 文本装饰转换
  • 3.5 模板方法模式 - 文本格式化
• 四、组件布局架构
  • 4.1 Row布局结构
  • 4.2 条件渲染
  • 4.3 文本属性配置
• 五、交互处理机制
  • 5.1 点击事件处理
  • 5.2 事件冒泡
• 六、设计原则体现
  • 6.1 单一职责原则
  • 6.2 开闭原则
  • 6.3 里氏替换原则
  • 6.4 接口隔离原则
  • 6.5 依赖倒置原则
• 七、类型安全保障
  • 7.1 泛型工具类型
  • 7.2 联合类型
  • 7.3 可选类型
• 八、总结

前言

各位开发者,大家好!我是若城。

在鸿蒙应用开发过程中,我发现许多组件样式和工具方法具有高度的复用性,但每次新项目都需要重复编写,这极大地降低了开发效率。因此,我决定投入半年时间,打造一款专为鸿蒙生态设计的 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语义类型
• 每种类型对应特定的视觉风格
• 与设计规范中的色彩体系一致

颜色映射关系:

尺寸规格类型

exporttypeRcTextSize='large'|'default'|'small'

尺寸预设规范:

设计考量:

• 提供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的创新设计,内置了常见的业务场景:

模式详解:

1. text模式(默认)
   • 普通文本显示
   • 不做任何格式化处理

2. price模式
   • 自动添加货币符号(¥)
   • 保留两位小数
   • 添加千分位分隔符
   • 示例: 1234.56 → ¥1,234.56
3. phone模式
   • 手机号脱敏显示
   • 中间4位替换为星号
   • 示例: 13888888888 → 138****8888
4. 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'}}

设计亮点:

1. 优先级机制: 自定义color优先级最高,提供完全覆盖能力
2. 默认兜底: default分支确保任何情况都有颜色返回
3. 类型安全: 返回类型支持Resource,兼容系统资源引用
4. 集中管理: 所有颜色配置集中在一处,便于维护和主题扩展

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'}}

优先级规则:

1. 自定义fontSize: 最高优先级,提供像素级精确控制
2. 预设textSize: 次级优先级,提供快捷配置
3. 默认值: 兜底逻辑,确保组件始终可用

工具函数集成:

• 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位手机号,其他长度保持原样
1. 容错处理
   • 价格格式化失败时返回原文本
   • 手机号长度不符时返回原文本
   • 确保在任何输入下不会崩溃

手机号脱敏算法

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)

属性解析:

1. 基础样式: 字号、颜色、字重、对齐、装饰
2. 行高控制: 可选配置,未设置时使用默认行高
3. 截断逻辑:
   • maxLines优先级更高
   • truncated快捷设置单行截断
   • 同时控制textOverflow为省略号
4. 选中功能: 通过copyOption控制是否可选中复制
5. 弹性布局: layoutWeight(1)使文本占据剩余空间

五、交互处理机制

5.1 点击事件处理

组件提供了统一的点击事件处理机制:

privatehandleClick(){if(this.mode ==='link'&&this.href){console.log('Open link:',this.href)}if(this.onTextClick){this.onTextClick()}}

处理流程:

1. 检查是否为链接模式
2. 链接模式下处理跳转逻辑(预留扩展点)
3. 执行用户自定义的点击回调

扩展性设计:

• 链接跳转逻辑可后续扩展为真实的页面跳转
• 回调函数可选,不影响基础功能
• 支持链式处理,先处理内部逻辑再执行回调

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可以帮助到各位开发者