> 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.

# Spinner

反馈`@rockshin/tao-ui`

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

展示局部、内容覆盖或全屏加载状态。

## 何时使用

系统正在等待且无法立即展示最终内容时使用 Spinner。

**推荐**

- 快速操作使用 delay 避免闪烁。
- 较长等待提供说明文字。

**避免**

- 不要用 Spinner 掩盖没有结束条件的流程。

## 代码演示


### 基础用法
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

function SpinnerExample() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Spinner size="small" />
      <Spinner size="medium" tip="Loading" />
      <Spinner size="large" />
    </Stack>
  );
}

export default SpinnerExample;
```

### 提示与自定义指示器
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

function SpinnerIndicators() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Spinner tip="Loading data" />
      <Spinner
        indicator={<span style={{ fontSize: 24 }}>◌</span>}
        tip="Custom"
      />
      <Spinner size="large" tip="Preparing preview" />
    </Stack>
  );
}

export default SpinnerIndicators;
```

### 内容覆盖与延迟
```tsx preview
import { Button, Spinner, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function SpinnerOverlay() {
  const [spinning, setSpinning] = useState(true);

  return (
    <Stack gap="md" style={{ maxWidth: 420 }}>
      <Button
        variant="secondary"
        onClick={() => setSpinning((value) => !value)}
      >
        {spinning ? 'Stop' : 'Start'} loading
      </Button>
      <Spinner spinning={spinning} delay={200} tip="Loading content">
        <div
          style={{
            minHeight: 120,
            padding: 20,
            border: '1px solid var(--tao-color-border)',
          }}
        >
          Content remains mounted below the overlay.
        </div>
      </Spinner>
    </Stack>
  );
}

export default SpinnerOverlay;
```

### 内容加载遮罩
spinning 控制内容区域的加载状态。
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function SpinnerWrapContent() {
  function Demo() {
    const [spinning, setSpinning] = useState(true);
    return (
      <Stack gap="md" style={{ maxWidth: 360 }}>
        <button type="button" onClick={() => setSpinning((s) => !s)}>
          {spinning ? 'Stop' : 'Start'} loading
        </button>
        <Spinner spinning={spinning} tip="Loading">
          <div
            style={{
              padding: 24,
              border: '1px solid var(--tao-color-border)',
              borderRadius: 8,
              lineHeight: 1.6,
            }}
          >
            <h4 style={{ margin: '0 0 8px' }}>Card title</h4>
            <p style={{ margin: 0 }}>
              Content stays in place and dims while the spinner overlays it.
            </p>
          </div>
        </Spinner>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 延迟显示加载
短暂请求可在 delay 之前结束，减少闪烁。
```tsx preview
import { Spinner, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function SpinnerDelay() {
  function Demo() {
    const [spinning, setSpinning] = useState(false);
    return (
      <Stack gap="md" style={{ maxWidth: 360 }}>
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          500ms delay — quick toggles won&apos;t flash the spinner.
        </p>
        <button type="button" onClick={() => setSpinning((s) => !s)}>
          Toggle spinning ({String(spinning)})
        </button>
        <Spinner spinning={spinning} delay={500}>
          <div
            style={{
              padding: 24,
              border: '1px solid var(--tao-color-border)',
              borderRadius: 8,
            }}
          >
            Toggle quickly to see the delay in action.
          </div>
        </Spinner>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 自定义加载图标
indicator 替换视觉图标，仍需提供清晰的状态文字。
```tsx preview
import { Spinner } from '@rockshin/tao-ui';

export default function SpinnerCustomIndicator() {
  return (
    <Spinner
      indicator={<span style={{ fontSize: 24 }}>⏳</span>}
      tip="Please wait"
    />
  );
}
```

### 受控加载状态
用外部状态控制 spinning，内容保留在原位置。
```tsx preview
import { useState } from 'react';
import { Spinner, Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [loading, setLoading] = useState(false);
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Loading"
        checked={loading}
        onChange={setLoading}
        style={{ alignSelf: 'flex-start' }}
      />
      <Spinner spinning={loading} tip="Loading content">
        <div style={{ padding: 24 }}>Your workspace content stays here.</div>
      </Spinner>
    </Stack>
  );
}
```

## API


### [#](#spinner)Spinner



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| spinning | Whether the spinner is visible. Defaults to true. | `boolean | undefined` | `true` |
| size | Size of the indicator. Inherits from TaoProvider. | `TaoSize | undefined` | `-` |
| tip | Description text rendered under the indicator. | `ReactNode` | `-` |
| delay | Delay (ms) before showing the spinner — prevents flicker on fast loads. | `number | undefined` | `-` |
| indicator | Custom indicator node, replaces the default spinner. | `ReactNode` | `-` |
| children | Wrap content: the spinner overlays `children` while spinning. | `ReactNode` | `-` |
| fullscreen | Render a full-screen backdrop with a centered spinner. | `boolean | undefined` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

