深入理解HTML模板在组件开发中的作用

template标签不渲染且不激活slot，必须通过customElements.define定义自定义元素、attachShadow挂载Shadow DOM、cloneNode(true)克隆template.content三步才能使slot生效。

template 标签本身不渲染，也不自动激活 slot

直接把 <template><slot></slot></template> 写在页面里，什么都不会发生——浏览器只把它当一段“待用但暂存”的 HTML 片段。它不会解析内部的 <slot>，更不会触发内容分发逻辑。

常见错误现象包括：

• 模板内容完全不可见，控制台无报错
• 写在 <template> 里的 <script> 或 <style> 不执行、不生效
• 试图用 innerHTML 直接插入 <template> 元素，结果只得到空节点

根本原因在于：<template> 的 content 是一个 DocumentFragment，必须显式调用 cloneNode(true) 才能生成可挂载的节点树。

slot 只在 Shadow DOM 中起作用，且只匹配直系子节点

<slot> 不是通用的内容占位符，它只在自定义元素的 Shadow DOM 作用域内工作，并且只对该自定义元素的**直接子元素**进行分发。层级嵌套或间接包裹都会导致匹配失败。

立即学习“前端免费学习笔记（深入）”；

例如，以下写法无效：

<my-card>
  <p><h2 slot="header">Title</h2></p>
</my-card>

因为 <h2 slot="header"> 不是 <my-card> 的直系子节点，slot 无法捕获它。

正确做法是：

• 确保插槽内容是自定义元素的直接子节点
• slot 的 name 属性必须与模板中声明的完全一致（大小写敏感）
• 默认插槽（无 name）只接收所有未被命名插槽匹配的直系子节点

必须通过 customElements.define + attachShadow 显式桥接 template 和 slot

想让 <template> 里的 <slot> 生效，三步缺一不可：

• 定义一个继承 HTMLElement 的类
• 在 constructor() 中调用 this.attachShadow({ mode: 'open' })
• 从 <template> 获取 content.cloneNode(true) 并 append 到 this.shadowRoot

示例关键代码：

class MyCard extends HTMLElement {
  constructor() {
    super();
    const tpl = document.getElementById('card-tpl');
    this.attachShadow({ mode: 'open' }).appendChild(tpl.content.cloneNode(true));
  }
}
customElements.define('my-card', MyCard);

漏掉 attachShadow 或跳过 cloneNode，<slot> 就只是普通标签，不会做任何分发。

template.content.cloneNode(true) 是安全克隆的唯一可靠方式

不要用 innerHTML 或 outerHTML 提取模板内容——这会丢失事件监听器、脚本上下文，还可能触发重复执行或 XSS 风险。

cloneNode(true) 的优势：

• 保留所有节点结构、属性、文本内容
• 不执行其中的 <script>，避免意外副作用
• 分离样式作用域，适合注入 Shadow DOM
• 多次调用互不影响，天然支持复用

注意：如果模板里有 <input> 或 <textarea>，克隆后需手动重置其 value，因为 cloneNode 不复制用户输入值。

最容易被忽略的一点：template 和 slot 的联动不是语法糖，而是需要你亲手搭桥的底层机制。没注册自定义元素、没挂 Shadow DOM、没克隆 content，三者任一缺失，整个链路就断在第一步。