PDFKit 图片使用完全指南格式支持、缩放模式、EXIF 方向与透明通道【免费下载链接】pdfkitA JavaScript PDF generation library for Node and the browser项目地址: https://gitcode.com/gh_mirrors/pd/pdfkit本文是 PDFKitdocs/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.jsBuffer 类型则在构造阶段直接使用。每张图片对象以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.widthwidthheight拉伸到指定尺寸不保持比例options.width \|\| width直接赋值scale按比例因子缩放w width * scaleoptions.scalefit: [w, h]等比缩放完整装入指定矩形不留白不裁切options.fitcover: [w, h]等比缩放完全覆盖指定矩形允许裁切options.coverlink/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控制图片在矩形内的位置alignleft默认centerrightvaligntop默认centerbottom对齐计算同样在 lib/mixins/images.js 中完成center会把起点平移(矩形宽 - 图片宽) / 2right/bottom则平移完整差值。// 在 100x100 矩形内水平、垂直居中 doc.image(images/test.jpeg, 430, 15, { fit: [100, 100], align: center, valign: center, }) .rect(430, 15, 100, 100) .stroke();交互与注释link、goTo、destinationimage方法内置了三个注释快捷选项底层分别调用 lib/mixins/annotations.js 中的link与goTo见 lib/mixins/images.jslink: https://example.com— 为图片区域创建超链接注释跳转外部 URLgoTo: 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 各段定位 APP10xFFE1中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.pngfit/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透明度生成灰度 SMasklib/image/png.js 与loadIndexedAlphaChannel内建 alpha 通道color type 4/6splitAlphaChannel把颜色像素与 alpha 像素分离alpha 以 8 位灰度 SMask 写入 PDF16 位图只取高字节lib/image/png.js交错Adam7PNGdecodeData会先解码再重新压缩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），仅供参考 PDFKit 图片使用完全指南：格式支持、缩放模式、EXIF 方向与透明通道
PDFKit 图片使用完全指南格式支持、缩放模式、EXIF 方向与透明通道【免费下载链接】pdfkitA JavaScript PDF generation library for Node and the browser项目地址: https://gitcode.com/gh_mirrors/pd/pdfkit本文是 PDFKitdocs/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.jsBuffer 类型则在构造阶段直接使用。每张图片对象以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.widthwidthheight拉伸到指定尺寸不保持比例options.width \|\| width直接赋值scale按比例因子缩放w width * scaleoptions.scalefit: [w, h]等比缩放完整装入指定矩形不留白不裁切options.fitcover: [w, h]等比缩放完全覆盖指定矩形允许裁切options.coverlink/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控制图片在矩形内的位置alignleft默认centerrightvaligntop默认centerbottom对齐计算同样在 lib/mixins/images.js 中完成center会把起点平移(矩形宽 - 图片宽) / 2right/bottom则平移完整差值。// 在 100x100 矩形内水平、垂直居中 doc.image(images/test.jpeg, 430, 15, { fit: [100, 100], align: center, valign: center, }) .rect(430, 15, 100, 100) .stroke();交互与注释link、goTo、destinationimage方法内置了三个注释快捷选项底层分别调用 lib/mixins/annotations.js 中的link与goTo见 lib/mixins/images.jslink: https://example.com— 为图片区域创建超链接注释跳转外部 URLgoTo: 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 各段定位 APP10xFFE1中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.pngfit/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透明度生成灰度 SMasklib/image/png.js 与loadIndexedAlphaChannel内建 alpha 通道color type 4/6splitAlphaChannel把颜色像素与 alpha 像素分离alpha 以 8 位灰度 SMask 写入 PDF16 位图只取高字节lib/image/png.js交错Adam7PNGdecodeData会先解码再重新压缩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），仅供参考