RcButton 按钮组件

按钮组件，支持多种类型、尺寸、形状以及加载、禁用等状态。

基本用法

import { RcButton, RcButtonType, RcButtonSize, RcButtonShape } from 'rchoui'

@Entry
@Component
struct Index {
  build() {
    Column({ space: 10 }) {
      RcButton({ text: '默认按钮' })
      RcButton({ text: '主要按钮', type: RcButtonType.PRIMARY })
      RcButton({ text: '成功按钮', type: RcButtonType.SUCCESS })
    }
  }
}

导出内容

从 rchoui 包中可以导入以下内容：

组件

• RcButton - 按钮组件

类型/枚举

• RcButtonType - 按钮类型枚举（DEFAULT, PRIMARY, SUCCESS, WARNING, ERROR, INFO）
• RcButtonSize - 按钮尺寸枚举（LARGE, NORMAL, SMALL, MINI）
• RcButtonShape - 按钮形状枚举（SQUARE, ROUND, CIRCLE）

导入示例

// 只导入组件
import { RcButton } from 'rchoui'

// 导入组件和类型
import { RcButton, RcButtonType } from 'rchoui'

// 导入所有相关内容
import { 
  RcButton, 
  RcButtonType, 
  RcButtonSize, 
  RcButtonShape 
} from 'rchoui'

基础使用

按钮类型展示

RcButton提供了6种预设的按钮类型，满足不同场景的视觉需求。

// 导入必要的组件和类型
import { RcButton, RcButtonType } from 'rchoui'

// 使用示例
Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '默认按钮', type: RcButtonType.DEFAULT })
  RcButton({ text: '主要按钮', type: RcButtonType.PRIMARY })
  RcButton({ text: '成功按钮', type: RcButtonType.SUCCESS })
  RcButton({ text: '警告按钮', type: RcButtonType.WARNING })
  RcButton({ text: '错误按钮', type: RcButtonType.ERROR })
  RcButton({ text: '信息按钮', type: RcButtonType.INFO })
}

类型说明：

类型	枚举值	使用场景	视觉特点
默认按钮	RcButtonType.DEFAULT	普通操作、次要功能	灰色系，视觉权重低
主要按钮	RcButtonType.PRIMARY	主要操作、核心功能	蓝色系，视觉权重最高
成功按钮	RcButtonType.SUCCESS	成功提示、确认操作	绿色系，表示正向反馈
警告按钮	RcButtonType.WARNING	警告提示、需谨慎操作	橙色系，提示用户注意
错误按钮	RcButtonType.ERROR	危险操作、删除功能	红色系，强烈警示
信息按钮	RcButtonType.INFO	信息提示、辅助操作	青色系，中性提示

使用建议：

• 一个页面中主要按钮不宜超过2个，保持视觉焦点
• 删除等危险操作使用ERROR类型，并配合二次确认
• 表单提交使用PRIMARY类型，取消使用DEFAULT类型

---

镂空按钮

镂空按钮适用于需要降低视觉权重但仍需保持类型特征的场景。

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '默认镂空', plain: true })
  RcButton({ text: '主要镂空', type: RcButtonType.PRIMARY, plain: true })
  RcButton({ text: '成功镂空', type: RcButtonType.SUCCESS, plain: true })
  RcButton({ text: '细边框', type: RcButtonType.PRIMARY, plain: true, hairline: true })
}

属性说明：

• plain: true - 开启镂空模式，背景透明，显示边框和文字
• hairline: true - 细线边框模式（0.5px），更加精致

镂空按钮特点：

• 背景色变为透明
• 文字颜色使用类型对应的主色
• 边框颜色使用类型对应的主色
• 按压时背景色显示为浅色

应用场景：

• 次要操作按钮（如"取消"按钮）
• 需要并列多个按钮且避免视觉过重
• 在深色背景上需要保持轻盈感

---

文本按钮

文本按钮是视觉权重最低的按钮形式，适合辅助性操作。

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '默认文本', textButton: true })
  RcButton({ text: '主要文本', type: RcButtonType.PRIMARY, textButton: true })
  RcButton({ text: '成功文本', type: RcButtonType.SUCCESS, textButton: true })
  RcButton({ text: '错误文本', type: RcButtonType.ERROR, textButton: true })
}

文本按钮特点：

