把 DOM 直接变成
真正的矢量 PDF。 Turn the DOM into
real vector PDFs.

npm

npm install dompdf.js

运行环境需要现代浏览器以及 Worker、WebAssembly、Blob 等 Web API。包本身要求 Node.js 18+ 用于安装、构建和开发，但导出 API 依赖 DOM，不能直接在纯 Node.js 环境中调用。

CDN

<script src="https://cdn.jsdelivr.net/npm/dompdf.js@latest/dist/dompdf.min.js"></script>

通过 <script> 引入后，API 会挂载到全局 dompdf。

npm

npm install dompdf.js

The runtime requires a modern browser with Web Workers, WebAssembly, Blob, and related Web APIs. The package requires Node.js 18+ for installation, builds, and development, but its export APIs depend on the DOM and cannot be called directly in a plain Node.js environment.

CDN

<script src="https://cdn.jsdelivr.net/npm/dompdf.js@latest/dist/dompdf.min.js"></script>

When loaded through a <script> tag, the API is exposed globally as dompdf.

import dompdf, { exportPDF, renderToBytes, downloadPDF, inspect } from 'dompdf.js';

// 默认导出：返回 Blob
const blob = await dompdf(element, options);

// 与默认导出等价
const sameBlob = await exportPDF(element, options);

// 原始字节
const bytes: Uint8Array = await renderToBytes(element, options);

// 触发浏览器下载
await downloadPDF(element, options, 'invoice.pdf');

// 诊断摘要
console.log(await inspect(element, { pagination: true }));

高级快照 API

包还导出了以下底层函数：

• collectSnapshot(root, options?) -> Promise<Uint8Array>：采集并编码 DOM 快照
• collectSnapshotData(root, options?)：返回编码前的中间数据
• encodeSnapshot(data, perPageHF, perPageWatermark?) -> Uint8Array：编码中间数据
• computePageBreaks(root, options?) -> number[]：计算相对根元素顶部的分页 Y 坐标
• pageConfigNeedsPerPageResolution、watermarkNeedsPerPageResolution：判断配置是否需要逐页解析
• resolvePerPageHF、resolveStaticPageConfigHF：解析逐页页眉页脚
• resolvePerPageWatermark、resolveStaticWatermarkPages：解析逐页水印

这些接口面向调试、可视化分页和自定义流水线。快照二进制格式属于项目内部协议，普通业务代码应优先使用 dompdf、exportPDF、renderToBytes 或 downloadPDF。

import dompdf, { exportPDF, renderToBytes, downloadPDF, inspect } from 'dompdf.js';

// Default export: returns a Blob
const blob = await dompdf(element, options);

// Equivalent to the default export
const sameBlob = await exportPDF(element, options);

// Raw bytes
const bytes: Uint8Array = await renderToBytes(element, options);

// Triggers a browser download
await downloadPDF(element, options, 'invoice.pdf');

// Diagnostic summary
console.log(await inspect(element, { pagination: true }));

Advanced snapshot APIs

The package also exports these lower-level functions:

• collectSnapshot(root, options?) -> Promise<Uint8Array>: collect and encode a DOM snapshot
• collectSnapshotData(root, options?): return the intermediate data before encoding
• encodeSnapshot(data, perPageHF, perPageWatermark?) -> Uint8Array: encode intermediate data
• computePageBreaks(root, options?) -> number[]: calculate page-break Y coordinates relative to the root element
• pageConfigNeedsPerPageResolution and watermarkNeedsPerPageResolution: determine whether a configuration needs per-page resolution
• resolvePerPageHF and resolveStaticPageConfigHF: resolve per-page headers and footers
• resolvePerPageWatermark and resolveStaticWatermarkPages: resolve per-page watermarks

These APIs are intended for diagnostics, pagination overlays, and custom pipelines. The snapshot binary format is an internal protocol; normal application code should prefer dompdf, exportPDF, renderToBytes, or downloadPDF.

完整 TypeScript 类型以 src/snapshot.ts 和发布包内的 dist/types 为准。

See src/snapshot.ts and the published package's dist/types directory for the complete TypeScript definitions.

单页与分页模式

• pagination: false：生成一张内容驱动高度的长页面，适合票据、截图替代和连续文档
• pagination: true：根据纸张、页边距、页眉和页脚的可用区域生成多页 PDF

await dompdf(element, {
  format: 'a4',
  pagination: true,
  marginPt: [36, 36, 36, 36],
});

为了获得稳定的分页结果，建议让待导出容器的 CSS 宽度接近目标纸张的内容宽度。A4 在 96 DPI 下为约 794px × 1123px；如果设置了页边距，还要从中减去对应宽度。

常见纸张尺寸见 page_sizes.md。当前支持：

