HarmonyOS6 RcText 组件核心架构与类型系统设计

设计亮点:

• 所有样式参数都提供合理默认值
• 自定义参数优先级高于预设配置
• 参数命名清晰，语义明确
• 支持渐进式定制，基础用法简单，高级用法灵活

高级功能参数

@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 组件建立了完善的类型定义体系，确保类型安全和开发体验。

文本主题类型

export type RcTextType = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'

设计思路:

• 涵盖 6 种常见的 UI 语义类型
• 每种类型对应特定的视觉风格
• 与设计规范中的色彩体系一致

颜色映射关系:

尺寸规格类型

export type RcTextSize = 'large' | 'default' | 'small'

尺寸预设规范:

设计考量:

• 提供 3 档常用尺寸，覆盖 90% 使用场景
• 采用 vp 单位，适配不同屏幕密度
• 保持字号阶梯合理，视觉层级清晰

对齐方式类型

export type RcTextAlign = 'left' | 'center' | 'right' | 'start' | 'end'

类型说明:

• left/center/right: 传统的左中右对齐
• start/end: 支持国际化的开始/结束对齐
• 在 RTL(从右到左) 语言环境下，start/end 会自动适配

文本装饰类型

export type RcTextDecoration = 'none' | 'underline' | 'line-through'

装饰效果:

• none: 无装饰，默认状态
• underline: 下划线，常用于链接
• line-through: 删除线，表示作废或优惠前价格

字体粗细类型

export type RcTextWeight = 'normal' | 'bold' | 'lighter' | 'bolder' | number

灵活设计:

• 提供 4 种预设字重关键字
• 支持数值类型 (100-900)，满足精确控制需求
• 兼顾易用性和灵活性

显示模式类型

export type RcTextMode = '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 策略模式 - 主题颜色管理

组件采用策略模式管理不同主题的颜色配置：

private getTypeColor(): string | Resource {
  if (this.color) {
    return this.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 计算属性模式 - 尺寸计算

使用私有方法实现计算属性，处理尺寸的优先级逻辑：

private getSizeValue(): string {
  if (this.fontSize) {
    return getSizeByUnit(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 枚举：

private getTextAlign(): 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 装饰器模式 - 文本装饰转换

转换文本装饰类型为系统枚举：

private getDecoration(): 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 方法定义了文本格式化的算法骨架：

private getFormattedText(): 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)

属性解析:

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

五、交互处理机制

5.1 点击事件处理

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

private handleClick() {
  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 工具类型：

export type RcStringNumber = string | number

这个类型在 rchoui 组件库中广泛使用，统一处理尺寸参数的多种输入格式。

7.2 联合类型

大量使用联合类型提供类型约束：

@Param type: RcTextType = 'default'
@Param textSize: RcTextSize = 'default'

优势:

• IDE 自动补全
• 编译期类型检查
• 减少运行时错误
• 提升开发体验

7.3 可选类型

使用可选类型提供灵活性：

@Param color: string | Resource = ''

空字符串作为默认值，未设置时使用 type 对应的颜色。

八、总结

RcText 组件通过精心的架构设计实现了：6 种主题、3 种尺寸、多种对齐和装饰方式，支持预设配置和自定义样式的完美结合，预留扩展点，支持主题定制和功能增强，遵循设计原则，易于理解和维护。

组件的成功在于找到了'简单易用'和'功能强大'之间的平衡点，既满足快速开发需求，又提供深度定制能力。