awesomeh5

v0.1.0

Published

21 days ago

HTML enhancement toolkit with custom components and utilities for AI-generated content

0High
0Medium
0Low

cfnwmp

html web-components ai svg tts image-generation custom-elements shadow-dom ai-generated-html

awesomeh5 (a5)

HTML 功能增强工具包 - 为 AI 生成的 HTML 提供开箱即用的组件和工具方法

📖 目录

为什么需要 awesomeh5

在使用 AI 生成 HTML 时，我们发现很多常用功能需要大量原生代码：

<!-- ❌ 传统方式：需要写大量代码 -->
<div id="tts-container"></div>
<script>
  // 50+ 行代码实现 TTS 功能
  fetch('/api/tts', { ... })
    .then(res => res.json())
    .then(data => {
      const audio = new Audio(data.url);
      audio.play();
      // ... 更多代码
    });
</script>

<!-- ✅ 使用 awesomeh5：一行搞定 -->
<a5-tts voice="female">本节课我们讲解Canvas动画原理</a5-tts>

awesomeh5 的目标：把 AI 生成 HTML 时常用的功能封装成开箱即用的组件。

核心特性

✨ 开箱即用的组件

<!-- SVG 流程图 -->
<a5-svg type="flow" data-steps="导入→解析→渲染→输出"></a5-svg>

<!-- 文字转语音 -->
<a5-tts voice="female">欢迎使用 awesomeh5</a5-tts>

<!-- AI 图片生成 -->
<a5-img prompt="Canvas坐标系"></a5-img>

<!-- 提示卡片 -->
<a5-card type="tip">注意：this指向取决于调用方式</a5-card>

<!-- 测验题目 -->
<a5-quiz type="radio" title="typeof null 返回？" 
  options="object,null,undefined" answer="object"></a5-quiz>

🎯 基于 Web Components

样式隔离：组件样式不会污染全局
原生支持：无需框架，任何项目都能用
类型安全：完整的 TypeScript 支持

🔧 灵活的 API

// 组件方式
<a5-tts>播放这段文字</a5-tts>

// JavaScript API
await a5.playTts('播放这段文字', 'female');

// 配置管理
a5.config.set({
  apiBaseUrl: 'https://your-api.com',
  timeout: 60000
});

📚 自动化文档系统

单一数据源：只需维护 registry.ts
文档自动生成：组件文档、示例、演示自动同步
实时预览：文档即演示，代码和效果对照

快速开始

安装

npm install awesomeh5

浏览器引入

<!DOCTYPE html>
<html>
<head>
  <title>awesomeh5 示例</title>
</head>
<body>
  <!-- 使用组件 -->
  <a5-card type="tip">这是一个提示卡片</a5-card>
  
  <!-- 引入库 -->
  <script src="node_modules/awesomeh5/dist/index.js"></script>
  
  <!-- 配置 -->
  <script>
    a5.config.set({
      apiBaseUrl: 'https://your-api.com'
    });
  </script>
</body>
</html>

ES Module

import { a5, A5Card } from 'awesomeh5';

// 配置
a5.config.set({
  apiBaseUrl: 'https://your-api.com',
  ttsEndpoint: '/api/tts',
  imageEndpoint: '/api/image'
});

// 使用 API
await a5.playTts('Hello World', 'female');

组件列表

可视化

SVG 流程图 `<a5-svg>`

轻量级 SVG 流程图组件，支持动画效果。

<a5-svg type="flow" data-steps="导入→解析→渲染→输出"></a5-svg>

属性：

type: 流程图类型，默认 flow
data-steps: 流程步骤，用 → 分隔

媒体

文字转语音 `<a5-tts>`

将文字转换为语音播放。

<a5-tts voice="female">本节课我们讲解Canvas动画原理</a5-tts>

属性：

voice: 音色类型，可选 female | male，默认 female

JavaScript API：

await a5.playTts('文字内容', 'female');

AI 图片生成 `<a5-img>`

根据文字描述生成图片。

<a5-img prompt="Canvas坐标系" config='{"style":"technical"}'></a5-img>

属性：

prompt: 图片描述（必填）
config: 生成配置，JSON 格式

事件：

image-loaded: 图片加载完成，detail: { url: string }
image-error: 图片加载失败，detail: { error: Error }

展示

提示卡片 `<a5-card>`

多种样式的提示卡片组件。