• a0 到 a10
• b0 到 b10
• c0 到 c10
• letter、government-letter
• legal、junior-legal、government-legal
• tabloid、ledger

自定义横向 A4 可以直接交换宽高：

await dompdf(element, {
  format: [842.25, 595.5],
  pagination: true,
});

也可以使用 pageWidthPt 和 pageHeightPt 覆盖 format。orientation 目前只是旧版兼容参数，不会自动交换纸张宽高。

强制分页与避免拆分

在元素上添加 pageBreak 属性，可要求分页器在该元素前换页：

<section>第一页内容</section>
<section pageBreak>从新页面开始</section>

添加 divisionDisable 属性，可尽量避免整个元素跨页拆分：

<article divisionDisable>
  这部分内容会尽量保持在同一页。
</article>

当元素本身高于一整页可用高度时，分页器仍可能拆分它，避免产生无法放置的内容。

Continuous and paginated modes

• pagination: false: create one content-driven continuous page, useful for receipts, screenshot replacement, and continuous documents
• pagination: true: create a multi-page PDF using the available area left by the page size, margins, header, and footer

await dompdf(element, {
  format: 'a4',
  pagination: true,
  marginPt: [36, 36, 36, 36],
});

For stable pagination, keep the export container's CSS width close to the target page's content width. A4 is approximately 794px x 1123px at 96 DPI; configured margins must be subtracted from that width.

See page_sizes.md for common dimensions. Supported names include:

• a0 through a10
• b0 through b10
• c0 through c10
• letter and government-letter
• legal, junior-legal, and government-legal
• tabloid and ledger

For landscape A4, swap the dimensions explicitly:

await dompdf(element, {
  format: [842.25, 595.5],
  pagination: true,
});

You can also override format with pageWidthPt and pageHeightPt. The orientation option is currently retained only for legacy compatibility and does not swap the page dimensions automatically.

Forced breaks and avoiding splits

Add a pageBreak attribute to request a page break before an element:

<section>First-page content</section>
<section pageBreak>Start on a new page</section>

Add a divisionDisable attribute to keep an element on one page where possible:

<article divisionDisable>
  This block will be kept together when possible.
</article>

An element taller than the entire available page area may still be split so that the content remains placeable.

固定配置

await dompdf(element, {
  pagination: true,
  pageConfig: {
    excludePages: [1],
    header: {
      content: '季度经营报告',
      height: 48,
      contentColor: '#334155',
      contentFontSize: 11,
      contentPosition: 'centerLeft',
      padding: [0, 24, 0, 24],
    },
    footer: {
      content: '第 ${currentPage} / ${totalPages} 页',
      height: 48,
      contentColor: '#64748b',
      contentFontSize: 10,
      contentPosition: 'center',
      padding: [0, 24, 0, 24],
    },
  },
});

content 支持以下占位符：

• ${currentPage}：当前页码，从 1 开始
• ${totalPages}：总页数

contentPosition 支持：

• center、centerLeft、centerRight
• centerTop、centerBottom
• leftTop、leftBottom
• rightTop、rightBottom
• [x, y] 自定义坐标

padding 顺序为 [上, 右, 下, 左]。excludePage 可以接收单个页码或页码数组，excludePages 接收页码数组。

启用分页但没有传入 pageConfig 时，当前版本会默认保留 50px 的空页眉区域，并在 50px 页脚中输出 ${currentPage}/${totalPages}。如需完全自定义，请显式传入 pageConfig。

Slots（Phase 1）

header / footer 现在支持 slots，可在同一页眉或页脚中放置多个文本块，并为每个 slot 单独指定字体、颜色、位置：

await dompdf(element, {
  pagination: true,
  pageConfig: {
    header: {
      height: 48,
      padding: [8, 24, 0, 24],
      slots: [
        {
          content: '季度经营报告',
          position: 'leftTop',
          color: '#334155',
          fontSize: 11,
          fontFamily: 'Source Han Sans SC',
          fontWeight: 700,
        },
        {
          content: '第 ${currentPage} / ${totalPages} 页',
          position: { x: '100%', y: 0, anchor: 'rightTop' },
          color: '#64748b',
          fontSize: 10,
        },
      ],
    },
  },
});

说明：

• slots 存在时，优先于旧版 content / contentPosition
• position 既支持语义位置，也支持坐标对象
• 坐标对象的原点是页眉/页脚内容区左上角，x/y 支持数字、'50%'、'100%-24'
• anchor 默认是 leftTop

slot 可用字段：

• content: 文本内容，支持 ${currentPage} / ${totalPages}
• position: 语义位置，或 { x, y, anchor }
• color: 文本颜色
• fontSize: 字号（px）
• fontFamily: 字体名称，需配合 fontConfig 中已注册的字体使用
• fontWeight: 字重
• italic: 是否斜体

