TypeScript 使用指南：让 PDF 导出类型安全

类型安全是前端工程化的基石，PDF 导出功能也不例外。dompdf.js 本身由 TypeScript 编写，类型定义随包发布，引入项目后能直接获得参数提示与编译期校验，把参数传错、字段名拼错这类低级错误挡在编译阶段。但对不少团队来说，类型定义只是能用，离用好还有距离：如何封装项目自己的导出选项类型？如何让 Vue/React 组件与导出逻辑类型联动？模块解析报错怎么处理？本文从类型定义的使用方式讲起，覆盖选项类型的结构化封装、框架集成中的类型配合、声明文件解析机制，以及常见类型错误的排查方法，帮助你构建一套类型安全、易于维护的 PDF 导出层，让编译器成为导出功能最可靠的守护者。并分享窄类型、默认值校验等进阶技巧，让类型系统发挥最大价值。

dompdf.js 的类型支持现状

dompdf.js 仓库与构建产物均为 TypeScript，发布包自带类型声明，引入后编辑器能直接给出构造函数选项、addPage 参数与 save 参数的完整提示。这意味着不需要额外安装 @types 包，也不用维护本地 d.ts 补丁，开箱即有类型保障，接入成本几乎为零。

类型提示带来的直接收益是防呆：format 写错、margin 单位漏写、addPage 少传内容参数，编辑器会即时标红，而不是等到运行期才发现。对多人协作的项目，这相当于把一部分代码评审工作前移到了编码阶段，错误在源头被拦截，效率提升非常明显。

使用方式上，导入与运行时完全一致：import { DomPDF } from 'dompdf.js'，类型会自动跟随。构造函数配置对象、每页配置对象的字段都有明确类型约束，编写配置时还能获得字段补全，上手成本几乎为零，是 TS 项目中引入该库最省心的部分，团队新人也容易上手。

类型定义还有一个间接收益：文档化。编辑器悬停提示会直接显示参数说明，等于把官方文档带进了代码里。新成员不需要翻文档就能写出正确的调用，团队沟通成本也随之下降，这正是类型系统容易被低估的价值，长期来看收益非常可观。

把导出选项封装成业务类型

直接用库的选项类型可以，但业务项目通常需要更结构化的封装：把发票、报表、证书各自的默认配置收敛成业务类型，字段带语义命名，默认值集中管理，调用处只传差异化参数，代码的意图表达会清晰很多，可读性与可维护性同步提升。

封装思路：定义业务配置接口，内部持有页面尺寸、边距等字段，通过工厂函数生成 DomPDF 实例。业务代码只依赖自己的接口，不直接接触库的配置细节，后续库升级导致配置变化时，只需改动工厂函数一处，影响面被隔离在单点，升级成本大幅降低。

类型联动还能覆盖动态内容：为导出数据定义类型（如发票明细行、证书字段），模板渲染函数接收该类型并返回 HTML 字符串，数据与模板之间的契约由编译器保证，字段改名、漏传参数都会在编译期暴露，比运行时才发现可靠得多，重构也更安全。

封装时还要考虑默认值的类型安全：使用 as const 或满足类型约束的常量定义默认配置，让编译器校验默认值本身是否符合业务类型。默认值一旦写错，编译期就会报错，而不是在运行时才暴露，配置的安全边界更完整，团队协作时也更放心。

TypeScript 集成示例

import { DomPDF } from 'dompdf.js';

// 业务侧导出配置类型
interface ExportConfig {
  format: 'A4' | 'A3' | 'A5';
  margin: string;
  scale?: number;
}

const DEFAULTS: ExportConfig = {
  format: 'A4',
  margin: '20mm',
  scale: 2,
};

// 工厂函数：业务类型 -> DomPDF 实例
function createPdf(overrides?: Partial<ExportConfig>) {
  return new DomPDF({ ...DEFAULTS, ...overrides });
}

// 数据与模板的类型契约
interface InvoiceItem { name: string; amount: number; }

