npm package: @radishon/lumina
Description: A beautiful animated loading indicator web component for all frameworks
Latest version: 1.0.9

# Lumina

<div align="center">

🌐 **在线演示**: [https://lumina.radishon.com](https://lumina.radishon.com)

一个优雅的动画加载指示器 **Web Component**，提供多种预设动画序列，为你的应用增添独特的视觉体验。**适用于所有前端框架**。

</div>

## 简介

Lumina 是一个轻量级的 Loading 组件，通过精心设计的 Unicode 字符序列和颜色配置，呈现出流畅的动画效果。无论是科技感的赛博朋克风格，还是自然的月相变化，都能为你的应用加载状态提供独特的视觉表达。

**框架无关** - 可在 React、Vue、Angular、Svelte 或任何 HTML 页面中使用。

## 安装

```bash
npm install @radishon/lumina
```

或

```bash
yarn add @radishon/lumina
```

或

```bash
pnpm add @radishon/lumina
```

## 使用示例

### 基本用法 (所有框架)

```html
<lumina-loading></lumina-loading>
```

### React

```tsx
import '@radishon/lumina';

function App() {
  return (
    <div className="loading-container">
      <lumina-loading />
    </div>
  );
}
```

### Vue 3

**重要配置**：需要在 `vite.config.js` 或 `vue.config.js` 中配置 `isCustomElement` 来禁用 Vue 对 Web Component 的解析：

#### Vite 项目

```js
// vite.config.js
export default {
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: tag => tag === 'lumina-loading'
      }
    }
  }
}
```

#### Vue CLI 项目

```js
// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          isCustomElement: tag => tag === 'lumina-loading'
        }
      }))
  }
}
```

**使用示例**：

```vue
<template>
  <div class="loading-container">
    <lumina-loading />
  </div>
</template>

<script setup>
import '@radishon/lumina'
</script>
```

### Vue 2

**重要配置**：需要在 `vue.config.js` 中配置 `isCustomElement`：

```js
// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          isCustomElement: tag => tag === 'lumina-loading'
        }
      }))
  }
}
```

**使用示例**：

```vue
<template>
  <div class="loading-container">
    <lumina-loading />
  </div>
</template>

<script>
import '@radishon/lumina'

export default {
  mounted() {
    // Web Component 自动注册，无需额外操作
  }
}
</script>
```

### Angular

```typescript
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}
```

```html
<!-- app.component.html -->
<lumina-loading></lumina-loading>
```

### Svelte

```svelte
<script>
  import '@radishon/lumina'
</script>

<lumina-loading />
```

### 自定义序列类型

```html
<!-- 使用菱形脉冲效果 -->
<lumina-loading type="diamond"></lumina-loading>

<!-- 使用月相变化效果，调整动画速度 -->
<lumina-loading type="moon" speed="300"></lumina-loading>

<!-- 使用赛博朋克风格 -->
<lumina-loading type="braille" speed="100"></lumina-loading>
```

### 高级自定义

#### 自定义字符序列

通过 `chars` 属性传入 JSON 格式的字符数组，完全自定义动画内容：

```html
<!-- 使用自定义字符 -->
<lumina-loading chars='["🚀","⭐","🌙","☀️"]' speed="100"></lumina-loading>

<!-- 自定义文字动画 -->
<lumina-loading chars='["L","O","A","D","I","N","G"]' speed="150"></lumina-loading>

<!-- 自定义符号 -->
<lumina-loading chars='["▖","▘","▝","▗"]' speed="120"></lumina-loading>
```

#### 自定义颜色

通过 `color` 属性传入任意 CSS 颜色值：

```html
<!-- 自定义预设序列的颜色 -->
<lumina-loading type="star" color="#ff6b6b"></lumina-loading>

<!-- 结合自定义字符和颜色 -->
<lumina-loading chars='["●","○","★"]' color="#00ff88"></lumina-loading>

<!-- 支持所有 CSS 颜色格式 -->
<lumina-loading type="snow" color="rgb(255, 107, 107)"></lumina-loading>
<lumina-loading type="snow" color="hsl(330, 80%, 60%)"></lumina-loading>
<lumina-loading type="snow" color="coral"></lumina-loading>
```

#### 完整自定义示例

```html
<!-- 完全自定义：字符 + 颜色 + 速度 -->
<lumina-loading 
  chars='["🔥","✨","💫","🌟"]' 
  color="#ffd700" 
  speed="80">
</lumina-loading>

<!-- 混合使用：预设序列 + 自定义颜色 -->
<lumina-loading 
  type="flower" 
  color="#ff1493" 
  speed="200">
</lumina-loading>
```

### JavaScript 动态控制

```javascript
const el = document.querySelector('lumina-loading');
el.type = 'star';
el.speed = 200;
```

## Props API

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `type` | `SequenceKey` | `'claude'` | 动画序列类型，见下方可用序列列表 |
| `speed` | `number` | `180` | 动画帧切换速度（毫秒） |
| `chars` | `string[]` | `null` | 自定义字符序列（JSON 数组格式），优先级高于 `type` |
| `color` | `string` | `null` | 自定义颜色值，支持所有 CSS 颜色格式，优先级高于预设颜色 |

## 可用的序列类型

Lumina 提供了 32 种精心设计的动画序列：

| 类型 | 名称 | 描述 | 颜色 |
|------|------|------|------|
| `claude` | CLAUDE 轨迹 | Claude 专属星光轨迹动画 | 金黄色 `#fadb14` |
| `diamond` | 菱形脉冲 | 菱形闪烁变化效果 | 天蓝色 `#40a9ff` |
| `circle` | 柔光圆环 | 圆环渐变扩展动画 | 紫罗兰 `#b37feb` |
| `step` | 阶梯节奏 | 方块阶梯式进度变化 | 绿色 `#73d13d` |
| `flower` | 开花绽放 | 花朵绽放动画 | 粉色 `#ffadd2` |
| `star` | 星辰回环 | 星星旋转变化 | 白色 `#ffffff` |
| `snow` | 雪花晶格 | 雪花飘落效果 | 冰蓝 `#e6f7ff` |
| `spiral` | 螺旋回声 | 螺旋圆环变化 | 金黄色 `#fadb14` |
| `braille` | 布莱叶码 | 赛博朋克风格的布莱叶点码动画 | 荧光绿 `#00ff00` |
| `cypher` | 密码矩阵 | 赛博朋克几何方块变换 | 霓虹蓝 `#00d8ff` |
| `moon` | 月相变化 | 自然风格的月相周期动画 | 月光白 `#fffae6` |
| `wave` | 波浪起伏 | 自然风格的波浪动画 | 红色 `#ff4d4f` |
| `compass` | 方向罗盘 | 逻辑风格的指针旋转 | 橙红 `#ff4500` |
| `pixel` | 像素方块 | 复古风格的像素方块变化 | 紫色 `#722ed1` |
| `clock` | 时钟指针 | 复古风格的时钟动画 | 橙色 `#ffbb96` |
| `equalizer` | 音频均衡 | 音乐风格的音频波形动画 | 青色 `#00bcd4` |
| `waveform` | 波形振荡 | 音乐风格的声波可视化 | 橙红 `#ff5722` |
| `dice` | 骰子滚动 | 游戏风格的随机骰子动画 | 灰色 `#607d8b` |
| `bounce` | 弹跳球 | 动态几何的球体弹跳 | 珊瑚红 `#ff6b6b` |
| `radar` | 雷达扫描 | 动态几何的雷达扇形扫描 | 青绿 `#00d4aa` |
| `dots` | 点阵呼吸 | 数字符号的点阵渐变展开 | 蓝色 `#4d96ff` |
| `liquid` | 液体晃动 | 液体流体的波浪晃动 | 海蓝 `#118ab2` |
| `ripple` | 水纹扩散 | 液体流体的同心圆扩散 | 深蓝 `#073b4c` |
| `bubble` | 气泡浮起 | 液体流体的气泡上升动画 | 浅蓝 `#48cae4` |
| `gradient` | 渐变条 | 光谱渐变的进度条动画 | 紫罗兰 `#ee82ee` |
| `spectrum` | 光谱扫描 | 光谱渐变的三段滑动 | 粉红 `#ff69b4` |
| `bagua` | 八卦 | 中国传统风格的易经八卦 | 棕色 `#8d6e63` |
| `corners` | 角落旋转 | 几何风格的角落旋转 | 青绿 `#80cbc4` |
| `cards` | 纸牌 | 扑克风格的纸牌动画 | 红色 `#c62828` |
| `ornament` | 装饰符 | 装饰风格的花卉图案 | 粉红 `#e91e63` |
| `radiation` | 辐射警告 | 危险风格的警告符号 | 亮绿 `#76ff03` |

### 序列分类

- **赛博朋克风格**: `braille`, `cypher`
- **自然风格**: `moon`, `wave`, `snow`, `flower`, `liquid`, `ripple`, `bubble`
- **逻辑风格**: `compass`
- **复古风格**: `pixel`, `clock`
- **音乐风格**: `equalizer`, `waveform`
- **游戏风格**: `dice`, `cards`
- **动态几何**: `bounce`, `radar`, `corners`
- **数字符号**: `dots`
- **光谱渐变**: `gradient`, `spectrum`
- **中国传统**: `bagua`
- **装饰风格**: `ornament`, `radiation`

## 开发指南

### 构建

```bash
npm run build
```

### 发布

1. 确保已登录 npm：

```bash
npm login
```

2. 发布包：

```bash
npm publish
```

### 本地测试

在项目根目录运行：

```bash
npm link
```

然后在目标项目中：

```bash
npm link @radishon/lumina
```

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！