坐标定位示例：

slots: [
  {
    content: '左上标题',
    position: 'leftTop',
  },
  {
    content: '右上页码',
    position: { x: '100%', y: 0, anchor: 'rightTop' },
  },
  {
    content: '右下说明',
    position: { x: '100%-24', y: '100%-10', anchor: 'rightBottom' },
  },
]

其中：

• x: '100%' 表示内容区最右侧参考线
• x: '100%-24' 表示在最右侧基础上向左偏移 24px
• y: '100%-10' 表示在内容区底部基础上向上偏移 10px
• anchor 决定坐标对应的是文本框的哪个参考点

逐页配置

函数形式会在已知总页数后按页调用，返回 null 可禁用该页的页眉页脚：

await dompdf(element, {
  pagination: true,
  pageConfig(pageNum, totalPages) {
    if (pageNum === 1) return null;

    return {
      header: {
        content: '内部资料',
        height: 40,
        contentPosition: 'rightTop',
      },
      footer: {
        content: `${pageNum} / ${totalPages}`,
        height: 40,
        contentPosition: 'center',
      },
    };
  },
});

PageRegionConfig.content 的函数签名是旧版兼容入口，目前不会获得可操作的 PDF renderer。需要动态内容时，请使用 pageConfig(pageNum, totalPages) 返回字符串内容。

Static configuration

await dompdf(element, {
  pagination: true,
  pageConfig: {
    excludePages: [1],
    header: {
      content: 'Quarterly Operations Report',
      height: 48,
      contentColor: '#334155',
      contentFontSize: 11,
      contentPosition: 'centerLeft',
      padding: [0, 24, 0, 24],
    },
    footer: {
      content: 'Page ${currentPage} / ${totalPages}',
      height: 48,
      contentColor: '#64748b',
      contentFontSize: 10,
      contentPosition: 'center',
      padding: [0, 24, 0, 24],
    },
  },
});

content supports these placeholders:

• ${currentPage}: current page number, starting at 1
• ${totalPages}: total number of pages

contentPosition supports:

• center, centerLeft, and centerRight
• centerTop and centerBottom
• leftTop and leftBottom
• rightTop and rightBottom
• [x, y] for custom coordinates

padding uses the order [top, right, bottom, left]. excludePage accepts one page number or an array, while excludePages accepts an array of page numbers.

When pagination is enabled without an explicit pageConfig, the current version reserves an empty 50px header band and renders ${currentPage}/${totalPages} in a 50px footer. Pass pageConfig explicitly when you need full control.

Slots (Phase 1)

header / footer now support slots, so you can place multiple text blocks inside the same region and control font, color, and position per slot:

await dompdf(element, {
  pagination: true,
  pageConfig: {
    header: {
      height: 48,
      padding: [8, 24, 0, 24],
      slots: [
        {
          content: 'Quarterly Business Review',
          position: 'leftTop',
          color: '#334155',
          fontSize: 11,
          fontFamily: 'Source Han Sans SC',
          fontWeight: 700,
        },
        {
          content: 'Page ${currentPage} / ${totalPages}',
          position: { x: '100%', y: 0, anchor: 'rightTop' },
          color: '#64748b',
          fontSize: 10,
        },
      ],
    },
  },
});

Notes:

• slots take precedence over legacy content / contentPosition
• position supports both semantic presets and coordinate objects
• Coordinate objects use the header/footer inner box top-left as the origin; x/y accept numbers, '50%', and '100%-24'
• anchor defaults to leftTop

Available slot fields:

• content: text content, with ${currentPage} / ${totalPages} placeholders
• position: a semantic preset or { x, y, anchor }
• color: text color
• fontSize: font size in px
• fontFamily: font family name; pair it with a registered font in fontConfig
• fontWeight: font weight
• italic: whether italic styling is enabled

Coordinate examples:

slots: [
  {
    content: 'Top-left title',
    position: 'leftTop',
  },
  {
    content: 'Top-right page number',
    position: { x: '100%', y: 0, anchor: 'rightTop' },
  },
  {
    content: 'Bottom-right note',
    position: { x: '100%-24', y: '100%-10', anchor: 'rightBottom' },
  },
]

In this model:

• x: '100%' targets the right edge of the inner region
• x: '100%-24' moves 24px left from that edge
• y: '100%-10' moves 10px upward from the bottom edge of the inner region
• anchor defines which point of the text box is aligned to the coordinate

Per-page configuration

The function form is called for every page after the total page count is known. Return null to disable the header and footer for a page:

