HarmonyOS6 RcButton 组件交互逻辑与事件处理机制

流程说明：

1. 状态拦截：如果处于禁用或加载状态，直接返回，不执行后续逻辑。
2. 节流判断：如果设置了节流时间，计算当前时间与上次点击的时间差，若间隔不足则忽略本次点击。
3. 执行回调：通过上述检查后，才真正触发用户的业务逻辑。

三、状态控制机制

3.1 禁用状态 (disabled)

状态定义

@Param disabled?: boolean = false

影响范围

1. 点击事件拦截 禁用时所有点击被拦截，不会触发 onBtnClick 回调。

2. 交互能力控制 使用 HarmonyOS6 的 .enabled() 属性控制组件是否可交互：

.enabled(!this.disabled && !this.loading)

当 enabled(false) 时，组件不响应任何触摸事件，无法获得焦点，也不触发按压态样式。

3. 视觉样式变化 背景色、透明度和文字色都会根据禁用状态调整。例如实体按钮背景变为禁用色，透明度降为 0.6；镂空按钮边框和文字变灰。

使用场景

// 表单验证未通过
RcButton({ text: '提交', type: RcButtonType.PRIMARY, disabled: !isFormValid })

// 数据加载中
RcButton({ text: '删除', type: RcButtonType.ERROR, disabled: isDeleting })

3.2 加载状态 (loading)

状态定义

@Param loading?: boolean = false
@Param loadingText?: string = ''

影响范围

1. 点击事件拦截 与 disabled 相同，loading 状态也会拦截点击，防止重复提交。

2. 视觉内容替换 显示加载动画，隐藏普通图标，并可切换文本：

if (this.loading) {
  LoadingProgress().width(this.iconSize).height(this.iconSize).color(this.getTextColor())
}
if (!this.loading && this.icon) {
  RcIcon({ name: this.icon, iconSize: this.iconSize })
}

加载状态的内容优先级：

1. loading=true 且有 loadingText：显示 loadingText。
2. loading=true 但无 loadingText：只显示加载动画，保持原 text。
3. loading=false：显示正常内容。

加载动画特性

HarmonyOS6 的 LoadingProgress 组件特点：

• 自动旋转动画，无需额外代码。
• 颜色可自定义，跟随按钮文字色。
• 大小与图标大小保持一致。
• 性能优化，GPU 加速。

使用场景

异步操作反馈：

@State isLoading: boolean = false
const handleSubmit = async () => {
  this.isLoading = true
  try {
    await submitForm()
  } finally {
    this.isLoading = false
  }
}
RcButton({ text: '提交', loading: this.isLoading, loadingText: '提交中...', type: RcButtonType.PRIMARY, onBtnClick: handleSubmit })

3.3 状态组合

disabled 和 loading 可以同时为 true，逻辑关系如下：

.enabled(!this.disabled && !this.loading)

组合效果表：

最佳实践： 通常不需要同时设置 disabled 和 loading。如果同时设置，禁用样式会覆盖加载样式。建议只使用 loading，它自带禁用交互能力。

四、节流机制深度解析

4.1 节流原理

节流 (Throttle) 是一种性能优化手段，限制函数在一定时间内只能执行一次。

无节流问题：

• 用户可能快速多次点击。
• 每次点击都触发回调。
• 可能导致重复提交、性能问题。

节流解决方案：

• 记录上次执行时间。
• 在时间间隔内的点击被忽略。
• 间隔过后才允许下次点击。

4.2 节流实现

状态定义

@Param throttleTime?: number = 0
@Local lastClickTime: number = 0

• throttleTime: 节流间隔 (毫秒)，0 表示不节流。
• lastClickTime: 上次点击时间戳。

实现逻辑

private handleClick = (event: ClickEvent): void => {
  if (this.disabled || this.loading) { return }
  const currentTime = Date.now()
  if (this.throttleTime && this.throttleTime > 0) {
    if (currentTime - this.lastClickTime < this.throttleTime) { return }
    this.lastClickTime = currentTime
  }
  this.onBtnClick(event)
}

执行流程：

