template 标签是只读文档片段，不渲染、不执行、不绑定；其 content 为 DocumentFragment，需配合自定义元素注册、attachShadow 和 cloneNode(true) 才能生效，单独使用 slot 无效。
template 标签本身不渲染、不执行、不绑定，它只是个“待克隆的文档片段”；组件文档页面若直接嵌入 template 内容或依赖其自动生效，必然失败。
为什么文档里写<template><slot name="header"></slot></template>根本跑不起来
这是最典型的误解：把 template 当成 Vue 的 <template> 或 React 的 JSX 片段。浏览器原生 template 是只读容器，它的 content 是 DocumentFragment，不会解析内部 slot，也不触发任何分发逻辑——哪怕你把它 appendChild 到 body 里，slot 也纯属摆设。
- 常见错误现象：文档示例代码复制粘贴后空白、无内容、控制台无报错但渲染失败
- 真正起作用的前提是：该
template必须被某个自定义元素（如my-card）在constructor中通过this.attachShadow({ mode: 'open' })挂载，并显式cloneNode(true)插入shadowRoot - 文档中若只展示
template片段，却不说明“必须配合自定义元素注册”，等于给用户一个没钥匙的锁
组件文档里怎么安全嵌入可运行示例
用户要的是“复制、粘贴、双击打开就能看效果”，不是教你写 Web Component 全流程。所以示例必须是完整 HTML 页面，且规避沙箱限制。
- 每个示例区块用
<pre><code class="html">包裹，内容包含完整结构：<!DOCTYPE html>、<html>、<head>（含内联<style>和必要 polyfill）、<body>和组件使用代码 - 禁止用
innerHTML = '<my-card>...</my-card>'动态插入——这会绕过自定义元素注册时机，导致标签不升级 - 如果示例依赖 Shadow DOM，必须在
<script>中同步完成customElements.define()和实例创建，不能靠外部 JS 延迟加载 - 锚点 ID 必须全小写、无特殊字符（如
id="usage-basic"），否则文档内跳转失效；配合scroll-margin-top适配固定 header
template 与文档工具联动的关键约束点
所谓“联动”，不是让文档生成器自动识别 template 并渲染，而是人工约定如何组织、引用和验证模板片段。
立即学习“前端免费学习笔记（深入）”；
-
template必须有唯一id（如id="card-tpl"），文档中所有示例都通过document.getElementById('card-tpl')获取，避免硬编码内容导致维护断裂 - 文档构建脚本（如 VitePress 或手写 Node.js 脚本）可扫描页面中所有
template[id]，自动提取为“API 示例源”，但绝不能尝试直接append它们 - 若文档需支持 IE11，
template.content.cloneNode(true)不可用，得降级为注释包裹 +DOMParser解析，且必须加try/catch防止静默失败 - 服务端渲染（SSR）场景下，Go/Python 模板引擎输出的
template片段，必须用template.HTML类型绕过转义，否则<slot>标签会被当成纯文本
真正卡住人的从来不是语法，而是 template.content 的只读性、slot 对 Shadow DOM 的强依赖、以及文档示例和真实运行环境之间的那层“手动桥接”——漏掉 cloneNode(true) 或忘了 attachShadow，整个链条就断在第一步。
