> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/button.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Button 按钮

触发保存、提交或删除等操作。


## 基础用法

按钮文字应清楚描述操作，点击事件通过 `onClick` 处理。


保存

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/basic.tsx"
import { Button } from '@ifhover/leaf-ui';

export function ButtonBasic() {
  return <Button>保存</Button>;
}
```

展开代码

默认 `type="button"`，不会提交表单。需要提交时，请设置 `type="submit"`。


## 示例

### 按钮外观

通过 `variant` 选择外观：默认描边、实底、文字或行内链接。行内链接默认使用主题色，悬停时文字变亮，按下时变深，默认颜色过渡为 200ms。


描边

保存

实底

保存

文字

保存

链接

保存

variants.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/variants.tsx"
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'outline', label: '描边' },
  { value: 'solid', label: '实底' },
  { value: 'text', label: '文字' },
  { value: 'link', label: '链接' },
] as const;

export function ButtonVariants() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button variant={value}>保存</Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 尺寸

通过 `size` 设置尺寸，默认为 `md`。


小

保存

中

保存

大

保存

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/sizes.tsx"
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function ButtonSizes() {
  return (
    <Grid gap={16} align="center" style={{ gridTemplateColumns: 'max-content minmax(0, 1fr)' }}>
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button size={value}>保存</Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 危险操作

设置 `danger` 表示删除、清空等危险操作，可搭配任意外观。


描边

删除

实底

删除

文字

删除

链接

删除

danger.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/danger.tsx"
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'outline', label: '描边' },
  { value: 'solid', label: '实底' },
  { value: 'text', label: '文字' },
  { value: 'link', label: '链接' },
] as const;

export function ButtonDanger() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button danger variant={value}>
              删除
            </Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 禁用与加载

`disabled` 禁用按钮；`loading` 显示加载指示器并阻止重复点击。


禁用

保存

加载

保存

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/states.tsx"
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function ButtonStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">禁用</Text>
      <Flex align="center" wrap>
        <Button disabled>保存</Button>
      </Flex>
      <Text tone="muted">加载</Text>
      <Flex align="center" wrap>
        <Button loading>保存</Button>
      </Flex>
    </Grid>
  );
}
```

展开代码

### 图标

通过 `startIcon` 和 `endIcon` 添加图标。只有图标时，必须提供 `aria-label`。


小

新建项目继续下一步

中

新建项目继续下一步

大

新建项目继续下一步

