PDFKit 图片使用完全指南：格式支持、缩放模式、EXIF 方向与透明通道
【免费下载链接】pdfkitA JavaScript PDF generation library for Node and the browser项目地址: https://gitcode.com/gh_mirrors/pd/pdfkit
本文是 PDFKit（docs/images.md）图片能力的深度技术指南。PDFKit 是用于 Node 与浏览器环境的 JavaScript PDF 生成库，在文档中插入图片只需调用doc.image()并传入路径、Buffer 或 base64 Data URI。读完本文，你将掌握 PDFKit 图片 API 的全部入参（缩放、适配、对齐、链接、透明度、EXIF 方向），并理解其在 lib/mixins/images.js 与 lib/image.js 中的底层实现原理，从而在实际项目中精准控制图片的排版与渲染效果。
支持的图片格式与数据来源
PDFKit 的image方法支持JPEG与PNG两种格式。格式判定并非通过文件扩展名，而是读取数据的文件头魔数（magic bytes），相关逻辑集中在 lib/image.js：
- 以
0xFF 0xD8开头 → 按 JPEG 解析（lib/image/jpeg.js）； - 以
0x89 0x50 0x4E 0x47（即\x89PNG）开头 → 按 PNG 解析（lib/image/png.js）； - 其余情况抛出
Unknown image format.错误。
image方法的第一个参数支持三种数据源：
// 1. 文件路径（Node 环境，内部经 fs 读取） doc.image('images/test.jpeg'); // 2. Buffer / Uint8Array / ArrayBuffer const buf = fs.readFileSync('images/test.png'); doc.image(buf); // 3. Base64 编码的 Data URI doc.image('data:image/png;base64,iVBORw0KGgo...');其中 Data URI 通过fromBase64解码（见 lib/image.js），Buffer 类型则在构造阶段直接使用。每张图片对象以I${n}的形式打标签，并注册进文档的_imageRegistry，同一路径/对象重复插入时会复用已嵌入的 XObject，避免重复写入数据（见 lib/mixins/images.js）。
图片的定位：文档流内联与绝对定位
doc.image(src, x, y, options)的后两个参数决定图片的摆放方式：
- 不传
x、y：图片渲染在当前文本流的光标位置（紧接最后一行文本下方）。此时image返回后会自动把文档的当前y坐标下移图片高度，后续text等内容会自然排在图片下方（对应 lib/mixins/images.js）。这一行为有测试直接验证：tests/unit/image.spec.js中的 "y position should be updated" 用例断言document.y增加了图片高度。 - 传入
x、y：图片按绝对坐标定位在该点，不影响文本流。此外，x、y也可以放进options对象的x、y字段中（见 lib/mixins/images.js）。
// 流入文本流（跟随上文内容） doc.text('下面这张图跟随文本流'); doc.image('images/test.jpeg'); // 绝对定位 doc.image('images/test.jpeg', 320, 15);缩放规则：八种组合方式
若不提供任何缩放选项，图片以原始像素尺寸渲染（1 个 PDF 单位对应 1 像素）。image方法的缩放逻辑全部实现在 lib/mixins/images.js，规则如下：
| 传入选项 | 渲染行为 | 源码分支 |
|---|---|---|
无width/height | 全尺寸渲染 | 默认分支 |
仅width | 按宽等比缩放（高按比例计算） | options.width && !options.height |
仅height | 按高等比缩放（宽按比例计算） | options.height && !options.width |
width+height | 拉伸到指定尺寸（不保持比例） | options.width \|\| width直接赋值 |
scale | 按比例因子缩放（w = width * scale） | options.scale |
fit: [w, h] | 等比缩放，完整装入指定矩形（不留白不裁切） | options.fit |
cover: [w, h] | 等比缩放，完全覆盖指定矩形（允许裁切） | options.cover |
link/goTo/destination | 见下文"交互与注释"小节 | 注释分支 |
fit与cover的核心差异在于宽高比的比较：fit以"图片完整可见"优先，cover以"填满矩形"优先，两者在 lib/mixins/images.js 中对比图片宽高比ip与矩形宽高比bp后决定按宽还是按高适配。
// 等比缩放到指定宽度 doc.image('images/test.jpeg', 0, 15, { width: 300 }); // 拉伸到指定尺寸 doc.image('images/test.jpeg', 320, 145, { width: 200, height: 100 }); // 按比例因子缩放 doc.image('images/test.jpeg', 320, 280, { scale: 0.25 }); // fit：完整装入 100x100 矩形 doc.image('images/test.jpeg', 320, 15, { fit: [100, 100] }) .rect(320, 15, 100, 100) .stroke(); // cover：覆盖 100x100 矩形 doc.image('images/test.jpeg', 430, 145, { cover: [100, 100] });fit / cover 的对齐选项：align 与 valign
当使用fit或cover时，图片缩放后可能不会恰好填满目标矩形，此时可通过align与valign控制图片在矩形内的位置：
align：'left'（默认）｜'center'｜'right'valign：'top'（默认）｜'center'｜'bottom'
对齐计算同样在 lib/mixins/images.js 中完成：center会把起点平移(矩形宽 - 图片宽) / 2，right/bottom则平移完整差值。
// 在 100x100 矩形内水平、垂直居中 doc.image('images/test.jpeg', 430, 15, { fit: [100, 100], align: 'center', valign: 'center', }) .rect(430, 15, 100, 100) .stroke();交互与注释：link、goTo、destination
image方法内置了三个注释快捷选项，底层分别调用 lib/mixins/annotations.js 中的link与goTo（见 lib/mixins/images.js）：
link: 'https://example.com'— 为图片区域创建超链接注释（跳转外部 URL）；goTo: 'anchor-name'— 跳转到文档内的命名目标（配合destination或doc.addNamedDestination使用）；destination: 'anchor-name'— 将图片本身注册为一个命名目的地（锚点），供goTo跳转。
// 给图片加外链 doc.image('images/test.jpeg', 0, 15, { width: 300, link: 'https://example.com', }); // 图片作为锚点，另一个位置跳转过来 doc.image('images/test.jpeg', 0, 15, { destination: 'fig-1' });注意：链接区域的位置与尺寸使用缩放前的x、y、w、h（缩放计算之后的最终值），因此带fit/cover的图片其注释区域会与实际绘制区域保持一致。
透明度：opacity 选项
opacity接受0（完全透明）到1（完全不透明）之间的数值，通过为页面注册ExtGState实现（源码入口在 lib/mixins/images.js）。对于本身带 alpha 通道的 PNG，该值会与现有透明度叠加生效。数值会被钳制在[0, 1]区间，相同透明度的多次调用会复用同一个 ExtGState 对象——这些行为均有测试覆盖（见 tests/unit/image.spec.js）。
doc.image('images/test.png', 0, 15, { width: 200, opacity: 0.5 });JPEG EXIF 方向：ignoreOrientation 选项
相机或手机拍摄的 JPEG 常带有 EXIF Orientation 标签，指示拍摄时的旋转/翻转状态。PDFKit 默认会解析并应用该方向（值 1–8），确保图片"看起来是正的"；方向解析逻辑在 lib/image/jpeg.js 中实现——扫描 JPEG 各段，定位 APP1（0xFFE1）中Exif\x00\x00头，解析 TIFF 结构并在 IFD0 条目中查找0x0112标签，取值范围 1–8 之外的取值会被忽略并回退为 1。
在 lib/mixins/images.js 中，当方向值大于 4 时（即需要旋转 90°/270° 的 5–8），图片的宽高会互换；随后按方向值通过变换矩阵与旋转逐项还原（lib/mixins/images.js）。
关闭方向矫正的方式有两个层级：
// 1. 单张图片忽略 doc.image('orientation-6.jpeg', 0, 15, { height: 80, ignoreOrientation: true }); // 2. 整个文档默认忽略（new PDFDocument 时设置） const doc = new PDFDocument({ ignoreOrientation: true });需要特别留意：文档级选项只作为默认值。在 lib/mixins/images.js 中，单次调用传入ignoreOrientation: false会显式覆盖文档级默认值（options.ignoreOrientation !== false && this.options.ignoreOrientation），因此你可以在"文档默认忽略"的前提下，对个别图片单独开启方向矫正。8 种方向的逐一渲染对照，见 tests/visual/images.spec.js 的orientation用例，其视觉快照位于 tests/visual/image_snapshots/images-spec-js-images-orientation-1-snap.png；fit/cover与方向矫正的组合对齐效果也有独立用例与快照（images-spec-js-images-orientation-with-cover-and-alignment-1-snap.png）。
PNG 的深度支持：透明通道、调色板与交错图
PNG 的嵌入实现位于 lib/image/png.js，内部借助png-js解码像素后按 PDF 规范重新组织数据，覆盖了 PNG 的各类变体：
- 调色板索引色（color type 3）：将
PLTE调色板内联为Indexed颜色空间的独立对象，配合tRNS透明度生成灰度 SMask（lib/image/png.js 与loadIndexedAlphaChannel）； - 内建 alpha 通道（color type 4/6）：
splitAlphaChannel把颜色像素与 alpha 像素分离，alpha 以 8 位灰度 SMask 写入 PDF，16 位图只取高字节（lib/image/png.js）； - 交错（Adam7）PNG：
decodeData会先解码再重新压缩（lib/image/png.js），相关视觉测试见 tests/visual/interlaced-png.spec.js； - 非透明 PNG 使用
FlateDecode滤镜并带上DecodeParms预测器参数。
这也是"opacity与 PNG 自身 alpha 叠加生效"的底层原因：图片自身的 alpha 通道被写为 SMask，而opacity通过 ExtGState 的透明度再叠加一层。
完整示例：一次演示所有缩放模式
下面是 docs/images.md 中的经典示例，将各种缩放与对齐方式集中展示在同一页：
// 等比缩放到指定宽度 doc.image('images/test.jpeg', 0, 15, { width: 300 }) .text('Proportional to width', 0, 0); // fit 到 100x100，并描出矩形边框 doc.image('images/test.jpeg', 320, 15, { fit: [100, 100] }) .rect(320, 15, 100, 100) .stroke() .text('Fit', 320, 0); // 拉伸 doc.image('images/test.jpeg', 320, 145, { width: 200, height: 100 }) .text('Stretch', 320, 130); // 按比例因子缩放 doc.image('images/test.jpeg', 320, 280, { scale: 0.25 }) .text('Scale', 320, 265); // fit 到 100x100，并在矩形内水平垂直居中 doc.image('images/test.jpeg', 430, 15, { fit: [100, 100], align: 'center', valign: 'center', }) .rect(430, 15, 100, 100) .stroke() .text('Centered', 430, 0);示例中用到的images/test.jpeg可在 examples/images/test.jpeg 找到；仓库中也提供了可直接运行的参考脚本 examples/png.js（演示 PNG 插入并输出png.pdf）。若要快速验证各选项的实际渲染效果，可以运行视觉测试套件查看生成的快照，例如 tests/visual/image_snapshots/images-spec-js-images-orientation-with-fit-and-alignment-1-snap.png。
小结
PDFKit 的图片 API 在保持"一行代码插入图片"的简洁同时，覆盖了生产环境几乎全部诉求：双格式自动识别、文档流与绝对定位两种排版方式、width/height/scale/fit/cover五种缩放语义、align/valign对齐、link/goTo/destination交互注释、opacity透明度，以及 JPEG EXIF 方向矫正与 PNG 透明通道/交错图的底层处理。理解这些选项与 lib/mixins/images.js 的实现对应关系后，你可以在发票、报表、图片画廊等任何场景中精准控制每一张图片的呈现。
【免费下载链接】pdfkitA JavaScript PDF generation library for Node and the browser项目地址: https://gitcode.com/gh_mirrors/pd/pdfkit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
