企业官网建设流程全解析

为什么需要 dompdf.js 表单导出？

dompdf.js是一个纯前端的 HTML 转 PDF 引擎（基于 TypeScript + Rust + WebAssembly），无需后端即可在浏览器里生成可搜索、可选择文字的矢量 PDF。除了普通内容导出，它还提供了一套完整的表单导出能力：把页面上的 input、select、checkbox、radio、textarea 等控件，转换成可填写的 AcroForm 字段或保留为静态外观——导出的 PDF 打开后，收件人依然可以直接点击勾选、在下拉框里选择、在文本框中打字。

💡 相比 html2canvas 截图式方案，dompdf.js 导出的表单字段是真实的 PDF 表单对象，而不是"看起来像表单的图片"。

3 分钟上手：导出 HTML 表单为 PDF

安装后，只需在导出选项里加一个form配置即可。默认是static静态模式：

import dompdf from 'dompdf.js'; const blob = await dompdf(element, { format: 'a4', pagination: true, form: { mode: 'hybrid' }, // 静态外观 + 可交互字段 });

完整配置项与更多示例见官方文档 README.md 的 Form Export 章节，TypeScript 类型定义位于 src/snapshot.ts：

export type FormMode = 'static' | 'interactive' | 'hybrid'; export interface FormOptions { mode?: FormMode; include?: FormInclude[]; }

仓库中的 examples-main/demo1.html 页面内置了一个包含姓名输入框、邮箱、复选框、单选按钮、下拉框和文本域的完整表单演示，npm run serve启动后可以直接体验导出效果。

3 种表单导出模式对比：static、interactive 与 hybrid

form选项接受boolean | FormOptions，三种模式的行为如下：

几个容易踩的点：

• ⚠️form: true仍然只是默认的 static 模式。想要可填写字段，必须显式写mode: 'interactive'或mode: 'hybrid'。
• ⚠️ 表单值来自导出那一刻的 DOM 状态（el.value、el.checked），而不是 HTML 里的初始属性——用户改了再导出，PDF 里就是改过的值。
• ⚠️ 复选框和单选按钮在interactive模式下会省略底层静态图形，只渲染 PDF 表单控件本身，避免"双重绘制"。

哪些 HTML 控件能生成可填写的 PDF 字段？

并非所有控件都有自然的 PDF 表单映射。当前 src/snapshot.ts 中的映射逻辑如下：

✅ 可生成 AcroForm 交互字段

🖼️ 仅保留静态外观（不产生交互字段）

• 日期时间类：date、time、month、week、datetime-local
• 其他：range滑块、color取色器、file文件选择、progress进度条、meter仪表盘

这些控件会以截图式的静态视觉呈现，保证 PDF 里"长得和页面一样"。

用 include 白名单控制要导出的控件类型

include选项是一个白名单，支持以下 11 种类型（定义见 src/snapshot.ts）：

text · textarea · select · checkbox · radio · date-time · range · color · file · progress · meter

不在白名单里的控件会被完全忽略。典型用法：

form: { mode: 'hybrid', include: ['text', 'textarea', 'select', 'checkbox', 'radio'], }

💡 小技巧：如果页面上有调试用的滑块、颜色选择器等不想出现在 PDF 里的控件，把include收窄到真正需要的几项即可，输出更干净。

深入原理：生成的 PDF 里到底发生了什么

在 wasm/src/paginate.rs 中可以看到，Rust 引擎为每个可交互控件写入 PDF 规范定义的Widget 注释：

• 文本类控件生成/FT /Tx字段，携带当前值/V、默认值/DV，输入框的占位提示符会写入/TU（tooltip），并根据 CSStext-align计算文本对齐/Q；
• select生成/FT /Ch字段，<option>列表整体写入/Opt，当前选中项写入/V；
• 复选框/单选项生成/FT /Btn，同组 radio 合并为一个父字段加多个子 Widget；
• 所有顶级字段汇总到根对象的/AcroForm字典，并设置NeedAppearances true，让 PDF 阅读器在字段被填写时自动重新排版外观。

正是这套标准 AcroForm 结构，使得 Acrobat、Chrome 内置 PDF 阅读器、预览类 App 都能识别并允许用户直接填写表单——这与encrypt选项里的annot-forms权限配合使用：若希望收件人可填写，记得在userPermissions中保留该权限（见 README.md 的 PDF Encryption 章节）。

常见问题排查（FAQ）

1. 导出的 PDF 里输入框没有值？确认导出时机：值读取的是 DOM 实时状态。若表单是动态渲染的（SPA、异步填充），请等数据写入 input 后再调用导出。

2. 设了form: true为什么还不能填写？true等价于 static 模式，请改用form: { mode: 'interactive' }或hybrid。

3. 日期、滑块、取色器为什么不是可交互的？PDF 规范没有与之对应的字段类型，它们只保留静态外观。如需交互，可在页面上把它们替换为文本输入框（例如<input type="text">手填日期）。

4. 复选框在 PDF 里显示的是"框+标签"还是纯框？interactive/hybrid 模式下复选框与单选项只渲染为 PDF 表单控件本身（标签文字保留），不会出现重复的图形。

小结

dompdf.js 的表单导出把"HTML 表单"和"PDF AcroForm"打通了：

• static：保真截图式外观，适合归档；
• interactive/hybrid：生成真实的 AcroForm 字段，收件人可在 PDF 阅读器中直接填写；
• include白名单让你精确控制哪些控件参与导出；
• 文本、下拉、复选框、单选四类控件可交互，日期、滑块、文件等保留静态视觉。

配合 README_CN.md 中的字体嵌入（中文表单必配）、页眉页脚、水印与加密等能力，纯前端就能产出一份专业、可交互的 PDF 表单文档。