加载 Spin

Spin 是一个用于展示加载中状态的组件，支持自定义指示器、提示文案、全屏遮罩、不同尺寸以及嵌套内容。

---

📦 引入方式

import { Spin } from '@npmqg/react-ui-core';

---

🧩 使用示例

📚 基本使用

示例

加载中...

源码

<Spin />

📚 自定义提示文字

示例

正在处理数据...

源码

<Spin tip="正在处理数据..." />

📚 嵌套模式（遮罩内容）

示例

加载中...

数据加载中，请稍候...

源码

<Spin spinning={true}>
  <div className="p-4 bg-white shadow rounded">数据加载中，请稍候...</div>
</Spin>

📚 全屏加载效果

<Spin fullscreen />

📚 自定义加载指示器

示例

上传中...

源码

<Spin tip="上传中..." indicator={<div className="custom-loader" />} />

📚 不展示 spinner，仅展示内容

示例

加载完成，内容已显示

源码

<Spin spinning={false}>
  <p>加载完成，内容已显示</p>
</Spin>

---

🧩 Props

属性	类型	默认值	描述
spinning	boolean	true	是否显示加载状态
tip	React.ReactNode	'加载中...'	加载时展示的提示文字
indicator	React.ReactNode	内置默认动画	自定义加载指示器
fullscreen	boolean	false	是否以全屏形式展示 loading 遮罩
size	'small' | 'default' | 'large'	'default'	指示器尺寸大小
children	React.ReactNode	—	包裹的内容，加载中时仍可显示（通常用于内容遮罩）
className	string	—	自定义外层容器的 class 名
其他属性	React.HTMLAttributes<HTMLDivElement>	—	透传给根元素 <div> 的原生属性

---

📐 尺寸映射（size）

尺寸	类名映射	实际尺寸
small	h-4 w-4 border-2	16px
default	h-6 w-6 border-2	24px
large	h-8 w-8 border-4	32px

---

🎨 内置样式说明

• 使用 TailwindCSS 构建。
• 默认 spinner 使用 border 实现，旋转动画通过 animate-spin 实现。
• 全屏遮罩通过 fixed + inset-0 + backdrop-blur-sm 实现。

---

🔍 注意事项

• 若 spinning 设置为 false，组件内部不会渲染任何加载内容，仅渲染 children。
• fullscreen 模式适用于全局加载状态，如首次页面加载、长任务处理等。

---

✅ 最佳实践建议

• 在局部内容加载时使用嵌套方式，确保用户体验平滑。
• 全屏模式需谨慎使用，避免阻塞用户操作。
• 通过 indicator 传入动画图标，可以与品牌风格一致。