Lumina

🌐 在线演示: https://lumina.radishon.com

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

简介

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

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

安装

npm install @radishon/lumina

或

yarn add @radishon/lumina

或

pnpm add @radishon/lumina

使用示例

基本用法 (所有框架)

<lumina-loading></lumina-loading>

React

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 项目

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

Vue CLI 项目

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

使用示例：

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

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

Vue 2

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

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

使用示例：

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

<script>
import '@radishon/lumina'

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

Angular

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

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

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

Svelte

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

<lumina-loading />

自定义序列类型

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

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

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

高级自定义

自定义字符序列

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

<!-- 使用自定义字符 -->
<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 颜色值：

<!-- 自定义预设序列的颜色 -->
<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>

完整自定义示例

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

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

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

开发指南

构建

npm run build

发布

1. 确保已登录 npm：

npm login

2. 发布包：

npm publish

本地测试

在项目根目录运行：

npm link

然后在目标项目中：

npm link @radishon/lumina

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！