HarmonyOS6 RcButton 组件核心架构与设计思想解析

设计亮点:

• 所有参数都设置了合理的默认值
• 使用可选类型 (?) 提供灵活性
• 参数命名清晰，避免与系统关键字冲突

内部状态管理

@Local lastClickTime: number = 0

用于实现节流等内部逻辑，不对外暴露，保持 API 简洁。

2.3 类型系统设计

组件定义了完整的类型枚举体系:

按钮类型枚举

export enum RcButtonType {
    DEFAULT = 'default',
    PRIMARY = 'primary',
    SUCCESS = 'success',
    WARNING = 'warning',
    ERROR = 'error',
    INFO = 'info'
}

设计考量:

• 使用字符串枚举，便于调试和序列化
• 覆盖常见的 UI 语义类型
• 每种类型对应特定的视觉风格

尺寸枚举

export enum RcButtonSize {
    LARGE = 'large',
    NORMAL = 'normal',
    SMALL = 'small',
    MINI = 'mini'
}

提供 4 档尺寸，满足不同场景需求:

• LARGE (48px): 首要操作、底部固定按钮
• NORMAL (40px): 标准场景，默认尺寸
• SMALL (32px): 次要操作、卡片内按钮
• MINI (28px): 紧凑空间、表格操作

形状枚举

export enum RcButtonShape {
    SQUARE = 'square',
    ROUND = 'round',
    CIRCLE = 'circle'
}

使用场景:

• SQUARE: 常规方形按钮，圆角 4px
• ROUND: 胶囊按钮，圆角为高度的一半
• CIRCLE: 圆形按钮，适合纯图标按钮

2.4 配置接口设计

尺寸配置接口

export interface RcButtonSizeConfig {
    height: number      // 按钮高度
    fontSize: number    // 文字大小
    paddingH: number    // 水平内边距
    iconSize: number    // 图标大小
}

这个接口封装了尺寸相关的所有配置，确保不同尺寸的按钮各元素比例协调。

颜色配置接口

export interface RcButtonColorConfig {
    bg: ResourceColor   // 背景色
    text: ResourceColor // 文字色
    border: ResourceColor // 边框色
    activeBg: ResourceColor // 激活背景色
}

统一管理一种类型按钮的所有颜色状态，便于主题扩展。

三、核心设计模式

3.1 配置映射模式

组件通过私有方法将枚举类型映射为具体配置:

private getSizeConfig(): RcButtonSizeConfig {
    switch (this.btnSize) {
        case RcButtonSize.LARGE:
            return { height: 48, fontSize: 16, paddingH: 24, iconSize: 20 }
        case RcButtonSize.SMALL:
            return { height: 32, fontSize: 14, paddingH: 16, iconSize: 16 }
        case RcButtonSize.MINI:
            return { height: 28, fontSize: 12, paddingH: 12, iconSize: 14 }
        case RcButtonSize.NORMAL:
        default:
            return { height: 40, fontSize: 15, paddingH: 20, iconSize: 18 }
    }
}

优势:

• 集中管理尺寸配置，修改方便
• 使用对象返回，扩展性强
• 提供默认分支，确保健壮性

3.2 策略模式

颜色配置采用策略模式，根据不同按钮类型返回对应配置:

private getColorConfig(): RcButtonColorConfig {
    // 优先使用自定义颜色
    if (this.color !== undefined) {
        return { bg: this.color, text: Color.White, border: this.color, activeBg: this.color }
    }
    // 根据类型返回颜色
    switch (this.type) {
        case RcButtonType.PRIMARY:
            return { bg: RcPrimary, text: Color.White, border: RcPrimary, activeBg: RcPrimaryDark }
        // 其他类型...
    }
}

设计特点:

• 支持自定义颜色覆盖预设
• 每种类型有完整的颜色状态
• 包含激活态，提供更好的反馈

3.3 计算属性模式

组件使用大量 getter 方法实现计算属性:

private getButtonWidth(): Length | undefined {
    if (this.btnWidth !== undefined) {
        return this.btnWidth
    }
    return this.block ? '100%' : undefined
}

private getButtonHeight(): Length {
    if (this.btnHeight !== undefined) {
        return this.btnHeight
    }
    return this.getSizeConfig().height
}

优先级规则:

1. 自定义属性优先级最高
2. 特殊状态配置次之 (如 block)
3. 默认配置兜底