<a5-card type="tip">注意：this指向取决于调用方式</a5-card>
<a5-card type="warning">警告：该操作不可逆</a5-card>
<a5-card type="error">错误：API调用失败</a5-card>
<a5-card type="success">成功：数据已保存</a5-card>
<a5-card type="info">提示：按Ctrl+S保存</a5-card>

属性：

type: 卡片类型，可选 tip | warning | error | success | info | note | question，默认 info

交互

测验题目 `<a5-quiz>`

交互式测验题目组件。

<a5-quiz 
  type="radio" 
  title="typeof null 返回？" 
  options="object,null,undefined" 
  answer="object"
  explanation="在JavaScript中，typeof null 返回 'object'，这是一个历史遗留bug">
</a5-quiz>

属性：

type: 题目类型，可选 radio | checkbox，默认 radio
title: 题目标题（必填）
options: 选项列表，用逗号分隔（必填）
answer: 正确答案（必填）
explanation: 答案解析（可选）

事件：

quiz-answered: 用户答题后触发，detail: { correct: boolean, answer: string }

架构设计

核心理念

awesomeh5 基于 Web Components 标准构建，采用分层架构设计：

┌─────────────────────────────────────┐
│   components/  (UI 层)              │  ← 用户交互、渲染
├─────────────────────────────────────┤
│   api/  (业务逻辑层)                 │  ← 数据处理、API 调用
├─────────────────────────────────────┤
│   utils/  (工具层)                   │  ← 通用功能
├─────────────────────────────────────┤
│   core/  (核心层)                    │  ← 基础设施
└─────────────────────────────────────┘

目录结构

awesomeh5/
├── src/
│   ├── components/          # 组件目录（每个组件一个文件夹）
│   │   ├── card/           # 卡片组件
│   │   │   ├── index.ts    # 组件主逻辑
│   │   │   ├── styles.ts   # 样式定义
│   │   │   └── types.ts    # 类型定义
│   │   ├── quiz/           # 测验组件
│   │   │   ├── index.ts
│   │   │   ├── styles.ts
│   │   │   ├── types.ts
│   │   │   └── utils.ts    # 工具函数
│   │   ├── svg/            # SVG 组件
│   │   ├── tts/            # TTS 组件
│   │   └── img/            # 图片组件
│   ├── core/               # 核心基础设施
│   │   ├── base-component.ts  # 组件基类
│   │   └── config.ts          # 配置管理
│   ├── api/                # API 调用层
│   │   ├── tts.ts
│   │   └── image.ts
│   ├── utils/              # 通用工具
│   │   └── request.ts
│   ├── registry.ts         # 组件注册表（文档数据源）
│   ├── doc-generator.ts    # 文档生成器
│   └── index.ts            # 入口文件
├── dist/                   # 构建输出
├── docs.html              # 自动生成的文档页面
├── test.html              # 测试页面
└── README.md

组件文件夹结构

简单组件（逻辑简单，单文件即可）：

svg/
└── index.ts

复杂组件（逻辑复杂，拆分多个文件）：

card/
├── index.ts    # 组件主逻辑
├── styles.ts   # 样式定义（可能几百行）
├── types.ts    # TypeScript 类型
└── utils.ts    # 工具函数（可选）

BaseComponent 基类

所有组件继承 BaseComponent，提供统一的基础能力：

export abstract class BaseComponent extends HTMLElement {
  protected shadow: ShadowRoot;      // Shadow DOM
  protected mounted = false;         // 挂载状态

  constructor() {
    super();
    this.shadow = this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    if (!this.mounted) {
      this.render();
      this.mounted = true;
    }
  }

  protected abstract render(): void;  // 子类必须实现
  protected createStyle(css: string): HTMLStyleElement;
  protected emit(eventName: string, detail?: any): void;
}

工作原理

以 <a5-card> 为例：

1. 用户写 HTML
   <a5-card type="tip">注意事项</a5-card>
   
2. 浏览器解析
   customElements.define('a5-card', A5Card)
   ↓
   new A5Card()
   
3. 构造函数
   创建 Shadow DOM
   
4. connectedCallback
   元素插入 DOM 时触发
   ↓
   调用 render()
   
5. render() 方法
   ① 读取属性: type="tip"
   ② 选择配置: { icon: '💡', color: '#2196F3' }
   ③ 创建样式: createStyle(cardStyles)
   ④ 创建 DOM: <div class="card">...</div>
   ⑤ 插入 Shadow DOM
   