• 无背景色，无边框
• 仅显示文字，占用空间最小
• 点击态为文字颜色加深

应用场景：

• 导航链接
• 工具栏小操作
• 表格行内操作
• 需要密集排列的操作按钮

---

尺寸控制

预设尺寸

RcButton提供了4种预设尺寸，覆盖常见使用场景。

import { RcButtonSize } from 'rchoui'

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '大号按钮', btnSize: RcButtonSize.LARGE, type: RcButtonType.PRIMARY })
  RcButton({ text: '普通按钮', btnSize: RcButtonSize.NORMAL, type: RcButtonType.PRIMARY })
  RcButton({ text: '小号按钮', btnSize: RcButtonSize.SMALL, type: RcButtonType.PRIMARY })
  RcButton({ text: '迷你按钮', btnSize: RcButtonSize.MINI, type: RcButtonType.PRIMARY })
}

尺寸规格表：

尺寸	枚举值	高度	内边距(横向)	字号	使用场景
大号	RcButtonSize.LARGE	50px	20px	18px	页面主要操作、移动端
普通	RcButtonSize.NORMAL	40px	16px	16px	默认尺寸、通用场景
小号	RcButtonSize.SMALL	32px	12px	14px	工具栏、表格操作
迷你	RcButtonSize.MINI	24px	8px	12px	标签、筛选条件

选择建议：

• 移动端主按钮推荐使用LARGE尺寸，提升可点击性
• 桌面端表单推荐使用NORMAL尺寸
• 数据表格中的操作按钮推荐使用SMALL尺寸
• 标签类按钮推荐使用MINI尺寸

---

自定义尺寸

当预设尺寸不能满足需求时，可以自定义按钮尺寸。

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  // 自定义宽高
  RcButton({
    text: '自定义宽高',
    btnWidth: 200,
    btnHeight: 60,
    type: RcButtonType.PRIMARY
  })

  // 自定义字号
  RcButton({
    text: '大号文字',
    fontSize: 20,
    type: RcButtonType.SUCCESS
  })

  // 完全自定义
  RcButton({
    text: '完全自定义',
    btnWidth: 180,
    btnHeight: 50,
    fontSize: 18,
    bordersRadius: 25,
    color: '#9b59b6'
  })
}

自定义属性说明：

• btnWidth: number - 按钮宽度（单位：vp）
• btnHeight: number - 按钮高度（单位：vp）
• fontSize: number - 文字大小（单位：fp）
• bordersRadius: number - 圆角大小（单位：vp）

注意事项：

• 自定义宽高会覆盖btnSize设置
• 建议高度不低于44px，保证触摸区域足够
• 圆角值不应超过高度的一半（圆形按钮除外）

---

形状变化

三种预设形状

RcButton支持三种形状，满足不同设计风格需求。

import { RcButtonShape } from 'rchoui'

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '方形按钮', shape: RcButtonShape.SQUARE, type: RcButtonType.PRIMARY })
  RcButton({ text: '圆角按钮', shape: RcButtonShape.ROUND, type: RcButtonType.PRIMARY })
  RcButton({ text: '圆', shape: RcButtonShape.CIRCLE, type: RcButtonType.PRIMARY, btnWidth: 50, btnHeight: 50 })
}

形状特点：

形状	枚举值	圆角值	视觉效果	适用场景
方形	RcButtonShape.SQUARE	4px	轻微圆角，现代感	后台管理、数据表格
圆角	RcButtonShape.ROUND	高度的一半	两端圆润，友好感	移动应用、社交类APP
圆形	RcButtonShape.CIRCLE	50%	完全圆形，聚焦感	悬浮按钮、快捷操作

圆形按钮使用建议：

• 必须设置相等的宽高值
• 通常不设置文字，仅显示符号
• 适合作为页面悬浮操作按钮
• 建议尺寸：44×44、56×56、72×72

---

状态控制

禁用状态

禁用状态用于不可操作的场景，保持视觉存在但阻止交互。

Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
  RcButton({ text: '默认禁用', disabled: true })
  RcButton({ text: '主要禁用', type: RcButtonType.PRIMARY, disabled: true })
  RcButton({ text: '镂空禁用', type: RcButtonType.PRIMARY, plain: true, disabled: true })
  RcButton({ text: '文本禁用', type: RcButtonType.PRIMARY, textButton: true, disabled: true })
}

