- 前端
【免费下载链接】bentopdf
The Privacy First PDF Toolkit
本文围绕 BentoPDF 开源仓库中的 Add Page Labels 工具文档 展开。页码标签（Page Labels）是 PDF 阅读器在工具栏、缩略图与打印对话框中显示的编号元数据，它与"打印在纸面上的页码"是两回事。读完本文，你将掌握如何用 BentoPDF 为不同页面区间配置六种编号样式、自定义前缀与起始值，理解多规则标签背后的 CoherentPDF（CPDF）引擎调用链，并能直接在浏览器中完成书籍前言罗马数字、附录 A-1/B-1、扫描件修正等真实场景。
什么是 PDF 页码标签
页码标签控制的是PDF 阅读器如何显示页码——也就是阅读器工具栏中显示的那个数字，而不是打印在页面上的内容。它属于 PDF 的元数据层：PDF 规范通过页面标签树（page label tree，即/PageLabels字典）记录若干"标签序列"，每个序列覆盖一段连续或不连续的页面区间，并声明该区间采用的编号样式、前缀和起始偏移。
BentoPDF 的 Add Page Labels 工具正是围绕这套机制设计的：它允许你为同一个文档定义多条标签规则，把不同章节映射到不同的编号体系。例如：
- 前言（front matter）用罗马数字
i, ii, iii； - 正文用十进制
1, 2, 3； - 附录用带字母前缀的
A-1, A-2, B-1, B-2。
从仓库类型声明可以看到 CPDF 引擎对页标签的完整支持面：除写入用的 addPageLabels 与清除用的 removePageLabels 外，还提供读取接口 getPageLabelStringForPage（返回指定页的完整标签字符串）以及枚举已有标签序列的接口，这意味着标签不仅可写，也可被读取和校验。
使用流程
按照 工具文档 的步骤，操作流程非常直接：
- 上传 PDF 文件；
- 选项面板出现，默认带有一条标签规则；
- 为每条规则配置页面范围、样式、可选前缀与起始值；
- 点击Add Rule为不同章节追加更多规则；
- 点击Add Page Labels应用所有规则并下载结果。
对应页面 UI 由 add-page-labels.html 承载：上传区（#drop-zone）同时支持点击选择与拖拽，加载成功后显示文件名、大小与页数（{{size}} • {{count}} pages），随后展开选项面板。
上传阶段的两次校验
前端逻辑 add-page-labels-page.ts 在handleFiles中做了两层防护：
- 类型校验：文件 MIME 类型必须为
application/pdf或文件名以.pdf结尾，否则弹出 "Invalid File"； - 加密检测：通过
loadPdfDocument读取 PDF 后检查pdfDoc.isEncrypted，若为加密文档则提示 "Protected PDF"，并建议先用 Unlock PDF 移除密码再上传。这也是页面 FAQ 中"能否处理密码保护 PDF"的标准答复。
标签规则配置详解
每条标签规则由 LabelRule 类型 定义：pageRange、style、prefix、startValue、progress五个字段。以下逐一展开。
页面范围（Page Range）
- 留空：作用于全部页面（内部等价于
cpdf.all(pdf)）； - 支持格式：
1-4（连续区间）、7（单页）、odd（奇数页）、1-9,30-40（不连续区间组合）。
注意：这里的页码指文件中的物理页序，而非 PDF 已显示的标签编号。源码中，非空范围会交给 CPDF 的parsePagespec(pdf, trimmedRange)解析，解析失败会抛出带有规则序号与范围的明确错误信息（"Rule N has an invalid page range: …"），见 add-page-labels-page.ts。
标签样式（Label Style）
共六种样式，与 CPDF 的样式常量一一对应（常量值见 coherentpdf.global.d.ts）：
| 样式 | 示例 | CPDF 常量值 |
|---|---|---|
| Decimal Arabic（十进制阿拉伯数字） | 1, 2, 3 | decimalArabic= 0 |
| Uppercase Roman（大写罗马数字） | I, II, III | uppercaseRoman= 1 |
| Lowercase Roman（小写罗马数字） | i, ii, iii | lowercaseRoman= 2 |
| Uppercase Letters（大写字母） | A, B, C | uppercaseLetters= 3 |
| Lowercase Letters（小写字母） | a, b, c | lowercaseLetters= 4 |
| No Label（仅前缀） | 如 "A-" 只显示前缀 | noLabelPrefixOnly= 5 |
样式选择器遍历 PAGE_LABEL_STYLE_OPTIONS 渲染下拉框；提交时由resolvePageLabelStyle将样式名映射为 CPDF 常量。该映射在 单元测试 中被逐一验证，NoLabelPrefixOnly在运行时常量缺失时回退为数值 5。
标签前缀（Label Prefix）
可选文本，前置到每个标签上。例如输入A-并配合默认起始值 1，可生成A-1, A-2, A-3。前缀会经过rule.prefix.trim()去除首尾空白后传入 CPDF。
起始值（Start Value）
编号开始的数值，默认 1；设为 0 可实现零基编号（配合前缀可生成A-0, A-1, A-2）。输入框限制为min=0, step=1的整数，提交前还会经过normalizePageLabelStartValue规范化：
- 非有限数值（如 NaN）→ 回退为 1；
- 负数 → 钳制为 0；
- 小数 → 向下取整。
以上规则均有测试覆盖（见 page-labels.test.ts）。FAQ 还提到一个实用场景：从长书中截取的章节，把起始值设为 15 即可保留原文页码。
跨不连续区间连续编号（Continue numbering across disjoint ranges）
当一条规则的目标页面不连续（如1-9,30-40或odd）时启用该选项，编号会在区间之间顺序延续；关闭时，每个独立页面块都会从起始值重新开始。该选项直接对应addPageLabels的progress布尔参数，类型注释的解释是 "If true, labels continue the sequence"（见 coherentpdf.global.d.ts）。
移除已有标签（Remove existing page labels）
默认勾选，应用新规则前先用cpdf.removePageLabels(pdf)清空文档中已有的所有标签；取消勾选则只重标部分页面、保留其余页面的旧标签。
底层原理：CoherentPDF 引擎的完整调用链
该工具依赖 CoherentPDF（CPDF）WASM 引擎，处理完全发生在浏览器本地，PDF 文件不会离开设备。一次完整的"Add Page Labels"处理管线如下（见 addPageLabels 主流程）：
- 前置检查：
isCpdfAvailable()判断 CPDF 是否已配置，未配置则调用showWasmRequiredDialog('cpdf')弹出配置引导（见 wasm-provider.ts）； - 加载引擎：
getCpdf()通过 cpdf-helper.ts 按配置的 URL 动态注入coherentpdf.browser.min.js，默认源为 CDN（仓库默认coherentpdf@2.5.5），并调用cpdf.setSlow?.()以较大堆配置运行； - 读入文档：
cpdf.fromMemory(inputBytes, '')将文件字节载入 CPDF； - 清旧标签：若勾选移除，调用
cpdf.removePageLabels(pdf)； - 逐规则应用：对每条规则，用
parsePagespec（或all）解析页面范围，再调用cpdf.addPageLabels(pdf, style, prefix, offset, range, progress)写入标签序列； - 导出下载：
cpdf.toMemory(pdf, false, false)取回字节并校验非空，封装为application/pdf的 Blob 后触发下载； - 资源清理：
finally中调用cpdf.deletePdf(pdf)释放 CPDF 内存。
WASM 引擎的 URL 可在 WASM Settings 页面 中配置，仓库的WasmProvider会校验存储 URL 的主机是否属于受信主机（内置 CDN 域名 + 环境变量VITE_WASM_CPDF_URL对应主机），非受信地址会被丢弃，具体逻辑见 wasm-provider.ts。配置 CPDF 时请注意其 AGPL-3.0 许可声明（配置弹窗中会明确提示）。
实战用例
来自 工具文档 的典型场景：
- 书籍前言与正文：规则 1 设置
1-4+ Lowercase Roman 得到i, ii, iii, iv；规则 2 设置5-20+ Decimal Arabic 得到1, 2, …，两条规则覆盖同一文档的不同区间； - 字母化附录：为附录页区间保留 Decimal Arabic 样式并输入前缀
A-，默认起始值 1 即得A-1, A-2, A-3；再建一条前缀B-的规则处理下一个附录； - 扫描件修正：扫描 PDF 的物理页序与实际印刷页码不符时，用起始值把标签对齐到真实页码；
- 技术文档零基编号：起始值设为 0；
- 章节保持原页码：起始值设为原书页码（如 15），见页面 FAQ。
常见问题（FAQ）
页面内置了完整的 FAQ 区块（源码见 add-page-labels.html，文案位于 public/locales/en/tools.json）：
- 附录如何标成 A-1, A-2, A-3？为附录区间添加规则，样式保持 Decimal Arabic，前缀填
A-，默认起始值 1 即可；第二个附录用前缀B-。 - 编号可以从 0 或非 1 开始吗？每条规则都有 Start Value 字段，默认 1，可改为 0 或任意整数。
- "Continue numbering across disjoint ranges" 是做什么的？当一条规则覆盖不连续页（如
1-9,30-40、odd）且希望跨区间顺序计数时开启；关闭时各页面块各自从起始值重新开始。 - PDF 已有的标签会怎样？默认勾选移除，旧标签先被清空再应用新规则；取消勾选则保留未涉及页面的旧标签。
- 支持哪些区间格式？留空 = 全部页面，或使用
1-4、7、odd、1-9,30-40等；注意指向物理页序而非已有标签。 - 能处理加密 PDF 吗？不能直接处理，工具会提示 "Protected PDF"，需先用 Unlock PDF 移除密码。
- 为什么提示配置 CoherentPDF？页标签由 CPDF 引擎写入，默认从 CDN 加载；若自托管构建关闭了默认源，需在 WASM Settings 中指向本地副本。
- 如何验证标签生效？用支持显示页标签的阅读器（如 Adobe Acrobat、Firefox 内置查看器）打开下载的 PDF，查看工具栏页码框——它显示的是标签（如
iv、A-1）而非纯页索引。
与相邻工具的关系
- Page Numbers：把可见页码打印到页面上，而页标签是阅读器导航元数据、不打印。需要纸面可见编号时用前者。
- Bates Numbering：跨一个或多个文件的顺序编号戳记（法律/审计文档常用），与页标签的元数据式编号互补。
- Edit Bookmarks：组织 PDF 书签结构，与页标签一起构成文档导航体系。
工具本身注册于 src/js/config/tools.ts 的 PDF 工具列表中，且所有界面文案均通过 i18n 机制支持多语言（public/locales/下约二十种语言），中英文环境下呈现一致的功能行为。
小结
Add Page Labels 是 BentoPDF 中面向"文档导航元数据"的轻量工具：无需上传服务器，CPDF WASM 在浏览器内完成全部处理；六种编号样式 + 前缀 + 起始值 + 多规则组合，足以覆盖书籍、附录、扫描件与零基技术文档等绝大多数页码标签需求。核心实现集中在 add-page-labels-page.ts 与 page-labels.ts，配合 page-labels.test.ts 的测试，可进一步探索样式映射与起始值规范化的细节。
- 前端
【免费下载链接】bentopdf
The Privacy First PDF Toolkit
相关推荐
从0到1理解LocalPotato：Windows本地提权新手入门必读
从0到1理解LocalPotato：Windows本地提权新手入门必读 LocalPotato是一款针对Windows系统的本地提权工具，它利用新型potato
BentoPDF PDF编辑器深度指南：创建可填写表单和添加数字签名
BentoPDF PDF编辑器深度指南：创建可填写表单和添加数字签名 BentoPDF是一个隐私优先的PDF工具包，提供完全免费的在线PDF编辑功能。这个强大的
前端BentoPDF 为 PDF 添加附件（Add Attachments）功能全解析：文档级/页面级嵌入原理与实操指南
BentoPDF 为 PDF 添加附件（Add Attachments）功能全解析：文档级/页面级嵌入原理与实操指南 BentoPDF（The Privacy
前端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
