Button 按钮更新
可点击的按钮组件，支持多种变体与状态。
引入
import { Button } from '@heroui/react';用法
"use client";
import {Button} from "@heroui/react";
export function Basic() {
return <Button onPress={() => console.log("按钮已按下")}>点我</Button>;
}变体
import {Button} from "@heroui/react";
export function Variants() {
return (
<div className="flex flex-wrap gap-3">带图标
import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function WithIcons() {
return (仅图标
import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function IconOnly() {
return (加载中
"use client";
import {Button, Spinner} from "@heroui/react";
import React from "react";
加载状态
"use client";
import {Paperclip} from "@gravity-ui/icons";
import {Button, Spinner} from "@heroui/react";
import React, {useState} from "react";尺寸
import {Button} from "@heroui/react";
export function Sizes() {
return (
<div className="flex items-center gap-3">全宽
import {Plus} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function FullWidth() {
return (禁用状态
import {Button} from "@heroui/react";
export function Disabled() {
return (
<div className="flex flex-wrap gap-3">社交按钮
import {Button} from "@heroui/react";
import {Icon} from "@iconify/react";
export function Social() {
return (自定义渲染函数
"use client";
import {Button} from "@heroui/react";
export function CustomRenderFunction() {样式
传入 Tailwind CSS 类
import { Button } from '@heroui/react';
function CustomButton() {
return (
<Button className="bg-purple-500 text-white hover:bg-purple-600">
Purple Button
</Button>
);
}自定义组件类
若要自定义 Button 组件类，可以使用 @layer components 指令。
了解更多。
@layer components {
.button {
@apply bg-purple-500 text-white hover:bg-purple-600;
}
.button--icon-only {
@apply rounded-lg bg-blue-500;
}
}HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。
添加自定义变体
你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。
import type {ButtonProps} from "@heroui/react";
import type {VariantProps} from "tailwind-variants";
import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";添加涟漪效果
Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 m3-ripple。
"use client";
import {Button} from "@heroui/react";
import {Ripple} from "m3-ripple";
CSS 类
Button 组件使用以下 CSS 类（查看源码样式）：
基础与尺寸类
.button- 按钮基础样式.button--sm- 小尺寸变体.button--md- 中尺寸变体.button--lg- 大尺寸变体
变体类
.button--primary.button--secondary.button--tertiary.button--outline.button--ghost.button--danger
修饰符类
.button--icon-only.button--icon-only.button--sm.button--icon-only.button--lg
交互状态
该按钮同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
- 悬停：
:hover或[data-hovered="true"] - 激活/按压：
:active或[data-pressed="true"]（包含缩放变换） - 聚焦：
:focus-visible或[data-focus-visible="true"]（显示焦点环） - 禁用：
:disabled或[aria-disabled="true"]（降低透明度，禁用指针事件） - 等待中：
[data-pending]（加载期间禁用指针事件）
API 参考
Button Props
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
variant | 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost' | 'danger' | 'primary' | 视觉样式变体 |
size | 'sm' | 'md' | 'lg' | 'md' | 按钮尺寸 |
fullWidth | boolean | false | 按钮是否占满容器宽度 |
isDisabled | boolean | false | 按钮是否禁用 |
isPending | boolean | false | 按钮是否处于加载状态 |
isIconOnly | boolean | false | 按钮是否仅包含图标 |
onPress | (e: PressEvent) => void | - | 按钮被按下时的事件处理函数 |
children | React.ReactNode | (values: ButtonRenderProps) => React.ReactNode | - | 按钮内容或渲染 prop |
render | DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps> | - | 使用自定义渲染函数覆盖默认 DOM 元素。 |
ButtonRenderProps
使用渲染 prop 模式时，会提供以下值：
| Prop | 类型 | 描述 |
|---|---|---|
isPending | boolean | 按钮是否处于加载状态 |
isPressed | boolean | 按钮当前是否被按压 |
isHovered | boolean | 按钮是否处于悬停状态 |
isFocused | boolean | 按钮是否处于聚焦状态 |
isFocusVisible | boolean | 按钮是否应显示焦点指示 |
isDisabled | boolean | 按钮是否禁用 |
