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

# Button 按钮

通用`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

触发提交、保存、打开界面等即时操作。

## 代码演示


### 变体
每个视图或决策区域只保留一个主操作。Secondary、ghost 与 destructive 变体用于降低或明确操作层级。Bare 保留按钮行为，同时把视觉样式交给消费方的 class 或 style。
```tsx preview
import { Button } from '@rockshin/tao-ui';

function ButtonVariants() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button>Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="bare">Bare</Button>
      <Button variant="destructive">Delete</Button>
    </div>
  );
}

export default ButtonVariants;
```

### 尺寸
密集工具栏使用 `small`，常规操作使用 `medium`，需要突出时使用 `large`。
```tsx preview
import { Button } from '@rockshin/tao-ui';

function ButtonSizes() {
  return (
    <div
      style={{
        display: 'flex',
        flexWrap: 'wrap',
        alignItems: 'center',
        gap: 12,
      }}
    >
      <Button size="small">Small</Button>
      <Button>Medium</Button>
      <Button size="large">Large</Button>
    </div>
  );
}

export default ButtonSizes;
```

### 加载与禁用
加载按钮会设置 `aria-busy` 并阻止重复操作。图标插槽始终挂载，因此状态切换不会造成内容位移。
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';

function ButtonStates() {
  const [saving, setSaving] = useState(false);

  function save() {
    setSaving(true);
    window.setTimeout(() => setSaving(false), 1200);
  }

  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button loading>Loading</Button>
      <Button loading variant="secondary">
        Loading
      </Button>
      <Button disabled>Disabled</Button>
      <Button loading={saving} onClick={save}>
        Save changes
      </Button>
    </div>
  );
}

export default ButtonStates;
```

### 图标与自定义加载
通过 `icon` 传入装饰性前置图标。SVG 的显式宽高会被保留；未指定的宽高默认为按钮字号。只有内置 spinner 不符合周围视觉语言时才使用 `loadingIcon`。
```tsx preview
import { Button } from '@rockshin/tao-ui';

function DownloadIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M8 2v8m0 0 3-3m-3 3L5 7M3 13h10"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function ProgressIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
      <circle cx="3" cy="8" r="1.25" />
      <circle cx="8" cy="8" r="1.25" opacity="0.65" />
      <circle cx="13" cy="8" r="1.25" opacity="0.35" />
    </svg>
  );
}

function ButtonIcons() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
      <Button icon={<DownloadIcon />}>Download</Button>
      <Button variant="secondary" icon={<DownloadIcon />}>
        Export
      </Button>
      <Button loading loadingIcon={<ProgressIcon />}>
        Processing
      </Button>
    </div>
  );
}

export default ButtonIcons;
```

### Provider 默认值
Button 会从 `TaoProvider` 继承 `size` 与 `disabled`，局部属性可以覆盖继承的尺寸。
```tsx preview
import { Button, TaoProvider } from '@rockshin/tao-ui';

function ButtonProviderDefaults() {
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <div
        style={{
          display: 'flex',
          flexWrap: 'wrap',
          alignItems: 'center',
          gap: 12,
        }}
      >
        <TaoProvider size="small">
          <Button>Inherited small</Button>
          <Button size="large" variant="secondary">
            Local large
          </Button>
        </TaoProvider>
      </div>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
        <TaoProvider disabled>
          <Button>Provider disabled</Button>
          <Button variant="secondary">Also disabled</Button>
        </TaoProvider>
      </div>
    </div>
  );
}

export default ButtonProviderDefaults;
```

### 语义化定制
通过稳定的 `root` 部件定制样式，无需依赖私有选择器。
```tsx preview
import { Button } from '@rockshin/tao-ui';

function CustomizedButton() {
  return (
    <Button
      classNames={{ root: 'checkout-button' }}
      styles={{ root: { minWidth: 0, width: '100%', maxWidth: 160 } }}
    >
      Checkout
    </Button>
  );
}

export default CustomizedButton;
```

### 原生表单按钮
提交与重置遵循原生表单语义，演示不发送网络请求。
```tsx preview
import { useState } from 'react';
import { Button, Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [result, setResult] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setResult(String(new FormData(e.currentTarget).get('name')));
      }}
      onReset={() => setResult('')}
    >
      <Stack direction="vertical">
        <Input name="name" aria-label="Name" defaultValue="Alex" required />
        <Stack>
          <Button type="submit" variant="primary">
            Save
          </Button>
          <Button type="reset">Reset</Button>
        </Stack>
        <output aria-live="polite">
          {result ? `Saved: ${result}` : 'Edit and save'}
        </output>
      </Stack>
    </form>
  );
}
```

### 纯图标按钮
使用 aria-label 提供名称；图标自身从辅助技术中隐藏。
```tsx preview
import { useState } from 'react';
import { Button } from '@rockshin/tao-ui';
export default function Example() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <Button aria-label="Add item" onClick={() => setCount(count + 1)}>
        <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
          <path d="M8 2v12M2 8h12" stroke="currentColor" />
        </svg>
      </Button>
      <output aria-live="polite"> {count} items</output>
    </div>
  );
}
```

### 局部配置与覆盖
局部配置统一尺寸和禁用状态，单个按钮可以明确覆盖。
```tsx preview
import { Button, Stack, TaoProvider } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider size="small" disabled>
      <Stack>
        <Button>Inherited disabled</Button>
        <Button disabled={false}>Available</Button>
        <Button disabled={false} size="large">
          Large override
        </Button>
      </Stack>
    </TaoProvider>
  );
}
```

## API


### [#](#button)Button



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | Prevents interaction. Inherits from TaoProvider. | `boolean | undefined` | `-` |
| children | Button label or inline content. | `ReactNode` | `-` |
| variant | Visual emphasis for the action. | `"primary" | "secondary" | "ghost" | "destructive" | "bare" | undefined` | `primary` |
| size | Control height and horizontal spacing. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| loading | Shows the loading icon, sets aria-busy, and prevents interaction. | `boolean | undefined` | `-` |
| icon | Left-leading decorative icon (non-loading state). | `ReactNode` | `-` |
| loadingIcon | Icon shown while loading. Defaults to a built-in spinner. | `ReactNode` | `-` |
| classNames | Semantic class overrides keyed by ButtonSemanticPart. | `Partial<Record<"root", string>> | undefined` | `-` |
| styles | Semantic style overrides keyed by ButtonSemanticPart. | `Partial<Record<"root", CSSProperties>> | undefined` | `-` |