function renderInvoice(items: InvoiceItem[]): string {
  return items
    .map(i => `<tr><td>${i.name}</td><td>${i.amount}</td></tr>`)
    .join('');
}

const pdf = createPdf({ format: 'A4' });
pdf.addPage(renderInvoice([{ name: '咨询费', amount: 8000 }]));
pdf.save('invoice.pdf');

与 Vue / React 组件的类型配合

Vue 场景：通过 ref 或模板 ref 拿到容器元素后传给 addPage，类型上是 HTMLElement，直接匹配库的参数类型。导出函数建议抽成 composable，把 loading、error 状态与导出逻辑封装在一起，组件里只调用一个函数，类型与状态管理都集中在一处，组件代码非常干净。

React 场景：useRef 返回的 ref.current 可能为 null，调用 addPage 前需要判空，类型层面也要处理可能为 null 的情况。推荐把导出逻辑放进自定义 Hook，参数与返回值都定义清晰类型，组件消费时天然获得类型提示，错误处理也能统一收敛，避免每个组件各写一套。

无论框架如何，核心原则一致：业务层与库之间用自定义类型隔离，模板渲染函数输入输出都有类型约束。这样框架升级、库升级都不会波及业务代码，类型系统真正成为项目的安全网，而不是装饰品，长期维护的收益会越来越明显。

框架集成时，导出结果也可以用类型约束：定义一个 ExportResult 类型，成功返回文件名与页数，失败返回错误码。组件只需要 switch 这个结果类型，编译器会强制处理所有分支，UI 层不会再出现导出失败但页面无提示的遗漏，体验更有保障。

声明文件与模块解析

正常 npm 安装后，模块解析会自动找到包内的类型声明，import 即带类型。如果遇到找不到模块或类型声明的报错，优先检查安装是否完整、构建缓存是否过期，通常删除 node_modules 重装或清理缓存即可解决，不要急着手写 d.ts 绕过，那样反而掩盖了真正的问题。

使用打包工具时，确认 tsconfig 的 moduleResolution 与包格式匹配：现代打包器一般配置 Bundler 或 NodeNext 解析，配合 exports 字段能找到正确入口。配置不匹配时会出现类型与实际运行时不一致的怪问题，排查顺序建议从 tsconfig 开始，再检查构建配置。

如果项目中存在旧版 dompdf.js 的遗留声明或全局类型冲突，优先清理重复声明，保留包自带的类型。必要时用声明合并补充项目特有字段，但要在注释里说明原因与版本，避免后来者误删，维护成本要可控，不要为了临时需求破坏类型体系的整洁。

模块解析问题还有一个高频场景：IDE 与打包器使用的解析配置不一致。编辑器里类型正常、构建时却报错，多半是 tsconfig 被多个配置文件覆盖。建议统一从根 tsconfig 继承，避免各子项目各自为政，解析行为才能保持一致，问题也能一次解决。

常见类型错误与解决

最常见的类型错误是把 DOM 元素类型传错：addPage 期望 HTMLElement，传入了 EventTarget 或 null。解决方法是先对元素做类型收窄（instanceof 检查或判空），再调用，既满足编译器也避免运行期空引用，一举两得，是框架场景里最实用的一个技巧。

其次是配置对象字段拼写或类型不符：format 写错枚举值、margin 传了数字而不是字符串。得益于类型定义，这类错误在编辑器里即时可见，按提示修正即可；建议把常用配置收敛成常量，从源头避免手写错误，团队成员之间也更容易对齐规范。

还有一类是异步类型问题：导出函数返回 Promise 时忘记 await，或错误处理里 catch 的变量类型不明确。规范做法是给导出函数定义明确的返回类型与错误类型，调用处统一 await 与捕获，类型检查会把遗漏的 await 直接标出来，让异步边界也安全，运行期少踩很多坑。

排查类型错误时，善用编辑器的快速修复与类型推断面板：把鼠标悬停在报错位置，查看期望类型与实际类型，往往一眼就能发现问题。学会读类型错误信息，比反复试错更高效，这也是 TypeScript 开发者应该掌握的基本功，值得花时间练习。