icons.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/icons.tsx"
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { ArrowRight, Plus, Trash2 } from 'lucide-react';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function ButtonIcons() {
  return (
    <Grid gap={16} align="center" style={{ gridTemplateColumns: 'max-content minmax(0, 1fr)' }}>
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" gap={8} wrap>
            <Button size={value} startIcon={<Plus />}>
              新建项目
            </Button>
            <Button size={value} variant="outline" endIcon={<ArrowRight />}>
              继续下一步
            </Button>
            <Button size={value} variant="outline" aria-label="添加项目" startIcon={<Plus />} />
            <Button
              size={value}
              danger
              variant="outline"
              aria-label="删除项目"
              startIcon={<Trash2 />}
            />
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 整行显示

设置 `fullWidth`，让按钮填满父容器。


继续下一步

full-width.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/full-width.tsx"
import { Button } from '@ifhover/leaf-ui';

export function ButtonFullWidth() {
  return <Button fullWidth>继续下一步</Button>;
}
```

展开代码

### 异步保存

[](#)
通过应用状态控制 `loading`。示例使用定时器模拟请求，实际使用时替换为业务异步操作。


保存更改尚未保存

loading.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/loading.tsx"
import { Button, Flex, Text } from '@ifhover/leaf-ui';
import { useEffect, useRef, useState } from 'react';

export function ButtonLoading() {
  const [status, setStatus] = useState<'idle' | 'loading' | 'saved'>('idle');
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  useEffect(() => () => clearTimeout(timer.current), []);

  function save() {
    clearTimeout(timer.current);
    setStatus('loading');
    // 示例模拟一次异步保存；实际使用时替换成你的业务请求。
    timer.current = setTimeout(() => setStatus('saved'), 1200);
  }

  return (
    <Flex direction="column" gap="md" align="start">
      <Button loading={status === 'loading'} onClick={save}>
        {status === 'saved' ? '再次保存' : '保存更改'}
      </Button>
      <Text tone="muted" role="status">
        {status === 'saved' ? '更改已保存' : '尚未保存'}
      </Text>
    </Flex>
  );
}
```

展开代码

### 按钮组

使用 `ButtonGroup` 连接相邻操作，并统一配置尺寸或禁用状态。


上一步下一步

button-group.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/button-group.tsx"
import { Button, ButtonGroup } from '@ifhover/leaf-ui';

export function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="步骤操作">
      <Button>上一步</Button>
      <Button>下一步</Button>
    </ButtonGroup>
  );
}
```

展开代码

### 分裂按钮

`SplitButton` 将主要操作和相关菜单放在一起；主按钮使用 `onClick`，菜单项分别提供自己的操作。


保存

split-button.tsx

复制代码

```tsx lineNumbers file="../../src/examples/button/split-button.tsx"
import { Flex, SplitButton, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function SplitButtonDemo() {
  const [result, setResult] = useState('');

  return (
    <Flex direction="column" gap="md" align="start">
      <SplitButton
        variant="solid"
        onClick={() => setResult('已保存')}
        menuLabel="更多保存方式"
        items={[
          { key: 'copy', label: '保存副本', onClick: () => setResult('副本已保存') },
          { key: 'draft', label: '存为草稿', onClick: () => setResult('草稿已保存') },
        ]}
      >
        保存
      </SplitButton>
      <Text tone="muted" role="status">
        {result}
      </Text>
    </Flex>
  );
}
```

展开代码


## API

### Button API

支持 `onClick`、`name`、`form`、`aria-*`、`data-*` 等原生 `button` 属性。

| 属性          | 类型                                         | 默认值         | 说明                    |
| ----------- | ------------------------------------------ | ----------- | --------------------- |
| `variant`   | `'solid' \| 'outline' \| 'text' \| 'link'` | `'outline'` | 视觉样式                  |
| `size`      | `'sm' \| 'md' \| 'lg'`                     | `'md'`      | 按钮尺寸                  |
| `danger`    | `boolean`                                  | `false`     | 使用红色危险语义，支持所有 variant |
| `loading`   | `boolean`                                  | `false`     | 显示加载指示器并禁用交互          |
| `fullWidth` | `boolean`                                  | `false`     | 填满父容器宽度               |
| `startIcon` | `ReactNode`                                | —           | 文字前的图标，加载时由指示器替代      |
| `endIcon`   | `ReactNode`                                | —           | 文字后的图标                |
| `disabled`  | `boolean`                                  | `false`     | 禁用交互。                 |
| `type`      | `'button' \| 'submit' \| 'reset'`          | `'button'`  | 原生按钮类型                |
| `ref`       | `Ref<HTMLButtonElement>`                   | —           | 按钮 DOM 引用             |

### ButtonGroupProps API

用于组合一组相关按钮的参数。

| 属性         | 类型                     | 默认值    | 说明     |
| ---------- | ---------------------- | ------ | ------ |
| `size`     | `'sm' \| 'md' \| 'lg'` | —      | 按钮尺寸   |
| `disabled` | `boolean`              | —      | 禁用交互。  |
| `attached` | `boolean`              | `true` | 连接相邻按钮 |

### SplitButtonProps API

主操作与下拉操作组合按钮的参数。

| 属性              | 类型                                                                                                                                      | 默认值         | 说明                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------- |
| `variant`       | `'solid' \| 'outline' \| 'text' \| 'link'`                                                                                              | `'outline'` | 按钮样式              |
| `size`          | `'sm' \| 'md' \| 'lg'`                                                                                                                  | `'md'`      | 按钮尺寸。             |
| `danger`        | `boolean`                                                                                                                               | `false`     | 危险操作颜色            |
| `loading`       | `boolean`                                                                                                                               | `false`     | 加载状态              |
| `fullWidth`     | `boolean`                                                                                                                               | `false`     | 占满宽度              |
| `startIcon`     | `ReactNode`                                                                                                                             | —           | 前置图标              |
| `endIcon`       | `ReactNode`                                                                                                                             | —           | 后置图标              |
| `items`         | `readonly `[`DropdownItem`](https://ifhover.github.io/leaf-ui/components/dropdown.md#dropdownitem)`[]`                                  | 必填          | 数据项目，保持 key 唯一且稳定 |
| `menuLabel`     | `string`                                                                                                                                | —           | 菜单按钮的可访问名称        |
| `dropdownProps` | `Omit<`[`DropdownProps`](https://ifhover.github.io/leaf-ui/components/dropdown.md#dropdown-api)`, 'items' \| 'children' \| 'disabled'>` | —           | 操作菜单属性            |
