基础 · Button
按钮
用户使用按钮来触发一个操作或者进行跳转。

代码演示

如何引入

按钮类型

按钮支持以下类型:
  • 主按钮("primary",默认)
  • 次要按钮("secondary")
  • 第三按钮("tertiary")
  • 警告按钮("warning")
  • 危险按钮("danger")

关于类型字体色值

按钮的字体色值使用的都是 CSS Variables,分别为:
  • var(--semi-color-primary):主要
  • var(--semi-color-secondary):次要
  • var(--semi-color-tertiary):第三
  • var(--semi-color-warning):警告
  • var(--semi-color-danger):危险
你可以直接使用这些主题色定义你的元素。

按钮主题

目前可用的主题(theme)为:
  • light:浅色背景
  • solid:深色背景
  • borderless:无背景
  • outline: 边框模式
默认的主题为 light

浅色背景

深色背景

无背景

边框模式

尺寸

默认定义了三种尺寸:
  • 大:"large"
  • 默认:"default"
  • 小:"small"

块级按钮

块级按钮具有预先定义好的宽度,它的宽度与按钮里面内容的宽度无关。

图标按钮

可定义按钮的图标。

链接按钮

我们推荐使用 Typography 的 link 属性来实现链接型的文字按钮,具体用法详见Typography

禁用状态

加载状态

按钮支持加载状态,通过设置 loading 参数值为 true 即可,注意:disabled 状态优先级高于 loading 状态。

按钮组合

可以将多个按钮放入ButtonGroup的容器中,通过设置sizedisabledtype可统一设置按钮组合中的按钮尺寸,是否禁用和类型。

组合尺寸

组合禁用

组合类型

分裂按钮组合

V1.12.0新增
ButtonDropdown结合的场景下,可以使用分裂按钮,分裂按钮添加了按钮之间的间隔,并改变了按钮的边框圆角

基础使用

API 参考

Button

属性说明类型默认值
aria-label按钮的标签string-
block将按钮设置为块级按钮boolfalse
className类名string
contentClassName内容区域 classNamestring
disabled禁用状态booleanfalse
htmlType设置 button 原生的 type 值,可选值:buttonresetsubmitstring"button"
icon图标ReactNode
iconPosition图标位置,可选值:left|rightstringleft
loading加载状态booleanfalse
noHorizontalPadding设置水平方向是否去掉内边距,只对设置了 icon 的 Button 有效。可选值:true(等效于 ["left", "right"]),"left","right",["left", "right"]boolean|string|Array<string>false
size按钮大小,可选值:largedefaultsmallstring"default"
style自定义样式CSSProperties
theme按钮主题,可选值:solid(有背景色)、 borderless(无背景色)、 light(浅背景色)、outline(边框模式)string"light"
type类型,可选值:primarysecondarytertiarywarningdangerstring"primary"
onClick单击事件function(MouseEvent)
onMouseDown鼠标按下事件function(MouseEvent)
onMouseEnter鼠标移入事件function(MouseEvent)
onMouseLeave鼠标移出事件function(MouseEvent)

ButtonGroup

属性说明类型默认值版本
aria-label按钮组的标签string-
className自定义类名string-
disabled禁用状态booleanfalse
size按钮大小,可选值:largedefaultsmallstring"default"
style自定义样式CSSProperties-2.20.0
theme按钮主题,可选值:solid(有背景色)、 borderless(无背景色)、 light(浅背景色)、outline(边框模式)string"light"
type类型,可选值:primarysecondarytertiarywarningdangerstring"primary"

SplitButtonGroup V1.12.0新增

属性说明类型默认值
aria-label分裂按钮组的标签string-
className自定义类名string-
style自定义样式CSSProperties-

Accessibility

ARIA

  • aria-label 用于表示按钮的作用,对于图标按钮,我们推荐使用此属性
  • aria-disabled 与 disabled 属性同步,表示按钮禁用

键盘和焦点

  • Button 的焦点管理与原生 button 一致,键盘用户可以使用 Tab 及 Shift + Tab 切换焦点
  • Button 的触发与原生 button 一致,当按钮聚焦时,可以通过 Enter 或 Space 键激活
  • ButtonGroup 中的按钮与单个按钮的焦点管理方式一致,可以通过 Tab 以及 Shift + Tab 进行切换

文案规范

  • 按钮需要清晰可预测,用户应该能够预测他们点击按钮时会发生什么
  • 按钮应该总是以鼓励行动的强动词开头
  • 为了给用户提供足够的上下文,在按钮上使用 {动词}+{名词} 内容公式;除了常见的动作,如“Done”、“Close”、“Cancel”或“OK”
✅ 推荐用法❌ 不推荐用法
No permission to view this page
No permission to view this page
  • 当按钮和其他组件一起时候,如果其他组件(比如 Modal 和Sidesheet)已经提供了足够信息的上下文的话,按钮可以只展示 {动词},如“Add”、“Create”;
✅ 推荐用法❌ 不推荐用法
  • 始终按句子大小写(Sentence case)原则书写
✅ 推荐用法❌ 不推荐用法
Create projectCreate
Create a project
Edit profileEdit

设计变量

FAQ

  • 为什么Button中的icon属性不起作用?

    请检查你的Button import路径,正确的import路径应该为import { Button } from '@douyinfe/semi-ui;',如果你错误地从 @douyinfe/semi-ui/button/button中import的话,获取到的是不带icon功能的基础Button组件