await dompdf(element, {
  pagination: true,
  pageConfig(pageNum, totalPages) {
    if (pageNum === 1) return null;

    return {
      header: {
        content: 'Internal Use Only',
        height: 40,
        contentPosition: 'rightTop',
      },
      footer: {
        content: `${pageNum} / ${totalPages}`,
        height: 40,
        contentPosition: 'center',
      },
    };
  },
});

The function signature accepted by PageRegionConfig.content is a legacy compatibility entry point and does not receive an operable PDF renderer. For dynamic content, use pageConfig(pageNum, totalPages) and return string content.

文字水印

await dompdf(element, {
  pagination: true,
  watermark: {
    text: '内部资料 ${currentPage}/${totalPages}',
    color: 'rgba(185, 28, 28, 0.14)',
    fontFamily: 'Helvetica',
    fontSize: 28,
    fontWeight: 700,
    angle: -35,
    spacing: [180, 130],
    offset: [40, 40],
    layer: 'under',
    excludePages: [1],
  },
});

文字水印默认值包括：角度 35、字号 28px、颜色 rgba(0, 0, 0, 0.12)、间距 [160, 120]、偏移 [36, 36]、层级 under。

图片水印

await dompdf(element, {
  pagination: true,
  useCORS: true,
  watermark: {
    imageUrl: '/assets/company-mark.png',
    imageWidth: 120,
    opacity: 0.1,
    angle: -30,
    spacing: [220, 160],
    layer: 'over',
  },
});

图片水印支持 imageWidth、imageHeight 和 opacity。只指定宽或高时会按照原图比例计算另一边。

逐页水印

await dompdf(element, {
  pagination: true,
  watermark(pageNum) {
    if (pageNum === 1) return null;
    return {
      text: pageNum % 2 === 0 ? '偶数页' : '奇数页',
      color: 'rgba(30, 64, 175, 0.12)',
      layer: 'under',
    };
  },
});

Text watermarks

await dompdf(element, {
  pagination: true,
  watermark: {
    text: 'INTERNAL ${currentPage}/${totalPages}',
    color: 'rgba(185, 28, 28, 0.14)',
    fontFamily: 'Helvetica',
    fontSize: 28,
    fontWeight: 700,
    angle: -35,
    spacing: [180, 130],
    offset: [40, 40],
    layer: 'under',
    excludePages: [1],
  },
});

Text-watermark defaults include angle 35, font size 28px, color rgba(0, 0, 0, 0.12), spacing [160, 120], offset [36, 36], and layer under.

Image watermarks

await dompdf(element, {
  pagination: true,
  useCORS: true,
  watermark: {
    imageUrl: '/assets/company-mark.png',
    imageWidth: 120,
    opacity: 0.1,
    angle: -30,
    spacing: [220, 160],
    layer: 'over',
  },
});

Image watermarks support imageWidth, imageHeight, and opacity. If only width or height is supplied, the other dimension is calculated from the source aspect ratio.

Per-page watermarks

await dompdf(element, {
  pagination: true,
  watermark(pageNum) {
    if (pageNum === 1) return null;
    return {
      text: pageNum % 2 === 0 ? 'EVEN PAGE' : 'ODD PAGE',
      color: 'rgba(30, 64, 175, 0.12)',
      layer: 'under',
    };
  },
});

非拉丁文本建议显式嵌入 TTF 字体。最可靠的方式是先加载字体，再通过 fontBytes 传入：

import dompdf from 'dompdf.js';

const fontBuffer = await fetch('/fonts/SourceHanSansSC-Regular.ttf').then((response) => {
  if (!response.ok) throw new Error(`字体加载失败：${response.status}`);
  return response.arrayBuffer();
});

await dompdf(element, {
  fontConfig: {
    fontFamily: 'SourceHanSansSC-Regular',
    fontBytes: new Uint8Array(fontBuffer),
    fontStyle: 'normal',
    fontWeight: 400,
  },
});

fontConfig 可传单个字体或数组。主要字段：

类型中保留了 fontUrl，但当前采集器不会主动读取它。需要从 URL 加载字体时，请先 fetch 并转换为 Uint8Array。

多语言字体回退

langFontConfig 可以通过 Unicode 范围选择字体，并设置默认回退字体：

await dompdf(element, {
  langFontConfig: [
    {
      fontFamily: 'SourceHanSansSC-Regular',
      fontBytes: chineseFontBytes,
      charRange: [[0x3400, 0x9fff]],
    },
    {
      fontFamily: 'NotoSans-Regular',
      fontBytes: fallbackFontBytes,
      isDefault: true,
    },
  ],
});

仓库提供了 examples/SourceHanSansSC-Regular.ttf，可用于本地演示和验证。生产项目应确认所用字体的授权范围，并避免重复注册体积较大的完整字体。

