Light Components

切换主题

组件文档同步 ​

组件文档的默认流程不需要逐个编写 Markdown。文档站与 light-ai-agent 读取同一个组件中心接口，并以注册表的当前版本为准生成页面。

同步链路 ​

text
componentInfo/page
  └─ componentCode + currentVersionNo
       ├─ dist/manifest.json
       └─ dist/index.umd.cjs（优先）/ index.js
                ↓
          sync:materials
                ↓
     目录 + 路由 + 示例 + API + 真实预览

手动触发同步：

bash
npm run sync:materials

npm run dev 和 npm run build 会在启动前自动执行一次同步。

组件发布要求 ​

组件中心的一条可用记录需要满足：

  • enableStatus=1。
  • currentVersionNo 指向已经上传完成的版本。
  • 对应版本包含 dist/manifest.json。
  • 对应版本包含 dist/index.umd.cjs；老组件也可以只提供 dist/index.js。
  • manifest.componentName 是合法且与脚本注册结果一致的 Web Component 标签名。

Manifest 至少应包含：

json
{
  "componentName": "material-example",
  "version": "1.0.0",
  "title": "示例组件",
  "description": "组件说明",
  "propsConfig": [],
  "eventsConfig": [],
  "methodsConfig": []
}

同步时版本号以组件中心的 currentVersionNo 为准，不从 loadFullPath 推断，也不会被 Manifest 中的旧版本号覆盖。

UMD 与 Manifest 的职责 ​

index.umd.cjs 是运行产物，文档页可将它作为普通脚本加载并展示真实组件。它本身没有稳定、通用的结构可供文档系统提取属性、事件和方法。

manifest.json 是能力契约，文档站通过它生成标题、描述、默认属性和 API 表格。因此发布组件时应同时上传 UMD 与 Manifest；这一步完成后，文档站无需再为该组件手工开发页面。

人工增强页面 ​

自动页覆盖组件目录、基础预览、接入代码和 API。只有当某个组件需要复杂业务场景、交互流程或额外说明时，才需要创建：

text
docs/components/<manifest.componentName>.md

同步器会自动保留这个页面，并继续更新对应脚本和 Manifest。

定时同步 ​

本地可以运行：

bash
npm run sync:watch

默认每 10 分钟读取一次组件中心。可通过 LIGHT_COMPONENT_SYNC_INTERVAL_MS 调整间隔。

线上静态文档需要由 CI 或服务器定时执行 npm run build 并发布构建目录；只下载新组件而不重新构建，新的路由和侧边栏不会进入已上线站点。

故障处理 ​

  • 测试组件和基础设施包按配置自动排除。
  • 缺失 Manifest 或入口文件只影响对应组件。
  • UMD 不存在时自动尝试 ESM。
  • 空壳入口文件不会生成无法运行的文档页。
  • 组件中心整体临时不可用时，如果已有快照则继续使用上一次结果。