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

@Require 装饰器的引入非常关键——value 是双向绑定的核心字段，如果不标记为必传，开发者可能忘记传入而导致数据不同步的隐患。编译期即可报错，将问题消灭在萌芽状态。

二、类型系统深度解析

2.1 输入类型枚举：RcInputType

// index.type.ets
export type RcInputType = 'text' | 'number' | 'password' | 'email' | 'tel' | 'url'

这里使用字符串字面量联合类型而非枚举（enum），原因有三：

1. 字面量类型在 JSON 序列化/反序列化场景下天然兼容，无需转换
2. 消费方传值时有完整的 IDE 自动补全支持
3. 代码可读性更高，inputType: 'password' 比 inputType: RcInputType.PASSWORD 直观得多

在组件内部，getInputType() 方法负责将语义化的字符串类型映射为 ArkTS 原生的 InputType 枚举：

private getInputType(): InputType {
  // 密码类型需要额外判断：如果已开启"显示密码"，则降级为普通文本输入
  if (this.inputType === 'password' && !this.showPasswordText) {
    return InputType.Password
  }
  switch (this.inputType) {
    case 'number': return InputType.Number
    case 'email': return InputType.Email
    case 'tel': return InputType.PhoneNumber
    case 'password': case 'text': default: return InputType.Normal
  }
}

这里有一个设计亮点：password 类型在"显示密码"状态下会被映射为 InputType.Normal，而不是继续使用 InputType.Password。这样可以让用户看到明文字符，同时键盘行为保持不变。

2.2 尺寸系统：RcInputSize

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

三种尺寸对应的具体像素值由组件内部的私有方法统一管理：

default 尺寸的字体大小和图标大小会读取 fontSize、iconSize 属性，而 small 和 large 则使用硬编码的规范值。这个设计意图是：小尺寸和大尺寸是预设规格，整体协调一致；默认尺寸则允许开发者进行微调。

2.3 对齐方式：RcInputAlign

export type RcInputAlign = 'left' | 'center' | 'right'

映射逻辑：

private getTextAlign(): TextAlign {
  switch (this.textAlign) {
    case 'center': return TextAlign.Center
    case 'right': return TextAlign.End // 注意：ArkTS 中右对齐使用 End，而非 Right
    case 'left': default: return TextAlign.Start
  }
}

提示：ArkTS 中文本对齐使用 TextAlign.Start 和 TextAlign.End 而非 Left/Right，这是为了支持 RTL（从右到左）语言布局，RcInput 的映射层屏蔽了这一细节差异。

2.4 清空触发时机：RcInputClearTrigger

export type RcInputClearTrigger = 'always' | 'focus'

清空按钮的显示策略由 shouldShowClear() 方法决定：

private shouldShowClear(): boolean {
  // 禁用或只读状态下，永远不显示清空按钮
  if (!this.clearable || this.disabled || this.readonly) {
    return false
  }
  // always：只要有内容就显示
  if (this.clearTrigger === 'always') {
    return this.innerValue.length > 0
  }
  // focus（默认）：聚焦且有内容时才显示
  return this.isFocused && this.innerValue.length > 0
}

两种策略的适用场景：

• focus（默认）：适合常规表单，减少视觉噪音，聚焦时才展示操作按钮
• always：适合搜索框，用户随时可以一键清空搜索词

2.5 格式化函数类型

export type RcInputFormatter = (value: string) => string
export type RcInputParser = (value: string) => string

formatter 和 parser 是一对互逆函数，构成了完整的数据变换管道：

用户原始输入 -> parser（解析/清洗） -> processedValue -> formatter（格式化/装饰） -> 显示值

在 handleInput 中的处理顺序：

private handleInput(value: string) {
  let processedValue = value
  // 第一步：先用 parser 提取纯数据
  if (this.parser) {
    processedValue = this.parser(processedValue)
  }
  // 第二步：再用 formatter 重新格式化显示
  if (this.formatter) {
    processedValue = this.formatter(processedValue)
  }
  this.innerValue = processedValue
  this.onValueChange(processedValue)
  // ...
}

三、双向绑定的实现原理

3.1 内外值分离设计

RcInput 维护了三个与值相关的状态：

@Param @Require value: string = ''        // 外部传入的值（只读）
@Local innerValue: string = ''            // 内部实际渲染值
private lastValue: string = ''            // 上一次确认的值（用于 onChange 去重）

为什么需要 innerValue？

因为格式化函数的存在，外部的 value 和内部显示的值可能不同。例如金额输入时，外部存储的是纯数字 "1000"，但输入框显示的是 "¥ 1,000"。innerValue 就是格式化后的显示值。

aboutToAppear(): void {
  // 组件初始化时，用外部值同步内部值
  this.innerValue = this.value
  this.lastValue = this.value
}

3.2 onValueChange 回调模式

@Param onValueChange: (value: string) => void = () => {}

HarmonyOS6 的 @ComponentV2 中，子组件不能直接修改父组件传入的 @Param 值。因此 RcInput 采用回调通知模式：当值发生变化时，通过 onValueChange 通知父组件更新状态，父组件再将新值传回，形成单向数据流的闭环。

使用示例：

@Entry
@ComponentV2
struct LoginPage {
  @Local username: string = ''
  @Local password: string = ''

  build() {
    Column({ space: 16 }) {
      RcInput({
        value: this.username,
        onValueChange: (value: string) => {
          this.username = value
        },
        placeholder: '请输入用户名',
        clearable: true
      })
      RcInput({
        value: this.password,
        onValueChange: (value: string) => {
          this.password = value
        },
        inputType: 'password',
        showPassword: true,
        placeholder: '请输入密码'
      })
    }.padding(24).width('100%')
  }
}

提示：value 和 onValueChange 必须同时提供，缺少 onValueChange 会导致输入框变成"受控只读"状态——用户输入后值立刻被父组件旧值覆盖，看起来无法输入。

四、组件生命周期与状态同步

4.1 aboutToAppear 初始化

aboutToAppear(): void {
  this.innerValue = this.value
  this.lastValue = this.value
}

组件挂载时将外部 value 同步到内部两个状态变量，确保初始显示正确。

4.2 aboutToRecycle 外部值变更响应

aboutToRecycle(): void {
  if (this.value !== this.innerValue) {
    this.innerValue = this.value
  }
}

当父组件主动更新 value（如表单重置、数据回填）时，通过 aboutToRecycle 钩子将新值同步到 innerValue。条件判断 this.value !== this.innerValue 避免了用户正在输入时被意外覆盖。

主要特点：

1. 懒同步：只在外部值真正改变时才更新内部值，避免多余渲染
2. 防覆盖：用户输入过程中不会被外部值打断
3. 回填友好：支持异步数据回填场景（如编辑表单时从服务端加载原始值）

总结

RcInput 组件的核心架构体现了三个设计原则：类型安全优先（通过字面量联合类型消灭运行时类型错误）、职责清晰分离（类型定义与实现分文件）、受控组件模式（value + onValueChange 的单向数据流）。理解这些架构决策，是正确、高效使用 RcInput 的前提，也是在 HarmonyOS6 生态中构建高质量表单交互的重要基础。