For non-Latin text, explicitly embed a TTF font. The most reliable approach is to load the font first and pass it through fontBytes:

import dompdf from 'dompdf.js';

const fontBuffer = await fetch('/fonts/SourceHanSansSC-Regular.ttf').then((response) => {
  if (!response.ok) throw new Error(`Font request failed: ${response.status}`);
  return response.arrayBuffer();
});

await dompdf(element, {
  fontConfig: {
    fontFamily: 'SourceHanSansSC-Regular',
    fontBytes: new Uint8Array(fontBuffer),
    fontStyle: 'normal',
    fontWeight: 400,
  },
});

fontConfig accepts one font or an array. Its main fields are:

The type definition retains fontUrl, but the current collector does not fetch it. Load URL-based fonts yourself and pass them as a Uint8Array.

Language-based font fallback

langFontConfig selects fonts by Unicode range and can define a default fallback:

await dompdf(element, {
  langFontConfig: [
    {
      fontFamily: 'SourceHanSansSC-Regular',
      fontBytes: chineseFontBytes,
      charRange: [[0x3400, 0x9fff]],
    },
    {
      fontFamily: 'NotoSans-Regular',
      fontBytes: fallbackFontBytes,
      isDefault: true,
    },
  ],
});

The repository includes examples/SourceHanSansSC-Regular.ttf for local demos and verification. In production, verify the font's license and avoid registering duplicate copies of large complete fonts.

表单值以导出开始时的 DOM 当前状态为准，而不是初始 HTML 属性值。

await dompdf(element, {
  pagination: true,
  form: {
    mode: 'hybrid',
    include: [
      'text',
      'textarea',
      'select',
      'checkbox',
      'radio',
      'date-time',
      'range',
      'color',
      'file',
      'progress',
      'meter',
    ],
  },
});

模式说明：

• static：默认模式，只保留控件当前的静态视觉外观
• interactive：为具备自然 PDF 映射的控件生成 AcroForm 字段
• hybrid：保留静态视觉，同时附加交互字段

当前交互字段映射：

• 文本类 input、textarea
• select
• checkbox
• radio

以下类型会保留静态外观，但不会生成等价的交互字段：

• date、time、month、week、datetime-local
• range、color、file
• progress、meter

form: true 与默认行为一样仍是静态模式；要生成交互字段，必须显式设置 mode: 'interactive' 或 mode: 'hybrid'。

Form values are captured from the DOM state at the start of the export, rather than from the initial HTML attributes.

await dompdf(element, {
  pagination: true,
  form: {
    mode: 'hybrid',
    include: [
      'text',
      'textarea',
      'select',
      'checkbox',
      'radio',
      'date-time',
      'range',
      'color',
      'file',
      'progress',
      'meter',
    ],
  },
});

Modes:

• static: the default; preserve only the control's current visual appearance
• interactive: create AcroForm fields for controls with a natural PDF mapping
• hybrid: preserve the static appearance and add interactive fields

Current interactive-field mappings:

• Text-like input elements and textarea
• select
• checkbox
• radio

The following types retain a static appearance but do not produce equivalent interactive fields:

• date, time, month, week, and datetime-local
• range, color, and file
• progress and meter

form: true still uses the default static mode. To generate interactive fields, explicitly set mode: 'interactive' or mode: 'hybrid'.

await dompdf(element, {
  encryption: {
    userPassword: 'reader-password',
    ownerPassword: 'owner-password',
    userPermissions: ['print', 'copy'],
  },
});

可用权限：

• print：允许打印
• modify：允许修改
• copy：允许复制内容
• annot-forms：允许注释和填写表单

传入未知权限会抛出错误。PDF 权限最终是否严格执行还取决于阅读器；权限标志不能替代对敏感数据的访问控制。

await dompdf(element, {
  encryption: {
    userPassword: 'reader-password',
    ownerPassword: 'owner-password',
    userPermissions: ['print', 'copy'],
  },
});

Available permissions:

• print: allow printing
• modify: allow modifications
• copy: allow copying content
• annot-forms: allow annotations and form filling

Unknown permission names cause an error. Whether PDF permissions are strictly enforced ultimately depends on the reader; permission flags are not a substitute for access control over sensitive data.

设置 PDF 阅读器“文档属性”面板中显示的文档信息：

await dompdf(element, {
  metadata: {
    title: '季度报告',
    author: '刘发财',
    subject: '一季度汇总',
    keywords: ['报告', '财务'],
    creator: 'my-app',
    producer: 'my-app',
  },
});

