# haura

**Repository Path**: yzdalhj/haura

## Basic Information

- **Project Name**: haura
- **Description**: 面向沉浸式交互的 Vue 3 组件系统

不是组件的堆砌。是界面生命体征的重构。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Haura UI

> 面向沉浸式交互的 Vue 3 组件系统 —— 从 Schema 到界面的生成式 UI 框架

不是组件的堆砌。是界面生命体征的重构。

旨在成为「**有状态的 UI 生成框架**」——不仅提供精心调校的组件，更提供从数据 Schema 到完整 UI 配置的自动化管线。

---

## 为什么不是"另一个组件库"

市面上的组件库解决的是"有没有"的问题。

Haura UI 解决的是"好不好用"的问题——在肉眼可见与不可见之处，都有精心调校。

- **聚焦时的光晕**，不是简单的边框变色，而是柔和的能量场扩散
- **列表悬停切换**，不是突兀跳变，而是背景条像磁铁一样滑动跟随
- **按钮点击**，不是瞬间响应，而是从触点向外扩散的涟漪反馈

这些细节单独看微不足道，组合在一起形成**品牌级的体验一致性**。

而超越常规组件库，Haura 的核心差异在于**生成式 UI 引擎**——将 JSON Schema / OpenAPI / DDL 一键转换为可交互的界面配置，让后端数据模型直接驱动前端 UI。

---

## 架构设计

### 8 个子包 + Playground（pnpm monorepo）

```
haura-ui/
├── @haura/components    # 21 个生产级 Vue 3 组件
├── @haura/theme         # 6 套设计令牌预设（亮/暗 × 中性/暖/冷）
├── @haura/motion        # 基于 animejs 的动效引擎与手势系统
├── @haura/effects       # 粒子爆发、滚动视差等装饰层
├── @haura/icons         # 本地 SVG 图标注册与名称解析系统
├── @haura/generator     # 生成式 UI 引擎核心（SchemaEngine + DynamicRenderer）
├── @haura/locale        # 运行时国际化（zh-CN / en-US）
└── @haura/utils         # SSR 工具与 DOM 工具
```

### 交互分层策略

| 层级 | 包体积 | 引入方式 | 说明 |
|------|--------|----------|------|
| 核心层 | ~8KB | 内置 | 涟漪、悬停指示器、状态过渡 |
| 增强层 | 按需 | Vue 指令 | v-ripple、v-magnetic、v-tilt |
| 装饰层 | ~10-20KB | 独立包 | 粒子爆发、滚动视差 |
| 生成层 | ~15KB | 按需 | Schema 引擎 + 动态渲染器 |

**产品配置建议**：
- 企业后台：核心层 + 生成层（表单/表格自动生成）
- C 端产品：核心层 + 增强层
- 营销页面：全部启用

---

## 组件矩阵

### 已发布（32 个）

| 基础 | 表单 | 数据展示 | 反馈 | 导航 | 布局 | 工具 |
|------|------|----------|------|------|------|------|
| Button | Input | Table | Message | Breadcrumb | Row/Col | Empty |
| Icon | Select | Card | Dialog | Tabs/TabPane | Space | Tooltip |
| Tag | Checkbox | Badge | Drawer | Dropdown | Grid | ErrorBoundary |
| Avatar | Radio | Progress | Loading | Pagination | | Skeleton |
| | Switch | Result | | | | |
| | Form/FormItem | Timeline | | | | |
| | Upload | Tree | | | | |

---

## 核心系统

### 1. 生成式 UI 引擎（@haura/generator）

将结构化数据描述转化为完整 UI 配置，让界面从数据模型中自动生成。

| 能力 | 说明 |
|------|------|
| **SchemaEngine** | JSON Schema / OpenAPI / DDL → 中间表示(IR) → UI 配置 |
| **DynamicRenderer** | 运行时根据 UI 配置动态渲染组件树 |
| **DataLoader** | 数据源绑定（静态/API/自定义），可选字典 API 自动解析 |
| **输出验证** | 属性白名单过滤、配置校验、懒加载降级安全网 |

```ts
import { createSchemaEngine, DynamicRenderer } from '@haura/generator'

const engine = createSchemaEngine()
const config = engine.adaptFromSchema(userSchema, 'form')
// → 自动生成表单字段配置、校验规则、布局
```

### 2. 光效系统

不是阴影。是基于视觉层级的光子模拟。

| 光效类型 | 触发场景 | 技术实现 |
|----------|----------|----------|
| 聚焦光晕 | 输入框聚焦 | CSS 自定义属性 + 硬件加速合成 |
| 悬停微光 | 按钮/卡片悬停 | 透明度 30% 的柔和发光 |
| 选中脉冲 | 选中状态 | 短暂脉冲后保持微光 |
| 涟漪扩散 | 点击操作 | 从点击点向外扩散的圆形波纹 |
| 呼吸光效 | 加载状态 | 2-3s 周期性明暗变化 |

**参数规范**：
- 发光半径：0-8px（克制，避免刺眼）
- 过渡时长：200-300ms
- 颜色透明度：20-30%

### 3. 动效节奏系统（@haura/motion）

独特的缓动曲线形成品牌记忆。

| 曲线名称 | cubic-bezier | 手感描述 |
|----------|--------------|----------|
| Ease Out | (0, 0, 0.2, 1) | 轻盈结束 |
| Ease In Out | (0.4, 0, 0.2, 1) | 平衡自然 |
| Bounce | (0.34, 1.56, 0.64, 1) | 轻微弹跳 |
| Snappy | (0.6, 0, 0.7, 0.35) | 干脆利落 |

