Button 按钮

按钮组件用于触发一个即时操作，支持多种样式和状态。

适用场景：需要一个开箱即用的可点击操作控件，自带 primary/contrast/warning/text 样式，还支持禁用状态和图标时，用 <r-button> 代替手写 <button> 样式。

快速开始

基础用法

<r-button>Button</r-button>

API 参考

属性

按钮类型 type

按钮支持五种不同的类型，适用于不同的场景

<r-button type="primary">主要按钮</r-button>
<r-button type="warning">警告按钮</r-button>
<r-button type="text">文本按钮</r-button>
<r-button>默认按钮</r-button>

primary 是单色（无彩色）操作按钮，来自 Geist 设计语言：浅色模式下黑底白字，深色模式下白底黑字。蓝色在这里不承担品牌色的角色，只留给链接和聚焦环使用。它用的是 --ran-color-primary* 令牌（--ran-color-primary、-hover、-active，以及作为反色墨水的 --ran-color-primary-text），详见 Theme 主题与令牌。

禁用状态 disabled

添加 disabled 属性可以让按钮处于不可用状态，同时按钮样式也会相应改变

<r-button type="primary" disabled>主要按钮</r-button>
<r-button type="warning" disabled>警告按钮</r-button>
<r-button type="text" disabled>文本按钮</r-button>
<r-button disabled>默认按钮</r-button>

图标按钮 icon

可以通过 icon 属性为按钮添加图标，或者直接在按钮内使用 Icon 组件

💡 提示：如果需要控制图标的具体位置，建议直接使用 Icon 组件而不是 icon 属性

<r-button type="default" icon="user">默认按钮</r-button> <r-button type="primary" icon="home">主要按钮</r-button>

特效控制 effect

点击水波纹默认开启。想要纯净的按钮样式，设置 effect="false" 关掉它。下面两个按钮只有这一个属性不同，分别点一下就能看出区别。水波纹是指针设备上的效果，视口宽度 1024px 以上才会绘制。

<r-button type="primary" icon="home">默认：有水波纹</r-button>
<r-button type="primary" icon="home" effect="false">effect="false"：无水波纹</r-button>

只有字面值 false 会关闭水波纹，effect="true" 和其他任何值都保持开启。在脚本里请按布尔值设置属性值： button.effect = false。

事件

按钮支持标准的点击事件处理。

<r-button onclick="handleClick()">点击我</r-button>

<script>
  function handleClick() {
    console.log('按钮被点击了');
  }
</script>

自定义样式

<r-button> 自身暴露了 43 个 CSS 自定义属性：--ran-btn-background、--ran-btn-color、 --ran-btn-border-color 及其 hover / active 变体，再加上 warning 变体的三个；另外还会读取主题里的语义令牌。

/* 单个按钮，或某个作用域下的所有按钮 */
r-button {
  --ran-btn-background: var(--ran-color-bg-subtle);
  --ran-btn-hover-background: var(--ran-color-bg-hover);
  --ran-btn-border-radius: var(--ran-radius-full);
}

如果这次改动并非按钮独有，优先改语义令牌：覆盖 --ran-color-primary 会重塑所有地方的主操作，而不只是这里。

Part：button · content

r-button::part(content) {
  letter-spacing: 0.02em;
}

完整清单见样式令牌；该选哪个令牌见 设计系统。

最佳实践

• 主要操作：使用 type="primary" 的按钮（单色，浅色模式黑底白字，深色模式白底黑字）
• 危险操作：使用 type="warning" 的按钮
• 次要操作：使用 type="text" 的按钮
• 禁用状态：在操作不可用时使用 disabled 属性
• 图标使用：为按钮添加相关图标可以提升用户体验