• 所有字段均可选；keywords 接受字符串或字符串数组（数组以空格连接）。
• 提供 metadata 时，producer 默认为 dompdf.js，并自动将 creationDate/modDate 设为导出时间。
• 属性值以 UTF-16BE 字符串写入，支持中文等非 ASCII 文本。
• 未提供 metadata 时不写入 Info 字典，输出与之前版本字节级一致。

Set document properties shown in the PDF reader's document info panel:

await dompdf(element, {
  metadata: {
    title: 'Quarterly Report',
    author: 'Alice',
    subject: 'Q1 summary',
    keywords: ['report', 'finance'],
    creator: 'my-app',
    producer: 'my-app',
  },
});

• All fields are optional; keywords accepts a string or a string array (arrays are joined with spaces).
• When metadata is provided, producer defaults to dompdf.js, and creationDate/modDate are automatically set to the export time.
• Values are written as UTF-16BE strings, so Chinese and other non-ASCII text is supported.
• When metadata is omitted, no Info dictionary is written and the output stays byte-compatible with previous versions.

同源图片、data URL、Canvas 和可读取的 SVG 可以直接参与导出。跨域图片需要资源服务器返回正确的 CORS 响应头：

await dompdf(element, {
  useCORS: true,
  jpegQuality: 0.9,
});

注意：

• useCORS: true 只会以匿名 CORS 方式请求图片，不能绕过服务器策略
• 图片服务器通常需要返回 Access-Control-Allow-Origin
• 导出前应等待图片和字体加载完成
• 无法读取的图片可能被跳过或降级
• proxy、allowTaint、imageTimeout 等旧 html2canvas 参数目前不会提供原版行为

可以在导出前等待页面字体和图片：

await document.fonts.ready;

await Promise.all(
  Array.from(element.querySelectorAll('img')).map((image) => {
    if (image.complete) return Promise.resolve();
    return new Promise<void>((resolve) => {
      image.addEventListener('load', () => resolve(), { once: true });
      image.addEventListener('error', () => resolve(), { once: true });
    });
  }),
);

Same-origin images, data URLs, Canvas content, and readable SVGs can participate directly in an export. Cross-origin images require correct CORS response headers from the resource server:

await dompdf(element, {
  useCORS: true,
  jpegQuality: 0.9,
});

Notes:

• useCORS: true only requests images with anonymous CORS; it cannot bypass server policy
• The image server will normally need to return Access-Control-Allow-Origin
• Wait for images and fonts to finish loading before exporting
• Unreadable images may be skipped or degraded
• Legacy html2canvas options such as proxy, allowTaint, and imageTimeout do not provide their original behavior

You can wait for document fonts and images before exporting:

await document.fonts.ready;

await Promise.all(
  Array.from(element.querySelectorAll('img')).map((image) => {
    if (image.complete) return Promise.resolve();
    return new Promise<void>((resolve) => {
      image.addEventListener('load', () => resolve(), { once: true });
      image.addEventListener('error', () => resolve(), { once: true });
    });
  }),
);

• collecting：采集 DOM 和资源
• countingPages：为逐页页眉、页脚或水印计算总页数
• rendering：WASM 正在生成 PDF
• done：导出完成

await dompdf(element, {
  pagination: true,
  onProgress(progress) {
    switch (progress.stage) {
      case 'collecting':
        console.log('正在采集页面');
        break;
      case 'countingPages':
        console.log(`正在计算页数：${progress.totalPages ?? '...'}`);
        break;
      case 'rendering':
        console.log(
          `正在生成：${progress.currentPage ?? 0}/${progress.totalPages ?? '?'}`,
        );
        break;
      case 'done':
        console.log(`导出完成，共 ${progress.totalPages ?? 1} 页`);
        break;
    }
  },
});

并非每次导出都会出现 countingPages 阶段；只有需要先知道总页数的配置才会触发它。

• collecting: collecting the DOM and resources
• countingPages: determining the total page count for per-page headers, footers, or watermarks
• rendering: generating the PDF in WASM
• done: export completed

await dompdf(element, {
  pagination: true,
  onProgress(progress) {
    switch (progress.stage) {
      case 'collecting':
        console.log('Collecting the document');
        break;
      case 'countingPages':
        console.log(`Counting pages: ${progress.totalPages ?? '...'}`);
        break;
      case 'rendering':
        console.log(
          `Rendering: ${progress.currentPage ?? 0}/${progress.totalPages ?? '?'}`,
        );
        break;
      case 'done':
        console.log(`Export complete: ${progress.totalPages ?? 1} pages`);
        break;
    }
  },
});

Not every export emits a countingPages stage. It is used only when a configuration needs the total page count in advance.

