> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/loading-bar.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.

# LoadingBar 顶部加载条

展示页面或任务的加载进度。

## 基本用法


模拟页面加载

basic.tsx

复制代码

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

export function LoadingBarBasic() {
  const bar = useLoadingBar();
  return (
    <Button
      onClick={() => {
        const done = bar.start();
        setTimeout(done, 1600);
      }}
    >
      模拟页面加载
    </Button>
  );
}
```

展开代码

## 更多用法


进度 40%完成重置

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/loading-bar/advanced.tsx"
import { Button, Space, useLoadingBar } from '@ifhover/leaf-ui';

export function LoadingBarProgress() {
  const bar = useLoadingBar();
  return (
    <Space>
      <Button
        variant="outline"
        onClick={() => {
          bar.reset();
          bar.start();
          bar.set(40);
        }}
      >
        进度 40%
      </Button>
      <Button onClick={() => bar.finish()}>完成</Button>
      <Button variant="soft" onClick={() => bar.reset()}>
        重置
      </Button>
    </Space>
  );
}
```

展开代码

## 使用说明

ConfigProvider 自动提供加载条。start() 返回对应任务的完成函数，适合在 finally 中调用。多个任务同时运行时，全部完成后才结束。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { LoadingBarApi, LoadingBarProps, LoadingBarProviderProps } from '@ifhover/leaf-ui';
```

## LoadingBarApi API

| 属性       | 类型                           | 默认值 | 说明             |
| -------- | ---------------------------- | --- | -------------- |
| `start`  | `() => () => void`           | 必填  | 开始任务，返回该任务完成函数 |
| `finish` | `() => void`                 | 必填  | 完成一个任务，全部完成后收起 |
| `set`    | `(progress: number) => void` | 必填  | 设置显示进度         |
| `reset`  | `() => void`                 | 必填  | 重置状态或重试        |

## LoadingBarProps API

| 属性          | 类型                  | 默认值     | 说明               |
| ----------- | ------------------- | ------- | ---------------- |
| `active`    | `boolean`           | `false` | 正在加载             |
| `progress`  | `number`            | —       | 进度 0–100，省略时自动估计 |
| `color`     | `string`            | —       | 颜色               |
| `height`    | `number`            | `3`     | 高度，数字按像素计算       |
| `position`  | `'top' \| 'bottom'` | `'top'` | 显示或插入位置          |
| `className` | `string`            | —       | 容器类名             |
| `style`     | `CSSProperties`     | —       | 容器内联样式           |

## LoadingBarProviderProps API

| 属性          | 类型                  | 默认值     | 说明         |
| ----------- | ------------------- | ------- | ---------- |
| `color`     | `string`            | —       | 颜色         |
| `height`    | `number`            | `3`     | 高度，数字按像素计算 |
| `position`  | `'top' \| 'bottom'` | `'top'` | 显示或插入位置    |
| `className` | `string`            | —       | 容器类名       |
| `style`     | `CSSProperties`     | —       | 容器内联样式     |
| `children`  | `ReactNode`         | —       | 内容或下级项目    |