@group_wtf_npm/loading/README.md

loading加载

# @group_wtf_npm/loading

@group_wtf_npm/loading 是一个简易的 loading 加载组件，支持全局加载动画的显示、隐藏、暂停和恢复操作。

---

### 安装

```bash
pnpm add @group_wtf_npm/loading
```

---

### 使用

#### 基本用法

```js
import initGlobalLoading from '@group_wtf_npm/loading';

// 初始化全局加载管理器
globalThis.loading = initGlobalLoading();

// 显示加载动画
const loadId = loading.show('加载中');

// 模拟异步操作
setTimeout(() => {
    // 隐藏加载动画
    loading.hide(loadId);
}, 3000);
```

#### 在 React 中使用

```jsx
import React from 'react';

function App() {
    const [loading, setLoading] = React.useState(false);

    return (
        <div>
            <button onClick={() => setLoading(true)}>显示加载</button>
            <button onClick={() => setLoading(false)}>隐藏加载</button>
            {loading && <wtf-loading>数据加载中</wtf-loading>}
        </div>
    );
}
```

---

### Docmention

#### initGlobalLoading 配置项

- **tag**: 可选的自定义注册的元素名称，默认为 `wtf-loading`。
- **opts**: 可选的其它配置项：
  - **root**: 全局 loading 挂载的根元素，可以是 DOM 元素或选择器字符串，默认为 `document.body`。
  - **absolute**: 是否绝对定位，默认为 `true`。
  - **mask**: 遮罩层的背景，当可转为数字时表示透明度，否则表示背景色，默认为 `1`。

---

#### GlobalLoading 实例方法

- **show(msg?: string, id?: string, opts?: { absolute?: boolean; mask?: number }): string**  
  显示加载动画。
  - **msg**: 加载提示信息，默认为 `'加载中'`。
  - **id**: 可选的加载 ID，用于标识加载实例。
  - **opts**: 可选的配置选项：
    - **absolute**: 是否绝对定位，默认为 `true`。
    - **mask**: 遮罩层的背景，默认为 `1`。
  - **返回值**: 返回加载的唯一 ID。

- **hide(id: string): void**  
  隐藏指定的加载动画。
  - **id**: 加载的唯一 ID。

- **clear(): void**  
  清除所有加载动画。

- **pause(): void**  
  暂停加载动画（从 DOM 中移除）。

- **resume(): void**  
  恢复加载动画（重新添加到 DOM 中）。

---

### 示例

#### 显示和隐藏加载动画

```js
import initGlobalLoading from '@group_wtf_npm/loading';

globalThis.loading = initGlobalLoading();

// 显示加载动画
const loadId = loading.show('加载中');

// 隐藏加载动画
setTimeout(() => {
    loading.hide(loadId);
}, 2000);
```

#### 暂停和恢复加载动画

```js
// 暂停加载动画
loading.pause();

// 恢复加载动画
loading.resume();
```

#### 自定义配置

```js
globalThis.loading = initGlobalLoading('custom-loading', {
    root: '#app',
    absolute: false,
    mask: 'rgba(0, 0, 0, 0.5)',
});

// 显示自定义加载动画
loading.show('自定义加载动画');
```

---

### 自定义元素 `wtf-loading`

#### 属性

- **absolute**: 是否绝对定位，默认为 `true`。
- **mask**: 遮罩层的背景，默认为 `1`。

#### 示例

```html
<wtf-loading absolute mask="rgba(0, 0, 0, 0.5)">加载中...</wtf-loading>
```

---

### 常见问题

#### 如何自定义加载动画的样式？

可以通过覆盖 `wtf-loading` 的样式来实现自定义：

```css
wtf-loading {
    font-size: 16px;
    color: #333;
    background: rgba(255, 255, 255, 0.8);
    border: 1px solid #ccc;
}
```

#### 如何在多个页面中共享全局加载实例？

可以将 `loading` 挂载到 `globalThis`，这样在任何地方都可以访问：

```js
import initGlobalLoading from '@group_wtf_npm/loading';

globalThis.loading = initGlobalLoading();
```

---

### 版本

- **1.0.2**: 初始版本，支持基本的加载动画功能。

---

### 许可证

MIT License