Declarative Shadow DOM 怎么服务端输出组件结构

Declarative Shadow DOM（声明式 Shadow DOM）让服务器直接在 HTML 中输出组件内部结构。核心写法是：把 放在 Shadow Host 的直接子级，再把组件样式、内部标签和 写进这个模板。浏览器解析响应时会把模板内容变成宿主的 Shadow Root，不必等待 JavaScript 调用 attachShadow() 后再创建界面。

规范地址：https://html.spec.whatwg.org/multipage/scripting.html#attr-template-shadowrootmode

MDN 指南：https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM

消息是什么：Shadow Root 可以在解析 HTML 时建立

传统 Web Component 往往先输出一个空的自定义元素，等脚本下载和执行后再调用 attachShadow()，然后把内部结构塞进去。声明式方案把这部分结构提前放进服务器响应。浏览器的 HTML 解析器看到带 shadowrootmode 的 template 后，会在它的父元素上创建 Shadow Root，并把模板内容放入其中。

最小结构如下：

林澈
  
前端工程师，关注 Web Components。

页面解析完成后，user-card 是 Shadow Host；模板里的 style、article 和两个 slot 位于 Shadow Root；姓名和简介仍是 Light DOM 子节点，只是在渲染时分配进插槽。这种分工保留了组件封装，也让可替换内容继续属于文档树。

适用场景：首个响应就需要组件结构

Declarative Shadow DOM 最有价值的地方不是“少写一行 JavaScript”，而是把组件内部结构放进首个 HTML 响应。它适合以下场景：

• 内容型页面希望服务器先输出完整卡片、导航或文章部件，脚本稍后再增强交互。
• 组件内部 CSS 需要 Shadow DOM 作用域，但不希望首屏必须等待 JavaScript 构建节点。
• 站点采用流式 SSR，希望浏览器边接收边解析组件，而不是等整包客户端脚本加载。
• 自定义元素有清晰的结构层与交互层，服务器负责结构，客户端只负责事件和状态。

它并不会自动提供业务数据同步、事件绑定或应用状态恢复。声明式输出解决的是“结构如何出现在初始 HTML 中”，水合仍然是应用层工作。

快速试用：服务端渲染一个 user-card

下面使用 Node.js 内置 HTTP 模块演示，不依赖具体框架。重点是服务端渲染函数返回完整宿主结构，并对动态文本做 HTML 转义。

import http from "node:http";