6. 最终渲染
   <a5-card type="tip">
     #shadow-root
       <style>...</style>
       <div class="card">
         <div class="icon">💡</div>
         <div class="content">注意事项</div>
       </div>
   </a5-card>

样式隔离

使用 Shadow DOM 实现样式隔离：

<!-- 页面样式 -->
<style>
  .card { background: red; }  ← 不会影响组件
</style>

<a5-card>
  #shadow-root
    <style>
      .card { background: blue; }  ← 只在组件内生效
    </style>
    <div class="card">...</div>  ← 显示蓝色
</a5-card>

开发指南

新增组件流程

1. 创建组件文件夹

mkdir -p src/components/my-component

2. 创建组件文件

src/components/my-component/index.ts：

import { BaseComponent } from '../../core/base-component';
import { myComponentStyles } from './styles';

export class A5MyComponent extends BaseComponent {
  protected render() {
    // 1. 读取属性
    const type = this.getAttribute('type') || 'default';
    
    // 2. 创建样式
    const style = this.createStyle(myComponentStyles);
    
    // 3. 创建 DOM
    const container = document.createElement('div');
    container.innerHTML = `<div>My Component</div>`;
    
    // 4. 插入 Shadow DOM
    this.shadow.appendChild(style);
    this.shadow.appendChild(container);
  }
}

src/components/my-component/styles.ts：

export const myComponentStyles = `
  :host {
    display: block;
  }
  
  .container {
    padding: 16px;
    border: 1px solid #e0e0e0;
  }
`;

src/components/my-component/types.ts：

export interface MyComponentConfig {
  type: string;
  value: string;
}

3. 注册组件

src/index.ts：

import { A5MyComponent } from './components/my-component';

function registerComponents() {
  // ...
  customElements.define('a5-my-component', A5MyComponent);
}

export { A5MyComponent };

4. 注册到文档系统

src/registry.ts：

export const componentRegistry: ComponentMeta[] = [
  // ... 其他组件
  {
    name: '我的组件',
    tag: 'a5-my-component',
    description: '这是一个新组件',
    category: '展示',
    attributes: [
      {
        name: 'type',
        type: 'string',
        required: false,
        default: 'default',
        description: '组件类型',
        options: ['default', 'primary']
      }
    ],
    events: [],
    examples: [
      {
        title: '基础用法',
        code: '<a5-my-component type="primary"></a5-my-component>',
        description: '最简单的使用方式'
      }
    ]
  }
];

5. 测试

# 检查完整性
npm run check

# 生成文档
npm run docs

# 构建
npm run build

开发规范

文件命名

组件文件夹：小写，连字符分隔（my-component）
组件类名：大驼峰，A5 前缀（A5MyComponent）
HTML 标签：小写，连字符分隔（<a5-my-component>）

导入路径

// 从组件到核心层
import { BaseComponent } from '../../core/base-component';

// 从组件到 API 层
import { playTts } from '../../api/tts';

// 组件内部
import { myStyles } from './styles';
import { MyConfig } from './types';

样式编写

export const styles = `
  /* :host 代表组件本身 */
  :host {
    display: block;
  }
  
  /* 使用 CSS 变量实现动态样式 */
  .card {
    border-color: var(--card-color);
    background: var(--card-bg);
  }
`;

// 在组件中注入变量
container.style.setProperty('--card-color', config.color);

事件通信

// 组件内发射事件
this.emit('my-event', { value: 'data' });

// 外部监听
document.querySelector('a5-my-component')
  .addEventListener('my-event', (e) => {
    console.log(e.detail.value);
  });

文档系统

核心理念：单一数据源

所有组件信息维护在 src/registry.ts，文档自动生成：

registry.ts (唯一维护)
    ↓
    ├─→ docs.html (自动生成文档)
    ├─→ check script (完整性检查)
    └─→ README.md (可选同步)

文档结构

// src/registry.ts
export const componentRegistry: ComponentMeta[] = [
  {
    name: '组件名称',
    tag: 'a5-component',
    description: '组件描述',
    category: '分类',  // 可视化/媒体/展示/交互
    
    // 属性文档
    attributes: [
      {
        name: '属性名',
        type: 'string',
        required: true,
        default: '默认值',
        description: '属性说明',
        options: ['可选值1', '可选值2']
      }
    ],
    
    // 事件文档
    events: [
      {
        name: '事件名',
        description: '事件说明',
        detail: '{ key: value }'
      }
    ],
    
    // 示例代码
    examples: [
      {
        title: '示例标题',
        code: '<a5-component></a5-component>',
        description: '示例说明'
      }
    ]
  }
];

