JavaScript Element.getHTML 怎样序列化可序列化的 Shadow DOM

我第一次把自定义元素做成可保存 HTML 时，直觉是读取 innerHTML。结果 Light DOM 能导出，组件内部的 Shadow DOM 却像“消失”了一样。这个现象不是选择器失效，而是序列化边界不同：Element.getHTML() 负责把元素序列化成 HTML 字符串，但 ShadowRoot 默认不会自动写进去。

这篇只解决一个问题：怎样让可序列化的 Shadow DOM 出现在结果里。核心记法是两层开关——创建 ShadowRoot 时决定它是否 serializable，调用 getHTML() 时再决定是否包含这些可序列化根。

如果只想得到普通元素内容，使用 element.getHTML()；如果还要带出创建时标记为可序列化的 Shadow DOM，使用 element.getHTML({ serializableShadowRoots: true })。不要把这两个设置当成同一个开关。

Element.getHTML 默认和 innerHTML 差在哪里

innerHTML关注的是元素的 Light DOM。getHTML()返回的也是 HTML 字符串，但它提供了额外的 options，用来处理 ShadowRoot。MDN 当前文档明确说明：不传参数时，ShadowRoot 不会被序列化，这时它的效果接近读取 innerHTML。

因此，遇到“页面上看得到，导出的字符串没有”的情况，我会先区分两个事实：元素本身是否有 Light DOM，以及内容是否只存在于 ShadowRoot。前者可以由 innerHTML覆盖，后者需要继续看 ShadowRoot 的创建标记和 getHTML 的 options。

先在创建时给 ShadowRoot 留下可序列化标记

可序列化不是调用时临时推断出来的属性。使用 attachShadow() 创建根时，可以把 serializable 设为 true；之后可以通过只读属性 shadow.serializable 了解这个根是否带有该标记。

// 说明：创建一个可被 getHTML 选择性带出的 ShadowRoot。
const host = document.querySelector("profile-card");
const shadow = host.attachShadow({
  mode: "open", // open 只影响外部能否通过 host.shadowRoot 访问它
  serializable: true // 创建时写入“可序列化”标记
});

shadow.innerHTML = "组件内部内容";
console.log(shadow.serializable); // true

这里的 mode: "open" 和 serializable: true 解决的是两件事：前者关系到脚本能否通过宿主元素拿到 ShadowRoot，后者关系到它能否被“可序列化根”选项包含。把 mode 改成 closed，并不会自动让它失去序列化资格；只是你通常不能再从 host.shadowRoot 取得它。

调用时用 serializableShadowRoots 包含嵌套内容

创建时已经标记还不够，调用 Element.getHTML() 时还要显式传 serializableShadowRoots: true。这个参数的含义是：把元素树中标记为可序列化的 ShadowRoot 纳入结果。

// 说明：分别保留“普通内容”和“包含可序列化 Shadow DOM”的两种导出结果。
const plainHTML = host.getHTML();
const withShadowHTML = host.getHTML({
  serializableShadowRoots: true // 只选择已标记 serializable 的根
});

console.log(plainHTML); // 不主动包含 ShadowRoot
console.log(withShadowHTML); // 可包含 profile-card 的可序列化根

这也是我更愿意把它看成“边界组合”而不是“万能导出”的原因。serializableShadowRoots 默认是 false；设置为 true 只放宽对可序列化根的选择，并不表示所有 ShadowRoot 都会被无条件导出。

closed root 和 shadowRoots 选项不要混为一谈

如果业务确实保留了 ShadowRoot 对象，还可以把它们放进 shadowRoots 数组。MDN 说明，这个数组中的根会被纳入序列化，即使它们不是 serializable，也不论它们是 open 还是 closed。重点是“你必须已经持有这些对象的引用”。closed root 不会通过 host.shadowRoot 暴露，但创建时可以保存 attachShadow() 的返回值。

// 说明：closed root 不从 host.shadowRoot 读取，而是使用创建时保存的引用。
const closedHost = document.querySelector("private-card");
const closedShadow = closedHost.attachShadow({
  mode: "closed", // 外部读取 closedHost.shadowRoot 会得到 null
  serializable: false
});
closedShadow.innerHTML = "内部片段";

// 说明：显式提供引用时，该根可作为 getHTML 的 shadowRoots 输入。
const exported = closedHost.getHTML({
  shadowRoots: [closedShadow]
});

这个分支适合组件库或渲染管线在创建阶段就掌握根引用的场景，不适合拿来绕过封装边界。对普通组件，优先使用 serializable: true 加 serializableShadowRoots: true，让“哪些根允许被导出”成为明确的组件设计约定。

我的判断清单：什么时候选哪种写法

• 只需导出 Light DOM：使用 getHTML() 或 innerHTML，不要为不存在的 Shadow DOM 增加选项。
• 要导出组件内部且能在创建时控制根：创建时设置 serializable: true，调用时传 serializableShadowRoots: true。
• 要导出特定根且已经持有引用：使用 shadowRoots 数组，尤其注意 open/closed 只是访问方式，不等于是否可序列化。
• 面向旧浏览器：先做能力检测并准备降级文本或服务端渲染结果；MDN 将该能力标为 Baseline 2024，旧环境仍可能不支持。

最后再提醒一次：getHTML()只是序列化 API，不等于把字符串重新插入页面时的安全策略。导出结果如果要进入后续渲染流程，仍应按自己的输入来源和清洗策略处理。

相关问题

为什么 getHTML() 看不到 Shadow DOM？ 因为默认不包含 ShadowRoot；检查创建时的 serializable 标记，再考虑 serializableShadowRoots: true。

serializableShadowRoots 能包含任意 closed root 吗？ 不能。它面向标记为可序列化的根；需要显式包含特定 closed root 时，要在创建阶段保存返回引用，并传入 shadowRoots。

getHTML() 和 innerHTML 返回的是什么？ 两者都可以得到 HTML 字符串，但 getHTML 提供了处理 Shadow DOM 的 options，具体范围取决于调用参数和根的创建方式。