1. 主线程遍历目标元素，读取浏览器计算后的布局、样式、文本、图片和表单状态。
2. TypeScript 将采集结果编码成紧凑的二进制快照。
3. 快照通过可转移对象发送到 Web Worker。
4. Rust/WASM 完成分页、字体子集、绘制和 PDF 对象写入。
5. 主线程收到 PDF 字节，并按调用方式返回 Uint8Array、Blob 或触发下载。

这套结构避免将整个文档先绘制成一张 Canvas，同时让主要 PDF 生成工作离开主线程。

1. The main thread walks the target element and reads browser-computed layout, styles, text, images, and form state.
2. TypeScript encodes the collected result into a compact binary snapshot.
3. The snapshot is transferred to a Web Worker.
4. Rust/WASM performs pagination, font subsetting, drawing, and PDF object generation.
5. The main thread receives the PDF bytes and returns a Uint8Array, a Blob, or starts a download, depending on the API used.

This architecture avoids drawing the entire document into one Canvas and keeps the main PDF-generation work off the main thread.

浏览器兼容性

运行时依赖：

• DOM 和 CSSOM
• Web Worker
• WebAssembly
• Blob、URL.createObjectURL
• TextEncoder、TextDecoder

建议使用较新的 Chromium、Firefox 或 Safari。该库不支持直接在 Node.js、SSR 服务端或没有 DOM 的 Worker 中采集页面。Next.js、Nuxt 等 SSR 项目应仅在客户端调用导出 API。

旧版兼容参数

项目已经从 html2canvas + jsPDF 迁移到 DOM 快照 + Worker + WASM 。以下参数会被类型和运行时接受，但当前不会提供旧版等价行为，部分参数会输出 warning：

• onJspdfReady、onJspdfFinish
• foreignObjectRendering、allowTaint、proxy、imageTimeout
• logging、cache
• windowWidth、windowHeight、scrollX、scrollY
• x、y、width、height、scale
• canvas、removeContainer、onclone
• pdfFileName、floatPrecision、orientation、putOnlyUsedFonts

其中 ignoreElements 已真正生效，可以替代一部分旧版 clone 阶段的元素过滤逻辑。完整迁移建议见 旧版 API 迁移说明。

已知边界

• 动画、视频、iframe 和浏览器插件内容不能按动态状态完整导出
• 部分复杂滤镜、混合模式、遮罩和高级 CSS 会被降级或栅格化
• 超高分辨率图片和完整 CJK 字体会增加采集时间、内存和 PDF 体积
• fontUrl 和 putOnlyUsedFonts 目前只有兼容签名；字体 URL 需要由调用方先行加载
• PageRegionConfig.content 的 renderer 回调属于兼容签名，当前不提供可操作的 jsPDF 实例
• 依赖 jsPDF 插件或在导出结束后直接修改 jsPDF 实例的代码需要迁移

Browser compatibility

The runtime depends on:

• DOM and CSSOM
• Web Workers
• WebAssembly
• Blob and URL.createObjectURL
• TextEncoder and TextDecoder

Use a recent Chromium, Firefox, or Safari release. The library cannot collect a page directly in Node.js, during server-side rendering, or inside a Worker without a DOM. Next.js, Nuxt, and other SSR applications should call the export APIs only on the client.

Legacy compatibility options

The project has migrated from html2canvas + jsPDF to DOM snapshot + Worker + WASM. The following options are accepted by the types and runtime, but do not currently provide equivalent legacy behavior. Some emit a warning:

• onJspdfReady and onJspdfFinish
• foreignObjectRendering, allowTaint, proxy, and imageTimeout
• logging and cache
• windowWidth, windowHeight, scrollX, and scrollY
• x, y, width, height, and scale
• canvas, removeContainer, and onclone
• pdfFileName, floatPrecision, orientation, and putOnlyUsedFonts

ignoreElements is fully implemented and can replace some legacy clone-stage filtering. See the migration notes for the full migration path.

Known boundaries

• Animations, video, iframes, and browser-plugin content cannot be exported with their full dynamic behavior
• Some complex filters, blend modes, masks, and advanced CSS are degraded or rasterized
• Very high-resolution images and complete CJK fonts increase collection time, memory use, and PDF size
• fontUrl and putOnlyUsedFonts currently have compatibility signatures only; callers must load font URLs themselves
• The renderer callback accepted by PageRegionConfig.content is a compatibility signature and does not expose an operable jsPDF instance
• Code that depends on jsPDF plugins or modifies a live jsPDF instance after export must be migrated

为什么中文为空白或显示成方框？

浏览器字体不会自动嵌入 PDF。请通过 fontConfig.fontBytes 注册包含相应字符的 TTF 字体，并让元素的 CSS font-family 与 fontFamily 对应。

为什么分页位置和页面预览不一致？