1. 获取当前时间戳 currentTime。
2. 检查是否设置了节流时间。
3. 计算距离上次点击的时间间隔。
4. 如果间隔小于节流时间，忽略点击。
5. 否则，更新 lastClickTime 并触发回调。

4.3 节流 vs 防抖

节流 (Throttle):

• 固定时间间隔内只执行一次。
• 首次点击立即执行。
• 适合：按钮点击、滚动事件。

防抖 (Debounce):

• 连续触发时只执行最后一次。
• 等待触发停止后才执行。
• 适合：输入框搜索、窗口调整。

RcButton 使用节流而非防抖的原因：按钮点击需要立即反馈，防抖会延迟用户感知，而节流可以立即执行首次点击。

4.4 节流配置建议

使用示例：

// 表单提交按钮
RcButton({ text: '提交', type: RcButtonType.PRIMARY, throttleTime: 2000, onBtnClick: () => { submitForm() }})

// 付款按钮
RcButton({ text: '确认支付', type: RcButtonType.WARNING, throttleTime: 5000, onBtnClick: () => { processPay() }})

4.5 节流与 loading 的配合

实际应用中，通常将节流和 loading 结合使用，提供双重保护：

1. 节流: 限制点击频率，防止短时间内多次触发。
2. loading: 在处理期间禁用按钮，防止重复触发。

这种组合提供了最佳的用户体验和安全性。

五、按压反馈机制

5.1 状态样式系统

HarmonyOS6 提供了 stateStyles API 用于定义不同状态的样式：

.stateStyles({
  normal: { .opacity(1) },
  pressed: { .backgroundColor(this.getColorConfig().activeBg).opacity(1) },
  disabled: { .opacity(0.6) }
})

5.2 三种状态

Normal(正常态)

• 按钮未被按下时的状态。
• 透明度为 1，完全不透明。
• 使用正常的背景色和文字色。

Pressed(按压态)

• 用户手指按下按钮时进入此状态。
• 实体按钮背景色加深（PRIMARY 蓝色→深蓝色）。
• 镂空/文本按钮降低透明度至 0.7。
• 禁用按钮无变化。

Disabled(禁用态)

• 透明度固定 0.6。
• 配合 .enabled() 使用。
• 与 disabled 属性联动。

5.3 按压反馈的时机

触发时机：

1. 用户手指按下按钮 → 进入 pressed 状态。
2. 用户手指离开按钮 → 返回 normal 状态。
3. 按钮点击事件在手指离开时触发。

5.4 触觉反馈 (可选)

虽然当前代码未实现，但可以扩展触觉反馈以增强用户体验，特别适合重要操作按钮和游戏场景：

// 扩展示例
private handleClick = (event: ClickEvent): void => {
  if (this.disabled || this.loading) { return }
  // 触发触觉反馈
  vibrator.vibrate({ duration: 10, mode: 'short' })
  // 节流逻辑...
  this.onBtnClick(event)
}

六、图标与内容布局

6.1 内容布局结构

按钮内容使用 Row 布局，水平排列：

Row() {
  // 1. 加载动画 (loading 时显示)
  // 2. 图标 (非 loading 时显示)
  // 3. 文本
}.justifyContent(FlexAlign.Center).alignItems(VerticalAlign.Center)

布局特点：

• 水平居中对齐。
• 垂直居中对齐。
• 图标在左，文本在右。
• 图标与文本间距 6px。

6.2 加载动画布局

if (this.loading) {
  LoadingProgress().width(this.iconSize).height(this.iconSize).color(this.getTextColor()).margin({ right: (this.loadingText || this.text) ? 6 : 0 })
}

布局逻辑：

• loading=true 时显示。
• 尺寸与图标保持一致。
• 颜色跟随文字色。
• 如果有文本，右边距 6px；如果没有文本，无边距。

6.3 图标布局

if (!this.loading && this.icon) {
  RcIcon({ name: this.icon, iconSize: this.iconSize }).margin({ right: this.text ? 6 : 0 })
}

显示条件：

• 非 loading 状态。
• 设置了 icon 属性。

边距逻辑：

• 有文本：右边距 6px。
• 无文本：无边距 (纯图标按钮)。

6.4 文本布局