禁用效果：

• 按钮不可点击
• 颜色变淡（透明度降低）
• 鼠标悬停无效果
• 不触发点击事件

典型应用场景：

@Component
struct FormExample {
  @State username: string = ''
  @State password: string = ''
  
  build() {
    Column({ space: 20 }) {
      TextInput({ placeholder: '请输入用户名' })
        .onChange((value) => this.username = value)
      
      TextInput({ placeholder: '请输入密码', type: InputType.Password })
        .onChange((value) => this.password = value)
      
      // 根据表单验证结果动态控制禁用状态
      RcButton({
        text: '登录',
        type: RcButtonType.PRIMARY,
        block: true,
        disabled: !this.username || !this.password,
        onBtnClick: () => {
          console.log('执行登录')
        }
      })
    }
  }
}

---

加载状态

加载状态用于异步操作，提供视觉反馈，提升用户体验。

@Component
struct LoadingExample {
  @State loadingState: boolean = false
  
  build() {
    Flex({ wrap: FlexWrap.Wrap, space: {main: LengthMetrics.px(10), cross: LengthMetrics.px(10)} }) {
      // 静态加载状态
      RcButton({ text: '加载按钮', loading: true, type: RcButtonType.PRIMARY })
      
      // 自定义加载文字
      RcButton({ loadingText: '加载中...', loading: true, type: RcButtonType.SUCCESS })
      
      // 仅显示加载动画
      RcButton({ loading: true, type: RcButtonType.WARNING })
      
      // 动态控制加载状态
      RcButton({
        text: this.loadingState ? '加载中...' : '点击加载',
        loading: this.loadingState,
        type: RcButtonType.PRIMARY,
        onBtnClick: () => {
          this.loadingState = true
          setTimeout(() => {
            this.loadingState = false
          }, 2000)
        }
      })
    }
  }
}

加载状态特点：

• 显示旋转的加载动画
• 自动禁用按钮，阻止重复点击
• 可自定义加载时的文字提示
• 符号自动隐藏（避免布局冲突）

API

Props 属性

参数	说明	类型	默认值	可选值
text	按钮文本	string	''	-
type	按钮类型	RcButtonType	DEFAULT	DEFAULT/PRIMARY/SUCCESS/WARNING/ERROR/INFO
btnSize	按钮尺寸	RcButtonSize	NORMAL	LARGE/NORMAL/SMALL/MINI
shape	按钮形状	RcButtonShape	SQUARE	SQUARE/ROUND/CIRCLE
plain	是否镂空按钮	boolean	false	true/false
textButton	是否文本按钮	boolean	false	true/false
disabled	是否禁用	boolean	false	true/false
loading	是否加载中	boolean	false	true/false
loadingText	加载文本	string	''	-
icon	前置图标	ResourceStr	''	图标名称或路径
iconSize	图标大小	RcStringNumber	根据btnSize自动计算	-
color	自定义背景色	ResourceColor	undefined	任意颜色值
textColor	自定义文字颜色	ResourceColor	undefined	任意颜色值
bordersColor	自定义边框颜色	ResourceColor	undefined	任意颜色值
btnWidth	自定义宽度	Length	undefined	数值或百分比
btnHeight	自定义高度	Length	undefined	数值或百分比
fontSize	自定义文字大小	RcStringNumber	根据btnSize自动计算	-
bordersRadius	自定义圆角	Length	根据shape自动计算	-
bordersWidth	自定义边框宽度	Length	undefined	-
hairline	是否细边框(plain模式)	boolean	false	true/false
block	是否块级按钮(100%宽)	boolean	false	true/false
customStyle	自定义样式	Record<string, string | number>	{}	-
throttleTime	点击节流时间(ms)	number	0	-

Events 事件

事件名	说明	回调参数
onBtnClick	点击事件	(event: ClickEvent) => void

尺寸说明

尺寸	高度	字体大小	水平内边距	图标大小
LARGE	48px	16px	24px	20px
NORMAL	40px	15px	20px	18px
SMALL	32px	14px	16px	16px
MINI	28px	12px	12px	14px

相关文档

• RcButton组件核心架构与设计思想解析
• RcButton组件样式系统深度剖析
• RcButton组件交互逻辑与事件处理机制