这种设计使组件既灵活又有合理的默认行为。

3.4 组合优于继承

组件内部使用 RcIcon 等子组件:

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

通过组合实现复杂功能，而非继承，符合"组合优于继承"原则。

四、状态协调机制

4.1 互斥状态处理

某些状态之间存在互斥关系:

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

状态优先级:

1. disabled 状态最高优先级
2. plain 和 textButton 影响背景透明度
3. 默认使用类型配置

4.2 联动状态

加载状态会影响多个方面:

// 禁用点击
.enabled(!this.disabled && !this.loading)
// 显示加载图标
if (this.loading) {
    LoadingProgress().width(this.iconSize || this.getSizeConfig().iconSize).height(this.iconSize || this.getSizeConfig().iconSize).color(this.getTextColor())
}
// 切换文本
if (this.loading && this.loadingText) {
    Text(this.loadingText)
} else if (this.text) {
    Text(this.text)
}

loading 状态自动:

• 禁用按钮交互
• 隐藏普通图标，显示加载动画
• 支持切换加载文本

4.3 样式状态

使用 stateStyles 定义不同交互状态的样式:

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

状态细分:

• normal: 正常状态
• pressed: 按下状态，实体按钮切换背景色，镂空按钮降低透明度
• disabled: 禁用状态，统一降低透明度

五、设计原则体现

5.1 单一职责原则

每个私有方法职责单一:

• getSizeConfig(): 只负责尺寸配置
• getColorConfig(): 只负责颜色配置
• handleClick(): 只负责点击处理

5.2 开闭原则

组件对扩展开放，对修改封闭:

• 通过枚举类型扩展新的按钮类型
• 通过自定义属性覆盖默认行为
• 无需修改核心逻辑

5.3 依赖倒置原则

组件依赖抽象 (接口) 而非具体实现:

• 依赖 RcButtonSizeConfig 接口而非具体数值
• 依赖 ResourceColor 类型而非具体颜色值
• 通过全局配置注入而非硬编码

5.4 最少知识原则

组件只暴露必要的属性和事件:

• 内部计算逻辑通过 private 方法封装
• 内部状态 (如 lastClickTime) 不对外暴露
• 提供清晰的 API 接口

六、性能优化策略

6.1 计算缓存

尺寸和颜色配置通过方法调用获取，避免不必要的重复计算:

const sizeConfig = this.getSizeConfig()

虽然每次都调用方法，但 switch 语句执行速度很快，且返回的是静态对象。

6.2 条件渲染

根据状态条件渲染不同内容:

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

避免渲染不需要的组件，减少节点数量。

6.3 事件节流

内置节流机制防止重复点击:

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

实现细节:

• 记录上次点击时间
• 在节流时间内的点击直接忽略
• 节流时间可配置，默认为 0(不节流)

七、扩展性设计

7.1 自定义样式支持

组件预留了多个自定义属性:

• btnWidth/btnHeight: 自定义尺寸
• fontSize: 自定义文字大小
• color/textColor/bordersColor: 自定义颜色
• bordersRadius/bordersWidth: 自定义边框
• customStyle: 完全自定义样式对象

7.2 主题系统集成

通过全局配置对接主题系统:

@Local baseStyle: RcUIBaseStyleObjType = AppStorageV2.connect(RcUIBaseStyle, RcStorageKey.BASE_STYLE)!
@Local config: RcGlobalConfig = AppStorageV2.connect(RcGlobalConfig, RcStorageKey.GLOBAL_CONFIG)!

应用可以通过修改全局配置实现:

• 品牌色定制
• 圆角风格调整
• 字体大小适配
• 深色模式切换

7.3 组件组合能力

RcButton 可以与其他组件灵活组合:

• 可以嵌入表单组件
• 可以与对话框配合
• 可以组成按钮组

八、总结

RcButton 组件通过精心的架构设计，实现了:

1. 灵活性: 丰富的配置选项，满足各种使用场景
2. 一致性: 统一的类型系统和样式规范
3. 可维护性: 清晰的代码结构和设计模式
4. 可扩展性: 预留自定义接口，支持主题定制
5. 性能优化: 合理的状态管理和渲染策略

组件的成功在于平衡了易用性和灵活性，既提供了开箱即用的预设样式，又保留了充分的定制空间。这种设计思想值得在其他 UI 组件开发中借鉴。