// 转义来自数据库或请求的数据，避免把动态值当成 HTML 执行。
function escapeHTML(value) {
  return String(value).replace(/[&"']/g, (char) => ({
    "&": "&",
    "": ">",
    '"': """,
    "'": "'",
  })[char]);
}

// 服务端直接输出宿主、声明式 Shadow Root 与 Light DOM 数据。
function renderUserCard(user) {
  const name = escapeHTML(user.name);
  const bio = escapeHTML(user.bio);

  return `
    ${name}
      
${bio}
    `;
}

// 返回完整 HTML；客户端脚本只负责给现有结构补交互。
const server = http.createServer((request, response) => {
  const card = renderUserCard({ name: "林澈", bio: "关注 Web Components 与 SSR。" });
  response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
  response.end(`
    
      ${card}`);
});

// 监听本地端口，真实项目应交给框架或进程管理器处理生命周期。
server.listen(3000, "127.0.0.1");

这里把动态姓名和简介放在 Light DOM，是为了让服务端数据与组件内部结构解耦。卡片骨架和内部样式可以稳定复用，数据则通过 slot 注入。若数据需要成为 Shadow Tree 内部文本，也可以在服务端写入模板，但同样必须转义。

客户端水合：复用已有 shadowRoot

服务端已经创建了可解析结构，客户端类不应该再次把整棵树重建一遍。对于本文使用的 open 模式，可以读取 this.shadowRoot，找到按钮并绑定事件：

class UserCard extends HTMLElement {
  #events;

  connectedCallback() {
    // 先结束上一次连接留下的监听，避免节点移动后重复绑定。
    this.#events?.abort();
    this.#events = new AbortController();

    // 声明式 Shadow Root 已由解析器创建；这里直接复用。
    const root = this.shadowRoot;
    if (!root) {
      // 没有根通常表示浏览器不支持或服务端标记有误。
      console.warn("user-card 缺少声明式 Shadow Root");
      return;
    }

    const button = root.querySelector("[data-follow]");
    button?.addEventListener("click", () => {
      // 示例仅更新按钮状态，真实项目可在这里调用业务接口。
      button.textContent = "已关注";
      button.disabled = true;
    }, { signal: this.#events.signal });
  }

  disconnectedCallback() {
    // 组件离开文档时释放事件监听。
    this.#events?.abort();
  }
}

// 升级服务器已经输出到文档中的 user-card 元素。
customElements.define("user-card", UserCard);

这个实现有两个特点：一是没有调用 attachShadow()，因此不会破坏服务端结构；二是重连时主动清理旧监听，避免自定义元素在 DOM 中移动后产生重复事件。

MDN 对 attachShadow() 的当前说明里有一个容易踩坑的细节：如果宿主已有声明式 Shadow Root，再用相同 mode 调用 attachShadow()，浏览器会清空现有根并返回它；mode 不匹配则会抛出异常。因此水合代码不能把“再次 attach”当成无害操作。

和旧方案对比：结构创建时机不同

两者不是互相排斥的技术。一个组件库可以在 SSR 路径使用声明式模板，在纯客户端创建路径使用 attachShadow()。关键是让客户端知道当前宿主是否已经拥有服务端结构，避免一套代码无条件重建。

不支持时怎么降级

不认识 shadowrootmode 的浏览器会把普通 template 内容保持为惰性内容，组件内部结构不会自动显示。可以通过 HTMLTemplateElement.prototype.shadowRootMode 做特性检测，并在注册自定义元素之前，把模板内容手动移动到 Shadow Root。

// 只在缺少原生 Declarative Shadow DOM 时执行兼容逻辑。
if (!("shadowRootMode" in HTMLTemplateElement.prototype)) {
  document.querySelectorAll("template[shadowrootmode]").forEach((template) => {
    const host = template.parentElement;
    const mode = template.getAttribute("shadowrootmode");

    // 仅处理结构合法且 mode 明确的模板，避免误改普通 template。
    if (!host || (mode !== "open" && mode !== "closed")) return;

    const root = host.attachShadow({ mode });
    root.append(template.content);
    template.remove();
  });
}

// 兼容处理完成后再注册组件，让 connectedCallback 能看到现有结构。
await import("/user-card.js");

这个短兼容层只演示核心思路。复杂页面还要考虑嵌套声明式根、脚本执行顺序和内容安全策略。若产品必须覆盖大量旧环境，使用经过维护的 polyfill 比自行扩展这段示例更稳妥。

open、closed 与可水合性

shadowrootmode="open" 允许页面脚本通过宿主的 shadowRoot 属性访问内部根，适合需要客户端水合的组件。closed 会让该属性返回 null，更强调“外部代码不应直接访问”，但它不是安全隔离机制。

服务端渲染的交互组件通常更容易从 open 模式开始，因为升级类可以明确复用现有根。选择 closed 时，需要在组件设计阶段解决客户端如何获得内部引用，不能在水合时临时依赖 this.shadowRoot。

模板还可以声明 shadowrootdelegatesfocus、shadowrootclonable 等属性，但它们分别影响焦点委派和克隆行为，不是 SSR 的必选项。先把结构、水合与降级链路跑通，再根据组件实际需求启用。

采用风险与排查清单

上线前的最小核对

1. template[shadowrootmode] 是目标 Shadow Host 的直接子节点。
2. 内部样式、结构和 slot 都位于 template 中。
3. 所有服务端动态值都经过与输出上下文匹配的转义。
4. 交互组件使用 open 模式，并在水合时读取现有 shadowRoot。
5. 组件重连不会重复绑定事件，卸载时会释放监听。
6. 目标浏览器不支持时，有明确的 Light DOM 或 polyfill 降级路径。
7. 服务端与客户端共享同一套 slot 名、mode 和结构版本约定。

小结：服务端输出 Declarative Shadow DOM 的关键并不复杂：宿主内部放一个带 shadowrootmode 的模板，模板内写封装结构，模板外写可插槽化的 Light DOM 数据。真正需要工程判断的是水合边界——让服务器负责结构，让客户端复用现有根并补交互，才能避免重复创建和首屏结构被清空。