确保导出容器宽度与目标纸张的内容宽度接近，并在导出前等待字体和图片完成加载。页边距、页眉和页脚都会减少每页可用区域。

如何导出横向页面？

使用自定义 [宽, 高] 或 pageWidthPt/pageHeightPt。不要依赖目前仅用于兼容的 orientation。

为什么跨域图片没有出现在 PDF 中？

设置 useCORS: true ，并确认图片服务器允许跨域读取。仅在前端设置 CORS 选项不能绕过服务器响应头限制。

如何减小 PDF 体积？

启用 compress: true，避免使用远超显示尺寸的大图，适当降低 jpegQuality，并尽量只注册实际需要的字体和字重。

Why is Chinese text blank or rendered as boxes?

Browser fonts are not embedded into the PDF automatically. Register a TTF containing the required characters through fontConfig.fontBytes, and ensure the element's CSS font-family matches fontFamily.

Why do page breaks differ from the browser preview?

Keep the export container width close to the target page's content width, and wait for fonts and images to load before exporting. Margins, headers, and footers all reduce the usable area on each page.

How do I export a landscape page?

Use a custom [width, height] pair or pageWidthPt/pageHeightPt. Do not rely on the currently compatibility-only orientation option.

Why is a cross-origin image missing from the PDF?

Set useCORS: true and verify that the image server permits cross-origin reads. A frontend CORS option alone cannot bypass missing server response headers.

How can I reduce PDF size?

Enable compress: true, avoid images far larger than their displayed dimensions, reduce jpegQuality where appropriate, and register only the fonts and weights the document needs.

环境要求

• Node.js 18+
• Rust 工具链
• wasm32-unknown-unknown target

rustup target add wasm32-unknown-unknown
npm install
npm run build
npm test
npm run serve

常用脚本：

npm test 当前会执行 scripts/verify.mjs，验证基础分页、PDF 结构、图片、中文字体子集、透明度和复合字形。

Requirements

• Node.js 18+
• Rust toolchain
• wasm32-unknown-unknown target

rustup target add wasm32-unknown-unknown
npm install
npm run build
npm test
npm run serve

Common scripts:

npm test currently runs scripts/verify.mjs, which verifies basic pagination, PDF structure, images, Chinese font subsetting, opacity, and composite glyphs.

示例页面

• examples/index.html：综合功能演示
• examples/comparison.html：与其他前端 PDF 方案对比
• examples/markdown-editor.html：Markdown 编辑和实时导出
• userscript/dompdf-page-exporter.user.js：支持整页、单节点和排除元素的油猴导出脚本

在仓库根目录运行 npm run serve 后访问对应页面。不要直接通过 file:// 打开示例，否则模块、字体和跨域资源可能受浏览器安全策略限制。

项目结构

dompdf.js/
├── src/                  # TypeScript API、DOM 采集、Worker 和 WASM 连接层
├── wasm/                 # Rust 分页、字体、压缩、加密和 PDF 写入器
├── dist/                 # 构建后的发布产物
├── examples/             # 浏览器演示页面和示例字体
├── docs/                 # 迁移说明与 PDF 差异系统文档
└── scripts/              # 构建、验证和 PDF 差异工具

Examples

• examples/index.html: comprehensive feature demo
• examples/comparison.html: comparison with other frontend PDF approaches
• examples/markdown-editor.html: Markdown editing and live export
• userscript/dompdf-page-exporter.user.js: userscript for full-page, single-node, and exclusion-based exports

Run npm run serve from the repository root before opening an example. Do not open examples directly through file://, because browser security policies may block modules, fonts, and cross-origin resources.

Project structure

dompdf.js/
|-- src/                  # TypeScript API, DOM collection, Worker, and WASM bridge
|-- wasm/                 # Rust pagination, fonts, compression, encryption, and PDF writer
|-- dist/                 # Built package artifacts
|-- examples/             # Browser demos and example fonts
|-- docs/                 # Migration notes and PDF-diff documentation
`-- scripts/              # Build, verification, and PDF-diff tooling

参与贡献

提交 PR 前请阅读 CONTRIBUTING.md，并至少运行：

npm test
npm run build

安全报告

安全问题请按照 SECURITY.md 中的方式反馈，不要在公开 Issue 中披露尚未修复的漏洞。

变更记录

近期版本变化见 CHANGELOG.md。

许可证

本项目基于 MIT License 开源。

dompdf.js 交流群

Contributing

Read CONTRIBUTING.md before submitting a pull request, and run at least:

npm test
npm run build

Security

Report security issues as described in SECURITY.md. Do not disclose an unpatched vulnerability in a public issue.

Changelog

See CHANGELOG.md for recent version changes.

License

This project is licensed under the MIT License.