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

处理流程图:

用户点击 ↓ handleClick 被调用 ↓ 检查 disabled/loading ─→ 是 ─→ 忽略点击，返回 ↓ 否 节流时间检查 ─→ 在节流期内 ─→ 忽略点击，返回 ↓ 否或无节流 触发 onBtnClick 回调 ↓ 用户代码执行 

三、状态控制机制

3.1 禁用状态 (disabled)

状态定义

@Param disabled?: boolean = false

影响范围

1. 点击事件拦截

if (this.disabled || this.loading) {
  return
}

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

2. 交互能力控制

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

使用 HarmonyOS6 的 .enabled() 属性控制组件是否可交互。当 enabled(false) 时:

• 组件不响应任何触摸事件
• 无法获得焦点
• 不触发按压态样式

3. 视觉样式变化

背景色:

.backgroundColor(this.disabled ? this.getDisabledColor() : (this.plain || this.textButton ? Color.Transparent : this.getColorConfig().bg))

透明度:

.opacity(this.disabled ? 0.6 : 1)

文字色:

private getTextColor(): ResourceColor {
  if (this.textColor !== undefined) {
    return this.textColor
  }
  if (this.disabled) {
    return this.getDisabledColor()
  }
  // ...其他逻辑
}

视觉效果总结:

• 实体按钮：背景变为禁用色，透明度 0.6
• 镂空按钮：边框和文字变为灰色，透明度 0.6
• 文本按钮：文字变为灰色，透明度 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 状态也会拦截点击:

if (this.disabled || this.loading) {
  return
}
.enabled(!this.disabled && !this.loading)

2. 视觉内容替换

显示加载动画:

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

隐藏普通图标:

if (!this.loading && this.icon) {
  RcIcon({ name: this.icon, iconSize: this.iconSize || this.getSizeConfig().iconSize, color: this.getTextColor() })
}

文本切换:

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=true 且有 loadingText: 显示 loadingText
2. loading=true 但无 loadingText: 只显示加载动画，保持原 text
3. loading=false: 显示正常内容

加载动画特性

LoadingProgress()

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

只显示动画:

RcButton({ text: '加载', loading: true, type: RcButtonType.PRIMARY })
// 显示：[旋转动画] 加载

带加载文案:

RcButton({ text: '加载', loading: true, loadingText: '加载中...', type: RcButtonType.PRIMARY })
// 显示：[旋转动画] 加载中...

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 并触发回调

时间轴示例:

假设节流时间为 1000ms:

时刻 操作 lastClickTime currentTime 间隔 结果
0ms 首次点击 0 0 0 执行，更新为 0
300ms 第 2 次点击 0 300 300 忽略
600ms 第 3 次点击 0 600 600 忽略
1100ms 第 4 次点击 0 1100 1100 执行，更新为 1100
1200ms 第 5 次点击 1100 1200 100 忽略
2200ms 第 6 次点击 1100 2200 1100 执行，更新为 2200

4.3 节流 vs 防抖

节流 (Throttle):

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

防抖 (Debounce):

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

RcButton 使用节流而非防抖的原因:

• 按钮点击需要立即反馈
• 防抖会延迟用户感知
• 节流可以立即执行首次点击

4.4 节流配置建议

场景推荐:

使用示例:

// 表单提交按钮
RcButton({ text: '提交', type: RcButtonType.PRIMARY, throttleTime: 2000, // 2 秒内只能点击一次
  onBtnClick: () => { submitForm() }
})
// 付款按钮
RcButton({ text: '确认支付', type: RcButtonType.WARNING, throttleTime: 5000, // 5 秒内只能点击一次
  onBtnClick: () => { processPay() }
})

4.5 节流与 loading 的配合

实际应用中，通常将节流和 loading 结合使用:

@State isSubmitting: boolean = false
const handleSubmit = async () => {
  this.isSubmitting = true
  try {
    await api.submit()
  } finally {
    this.isSubmitting = false
  }
}
RcButton({ text: '提交', type: RcButtonType.PRIMARY, loading: this.isSubmitting, throttleTime: 1000, onBtnClick: handleSubmit })

双重保护:

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

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

五、按压反馈机制

5.1 状态样式系统

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

.stateStyles({
  normal: { .opacity(1) },
  pressed: {
    .backgroundColor(this.disabled || this.plain || this.textButton ? undefined : this.getColorConfig().activeBg)
    .opacity(this.disabled ? 0.6 : (this.plain || this.textButton ? 0.7 : 1))
  },
  disabled: { .opacity(0.6) }
})

5.2 三种状态

Normal(正常态)

normal: { .opacity(1) }

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

Pressed(按压态)

pressed: {
  .backgroundColor(this.disabled || this.plain || this.textButton ? undefined : this.getColorConfig().activeBg)
  .opacity(this.disabled ? 0.6 : (this.plain || this.textButton ? 0.7 : 1))
}

背景色逻辑:

• 禁用/镂空/文本按钮：不改变背景色 (undefined)
• 实体按钮：使用 activeBg(深色背景)

透明度逻辑:

• 禁用：保持 0.6
• 镂空/文本：降低到 0.7
• 实体：保持 1.0

反馈策略对比:

Disabled(禁用态)

disabled: { .opacity(0.6) }

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

5.3 按压反馈的时机

触发时机:

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

时序图:

用户操作 按钮状态 事件触发
↓ 手指按下 → pressed ↓ ↓ 背景变深/透明度降低 ↓ ↓ 手指离开 → normal → onClick 触发 ↓ ↓ ↓ 恢复原样 handleClick 执行 

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 布局，水平排列:

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

布局特点:

• 水平居中对齐 (FlexAlign.Center)
• 垂直居中对齐 (VerticalAlign.Center)
• 图标在左，文本在右
• 图标与文本间距 6px

6.2 加载动画布局

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

布局逻辑:

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

边距判断:

.margin({ right: (this.loadingText || this.text) ? 6 : 0 })

这个判断确保:

• 有文本时：[动画] [6px] [文本]
• 无文本时：[动画] (无多余空间)

6.3 图标布局

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

显示条件:

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

图标尺寸:

1. 优先使用 iconSize 属性
2. 否则根据 btnSize 自动计算

图标颜色:

• 跟随文字颜色
• 确保与按钮类型和状态匹配

边距逻辑:

• 有文本：右边距 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. 都没有：不显示文本

优先级:

loadingText(loading 时) > text 

6.5 内容组合模式

模式 1: 纯文本

RcButton({ text: '按钮' })

布局：[文本]

模式 2: 图标 + 文本

RcButton({ text: '搜索', icon: 'search' })

布局：[图标] [6px] [文本]

模式 3: 纯图标

RcButton({ icon: 'plus' })

布局：[图标]

模式 4: 加载 + 文本

RcButton({ text: '提交', loading: true })

布局：[加载动画] [6px] [文本]

模式 5: 加载 + 自定义文本

RcButton({ text: '提交', loading: true, loadingText: '提交中...' })

布局：[加载动画] [6px] [提交中…]

模式 6: 纯加载动画

RcButton({ loading: true })

布局：[加载动画]

七、交互状态转换

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 方法，但这些方法:

• 计算简单 (switch 语句)
• 返回静态对象
• 执行速度极快

如果需要进一步优化，可以使用 @Computed(如果框架支持):

// 优化示例
@Computed
get sizeConfig(): RcButtonSizeConfig {
  return this.getSizeConfig()
}

九、可访问性支持

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. 良好的可访问性: 焦点管理、语义化、状态反馈