组件文档页面应手写HTML+原生JS,禁用框架;API表格须用语义化table固定四列;示例代码需最小可运行HTML片段;模板须纯结构、语义清晰、路径可配置。

组件文档页面该不该用模板引擎
手写 HTML + 原生 JS 就够了,别上 React/Vue 或 art-template。你只是展示 API 和用法,不是跑应用——框架会引入构建依赖、跨域限制、模块解析失败,连双击打开 index.html 都可能白屏。本地可运行、零构建、无运行时依赖,才是文档页的底线。
API 表格怎么用 HTML 原生结构写清楚
表格必须固定四列:Name、Type、Default、Description。别用 div 模拟表格,语义丢失、屏幕阅读器读不出结构、复制粘贴错行。
-
Type写string、boolean | undefined,不写“字符串类型”或“可为空” -
Name末尾加?表示可选,如size?,别靠文字说明 -
Default填具体值:false、''、null,不填“无”或“默认关闭” - ID 必须全小写、无空格和特殊字符,否则锚点跳转失效;配合
scroll-margin-top适配固定 header
示例代码区块怎么嵌入才真正可用
每个示例必须是「最小可运行片段」:含 <!DOCTYPE html>、<html lang="zh-CN">、必要 <meta charset="UTF-8">、引入样式与脚本的相对路径,以及组件标签本身。
- HTML 示例用
<pre><code class="html">包裹,JS 示例第一行加// 在组件定义之后执行,避免用户误当入口 - 绝对不用
document.write()或同步fetch加载 demo,阻塞渲染且无法离线查看 - 图片、图标等资源用相对路径,不写死
https://cdn.example.com/,否则本地双击就 404
模板复用时最容易被忽略的语义断层
把 <div class="button"> 抽成模板没问题,但若它内部硬编码了 <svg> 或内联 style,就丧失复用前提——模板必须是纯结构钩子,样式和行为由外部控制。
立即学习“前端免费学习笔记(深入)”;
- 所有模板应以语义化标签为边界:
<button>模板里不能塞<h3>,标题属于父级上下文 - 混内联 JS 的片段(如
onclick="doSomething()")必须先剥离逻辑,改用事件委托或data-*属性驱动 - 硬编码路径(如
src="assets/logo.png")要替换为占位符或通过 JS 注入,否则换项目就挂
真正难的不是拆模板,而是让每个模板在脱离上下文时仍保有明确职责——它得知道自己是按钮、是表单域、还是错误提示,而不是一堆 class 堆出来的 div。



















