告别固定尺寸：pdfmake自定义页面大小完全指南
项目地址: https://gitcode.com/gh_mirrors/pd/pdfmake 你是否还在为PDF文档的固定尺寸限制而烦恼？营销传单需要特殊宽高比、证书模板要求精确尺寸、报表打印必须匹配特定纸张规格？本文将彻底解决这些问题，通过PageSize类与标准尺寸扩展技术，让你在5分钟内掌握pdfmake的页面尺寸自由控制。
读完本文你将学到：
- 如何利用PageSize类实现毫米/厘米到PDF单位的精准转换
- 10种标准纸张尺寸的特性与应用场景
- 自定义页面大小在证书、传单、票据等场景的实战配置
- orientation属性与尺寸自动适配的核心逻辑
页面尺寸系统核心架构
pdfmake的页面尺寸控制系统由两个核心模块构成：PageSize类负责尺寸标准化处理，standardPageSizes.js提供预设尺寸定义。这种分层设计既保证了使用简便性，又保留了高度的扩展性。
// 核心处理流程 [src/PageSize.js](https://link.gitcode.com/i/6c22a0deb50b51b1e60e9343a39e74d6)
export function normalizePageSize(pageSize, pageOrientation) {
let size = pageSizeToWidthAndHeight(pageSize || 'A4'); // 默认A4
if (isNeedSwapPageSizes(pageOrientation)) {
size = { width: size.height, height: size.width }; // 方向适配
}
return size;
}
上述代码展示了尺寸处理的核心逻辑：系统首先将输入转换为宽高对象，再根据orientation参数决定是否交换宽高，最终返回标准化的尺寸数据。这种设计确保了无论是预设尺寸字符串还是自定义数值，都能得到一致的处理。
标准尺寸全景解析
标准尺寸定义文件src/standardPageSizes.js包含了从A0到A10、B系列、C系列以及北美常用的LETTER、LEGAL等40余种预设尺寸。这些尺寸采用PostScript点为单位（1英寸=72点），以下是最常用尺寸的特性对比：
| 尺寸名称 | 宽(pt) | 高(pt) | 宽(mm) | 高(mm) | 典型应用场景 |
|---|---|---|---|---|---|
| A4 | 595.28 | 841.89 | 210 | 297 | 文档、报表 |
| LETTER | 612.00 | 792.00 | 216 | 279 | 北美商务文件 |
| LEGAL | 612.00 | 1008.00 | 216 | 356 | 合同、法律文件 |
| TABLOID | 792.00 | 1224.00 | 279 | 432 | 海报、大幅图表 |
| B5 | 498.90 | 708.66 | 176 | 250 | 书籍、手册 |
提示：A系列尺寸的特点是宽高比为√2 (约1.414)，这意味着A4对折后正好是A5尺寸，便于文档缩放和嵌套设计。
自定义尺寸实战指南
基础自定义：直接数值定义
最直接的自定义方式是在文档定义中指定width和height数值：
// 简单自定义尺寸示例
var docDefinition = {
pageSize: { width: 400, height: 600 }, // 宽400pt × 高600pt
content: [
{ text: '这是一个自定义尺寸的PDF', fontSize: 20 }
]
};
这种方式适用于一次性特殊尺寸需求，但需要手动进行单位换算。pdfmake使用的PostScript点与实际物理单位的换算关系为：
- 1毫米 = 2.83465点
- 1厘米 = 28.3465点
- 1英寸 = 72点
高级应用：单位转换工具函数
为解决单位换算问题，我们可以创建一个简单的转换工具函数，将毫米/厘米转换为pdfmake使用的点单位：
// 单位转换工具函数
const units = {
mm: 2.83465,
cm: 28.3465,
inch: 72
};
function toPoints(value, unit = 'mm') {
return value * units[unit];
}
// 实战应用：创建90mm × 55mm的名片
var docDefinition = {
pageSize: {
width: toPoints(90), // 90mm × 2.83465 ≈ 255.12pt
height: toPoints(55) // 55mm × 2.83465 ≈ 155.91pt
},
content: [/* 名片内容 */]
};
这种方法特别适合需要精确匹配物理尺寸的场景，如会员卡、名片、标签等印刷品设计。
方向控制与自动适配
orientation属性用于控制页面方向，它与pageSize配合工作时会触发自动尺寸调整逻辑。系统通过src/PageSize.js中的isNeedSwapPageSizes函数判断是否需要交换宽高：
// 方向判断逻辑 [src/PageSize.js](https://link.gitcode.com/i/6c22a0deb50b51b1e60e9343a39e74d6)
function isNeedSwapPageSizes(pageOrientation) {
if (isString(pageOrientation)) {
pageOrientation = pageOrientation.toLowerCase();
return ((pageOrientation === 'portrait') && (size.width > size.height)) ||
((pageOrientation === 'landscape') && (size.width < size.height));
}
return false;
}
以下是不同方向设置的效果对比：
// 方向控制示例
var docDefinition = {
pageSize: 'A4', // 标准A4尺寸
pageOrientation: 'landscape', // 横向模式
content: [/* 横向内容 */]
};
当设置为landscape时，系统会自动交换宽高值，使A4从默认的595.28×841.89变为841.89×595.28，无需手动计算。
场景化解决方案
证书/奖状模板
证书通常需要特殊的纵向比例，以下是一个210mm×297mm的证书模板配置：
// 证书模板尺寸配置
var docDefinition = {
pageSize: {
width: toPoints(210), // 210mm宽度
height: toPoints(297) // 297mm高度
},
pageMargins: [toPoints(25), toPoints(40), toPoints(25), toPoints(30)], // 边距
content: [
{ text: '荣誉证书', style: 'title' },
{ text: '授予：XXX', style: 'recipient' },
// 其他内容...
],
styles: {
title: { fontSize: 36, bold: true, alignment: 'center', margin: [0, 60, 0, 40] },
recipient: { fontSize: 24, alignment: 'center', margin: [0, 80, 0, 60] }
}
};
营销传单设计
对于需要特殊宽高比的传单设计，可以使用如下配置：
// 16:9宽屏传单配置
var docDefinition = {
pageSize: { width: 1000, height: 562.5 }, // 精确16:9比例
pageOrientation: 'landscape',
content: [/* 传单内容 */]
};
常见问题与解决方案
Q: 为什么设置的毫米尺寸与实际打印不符？
A: 确保没有混合使用不同单位系统，建议使用本文提供的toPoints函数统一转换。同时检查是否在样式中设置了额外边距影响内容区域大小。
Q: 自定义尺寸后内容排版错乱？
A: 可能是内容元素使用了固定宽度，尝试使用相对布局或百分比宽度。可参考examples/margins.js中的自适应布局示例。
Q: 如何为文档不同部分设置不同尺寸？
A: pdfmake支持sections功能，允许为文档不同部分设置独立尺寸：
// 多部分不同尺寸示例
var docDefinition = {
content: [
{ text: '第一部分使用A4尺寸', pageBreak: 'after' },
{
text: '第二部分使用自定义尺寸',
pageSize: { width: 400, height: 600 },
pageOrientation: 'portrait'
}
]
};
总结与进阶展望
通过PageSize类与标准尺寸扩展技术，我们打破了PDF文档的尺寸限制，实现了从毫米到英寸的精确控制。无论是常规文档还是特殊场景，都能找到简洁高效的解决方案。
进阶学习建议：
- 深入研究src/PageSize.js中的尺寸标准化算法
- 探索examples/columns_simple.js中的多列布局与页面尺寸配合使用
- 尝试实现动态尺寸计算，根据内容自动调整页面大小
掌握这些技能后，你将真正实现PDF文档的"量体裁衣"，让每一份文档都能完美呈现你的设计意图。现在就打开你的编辑器，开始创建第一个自定义尺寸的PDF吧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
