Musk Web Components Library

为AI生成HTML而设计的高质量Web组件库

🎯 项目背景

在AI生成HTML的过程中，从零开始生成完整的HTML、CSS、JavaScript代码存在以下挑战：

• ⏱️ 生成耗时长：复杂组件需要大量代码生成时间
• 🎲 质量不稳定：AI生成的代码质量参差不齐，可能存在兼容性问题
• 🔄 重复造轮子：常用功能组件需要反复生成，效率低下
• 🐛 调试困难：生成的代码可能存在难以发现的bug

Musk Web Components Library 通过提供预制的高质量组件库，让AI直接使用现成组件，显著提升生成效率和代码质量。

✨ 核心优势

🚀 显著提升AI生成效率

• 即插即用：AI可以直接引用组件，无需生成复杂代码
• 标准化接口：统一的属性配置方式，AI易于理解和使用
• 零配置启动：组件开箱即用，减少配置复杂度

🎨 保证代码质量稳定

• 经过充分测试：每个组件都经过严格的单元测试和集成测试
• 跨浏览器兼容：基于Web Components标准，确保广泛兼容性
• 性能优化：使用Stencil编译优化，运行时性能卓越

🛠️ 灵活的定制能力

• 多种渲染模式：支持内置UI、外部自定义、无头模式
• 丰富的配置选项：满足不同场景的个性化需求
• 事件驱动架构：完善的事件系统，便于集成和扩展

📦 现有组件

🧠 QuizQuestion - 智能答题组件

功能完整的答题组件，支持多种题型和灵活的渲染模式：

• 题型支持：单选题、多选题、判断题
• 选项类型：文字选项、图片选项、混合选项
• 渲染模式：内置UI、外部自定义、无头模式
• 反馈系统：实时判对错、答案解析、得分统计
• 事件丰富：选择、提交、正确、错误等事件

<!-- 基础单选题 -->
<quiz-question
  question="以下哪个是 JavaScript 的正确语法？"
  type="single"
  correct-answer="2"
  options='["variable x = 10;", "int x = 10;", "let x = 10;", "x := 10;"]'
  points="10"
  explanation="JavaScript 使用 var、let 或 const 来声明变量。">
</quiz-question>

📝 WordCard - 词汇卡片组件

（开发中...）

🚀 快速开始

安装

npm install @yuanfudao/musk-web-components-library

使用方式

方式一：懒加载（推荐）

适合现代Web应用，支持按需加载：

<script type="module" src="https://unpkg.com/@yuanfudao/musk-web-components-library"></script>
<quiz-question 
  question="你的问题" 
  options='["选项1", "选项2"]' 
  correct-answer="0">
</quiz-question>

方式二：独立组件导入

适合React、Vue等框架项目：

import '@yuanfudao/musk-web-components-library/quiz-question';

function App() {
  return (
    <quiz-question
      question="你的问题"
      options={["选项1", "选项2"]}
      correctAnswer={0}
    />
  );
}

开发环境

# 克隆项目
git clone [repository-url]
cd musk-web-components

# 安装依赖
yarn install

# 启动开发服务器
yarn dev:library

# 构建组件库
yarn workspace @yuanfudao/musk-web-components-library run build

🎯 AI使用指南

为AI优化的设计

本组件库专门为AI生成HTML场景设计，具有以下特点：

🤖 AI友好的属性设计

• 字符串属性支持：所有复杂数据类型都支持JSON字符串格式
• 智能类型转换：自动解析和转换属性类型
• 容错机制：对无效输入提供友好的错误处理

<!-- AI可以直接生成这样的代码，无需复杂的JavaScript对象 -->
<quiz-question
  question="选择正确答案"
  options='["选项A", "选项B", "选项C"]'
  correct-answer="1"
  type="single">
</quiz-question>

📋 标准化的使用模式

AI可以按照以下模式生成组件代码：

<!-- 单选题模板 -->
<quiz-question
  question="[题目内容]"
  type="single"
  options='["选项1", "选项2", "选项3", "选项4"]'
  correct-answer="[正确答案索引]"
  points="[分值]"
  explanation="[答案解析]">
</quiz-question>

<!-- 多选题模板 - 显示内置提交按钮 -->
<quiz-question
  question="[题目内容]"
  type="multiple"
  options='["选项1", "选项2", "选项3", "选项4"]'
  correct-answer="[0,2]"
  auto-submit="true"
  points="[分值]"
  explanation="[答案解析]">
</quiz-question>

<!-- 多选题模板 - 外部自定义提交按钮 -->
<quiz-question
  id="custom-quiz"
  question="[题目内容]"
  type="multiple"
  options='["选项1", "选项2", "选项3", "选项4"]'
  correct-answer="[0,2]"
  auto-submit="false"
  points="[分值]"
  explanation="[答案解析]">
</quiz-question>
<button onclick="document.getElementById('custom-quiz').submit()">
  提交答案
</button>

<!-- 判断题模板 -->
<quiz-question
  question="[题目内容]"
  type="boolean"
  correct-answer="true"
  points="[分值]"
  explanation="[答案解析]">
</quiz-question>

🔧 高级功能

外部自定义渲染

支持完全自定义选项外观，适合复杂的设计需求：

<quiz-question
  question="选择正确的图标"
  option-render-mode="external"
  type="single"
  correct-answer="0">
  
  <!-- 自定义选项内容 -->
  <div slot="option-0" class="custom-option">
    <img src="icon1.png" alt="图标1">
    <span>React</span>
  </div>
  
  <div slot="option-1" class="custom-option">
    <img src="icon2.png" alt="图标2">
    <span>Vue</span>
  </div>
</quiz-question>

事件监听和状态管理

丰富的事件系统，便于集成到复杂应用中：

const quizElement = document.querySelector('quiz-question');

// 监听答案选择
quizElement.addEventListener('answerSelected', (event) => {
  console.log('选择了答案:', event.detail);
});

// 监听提交事件
quizElement.addEventListener('questionSubmitted', (event) => {
  const { isCorrect, score, selectedAnswers } = event.detail;
  console.log('答题结果:', { isCorrect, score, selectedAnswers });
});

// 获取当前状态
const state = await quizElement.getState();
console.log('当前状态:', state);

🛠️ 开发和贡献

项目结构

musk-web-components/
├── packages/
│   ├── musk-web-components-library/    # 组件库核心
│   │   ├── src/components/             # 组件源码
│   │   ├── dist/                       # 构建产物
│   │   └── package.json
│   └── musk-web-components-docs/       # 文档站点
└── package.json                        # 根配置

开发命令

# 启动组件库开发服务器
yarn dev:library

# 启动文档站点
yarn dev:docs

# 构建组件库
yarn workspace @yuanfudao/musk-web-components-library run build

# 运行测试
yarn workspace @yuanfudao/musk-web-components-library run test

# 发布预发布版本
yarn publish:beta

技术栈

• Stencil: Web Components编译器
• TypeScript: 类型安全的JavaScript
• Jest: 单元测试框架
• Puppeteer: E2E测试