按钮
按钮允许用户执行操作并通过单击进行选择。
安装
npx nextui-cli@latest add button
上述命令仅用于单独安装。如果@nextui-org/react
已全局安装,则可以跳过此步骤。
导入
NextUI 导出了 2 个与按钮相关的组件
- Button:显示按钮的主要组件。
- ButtonGroup:显示一组按钮的包装组件。
用法
已禁用
尺寸
半径
颜色
变体
加载
传递 isLoading
属性以在按钮内显示 Spinner 组件。
您还可以通过将自定义组件传递给 spinner
属性来自定义加载 spinner。
带有图标
您可以通过传递 startContent
或 endContent
属性将图标添加到 Button
中。
仅图标
您还可以通过传递 isIconOnly
属性和所需的图标作为 children
来显示没有文本的按钮。
自定义样式
可以通过向组件插槽传递自定义 Tailwind CSS 类来定制 Button
组件。
由于 Tailwind Merge 库,自定义类名将覆盖默认类名。这意味着您不必担心类冲突。
自定义实现
您还可以使用 useButton
钩子来创建自己的按钮组件。
按钮组
组禁用
ButtonGroup
组件还接受 isDisabled
属性以禁用其中的所有按钮。
组用例
ButtonGroup
组件的常见用例是显示一组两个按钮,一个用于选定的值,另一个用于 下拉菜单
。
有关更多详细信息,请参阅 下拉菜单 组件。
数据属性
Button
在 base
元素上具有以下属性
- data-hover:当按钮被悬停时。基于 useHover
- data-focus:当按钮被聚焦时。基于 useFocusRing。
- data-focus-visible:当按钮使用键盘聚焦时。基于 useFocusRing。
- data-disabled:当按钮被禁用时。基于
isDisabled
属性。 - data-pressed:当按钮被按下时。基于 usePress
- data-loading:当按钮正在加载时。基于
isLoading
属性。
辅助功能
- 按钮的角色为
button
。 - 键盘事件支持 空格 和 回车 键。
- 鼠标和触摸事件处理,以及按下状态管理。
- 键盘焦点管理和跨浏览器规范化。
我们推荐阅读这篇 博客文章,了解在各种设备和交互方式下构建按钮的复杂性。
API
按钮属性
属性 | 类型 | 描述 | 默认值 |
---|---|---|---|
children | ReactNode | 按钮中显示的内容。 | - |
variant | solid | bordered | light | flat | faded | shadow | ghost | 按钮外观样式。 | solid |
color | default | primary | secondary | success | warning | danger | 按钮颜色主题。 | default |
size | sm | md | lg | 按钮大小。 | md |
radius | none | sm | md | lg | full | 按钮边框半径。 | - |
startContent | ReactNode | 按钮开始内容。 | - |
endContent | ReactNode | 按钮结束内容。 | - |
spinner | ReactNode | 加载时显示的旋转器。 | - |
spinnerPlacement | start | end | 旋转器位置。 | start |
fullWidth | boolean | 按钮是否应采用其父元素的全部宽度。 | false |
isIconOnly | boolean | 按钮是否应具有相同的宽度和高度。 | false |
isDisabled | boolean | 按钮是否已禁用。 | false |
isLoading | boolean | 按钮是否正在加载。 | false |
disableRipple | boolean | 按钮是否应在按下时显示波纹效果。 | false |
disableAnimation | boolean | 按钮是否应显示动画。 | false |
按钮事件
属性 | 类型 | 描述 |
---|---|---|
onPress | (e: PressEvent) => void | 在目标上释放按下时调用的处理程序。 |
onPressStart | (e: PressEvent) => void | 按下交互开始时调用的处理程序。 |
onPressEnd | (e: PressEvent) => void | 按下交互结束时调用的处理程序,无论是在目标上还是指针离开目标时。 |
onPressChange | (isPressed: boolean) => void | 按下状态更改时调用的处理程序。 |
onPressUp | (e: PressEvent) => void | 在目标上释放按下时调用的处理程序,无论它是否从目标开始。 |
onKeyDown | (e: KeyboardEvent) => void | 按下某个键时调用的处理程序。 |
onKeyUp | (e: KeyboardEvent) => void | 释放某个键时调用的处理程序。 |
onClick | MouseEventHandler | 本机按钮单击事件处理程序 (已弃用) 使用 onPress 代替。 |
按钮组属性
属性 | 类型 | 描述 | 默认值 |
---|---|---|---|
children | ReactNode | ReactNode[] | 要显示的按钮。 | - |
variant | solid | bordered | light | flat | faded | shadow | ghost | 按钮外观样式。 | solid |
color | default | primary | secondary | success | warning | danger | 按钮颜色主题。 | default |
size | sm | md | lg | 按钮大小。 | md |
radius | none | sm | md | lg | full | 按钮边框半径。 | xl |
fullWidth | boolean | 按钮是否应采用全宽。 | false |
isDisabled | boolean | 按钮是否禁用。 | false |