按钮

按钮允许用户执行操作并通过单击进行选择。


安装

npx nextui-cli@latest add button
上述命令仅用于单独安装。如果@nextui-org/react已全局安装,则可以跳过此步骤。

导入

NextUI 导出了 2 个与按钮相关的组件

  • Button:显示按钮的主要组件。
  • ButtonGroup:显示一组按钮的包装组件。

用法

已禁用

尺寸

半径

颜色

变体

加载

传递 isLoading 属性以在按钮内显示 Spinner 组件。

您还可以通过将自定义组件传递给 spinner 属性来自定义加载 spinner。

带有图标

您可以通过传递 startContentendContent 属性将图标添加到 Button 中。

仅图标

您还可以通过传递 isIconOnly 属性和所需的图标作为 children 来显示没有文本的按钮。

自定义样式

可以通过向组件插槽传递自定义 Tailwind CSS 类来定制 Button 组件。

由于 Tailwind Merge 库,自定义类名将覆盖默认类名。这意味着您不必担心类冲突。

自定义实现

您还可以使用 useButton 钩子来创建自己的按钮组件。

按钮组

组禁用

ButtonGroup 组件还接受 isDisabled 属性以禁用其中的所有按钮。

组用例

ButtonGroup 组件的常见用例是显示一组两个按钮,一个用于选定的值,另一个用于 下拉菜单

有关更多详细信息,请参阅 下拉菜单 组件。

数据属性

Buttonbase 元素上具有以下属性

  • data-hover:当按钮被悬停时。基于 useHover
  • data-focus:当按钮被聚焦时。基于 useFocusRing
  • data-focus-visible:当按钮使用键盘聚焦时。基于 useFocusRing
  • data-disabled:当按钮被禁用时。基于 isDisabled 属性。
  • data-pressed:当按钮被按下时。基于 usePress
  • data-loading:当按钮正在加载时。基于 isLoading 属性。

辅助功能

  • 按钮的角色为 button
  • 键盘事件支持 空格回车 键。
  • 鼠标和触摸事件处理,以及按下状态管理。
  • 键盘焦点管理和跨浏览器规范化。

我们推荐阅读这篇 博客文章,了解在各种设备和交互方式下构建按钮的复杂性。

API

按钮属性

属性类型描述默认值
childrenReactNode按钮中显示的内容。-
variantsolid | bordered | light | flat | faded | shadow | ghost按钮外观样式。solid
colordefault | primary | secondary | success | warning | danger按钮颜色主题。default
sizesm | md | lg按钮大小。md
radiusnone | sm | md | lg | full按钮边框半径。-
startContentReactNode按钮开始内容。-
endContentReactNode按钮结束内容。-
spinnerReactNode加载时显示的旋转器。-
spinnerPlacementstart | end旋转器位置。start
fullWidthboolean按钮是否应采用其父元素的全部宽度。false
isIconOnlyboolean按钮是否应具有相同的宽度和高度。false
isDisabledboolean按钮是否已禁用。false
isLoadingboolean按钮是否正在加载。false
disableRippleboolean按钮是否应在按下时显示波纹效果。false
disableAnimationboolean按钮是否应显示动画。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释放某个键时调用的处理程序。
onClickMouseEventHandler本机按钮单击事件处理程序 (已弃用) 使用 onPress 代替。

按钮组属性

属性类型描述默认值
childrenReactNode | ReactNode[]要显示的按钮。-
variantsolid | bordered | light | flat | faded | shadow | ghost按钮外观样式。solid
colordefault | primary | secondary | success | warning | danger按钮颜色主题。default
sizesm | md | lg按钮大小。md
radiusnone | sm | md | lg | full按钮边框半径。xl
fullWidthboolean按钮是否应采用全宽。false
isDisabledboolean按钮是否禁用。false