if (this.loading && this.loadingText) {
  Text(this.loadingText).fontSize(this.getTextSize()).fontColor(this.getTextColor())
} else if (this.text) {
  Text(this.text).fontSize(this.getTextSize()).fontColor(this.getTextColor())
}

显示逻辑：

1. loading 且有 loadingText：显示 loadingText。
2. 否则有 text：显示 text。
3. 都没有：不显示文本。

6.5 内容组合模式

• 模式 1: 纯文本 [文本]
• 模式 2: 图标 + 文本 [图标] [6px] [文本]
• 模式 3: 纯图标 [图标]
• 模式 4: 加载 + 文本 [加载动画] [6px] [文本]
• 模式 5: 加载 + 自定义文本 [加载动画] [6px] [提交中…]
• 模式 6: 纯加载动画 [加载动画]

七、交互状态转换

7.1 状态机模型

按钮可以看作一个状态机，具有以下状态：

正常 (Normal) ←→ 按压 (Pressed)
↓
禁用 (Disabled)
↓
加载 (Loading)

状态转换规则：

7.2 交互阻断机制

某些状态会阻断交互：

.enabled(!this.disabled && !this.loading)

阻断条件：

• disabled=true: 完全阻断。
• loading=true: 完全阻断。

阻断效果：

• 不响应触摸事件。
• 不进入 pressed 状态。
• 不触发 onClick 回调。
• 不获得焦点。

7.3 状态恢复

通常状态转换由外部控制 (通过属性变化)：

@State submitDisabled: boolean = false
@State submitLoading: boolean = false
const handleSubmit = async () => {
  this.submitLoading = true
  try {
    await api.submit()
    // 成功后可能禁用按钮
    this.submitDisabled = true
  } catch (error) {
    // 失败后恢复可点击状态
  } finally {
    this.submitLoading = false
  }
}
RcButton({ text: '提交', disabled: this.submitDisabled, loading: this.submitLoading, onBtnClick: handleSubmit })

八、性能优化策略

8.1 事件处理优化

使用箭头函数绑定：

private handleClick = (event: ClickEvent): void => {
  // ...
}

箭头函数自动绑定 this，避免使用 .bind(this) 或在 render 中创建新函数。

方法引用：

.onClick(this.handleClick)

而非：

.onClick((e) => this.handleClick(e)) // 每次 render 创建新函数

8.2 条件渲染优化

使用条件判断而非隐藏：

if (this.loading) { LoadingProgress() }
if (!this.loading && this.icon) { RcIcon() }

优势：

• 不渲染不需要的组件。
• 减少组件树节点数。
• 降低内存占用。

8.3 状态管理优化

使用 @Local 管理内部状态：

@Local lastClickTime: number = 0

优势：

• 不触发外部 re-render。
• 只在组件内部使用。
• 性能开销最小。

8.4 样式计算缓存

虽然当前实现在每次 render 时都调用 getter 方法，但这些方法计算简单，返回静态对象，执行速度极快。如果需要进一步优化，可以使用 @Computed (如果框架支持)。

九、可访问性支持

9.1 焦点管理

通过 .enabled() 控制可获得焦点：

.enabled(!this.disabled && !this.loading)

禁用或加载时不可获得焦点，符合无障碍标准。

9.2 语义化

使用 HarmonyOS6 的 Button 组件：

Button({ type: ButtonType.Normal })

Button 组件自带无障碍支持：

• 屏幕阅读器识别为按钮。
• 可以通过键盘操作。
• 支持辅助触摸。

9.3 状态反馈

视觉状态变化为辅助功能用户提供反馈：

• 禁用：降低透明度，改变颜色。
• 加载：显示动画，可切换文本。
• 按压：背景色或透明度变化。

十、总结

RcButton 的交互系统具有以下特点：

1. 完善的事件处理: 节流、状态检查、回调触发。
2. 丰富的状态控制: disabled、loading 及其组合。
3. 清晰的视觉反馈: 按压态、禁用态、加载态。
4. 灵活的内容布局: 图标、文本、加载动画自由组合。
5. 优秀的性能: 事件优化、条件渲染、状态管理。
6. 良好的可访问性: 焦点管理、语义化、状态反馈。