**时序编排**：
- 微交互：100-150ms（快速响应）
- 状态切换：200-250ms（流畅自然）
- 页面转场：300-400ms（有序展开）
- 编排动画：间隔 50ms（错落有致）

### 4. 玻璃效果系统

用于悬浮层和导航，增强层次感。

```css
.glass-effect {
  background: rgba(255, 255, 255, 0.75);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}
```

**使用边界**：仅用于悬浮层（导航栏、模态框、抽屉），不用于内容承载区域。

### 5. 国际化系统（@haura/locale）

开箱即用的中英文切换，运行时动态加载。

| 语言 | 标识 | 状态 |
|------|------|------|
| 简体中文 | zh-CN | ✅ 已支持 |
| English | en-US | ✅ 已支持 |

### 6. 图标系统（@haura/icons）

灵活的图标注册与解析机制，支持多源图标。

| 图标源 | 格式 | 说明 |
|--------|------|------|
| 本地 SVG | `local:my-icon` | 脱机可用，tree-shakeable |
| Iconify | `mdi:home` | 海量图标库按需加载 |
| 默认解析 | `home` | 自动降级为 Iconify MDI |

### 7. 风格预设系统

6 套开箱即用的主题预设。

| 预设 | 亮度 | 色调 | 适用场景 |
|------|------|------|----------|
| Light | 亮色 | 中性 | 通用默认 |
| Dark | 暗色 | 中性 | 开发者工具 |
| Light Warm | 亮色 | 暖色 | 社交、生活类产品 |
| Dark Warm | 暗色 | 暖色 | 夜间阅读 |
| Light Cool | 亮色 | 冷色 | 科技、金融 |
| Dark Cool | 暗色 | 冷色 | 专业后台 |

---

## 迭代规划

| 版本 | 状态 | 规划内容 |
|------|------|----------|
| v0.1 | ✅ 完成 | 18 个 P0 核心组件 + 光效/动效/主题系统 |
| v0.2 | ✅ 完成 | motion/locale/icons/effects 子包 + 动效引擎 |
| v0.3 | ✅ 完成 | SchemaEngine + DynamicRenderer + 字典 API + 45 测试 |
| v0.4 | ✅ 完成 | Empty/Tooltip/ErrorBoundary + DataLoader + 输出验证 + 67 测试 |
| v0.5 | ✅ 完成 | 新增 11 组件（Avatar/Badge/Breadcrumb/Dropdown/Pagination/Progress/Result/Skeleton/Timeline/Tree/Upload）|
| v0.6 | ✅ 完成 | 32 组件文档全覆盖 + 搜索栏/树形表格/行展开等增强 |
| v1.0 | 🚧 进行中 | Playground 演练场、AIPromptBuilder、组件测试覆盖 |

---

## 设计原则

**克制而精致，耐看而不乏味**

- **克制**：装饰只在关键位置出现，渐变一个界面不超过 2 处
- **留白**：充足的负空间，元素不拥挤
- **一致**：统一的设计语言贯穿始终
- **微妙**：细节需要发现，不是一眼看穿
- **功能导向**：每个设计决策服务于体验，不为炫技而动效

---

## 快速开始

```bash
npm install haura-ui
```

```ts
import { createApp } from 'vue'
import HauraUI from 'haura-ui'
import 'haura-ui/style.css'

createApp(App)
  .use(HauraUI, {
    theme: 'auto',        // 响应系统主题
    motion: 'natural',    // 自然动效模式
  })
  .mount('#app')
```

### 使用生成式引擎

```ts
import { createSchemaEngine, DynamicRenderer } from '@haura/generator'
import { setDictApi } from '@haura/generator'
import type { DictApi } from '@haura/generator'

// 配置字典 API（可选）
setDictApi({
  fetchDict: async (code) => {
    const res = await fetch(`/api/dict/${code}`)
    return res.json()
  },
} satisfies DictApi)

// 从 Schema 生成表单
const engine = createSchemaEngine()
const formConfig = engine.adaptFromSchema(userSchema, 'form')
```

---

## 无障碍

尊重每一次用户选择。

- `prefers-reduced-motion` — 静谧模式，动效归零
- `prefers-color-scheme` — 跟随系统明暗
- WAI-ARIA 语义化标记
- 键盘导航支持

---

## 技术栈

| 领域 | 技术 |
|------|------|
| 框架 | Vue 3 + TypeScript 5 |
| 构建 | Rollup（组件）+ TSC（子包） |
| 测试 | Vitest |
| 包管理 | pnpm 8 monorepo |
| 动效 | animejs v4 |
| 国际化 | 运行时动态切换（zh-CN / en-US） |
| 文档 | VitePress + GitHub Pages |

---

## 开发

```bash
# 安装依赖
pnpm install

# 启动开发环境（Playground）
pnpm dev

# 构建所有包
pnpm build

# 运行测试
pnpm test

# 类型检查
pnpm typecheck

# 启动文档开发
pnpm docs:dev
```

---

## 资源

📘 [完整文档](https://yzdalhj.github.io/haura/)  
🎮 [组件演练场](https://yzdalhj.github.io/haura/components/button.html)  
💬 [GitHub Discussions](https://github.com/yzdalhj/haura/discussions)  

---

**Haura** — 你的光环。

MIT License © 2024-2025