文档命令

# 检查组件完整性
npm run check
# 输出：
# ✓ 所有组件文件存在
# ✓ 文档完整
# ✓ 示例充足

# 生成并打开文档
npm run docs
# 自动构建并在浏览器打开 docs.html

文档页面功能

侧边栏导航：按分类分组，点击跳转
搜索功能：实时过滤组件
属性表格：完整的属性说明
事件列表：事件名称和数据结构
实时演示：代码和效果对照

维护工作流

# 新增组件
1. 创建组件代码
2. 在 registry.ts 添加元数据  ← 唯一需要手动维护
3. npm run check              ← 自动检查
4. npm run docs               ← 自动生成文档

# 更新组件
1. 修改组件代码
2. 同步更新 registry.ts       ← 唯一需要手动维护
3. npm run docs               ← 文档自动更新

API 文档

全局对象 `a5`

interface A5 {
  // 配置管理
  config: {
    set(options: A5ConfigOptions): void;
    get<K extends keyof A5ConfigOptions>(key: K): A5ConfigOptions[K];
    getAll(): A5ConfigOptions;
  };
  
  // TTS API
  playTts(text: string, voice?: string): Promise<void>;
  
  // 图片生成 API
  generateImage(prompt: string, config?: any): Promise<string>;
  
  // 版本号
  version: string;
  
  // 文档生成器
  componentRegistry: ComponentMeta[];
  generateDocumentation(): string;
  generateComponentList(): string;
}

配置选项

interface A5ConfigOptions {
  apiBaseUrl?: string;      // API 基础地址
  ttsEndpoint?: string;     // TTS 端点
  imageEndpoint?: string;   // 图片生成端点
  defaultVoice?: string;    // 默认音色
  timeout?: number;         // 请求超时时间（毫秒）
}

配置示例

// 设置配置
a5.config.set({
  apiBaseUrl: 'https://your-api.com',
  ttsEndpoint: '/api/tts',
  imageEndpoint: '/api/image',
  defaultVoice: 'female',
  timeout: 30000
});

// 获取单个配置
const baseUrl = a5.config.get('apiBaseUrl');

// 获取所有配置
const allConfig = a5.config.getAll();

TTS API

// 播放文字
await a5.playTts('欢迎使用 awesomeh5', 'female');

// 使用默认音色
await a5.playTts('Hello World');

图片生成 API

// 生成图片
const imageUrl = await a5.generateImage('Canvas坐标系', {
  style: 'technical',
  size: '1024x1024'
});

console.log(imageUrl); // https://cdn.example.com/image.png

浏览器支持

Chrome 53+
Firefox 63+
Safari 10.1+
Edge 79+

需要支持：

Custom Elements v1
Shadow DOM v1
ES2020

开发命令

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 检查组件完整性
npm run check

# 生成文档
npm run docs

# 运行测试
npm test

# 代码检查
npm run lint

项目文件说明

ARCHITECTURE.md - 项目架构详细说明
DOCUMENTATION.md - 文档维护指南
DOCS-SYSTEM.md - 文档系统详解
test.html - 组件测试页面
docs.html - 自动生成的文档页面

设计思想

1. 单一职责原则

每个组件只做一件事：

a5-card 只负责展示卡片
a5-tts 只负责语音播放
a5-quiz 只负责测验交互

2. 开放封闭原则

对扩展开放：轻松添加新组件
对修改封闭：不影响现有组件

3. 依赖倒置原则

components → api → utils → core
   ↓          ↓      ↓       ↓
  高层     中层    底层    基础

高层不依赖底层，都依赖抽象（BaseComponent）。

4. 单一数据源

registry.ts
    ↓
  一次维护
    ↓
  处处同步

所有文档、演示、检查都基于 registry.ts 自动生成。

贡献指南

欢迎贡献！请遵循以下流程：

Fork 本仓库
创建特性分支 (git checkout -b feat/new-component)
提交更改 (git commit -m 'feat: add new component')
推送到分支 (git push origin feat/new-component)
创建 Pull Request

提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具相关

许可证

MIT License

联系方式

Issues: GitHub Issues
Email: [email protected]

Made with ❤️ for AI-generated HTML