直接用html模板写组件文档易失控，因缺乏元数据、类型约束和复用机制，导致写法不一、props易漏、示例不可验；需通过jsdoc注释驱动、data-demo动态加载及构建时校验实现自动化与一致性。
为什么直接用 HTML 模板写组件文档容易失控
HTML 模板本身不带元数据、无类型约束、难复用，写多了就会出现：同一组件在不同文档里写法不一致、props 列表靠手敲易漏、示例代码无法校验是否真实可运行。核心问题不是“能不能写”，而是“改一个组件，要同步更新多少个 HTML 文件”。
真正需要的不是更漂亮的 HTML，而是让模板能被程序识别、提取、校验。
-
data-props或data-example这类自定义属性别乱加——它们不会被任何工具自动读取，纯属徒劳 - 不要把示例代码硬塞进
<pre class="brush:php;toolbar:false;"><code></code> 里就完事，缺少上下文（比如是否引入了 CSS、是否挂载了 JS）会导致复制即报错</pre> - 避免用
id或class做语义标识（如class="props-table"），这类选择器极易被样式污染或误删
用 JSDoc + 注释驱动生成 HTML 文档
把组件定义和文档写在一起，而不是维护两套东西。关键不是“写文档”，而是“让组件自己说话”。
以一个 Button 组件为例，在其 HTML 模板顶部加 JSDoc 注释块：
/**
* @component Button
* @description 主要用于触发操作，支持多种尺寸和状态
* @prop {string} size - 可选值：'sm' | 'md' | 'lg'
* @prop {boolean} disabled - 是否禁用
* @example
* <button class="btn" data-size="md" data-disabled="true">提交</button>
*/
然后用 jsdoc 配合自定义模板（如 jsdoc-to-html 或轻量脚本）提取这些注释，生成结构化 HTML。所有 @prop 会转成表格，@example 自动渲染为可复制代码块。
- 必须用
@component标记组件名，否则工具无法归类 -
@example中的代码需是完整可运行片段（含必要 class 和 data 属性），不能只写<button></button> - 避免在注释里写“见 demo 页面”——这等于放弃自动化，回归人工同步
HTML 模板里嵌入可执行示例的最小安全方案
用户点开文档就想看效果，但 iframe 或 script 标签直接内联有 CSP 风险，且无法热更新。稳妥做法是用 data-demo 属性标记容器，由统一加载器接管。
在文档 HTML 中这样写：
<div data-demo="Button" data-props='{"size": "md", "disabled": false}'></div>
配套一个全局 initDemos() 函数，它会查找所有 data-demo 元素，根据值动态 import 对应组件模块（如 ./components/Button.js），再用 data-props 渲染实例。
-
data-props必须是合法 JSON 字符串，不能写{size: md}（缺引号、未字符串化） - 组件模块导出必须是函数或类，且接受 props 参数并返回 DOM 节点，否则加载器无法调用
- 不要给
data-demo容器设固定高度——组件实际渲染后才知高矮，强制设值会导致截断或留白
构建时校验 HTML 模板与 JSDoc 的一致性
最常被忽略的一环：没人检查你写的 @prop size 在模板里是不是真用了 data-size。靠人眼比对等于没防。
写个简单 CLI 脚本（比如用 cheerio 解析 HTML，用 doctrine 解析 JSDoc），做三件事：
- 扫描所有 HTML 文件里的
data-*属性，提取前缀（如size来自data-size） - 对比 JSDoc 中
@prop列表，报告缺失项（写了文档但模板没用）和冗余项（模板用了但没文档） - 检查
@example中的属性是否全在@prop中声明过，防止示例误导
把这个脚本加进 npm run build 或 CI 流程里。一旦不一致，直接退出并输出类似 Button.html: data-loading missing in @prop 的提示——比等 QA 发现快得多。
复杂点在于模板可能用条件渲染（如 data-size 只在 variant !== 'text' 时出现），这种得靠人工标注 @prop size [optional]，工具才不会误报。别指望全自动覆盖所有逻辑分支。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
