html-serialize

English version: README.md.

浏览器侧 HTML 序列化库，用于将实时 DOM 子树转换为包含布局、样式、变换、字体和资源信息的结构化 JSON。

这个仓库是独立 htmlSerialize() 运行时的正式公开包。它只发布浏览器序列化库和发布相关工具，不包含内部开发仓库中的调试插件或扩展侧能力。

功能特性

• 将 DOM 子树序列化为稳定的 JSON 文档。
• 捕获元素矩形、CSS 变换以及旋转后的四边形坐标。
• 保留文本节点，并可选保留纯空白文本节点。
• 只收集样式差量，而不是导出完整 computed style 对象。
• 在浏览器支持 computedStyleMap 时，为部分 Grid 相关属性补充 computedStyles。
• 将内联 SVG 序列化到 content 字段。
• 收集图片、background-image、canvas 栅格化结果和视频相关资源。
• 捕获字体使用信息。
• 支持 Shadow DOM 和 slot.assignedNodes({ flatten: true })。

安装

npm install html-serialize

运行要求

• 仅支持浏览器环境。
• 依赖 window、document、Range、DOMMatrix、DOMQuad、getComputedStyle，以及可选的 computedStyleMap 等 DOM API。
• 不适用于纯 Node.js SSR 环境。

快速开始

import { htmlSerialize } from 'html-serialize'

const target = document.querySelector('#app')

if (!target) {
  throw new Error('Target element not found')
}

const result = await htmlSerialize(target, {
  inlineAssets: true,
  inlineCanvasAssets: true,
  inlineVideoAssets: true,
  preserveWhitespaceTextNodes: true,
})

console.log(result)

Script 标签用法

<script src="./dist/index.umd.js"></script>
<script>
  const target = document.getElementById('app')
  HtmlSerialize.htmlSerialize(target).then(console.log)
</script>

Demo 示例

仓库内置了一个浏览器 Demo 页面，示例数据来自迁移后的 demo/cases/*.html。

npm install
npm run demo

执行后会：

• 从示例文件重新生成 demo/generated/cases.generated.js
• 重新构建 dist/index.umd.js
• 在 http://127.0.0.1:4173 启动本地静态服务器

如果你只想刷新生成后的示例清单，可以运行：

npm run build:demo

API

htmlSerialize(element, options?)

对一个 DOM 元素执行序列化，并返回 Promise。

function htmlSerialize(
  element: Element,
  options?: HtmlSerializeOptions
): Promise<SerializedDocument>

HtmlSerializeOptions

| 参数 | 类型 | 默认值 | 说明 | | --------------------------- | ----------- | --------- | ----------------------------------------------- | | abortSignal | AbortSignal | undefined | 取消序列化过程。 | | assertLayoutValid | boolean | true | 当根元素最终布局尺寸为 0 时抛错。 | | includeDataAttributes | boolean | string[] | false | 控制是否在 attributes 中保留 data-*；true 保留全部，string[] 按属性名白名单保留。 | | inlineAssets | boolean | true | 控制图片和 background-image 是否输出内联 blob。 | | inlineCanvasAssets | boolean | true | 控制 canvas 栅格化及 canvas 资源 blob 输出。 | | inlineVideoAssets | boolean | true | 控制 video poster 和当前帧相关资源处理。 | | preserveWhitespaceTextNodes | boolean | true | 是否保留纯空白或零尺寸文本节点。 | | skipRemoteAssets | boolean | false | 跳过远程资源下载，但不影响 data: 和 blob: URL。 |

输出概览

interface SerializedDocument {
  root: SerializedElementNode
  documentTitle?: string
  documentRect: SerializedRect
  viewportRect: SerializedRect
  devicePixelRatio: number
  fonts: Record<string, FontEntry>
  assets: Record<string, SerializedAssetEntry>
}

开发

npm install
npm run typecheck
npm run build

构建产物会输出到 dist/，包含 CJS、ESM、UMD 以及打包后的类型声明。

公开 Demo 用例的快照基线默认使用 system-browser 通道，位于 tests/snapshots/dom/system。

npm run snapshot:update
npm run snapshot:test

这些命令现在默认优先使用本机已安装的 Chromium 内核浏览器，例如 Google Chrome 或 Microsoft Edge，因此默认情况下不再依赖 Playwright 下载浏览器。

如果你仍然想使用旧的 bundled-browser 通道，请先安装 Playwright 自带浏览器，再运行：

npm run snapshot:install
npm run snapshot:update:bundled
npm run snapshot:test:bundled