不依赖第三方 PDF 库的页面处理实现——鸿蒙PC版 PDFCreator 对象解析、页面重组与 RC4 加密边界
PDF 处理工具通常被拆成三件事:读得懂文件结构、改得动页面集合、写得回合法文件。本项目把这三件事放在渲染层的纯函数引擎里实现,用 Electron 壳承担窗口、文件对话框、字节搬运与用户数据持久化,再把它装进鸿蒙 PC 的 HAP 工程。全部解析与组装逻辑不依赖任何第三方 PDF 库,也不依赖原生扩展,因此可以在普通 Node 环境里直接验证。本文基于实际业务源码、当前鸿蒙工程配置和三张应用截图,梳理一份 PDF 从字节流进入界面、被拆成页面对象、再被重新组装成新文件的过程,同时标出解析覆盖范围、加密强度与页面重组的边界。
这是一套独立编写的 JavaScript 壳应用,不是将上游 PDFCreator 及其打印驱动、PDF 转换后端移植到鸿蒙。本文执行了 JavaScript 语法检查与一组引擎级验证(样例解析、文本抽取、合并与拆分、旋转与重排、RC4 加密与空口令解密、PNG 与 JPEG 图片转 PDF 的组装回读),没有运行 Electron 界面、没有执行 HAP 构建,也没有在鸿蒙设备上安装、点击或排障;与这些环节相关的内容属于源码说明或后续验收建议。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_PDFCreator
一、技术架构分析
1.1 整体架构
项目由鸿蒙工程、Electron 主进程、渲染层与四个业务引擎组成:
- 鸿蒙工程:electron 是 entry 模块,依赖 web_engine HAR;业务资源位于 web_engine 的 resources/app 目录。
- 主进程:负责窗口、文件与目录对话框、二进制与文本读写、剪贴板、文件管理器定位、偏好与会话持久化,共 18 条 IPC 通道。
- 渲染层:维护已打开文档、合并队列、图片清单、页面勾选、待保存输出与六个工作面板。
- 纯函数引擎:PdfCrypt 处理 RC4 与权限位,PdfParse 处理结构解析与文本抽取,PdfWrite 处理页面重组与序列化,PdfImage 处理 PNG 解码与图片页排版。
主要数据链路如下:
PDF 字节
↓ files:choosePdf → fs:readBinary(base64)
PdfParse.parse → doc(对象表 / 页树 / 信息字典 / 统计)
↓ 页面勾选与队列
PdfWrite.merge / subset / removePages / rotatePages / reorder / rewrite
↓ 只生成内存中的 Uint8Array,不动源文件
S.pending → file:saveBinary 或 fs:writeBinary → 磁盘
图片走的是另一条入口:
PNG / JPEG 字节
↓ PdfImage.probe 判定类型
PNG → 解压 → 逐行反滤波 → 重排像素 → Deflate 重新打包(alpha 另存 SMask)
JPEG → 只读 SOF 取尺寸,整段以 DCTDecode 直嵌
↓ PdfImage.build 按纸张与适应方式排版
PdfWrite.create → 每张图片一页 → trailer / xref / %%EOF
两条链路最后都汇到同一个序列化器,因此合并、拆分、图片转 PDF 与加密输出共享同一套对象编号与交叉引用生成逻辑。写回磁盘这一步完全独立,界面上把结果称为“待保存输出”,在右键另存之前不会产生任何文件。
1.2 技术方案
| 需求 | 当前实现 | 能力边界 |
|---|---|---|
| 结构解析 | 经典 xref 表、xref 流、对象流、增量更新链,损坏时回退全文件扫描 | 不覆盖线性化特殊布局、加密后的对象流二次派生与自定义过滤器 |
| 流过滤器 | FlateDecode、ASCIIHex、ASCII85、RunLength、PNG Predictor | 图像类过滤器只透传不重建;未知过滤器返回中文原因 |
| 文本抽取 | 内容流文本算子 + ToUnicode CMap + WinAnsi 回退 | 没有 OCR,扫描件无文本层;Identity-H 缺 CMap 时输出为空 |
| 页面重组 | 复制原始压缩流,重写页树与交叉引用 | 只搬页面与其引用链;书签、表单、附件、结构树不随页搬移 |
| 页面旋转 | 写入页面 /Rotate,不重绘内容 | 页面视觉变化由阅读器解释,本体内容流不变 |
| 加密 | Standard Security Handler R2/R3,RC4 40/128 位 | AES-128(R4)与 AES-256(R5/R6)明确拒绝,不做伪造兼容 |
| 图片转 PDF | PNG 完整解码后 Flate 打包;JPEG 直嵌 | 不支持隔行扫描 PNG;GIF 与 WebP 直接拒绝并提示先转换 |
| 桌面交互 | HTML、CSS Flex、原生 DOM、自定义浮层 | Electron 与鸿蒙壳仍是必需运行环境 |
这条路线把可移植的字节处理逻辑独立出来,使 PDF 结构、页面搬移与加密算法能够在 Node 中直接验证;涉及窗口、系统菜单、文件对话框与设备权限的部分,则留给对应运行环境验收。
1.3 核心功能清单
| 模块 | 已接入的功能 |
|---|---|
| 文档与解析 | 打开单份或多份 PDF、内置样例载入、目录扫描、结构统计、页面列表与勾选、文本抽取与复制 |
| 合并与拆分 | 合并队列上下移与移除、按页码表达式抽取、只保留选中页、删除选中页、重排顺序、每页单独存成 PDF |
| 页面操作 | 按选中页或全部页旋转 90/180/270 度、纸张尺寸分组统计、顺序预览条 |
| 图片转 PDF | PNG 与 JPEG 清单、透明通道、纸张 A4/Letter/A3/A5/按图片尺寸、纵向或横向、等比缩放/原始尺寸/拉伸铺满、边距与 DPI |
| 安全与元数据 | 信息字典读取与写入、RC4 40/128 位加密、八项权限位、空口令解除保护、当前文档加密状态展示 |
| 设置与诊断 | 默认排版偏好、文本导出 BOM 开关、授权目录增删、运行环境与格式支持说明 |
| 持久化 | 偏好写入 PDFCreatorPrefs.json,会话写入 PDFCreatorSession.json,均在 userData 下 |
二、环境准备
2.1 开发环境与工程入口
本文核对与验证使用的环境如下,未包含设备侧信息:
- 操作系统:Windows 22H2,命令行使用 PowerShell 5.1。
- Node.js:v22.20.0,用于语法检查与引擎级验证。
- 工程根目录:ohos_PDFCreator_electron-main。
- 鸿蒙工程目录:ohos_hap,包含 electron 与 web_engine 两个模块。
- 业务入口:web_engine/src/main/resources/resfile/resources/app/package.json 声明的 main.js。
业务目录内的 package.json 全文只有五项,没有 scripts、没有依赖、没有许可证字段:
{
"name": "pdfcreator-ohos",
"version": "1.0.0",
"private": true,
"description": "PDFCreator PDF 处理工作台(鸿蒙 PC Electron 壳)",
"main": "main.js"
}
因此不能写成执行 npm start 即可运行,也不能从这份文件推导出许可证结论。关于弹层里声明的是 Apache-2.0,而业务 package.json 完全没有 license 字段,两者需要在发布前统一。
2.2 项目结构
与业务直接相关的位置如下,其余为鸿蒙模板自带的资源与配置:
ohos_PDFCreator_electron-main/
├── lib.unstripped/
│ ├── libadapter.so
│ └── libelectron.so
├── ohos_hap/
│ ├── AppScope/
│ │ ├── app.json5
│ │ └── resources/base/element/string.json
│ ├── electron/
│ │ ├── src/main/module.json5
│ │ └── oh-package.json5
│ ├── web_engine/
│ │ ├── src/main/module.json5
│ │ └── src/main/resources/resfile/resources/app/
│ │ ├── index.html 584 行,六个面板与关于弹层
│ │ ├── main.js 484 行,窗口与 18 条 IPC
│ │ ├── renderer.js 1818 行,文档模型与全部交互
│ │ ├── package.json
│ │ ├── styles/pdfcreator.css 733 行
│ │ ├── engines/
│ │ │ ├── pdf-crypt.js 306 行
│ │ │ ├── pdf-parse.js 1068 行
│ │ │ ├── pdf-write.js 490 行
│ │ │ └── pdf-image.js 363 行
│ │ └── samples/
│ │ ├── alpha-badge.png
│ │ ├── encrypted-briefing.pdf
│ │ ├── gradient-poster.png
│ │ ├── invoice-2026-0317.pdf
│ │ └── quarterly-report.pdf
│ ├── build-profile.json5
│ └── oh-package.json5
└── README.OpenHarmony_CN.md
四个引擎都用同一套 UMD 外壳,浏览器里挂到 window,Node 里走 module.exports,因此同一份文件既能被 index.html 顺序加载,也能被 Node 直接 require 做验证。
2.3 依赖与模块衔接
业务代码没有第三方运行时依赖,PDF 结构解析、压缩流解压、PNG 解码、RC4 与 MD5 全部自己实现。唯一的外部能力是 Node 内置的 zlib,在浏览器环境下拿不到时会显式返回失败,而不是静默产出坏文件:
var zlib = null;
try { if (typeof require === 'function') zlib = require('zlib'); } catch (e) { zlib = null; }
electron 模块对 HAR 的依赖写法如下:
"dependencies": {
"web_engine": 'file:../web_engine',
}
构建配置里 compatibleSdkVersion 为 5.0.5(17),runtimeOS 为 HarmonyOS,nativeLib.collectAllLibs 打开为 true,用于把 lib.unstripped 下的 libadapter.so 与 libelectron.so 一并收进产物。这两个库分别约 14.8 MB 与 1.06 GB,体积主要由 Electron 运行时本身决定,与业务 JavaScript 无关。
三、核心适配流程
3.1 主进程:窗口、18 条 IPC 与路径授权
主进程只做三件与业务相关的事:创建窗口、搬运真实字节、维护“哪些目录被授权”。18 条通道依次是 app:info、dir:choose、dir:forget、fs:scan、fs:readBinary、fs:writeBinary、fs:writeText、files:choosePdf、files:chooseImage、file:saveBinary、file:saveText、clip:write、shell:reveal、prefs:get、prefs:set、session:save、session:load、samples:list。渲染层实际调用了全部 18 条,共 26 处调用点。
所有处理函数都经过同一个包装器,把同步异常转成统一的结果对象:
function handle(channel, fn) {
ipcMain.handle(channel, function (event, req) {
try {
return fn(req || {});
} catch (e) {
return { success: false, error: errText(e), code: e && e.code };
}
});
}
路径授权是这套设计里最需要读清楚的部分。allowedRoots 由主进程独占维护,起点只有两个内置目录:userData 与业务代码所在目录。其余目录必须通过 dir:choose、files:choosePdf、files:chooseImage、file:saveBinary、file:saveText 的对话框结果进入白名单。判定不是真实路径比较,而是归一化之后的字符串前缀比较:
function isInside(child, parent) {
var c = normForCompare(child), p = normForCompare(parent);
if (!c || !p) return false;
return c === p || c.indexOf(p + '/') === 0;
}
normForCompare 会把反斜杠统一成斜杠、去掉一个末尾斜杠,并在 win32 上转小写。这个比较能挡住相邻目录名的误判,但不处理符号链接、大小写敏感分区与相对路径穿越的真实解析,也不能当作系统沙箱使用,因为渲染层开启了 nodeIntegration,本身就可以直接调用 Node 的文件接口。
读字节的通道则同时承担体积上限与错误文案两件事:
handle('fs:readBinary', function (req) {
var file = fwd(req.path || '');
if (!file) return { success: false, error: '缺少 path 参数' };
guard(file);
var st = fileStat(file);
var cap = clampInt(req.maxBytes, 1024, MAX_BINARY_BYTES, MAX_BINARY_BYTES);
if (st.size > cap) {
return { success: false, error: '文件 ' + sizeText(st.size) + ' 超过单次读取上限 ' + sizeText(cap) };
}
var buf = fs.readFileSync(file);
return { success: true, path: file, name: path.basename(file), bytes: buf.length, base64: buf.toString('base64') };
});
二进制以 base64 交给渲染层,是为了让 IPC 载荷保持可序列化。代价是传输过程中内存占用约为原文件的三分之一以上,因此 64 MB 的上限实际对应更大的峰值占用;这条链路在读取大文件时需要单独评估,本文没有做压力测试。
窗口创建同样按实际值理解,不套用其他项目的“三防配置”结论:
function createWindow() {
try {
var display = screen.getPrimaryDisplay();
var width = display.workAreaSize.width;
var height = display.workAreaSize.height;
mainWindow = new BrowserWindow({
width: Math.floor(width * 0.92),
height: Math.floor(height * 0.86),
minWidth: 980,
minHeight: 640,
frame: true,
transparent: false,
resizable: true,
backgroundColor: '#1e1e2e',
title: WINDOW_TITLE,
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
});
mainWindow.loadFile('index.html');
mainWindow.on('closed', function () { mainWindow = null; });
} catch (e) {
console.warn('[PDFCreator] 创建窗口失败:', String(e && e.message));
}
}
启动顺序是 rememberRoot(userData) → rememberRoot(__dirname) → restoreRoots → registerIpc → createWindow。restoreRoots 只恢复在上次运行中仍然存在的目录,不会为了“能打开”而放宽到上一级。这一条在源码注释里写得很直白,实际行为也与之相符。
3.2 六面板布局、文档模型与页面选择
界面是工具栏、三栏主体、状态栏的纵向 flex:左侧 208 像素固定导航,中间自适应工作区,右侧 268 像素固定信息坞。六个面板通过切换 class 显示或隐藏,不销毁节点,因此表格内容在切回时仍然存在。
文档模型是一个扁平数组 S.docs,每一项保存路径、原始字节、解析结果、页数与警告:
function makeEntry(path, name, size, bytes, res) {
var info = res.doc.info || {};
return {
id: nextId('doc'),
path: path,
name: name,
size: size,
data: bytes,
res: res,
doc: res.doc,
pages: res.pages.length,
info: info,
encrypted: !!res.doc.encrypted,
decryptable: !!res.doc.fileKey,
openError: res.doc.openError || '',
warnings: res.warnings || []
};
}
原始字节被留在内存里,因为后续每次生成输出都要从同一份已解析文档重新走一遍对象搬移;重复走 fs:readBinary 会让大文件反复过一遍 base64。代价是打开多个大文档时渲染进程内存会持续增长,界面上没有关闭以外的回收手段。
打开文档时的判定顺序值得注意:先看文件层是否成功,再看结构解析是否成功,最后看是否存在 openError。带非空打开口令的 PDF 结构上仍然可以被解析,但对象字符串解不开,此时 openError 有值,处理方式是按打开失败处理:
if (res.doc.openError) {
if (!o.quiet) fail('打开 ' + r.name + ' 失败:' + res.doc.openError);
return null;
}
页面勾选保存在 S.sel 对象里,键是页码,值恒为真。全选、全不选、反选都直接重建这个对象,然后整表重绘。页面列表最多渲染 500 行,顺序预览最多渲染 200 个芯片,超出部分用一行提示说明“操作仍对全部页面生效”——渲染上限只影响显示,不影响被操作的页面集合:
if (infos.length > show) {
body.appendChild(emptyRow(6, '页面较多,只显示前 ' + show + ' 页;操作仍对全部页面生效。'));
}
这一条对超长文档很关键:如果误以为没渲染的行不在选择范围里,就会对“全选”产生的选择集产生错误预期。
3.3 PDF 结构解析:xref、对象流、过滤器与文本抽取
解析入口先做文件头判定,再取版本号,然后把全文件的对象偏移扫一遍。这张扫描表既是损坏回退的依据,也是后面 findRoot 的兜底:
function parse(input, opts) {
var buf = bytes(input);
var warnings = [];
var src = latin1(buf);
if (src.indexOf('%PDF-') < 0) {
return { ok: false, error: '不是有效的 PDF:缺少 %PDF- 文件头' };
}
var version = (/%PDF-(\d+\.\d+)/.exec(src.slice(0, 1024)) || [, '1.4'])[1];
交叉引用优先按 startxref 读,并沿 /Prev 链回溯,最多 32 层防止死循环;遇到 xref 流则按 /W 与 /Index 分段读取字段。任何一步抛错都会降级为扫描表,并在 warnings 里留下说明:
function readXref(src, doc, warnings) {
var tail = src.lastIndexOf('startxref');
if (tail < 0) throw new Error('缺少 startxref');
var lx = new Lexer(doc.bytes, tail + 9);
lx.skip();
var off = parseInt(lx.word(), 10);
var entries = {}, trailer = null, style = 'table', guard = 0;
对象读取之后才是解密与过滤器。加密必须在读流之前完成初始化,否则内容流会被当成明文直接解压失败。过滤器链是逐层应用的,图像类过滤器不再继续处理,而是原样透传并标记 imageFilter:
function applyFilters(data, filters, parms) {
var list = filters || [];
for (var i = 0; i < list.length; i++) {
var f = list[i];
var p = Array.isArray(parms) ? parms[i] : (i === 0 ? parms : null);
if (f === 'FlateDecode' || f === 'Fl') {
var out = inflate(data);
if (!out) return { ok: false, error: 'FlateDecode 解压失败(文件可能损坏或用了不支持的压缩)' };
data = out;
} else if (f === 'ASCIIHexDecode' || f === 'AHx') data = asciiHex(data);
else if (f === 'ASCII85Decode' || f === 'A85') data = ascii85(data);
else if (f === 'RunLengthDecode' || f === 'RL') data = runLength(data);
else if (f === 'DCTDecode' || f === 'JPXDecode' || f === 'CCITTFaxDecode' || f === 'JBIG2Decode') {
return { ok: true, data: data, imageFilter: f };
} else return { ok: false, error: '不支持的过滤器:' + f };
页树遍历会继承 MediaBox、Rotate 与 Resources 三项,这三项都可以写在中间节点上;页码按遍历顺序重新编号,不沿用文档里的 /Labels:
function collectPages(doc, node, kidRef, inherited, out, depth) {
if (!isDict(node) || depth > 32) return;
var inh = {
MediaBox: node.MediaBox !== undefined ? node.MediaBox : (inherited && inherited.MediaBox),
Rotate: node.Rotate !== undefined ? node.Rotate : (inherited && inherited.Rotate),
Resources: node.Resources !== undefined ? node.Resources : (inherited && inherited.Resources)
};
var kids = resolve(doc, node.Kids);
if (Array.isArray(kids) && kids.length) {
for (var i = 0; i < kids.length; i++) {
collectPages(doc, resolve(doc, kids[i]), kids[i], inh, out, depth + 1);
}
return;
}
文本抽取走的是内容流算子解析。字体解码器按 /Tf 切换,优先读 ToUnicode CMap,读不到时按 1 字节编码回退到可打印 ASCII。行切分由 Td、TD、T*、Tm 与 ET 触发,规则是先合并连续空白,再判断纵向位移是否超过 0.5:
function fontDecoder(doc, resources, fontName) {
var res = isDict(resources) ? resources : null;
if (!res) return null;
var fonts = resolve(doc, res.Font);
if (!isDict(fonts)) return null;
var font = resolve(doc, fonts[fontName]);
if (!isDict(font)) return null;
var enc = resolve(doc, font.Encoding);
var identity = isName(enc) && /^Identity-[HV]$/.test(enc.__name);
var tu = resolve(doc, font.ToUnicode);
if (isStream(tu)) {
var d = decodeStreamRaw(doc, tu);
if (d.ok) {
var cm = parseCMap(d.data);
cm.identity = identity;
return cm;
}
}
return { map: {}, bytesPerCode: identity ? 2 : 1, identity: identity };
}
这套抽取得到的是“阅读顺序近似”的纯文本,不是版式重建:表格会变成一串按行拆开的文本,双栏会被按内容流顺序交错,扫描件则完全没有文本层。本次对内置的三份样例做了实测,字符数分别是 442、253/248/386、183/75,文本行与文件内容一致,说明这条路径在字体带 ToUnicode 的常见生成器输出上是有效的。
3.4 页面重组:合并、抽取、删除、旋转与重排
重组不重新编码页面内容,而是把源文档中被页面引用到的对象整棵搬进新文档,压缩流原样复制。要做到这一点,必须为每个来源文档单独准备一张对象映射表,否则两份文档的相同对象号会互相覆盖:
function buildFromPages(entries, opts) {
var o = opts || {};
if (!entries || !entries.length) return { ok: false, error: '没有可输出的页面' };
var w = new Writer();
var pageRefs = [], pageObjs = [];
/* 每个来源文档单独一张对象映射表,避免不同文档的对象号互相覆盖 */
var maps = [];
function mapFor(doc) {
for (var i = 0; i < maps.length; i++) if (maps[i].doc === doc) return maps[i].map;
var m = {};
maps.push({ doc: doc, map: m });
return m;
}
搬移页面时会丢掉 /Parent,因为它指向旧文档的页树节点;/Resources 若页面自身没有,就从继承链上补一份。旋转按条目传入的值处理,传 null 表示沿用原值:
entries.forEach(function (e) {
var r = importPage(w, e.doc, e.page, mapFor(e.doc));
var d = w.get(r.__ref.num);
if (e.rotate !== null && e.rotate !== undefined) d.Rotate = ((e.rotate % 360) + 360) % 360;
pageRefs.push(r);
pageObjs.push(r.__ref.num);
});
旋转是最轻的一种操作:它只改页面字典里的 /Rotate,内容流一个字节都不动,所以页面上的文字仍然可选中、可搜索:
function rotatePages(doc, indices, delta, opts) {
var set = {};
(indices || []).forEach(function (i) { set[i] = 1; });
var list = doc.pages.map(function (p) {
return { doc: doc, page: p, rotate: set[p.index] ? (((p.rotate + delta) % 360) + 360) % 360 : null };
});
return buildFromPages(list, opts);
}
输出文件走的是完全重写的交叉引用表,不写增量更新。因此体积与源文件之间没有简单换算关系:被页面引用到的对象会被搬过来,没被引用到的对象(例如旧文档自己的信息字典、废弃对象、原交叉引用表以外的结构)不会进入新文件。本次实测把 2464 字节与 4117 字节的两份样例合并,输出为 5817 字节、4 页,回读页数与来源合计一致,但文件比两份之和更小。
序列化的最后一步决定文件能否被其他阅读器打开:
var xrefAt = offset;
var size = w.objs.length + 1;
var lines = ['xref', '0 ' + size, '0000000000 65535 f '];
for (var n = 1; n < size; n++) {
lines.push(('0000000000' + (offsets[n] || 0)).slice(-10) + ' 00000 n ');
}
push(lines.join('\n') + '\n');
页码表达式解析是界面上最容易被误用的一处,规则写在渲染层:区间自动按小到大排序、重复页码去重、越界立即报错并指出具体片段:
function parseRange(text, max) {
var s = String(text || '').replace(/\s+/g, '');
if (!s) return { ok: false, error: '请输入页码表达式' };
var out = [], seen = {}, parts = s.split(',');
for (var i = 0; i < parts.length; i++) {
var p = parts[i];
if (!p) continue;
var m = /^(\d+)-(\d+)$/.exec(p);
var a, b;
if (m) { a = parseInt(m[1], 10); b = parseInt(m[2], 10); }
else if (/^\d+$/.test(p)) { a = b = parseInt(p, 10); }
else return { ok: false, error: '无法识别页码片段:' + p };
if (a > b) { var t = a; a = b; b = t; }
if (a < 1 || b > max) return { ok: false, error: '页码超出范围(1-' + max + '):' + p };
for (var n = a; n <= b; n++) {
if (!seen[n]) { seen[n] = 1; out.push(n); }
}
}
if (!out.length) return { ok: false, error: '没有解析出任何页码' };
return { ok: true, list: out };
}
需要注意的是,去重只发生在表达式内部。页面勾选传入的是页码数组,引擎层并不做二次去重,因此同一个页码出现两次会得到两页,且这两页指向同一个页面对象。本次用页码 1、1 实测,输出的页数是 2,回读页数也是 2——这不是“复制了一页”,而是“同一对象被引用两次”,后续对其中一页做编辑会同时影响两页。
生成的输出统一进“待保存输出”,不落盘:
function setPending(res, name, note) {
if (!res || !res.ok) {
fail('生成失败:' + ((res && res.error) || '引擎没有返回内容'));
return false;
}
S.pending = {
name: name,
data: res.data,
bytes: res.bytes,
pages: res.pages,
encrypted: !!res.encrypted,
note: note || '',
savedPath: ''
};
renderPending();
这个延迟落盘的设计让“试错”变得便宜:改一次顺序、换一个纸张、换一次加密强度,都只是替换内存里的一份 Uint8Array,源文件始终没有被改动。真正写磁盘只有两条通道,一是 file:saveBinary 的另存为对话框,二是 fs:writeBinary 的按目录批量写入(拆分单页时使用)。
3.5 图片转 PDF:PNG 解码与 JPEG 直嵌
图片入口先做类型判定,判定依据是文件头而不是扩展名。PNG 走完整解码,JPEG 只读 SOF 段拿尺寸,然后整段原样嵌入:
function probe(name, data) {
var b = bytes(data);
var ext = String(name || '').toLowerCase().replace(/^.*\./, '');
if (b.length > 8 && sig(b, PNG_SIG)) {
var w = u32(b, 16), h = u32(b, 20);
return { ok: true, kind: 'png', width: w, height: h, ext: 'png' };
}
if (b.length > 4 && b[0] === 0xFF && b[1] === 0xD8) {
var info = jpegInfo(b);
if (info) return { ok: true, kind: 'jpeg', width: info.width, height: info.height, components: info.components, ext: 'jpg' };
return { ok: false, kind: 'jpeg', error: 'JPEG 文件头里找不到 SOF 段(可能已损坏)' };
}
if (ext === 'gif') return { ok: false, kind: 'other', error: 'GIF 需要先转成 PNG 或 JPEG' };
if (ext === 'webp') return { ok: false, kind: 'other', error: 'WebP 需要先转成 PNG 或 JPEG' };
return { ok: false, kind: 'other', error: '只支持 PNG 与 JPEG(扩展名 ' + (ext || '未知') + ')' };
}
PNG 解码覆盖 8 位与 16 位、灰度、RGB、调色板与带 alpha 五种情形。16 位取高字节,1/2/4 位按位展开并线性拉伸到 0 到 255,这些都在取样函数里处理:
function sample(row, idx) {
/* 8 位最简;16 位取高字节;1/2/4 位按位取值 */
if (ch.bitDepth === 8) return row[idx];
if (ch.bitDepth === 16) return row[idx * 2];
var bit = idx * ch.bitDepth;
var byteVal = row[bit >> 3];
var shift = 8 - ch.bitDepth - (bit & 7);
var maxV = (1 << ch.bitDepth) - 1;
return Math.round(((byteVal >> shift) & maxV) * 255 / maxV);
}
解码完成后像素被重新 Deflate 压缩,透明通道单独压一份作为 SMask;如果整张图的不透明度全是 255,就丢掉 SMask 以省体积。解码得到的位深不是 8 时,会在 notes 里留一条“原始位深 N 位,已按 8 位输出”的提示,通过界面的日志区展示,而不是静默改写。
排版部分的三点几何关系决定了最终页面观感:纸张尺寸决定 MediaBox,边距决定可用区域,适应方式决定缩放基准:
var availW = Math.max(1, pw - margin * 2);
var availH = Math.max(1, ph - margin * 2);
var scale;
if (fit === 'stretch') scale = 0;
else if (fit === 'actual') scale = 72 / dpi;
else scale = Math.min(availW / im.width, availH / im.height);
等比缩放取宽高两个比例里更小的一个,保证整图入框;原始尺寸按 72/dpi 换算,也就是 96 DPI 的图在 PDF 里占原始像素的 0.75 倍磅值;拉伸铺满直接把图拉到可用区域,宽高比会被改变。选“按图片尺寸”时,页面尺寸由像素与 DPI 反算并加上两侧边距,本次用 150 DPI 与 10 点边距实测,360×360 的图得到 192.8×192.8 的页面,640×420 的图得到 327.2×221.6 的页面,与算式完全吻合。
有一个统计口径需要说明:回读输出文件时,图像对象数可能大于图片张数。带透明通道的那一页会额外产生一个 DeviceGray 的 SMask 图像对象,它同样是 XObject 且 Subtype 为 Image,因此被计入统计。本次两张图(其中一张带透明)生成 2 页、回读图像数为 3,属于正常结果,不是重复嵌入。
3.6 RC4 加密、空口令解密与元数据写入
加密实现的是 PDF 1.4 时代的标准安全处理器,R2 对应 40 位,R3 对应 128 位,两者都用 RC4。文件密钥由口令、/O 值、权限位与文档 ID 一起派生,R3 还要额外做 50 轮 MD5 迭代:
function computeKey(userPwd, oEntry, p, id0, r, nBytes, encryptMetadata) {
var parts = [padPassword(userPwd), toBytes(oEntry), int32le(p), toBytes(id0)];
if (r >= 4 && encryptMetadata === false) parts.push(new Uint8Array([0xFF, 0xFF, 0xFF, 0xFF]));
var key = md5(concat(parts));
if (r >= 3) {
for (var i = 0; i < 50; i++) key = md5(key.subarray(0, nBytes));
}
return key.subarray(0, nBytes);
}
权限位从一个“先全允许、再按需去掉”的掩码生成,起点是 0xFFFFFFFC,末尾两位固定为 0 是规范要求:
function buildP(allowed) {
var mask = 0xFFFFFFFC;
var allow = allowed || {};
PERM_BITS.forEach(function (b) {
if (!allow[b[0]]) mask &= ~b[1];
});
return mask | 0;
}
本次实测:八项全部关闭时 /P 为 -3904,八项全部打开时为 -4,只勾“打印”与“辅助功能提取”时 describeP 返回这两项名称,说明掩码与反向解析是对称的。
每个对象用文件密钥加对象号和代号派生独立密钥,再对字符串与流做 RC4:
function encryptValue(v, num, fileKey) {
var key = Crypt.objectKey(fileKey, num, 0);
return walkEncrypt(v, function (b) { return new Uint8Array(Crypt.rc4(key, b)); });
}
“解除保护”其实不做解密保存,而是用空口令派生出文件密钥把对象读成明文,再以未加密形式重新写出。它只对空打开口令的文档有效,判定逻辑在 tryOpen 里,能力之外的两类加密会给出明确原因而不是假装成功:
function tryOpen(enc, id0) {
var r = parseInt(enc.R, 10) || 2;
var v = parseInt(enc.V, 10) || 1;
var bits = parseInt(enc.Length, 10) || (v === 1 ? 40 : 128);
var nBytes = Math.max(5, Math.min(16, Math.round(bits / 8)));
if (r >= 5) return { ok: false, r: r, reason: 'AES-256(R5/R6)暂不支持,请先在原软件里另存为不加密文件' };
if (r === 4) return { ok: false, r: r, reason: 'AES-128(R4)暂不支持,请先在原软件里另存为不加密文件' };
元数据的写入同样要考虑中文。纯 ASCII 用字面量字符串,其余一律转成带 BOM 的 UTF-16BE 十六进制串,因此中文标题不会在别的阅读器里变成乱码:
function textString(s) {
var txt = String(s == null ? '' : s);
var ascii = /^[\x20-\x7E]*$/.test(txt);
if (ascii) {
return '(' + txt.replace(/\\/g, '\\\\').replace(/\(/g, '\\(').replace(/\)/g, '\\)') + ')';
}
var out = 'FEFF';
for (var i = 0; i < txt.length; i++) {
var c = txt.charCodeAt(i);
out += ('000' + c.toString(16).toUpperCase()).slice(-4);
}
return '<' + out + '>';
}
加密输出的边界必须写清楚:如果“打开口令”留空,只设置权限口令,生成的文件本应用仍能重新打开;如果填了打开口令,本应用既没有口令输入入口、也不做口令校验重试,生成之后自己就打不开了。界面在生成时会明确提示这一点,属于设计取舍而不是缺陷,但用户容易在“加密并生成新 PDF”之后立刻尝试重新打开而困惑。
四、鸿蒙稳定性适配
4.1 禁用默认菜单栏
问题现象: 自定义工具栏与 Electron 默认的 File/Edit/View/Window/Help 菜单并存时,会出现两套入口,且在深色界面上菜单栏的配色与业务主题不一致。这里讨论的是现有设计针对的问题,不是本文复现出的设备故障。
根因分析: 主界面已经把打开、合并、会话等操作放进了工具栏,默认菜单并非这个工作台的组成部分。
解决方案: 主进程在模块初始化阶段直接移除应用菜单,早于窗口创建:
// 去掉顶部 File/Edit/View/Window/Help 默认菜单栏
Menu.setApplicationMenu(null);
与使用 autoHideMenuBar 的做法不同,这里是把菜单从应用层整体去掉。需要注意两点:一是文件选择仍然使用 Electron 原生对话框,不能据此说项目已经移除了所有原生交互窗口;二是移除菜单后没有补充键盘快捷键绑定——本次检索 renderer.js 与 index.html,没有任何 keydown 监听,因此打开、保存、关闭弹层都只能靠鼠标。
4.2 自定义浮层与关于弹层
问题现象: 关于说明需要覆盖在工作区之上,而工作区本身是可滚动的表格区域;若只在工作区内做绝对定位,滚动后遮罩会跟着内容移动。不能仅凭一张弹层截图推断它的全部交互都经过设备验收。
根因分析: 样式文件开头的注释写的是“布局为工具栏 / 三栏主体 / 状态栏的纵向 flex,不使用固定定位、动画与变换”,而后面追加的关于弹层恰恰使用了固定定位。这条注释描述的是主布局,不覆盖追加的浮层规则。
解决方案: 关于弹层放在 app 容器之外,用 fixed 覆盖整个视口,并通过增删 hidden 类控制显隐:
#aboutDialogLayer.about-layer {
position: fixed;
top: 0; left: 0; right: 0; bottom: 0;
background: rgba(17, 17, 27, 0.72);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
#aboutDialogLayer.hidden { display: none; }
入口是状态栏最右侧的“关于”文字,它靠 margin-left: auto 推到右边;状态栏中间那个占位元素本身带 flex: 1,两者叠在一起保证了右对齐。弹层底色用写死的 rgba,而不是主题变量,换主题时需要单独调整这一处。
当前没有为弹层接入 Escape 关闭、焦点捕获或 role 声明,点击遮罩也不会关闭,只能点“关闭”按钮。这些属于可访问性层面的待办,本文没有修改源码,也不把截图当作这部分已验收的证据。
4.3 窗口配置与运行边界
当前窗口代码应按实际值解释,不套用其他项目的“三防配置”结论。
| 配置项 | 当前源码 | 本文结论 |
|---|---|---|
| width / height | workAreaSize 的 0.92 / 0.86 | 随主屏工作区自适应 |
| minWidth / minHeight | 980 / 640 | 限制最小尺寸 |
| backgroundColor | #1e1e2e | 与业务主题一致 |
| frame / transparent / resizable | true / false / true | 显式设置,保留系统标题栏 |
| autoHideMenuBar | 未设置 | 改用移除应用菜单 |
| nodeIntegration | true | 本地渲染层可使用 Node 能力 |
| contextIsolation | false | 不是隔离的 preload API 模型 |
| spellcheck | 未设置 | 没有关闭输入拼写检查 |
| disableHardwareAcceleration | 没有调用 | 未实施禁用硬件加速 |
| 窗口创建 try/catch | 已包裹 | 创建失败会打印警告而非抛出 |
当前安全模型适用于受信任的本地页面。它不应直接承载不可信远程内容,也不应把 allowedRoots 当作阻止已获得 Node 权限代码访问文件的安全边界——渲染层开启了 nodeIntegration,可以直接 require 内置模块。若以后增加外部网页、插件或在线模板,应重新设计渲染隔离、输入校验与最小权限接口。
4.4 IPC 错误反馈与体积上限
问题现象: 文件过大、路径未授权、磁盘不可写和解析失败这几类问题,如果直接抛到界面上,用户看到的是英文错误码;如果没有任何上限,一个异常大的文件可能把渲染进程拖死。
根因分析: 主进程的包装器只捕获同步异常,而多条通道是 async 函数;体积上限与错误文案分散在各个通道里,需要统一成一套约定。
解决方案: 主进程侧统一用 handle 包装并把系统错误码映射成中文,渲染层侧统一用一个 Invoke 出口把传输层拒绝也转成可展示对象:
function ipcCall(channel, payload) {
return ipc.invoke(channel, payload || {}).then(function (r) {
return r || { success: false, error: '主进程没有返回结果' };
}).catch(function (e) {
return { success: false, error: '调用失败:' + String((e && e.message) || e) };
});
}
按钮回调再统一包一层,保证同步抛错与 Promise 拒绝都落到状态栏,而不是变成一个没人处理的拒绝:
function guardRun(label, fn) {
try {
var r = fn();
if (r && typeof r.catch === 'function') {
r.catch(function (e) { fail(label + ':' + friendly(e)); });
}
return r;
} catch (e) {
fail(label + ':' + friendly(e));
return null;
}
}
上限方面有四组常量:二进制单文件 64 MB、文本单文件 16 MB、目录扫描 2000 条、格式探测文件头 8 KB。前三组都接入了实际校验,第四组只在 app:info 里暴露给界面展示,没有任何通道使用它——设置面板把它列出来,会让人以为存在一个“读文件头判断类型”的能力,实际类型判定发生在渲染层的引擎里,读的是已经完整搬运过来的字节。读者据此判断能力时需要注意这个差异。
还有一处边界值得写在文档里:handle 的 try/catch 是同步的,dir:choose、files:choosePdf、files:chooseImage、file:saveBinary、file:saveText 这五条 async 通道在 await 之后发生的拒绝不会被包装器转换成 success:false,而是以 Promise 拒绝的形式传到渲染层,最终由 ipcCall 的 catch 兜住。结果上错误仍然可见,但返回体里不会有 errText 处理过的中文文案,也不会有 code 字段。
五、构建与部署
以下三张图片来自项目对应的上架素材目录,原图保留,副本归档到本文同级 assets。它们是既有界面素材,不是本文重新构建或操作设备产生的测试截图。

图 1:文档与解析面板的初始态。当前文档为“未打开”,已打开文档 0 个,页面列表 0 页,文本抽取 0 字符;下方目录扫描区显示内置样例目录的完整路径 /data/storage/el1/bundle/electron/resources/resfile/resources/app/samples,右侧信息坞提示“待保存输出:无”。状态栏显示“就绪 · 样例 5 个文件 · 授权目录 2 个”,两个内置目录就是 userData 与业务代码所在目录。截图支持“样例清单已列出”的说明,不支持“任何文件已成功打开或转换”的结论。

图 2:合并与拆分面板。合并队列为空,提示“队列为空。用「添加 PDF 到队列」或「已打开文档全部入队」。”;页码表达式默认 1-3,新顺序默认 1,2,3,前缀默认 page。右侧“另存为…”按钮为高亮状态但上方显示“无”,说明输出区在没有任何生成结果时仍保留了入口,真实使用时点击会得到“还没有待保存的输出”的提示。

图 3:关于弹层覆盖在合并与拆分面板之上,三段文字分别是开源声明、免责声明与完全开源。开源声明说明这是运行于鸿蒙 PC 的 Electron 壳应用、全部代码 JavaScript 独立编写且不包含上游源代码;完全开源一段声明遵循 Apache-2.0。该声明与业务 package.json 缺少 license 字段的现状尚不一致,需要发布前核实并统一。
三张图右上角的工具状态栏显示“openharmony arm64 · Electron 0.0.0-no-git-tag-found”,这是 app:info 返回的 process.versions.electron 原值,末尾的“no-git-tag-found”说明当前运行时构建没有可用的版本标签,不是本文测试出来的异常。右下角显示“PDFCreator 1.0.0”,取自 app.getVersion()。
5.1 本地调试与本文验证结果
业务 package.json 没有 start 或 test 脚本,不能直接写成执行 npm start 即可运行。若本机已经准备好匹配的 Electron 可执行程序,可在业务 app 目录手动执行以下调试命令;本文未执行该启动操作:
electron .
本次实际使用 Node.js v22.20.0,对 main.js、renderer.js 与四个引擎共六个文件执行 node --check,全部通过语法检查。随后直接 require 四个引擎,读取工程自带的三份 PDF 样例与两张 PNG 样例,在内存中完成解析、重组、加密与图片排版,再对输出结果重新 parse 一次做对称校验,没有创建 DOM 仿真、临时测试脚本或测试包。
| 实际检查 | 输入 | 观察结果 |
|---|---|---|
| MD5 已知向量 | 字符串 abc;空串 | 900150983cd24fb0d6963f7d28e17f72;d41d8cd98f00b204e9800998ecf8427e |
| RC4 已知向量 | Key / Plaintext | bbf316e8d940af0ad3 |
| 权限位掩码 | 八项全关;八项全开 | -3904;-4 |
| 权限位反向解析 | 仅勾打印与辅助提取 | 返回“打印”“辅助功能提取”两项 |
| 发票样例解析 | invoice-2026-0317.pdf | PDF 1.7,1 页,5 个对象,1 条流,2 个字体,0 张图,经典 xref,无警告 |
| 报告样例解析 | quarterly-report.pdf | PDF 1.7,3 页,9 个对象,3 条流,6 个字体,无警告 |
| 加密样例解析 | encrypted-briefing.pdf | PDF 1.7,2 页,R3 / V2 / 128 位,空口令解密成功,权限仅“打印”,/P 为 -3900 |
| 文本抽取 | 三份样例全部页面 | 442 字符;253 / 248 / 386 字符;183 / 75 字符,首行为英文正文原句 |
| 双文档合并 | 发票样例 + 报告样例 | 5817 字节,4 页;回读 4 页、无加密、无警告 |
| 加密文档参与合并 | 加密样例 + 发票样例 | 3395 字节,3 页;回读 3 页且输出未加密 |
| 按页抽取 | 页码 3,2 | 2916 字节,2 页,顺序为第 3 页在前 |
| 页码越界 | 单页范围 [9] | 拒绝,提示“没有选择页面” |
| 重复页码 | 范围 [1,1] | 输出 2 页,两页指向同一页面对象 |
| 删除页面 | 删第 1 页;删全部 3 页 | 2863 字节 / 2 页;后者拒绝,提示“不能删除全部页面” |
| 旋转 | 第 1 页 +90 度 | 回读 Rotate 为 90 / 0 / 0,内容流未变 |
| 重排 | 顺序 3,1 | 2273 字节,2 页 |
| 元数据重写 | 标题 x、作者 y | 回读 Title 为 x |
| 加密输出 128 位 | 空打开口令 | 2626 字节,R3 / V2 / 128 位;回读加密标记且可空口令解密 |
| 加密输出 40 位 | 空打开口令 | 2633 字节,R2 / V1 / 40 位;回读同样可解 |
| 加密输出带打开口令 | 用户口令 secret | 回读结构可解析但不可解密,提示“文档设置了打开口令(非空)”,信息字典为乱码 |
| 解除保护 | 加密样例 | 1455 字节,2 页,回读无 /Encrypt |
| PNG 识别 | alpha-badge.png;gradient-poster.png | 360×360;640×420 |
| 非支持格式 | 伪造扩展名 gif 与 webp | 均拒绝并提示先转成 PNG 或 JPEG |
| 透明通道 | alpha-badge.png | DeviceRGB + SMask 12582 字节;另一张无 SMask |
| 图片转 PDF(A4 等比) | 两张 PNG | 107880 字节,2 页,页面 595.28×841.89;回读图像对象 3 个 |
| 图片转 PDF(按图片尺寸) | 150 DPI、边距 10 点 | 页面 192.8×192.8 与 327.2×221.6,与像素换算完全一致 |
| 纸张与方向 | A5 横向;未知纸张名 | 595.28×419.53;未知时回退 A4 |
这些结果包括正常行为与已观察到的边界,不能合并成“全部功能通过”。具体来说,本次没有运行 Electron 界面与任何一次按钮点击,没有执行 HAP 构建,没有在设备上安装,没有访问用户真实文档目录,也没有用第三方阅读器打开生成的文件做视觉比对——所有“回读”都是由同一套解析引擎完成的,只能证明结构自洽,不能证明在其他阅读器里显示正确。合并、拆分与加密的正确性仍需要独立阅读器验收。
5.2 业务资源与鸿蒙模块的衔接
electron 模块对 web_engine 的依赖写法在 2.3 已给出。业务入口是 web_engine/src/main/resources/resfile/resources/app/package.json 里的 main.js,再由主进程加载 index.html。页面先按顺序加载四个引擎脚本,最后加载 renderer.js;引擎之间也有依赖关系,pdf-image 需要 pdf-write,pdf-write 需要 pdf-parse 与 pdf-crypt,所以脚本顺序不能随意调换:
<script src="engines/pdf-crypt.js"></script>
<script src="engines/pdf-parse.js"></script>
<script src="engines/pdf-write.js"></script>
<script src="engines/pdf-image.js"></script>
本项目资源已经平铺在 app 目录;不要为了套用其他项目的部署步骤而清空该目录,或从不存在的开发副本进行覆盖。后续若维护者修改业务,应确认进入构建的资源就是上述目录,并在构建后核对产物中的业务文件版本。
偏好与会话写入运行环境的 userData,而不是回写安装资源,主要文件是 PDFCreatorPrefs.json 与 PDFCreatorSession.json。偏好里只保留 pageSize、fit、margin、dpi、bom 五项;allowedRoots 与 lastDir 被列在拒绝清单里,渲染层即使提交也会被主进程过滤掉,返回体里的 denied 字段会列出被拒的键名。会话里保存的是路径而不是文件内容,因此会话载入时需要重新读文件,已被删除的路径会逐条写入日志提示。文章归档与图片复制不会触碰这些运行时用户数据。
5.3 HAP 构建与部署检查点
在 DevEco Studio 中打开 ohos_hap,确认 SDK、产品、签名和模块依赖后,再使用 IDE 对应的 HAP 构建入口。本文没有执行构建命令,因此不提供虚构的成功日志、产物路径或安装结论。
发布前建议分层检查:
- 工程身份:当前 bundleName 仍为 com.huawei.ohos_electron,vendor 为 example,AppScope 的 app_name 为 Electron;页面标题与窗口标题是“PDFCreator PDF 处理工作台”。三类名称需要统一,Ability 标签与各语言资源也要一并核对。
- 权限与模板项:web_engine 声明了网络、打印、文件目录访问与剪贴板等权限,同时还存在位置、相机、麦克风、加速度计、陀螺仪、蓝牙、截屏等模板能力。应在核实用途后保留必要项,并记录删除依据,而不是因为本文提到就批量删改。
- 许可证:关于弹层声明 Apache-2.0,业务 package.json 无 license 字段,仓库 README 也需一并核对,三者应一致。
- 加密算法:当前只能输出 RC4 40/128 位。很多新版阅读器对 RC4 已不再默认允许,发布说明里应写明算法与兼容性,或先补上 AES-128 再对外声明加密能力。
- 大文件路径:64 MB 上限与 base64 传输的峰值内存、渲染层保存原始字节的策略会叠加;需要用接近上限的真实文件跑一次打开、合并与保存,记录峰值占用与是否出现白屏。
- 结构覆盖:用带书签、表单域、嵌入附件、增量更新与 xref 流的真实文件分别验证解析与重组,确认哪些结构会在重组后丢失。
- 设备交互:检查标题栏、最小窗口 980×640、表格滚动与固定表头、图片缩略图、目录对话框、关于弹层的焦点与关闭方式,以及重启后的会话恢复。
只有完成对应验证,才能将“源码具备某条调用路径”升级为“在指定设备和条件下通过验收”。三张界面素材不能替代这些步骤。
六、常见问题与解决方案
以下问题来自源码核对与本次有限引擎验证。标为建议的措施尚未实施,不是已经完成的修复或上架排障记录。
Q1:合并后的 PDF 里,页面内容和字体还是原来的吗?书签和表单去哪了?
问题现象: 合并、拆分、旋转后的文件在其他阅读器里页面观感应与原文件一致,但目录、书签、表单域不见了。
根因分析: 页面搬移复制的是原始压缩流与页面字典,字体作为资源被引用时会一并复制,因此视觉与嵌入字体保持一致;但新文档只重建了 Catalog 与 Pages 两层,没有复制 /Outlines、/AcroForm、/Names、/StructTreeRoot 等文档级结构。旋转只改 /Rotate,内容流一字未动。
解决: 把当前实现理解为“页面级重组”而不是“文档克隆”:需要保留书签、表单或结构标签的文件,应先在原软件里处理,再用本工具做页面操作。后续若要补齐,需要在 buildFromPages 里额外搬移文档级字典并重建页面对应的表单域引用。
教训: “页面看起来一样”与“文档语义完全保留”是两件事,验证时要分别检查每页渲染与目录、表单、标签是否存在。
Q2:为什么合并后的文件比两份原文件之和还小?会不会丢内容?
问题现象: 2464 字节与 4117 字节的两份样例合并后是 5817 字节,比总和少了一千多字节。
根因分析: 输出是完全重写的文件:只搬被页面引用到的对象,重新生成 xref 与 trailer,原文件里的信息字典、旧交叉引用表、未被引用的废弃对象都不会进入新文件。这属于压缩掉的冗余,不是内容丢失。
解决: 判断是否丢内容要看页面数与文本抽取结果,而不是字节数。本次合并后回读为 4 页,与来源页数之和一致;抽取文本也能读出原文。如果发现页数正确但某页空白,问题更可能出在资源引用上,应检查该页的 /Resources 是否来自继承链。
教训: 体积变化不能作为内容完整性的判断依据,页数、文本与视觉三项要分别核对。
Q3:为什么加密只能选 40 位和 128 位?为什么加密后的文件我自己打不开了?
问题现象: 加密面板只有 RC4 40 位与 RC4 128 位两个强度选项;设置了打开口令后,再次打开该文件会失败。
根因分析: 引擎只实现 Standard Security Handler 的 R2 与 R3,R4 的 AES-128 与 R5/R6 的 AES-256 会在 tryOpen 里直接返回“暂不支持”。另一方面,应用没有口令输入入口,解密路径固定用空口令派生文件密钥,因此任何带非空打开口令的文件都会判定为无法打开——包括本应用自己刚生成的。
解决: 需要跨应用分发的文件,建议只设权限口令、把打开口令留空,这样本应用仍能重新打开,其他阅读器也会按权限位限制操作;需要真正的口令保护时,应在其他具备完整 AES 支持的软件里完成。加密后立即用第三方阅读器验证一次,确认权限位生效。
教训: 加密强度、口令策略与自身能否读取是三件事,声明支持某算法之前,要先说明算法对应哪一代规范、哪些阅读器默认允许。
Q4:图片转 PDF 之后,为什么回读的图像数量比图片张数多?
问题现象: 两张 PNG 生成 2 页,回读统计显示图像对象 3 个。
根因分析: 带透明通道的 PNG 除主图外还会生成一个 DeviceGray 的 SMask 蒙版对象,它同样是 XObject 且 Subtype 为 Image,因此会被统计进图像计数。只有全不透明的图才会跳过 SMask。
解决: 检查页数即可:页数等于图片张数。如果需要图像对象数,应按 /SMask 关系把蒙版从主图统计中剔除。本次实测中 360×360 的带透明图产生了 12582 字节的 SMask,另一张 640×420 的全不透明图没有 SMask。
教训: 统计口径要写在功能说明里,否则“资源数”与“用户看到的元素数”对不上时,很容易被误判为重复嵌入。
Q5:文本抽取为什么对扫描件和部分中文 PDF 抽不出内容?
问题现象: 同一批文件,有的能抽出完整正文,有的只得到少量英文,扫描件则完全为空。
根因分析: 抽取依赖内容流里的文本算子与字体的 ToUnicode CMap。扫描件只有一个图像对象,没有文本层;Identity-H 编码但没有提供 ToUnicode 的字体,码位无法映射回 Unicode,只能输出空串;字体缺失时回退成 1 字节可打印 ASCII,非 ASCII 字符会被丢弃。
解决: 扫描件需要先做 OCR,本应用不提供。中文文档抽不出内容时,先用属性面板确认字体是否带了 ToUnicode;缺失时应由生成软件重新导出带 CMap 的版本。界面在空结果时会写入“(本页没有可抽取的文本层)”,看到这行提示说明该页确实没有可解码文本,不代表抽取流程失败。
教训: 文本抽取与 OCR 是两类能力,不能用“能不能复制文字”反过来推断文件是否损坏。
Q6:勾选同一页码两次,为什么输出的是两页相同的页面?
问题现象: 通过页码表达式输入的重复页码会被去重,但通过引擎接口传入重复索引时,输出页数会比预期多。
根因分析: 表达式解析在渲染层用 seen 表去重;引擎的 subset 只按数组逐项取值,并把同一个对象引用重复放入页树,于是出现“两页指向同一个页面对象”。本次用范围 [1,1] 实测,输出 2 页。
解决: 从界面操作不会触发这个场景,因为页码表达式已经去重;如果以后加了其他入口(例如批量脚本),需要在调用引擎前自行去重,或在引擎侧补一层去重以避免对象被多处引用。若确实需要页面副本,应当做深拷贝而不是共享引用。
教训: 引用语义的重复和内容级别的复制要区分清楚,“页数变多”不等于“多了一份内容”。
Q7:为什么有界面截图,仍要核对应用名、权限与许可证?
问题现象: 页面与状态栏都显示 PDFCreator,但 AppScope 使用模板包名与 Electron 标签,关于弹层声明 Apache-2.0 而业务 package.json 没有 license 字段。
根因分析: HTML 标题、BrowserWindow 标题、AppScope 标签、Ability 标签与商店材料属于不同层次,截图只能显示页内文字;模板权限与快捷方式配置也需要结合最终用途逐项核对。
解决: 发布前统一身份资源与许可证说明,审查权限用途,核对签名与目标产品,再执行构建、安装及设备回归。本文没有读取或公开签名秘密,也没有自行修改包名、权限、许可证或原生库。
教训: 界面已经展示与工程已经具备发布条件不是同一个结论,应分别提供证据。
七、总结
PDFCreator 壳应用把结构解析、页面重组、图片排版与加密输出组成一个不落盘的桌面工作台。值得复用的是职责分层:纯 JavaScript 引擎负责可测试的字节处理,主进程提供窗口与文件能力,渲染层组织交互与输出确认。
| 特性 | 当前实现与需要保留的边界 |
|---|---|
| 结构解析 | 经典 xref、xref 流、对象流、增量更新与损坏回退;过滤器覆盖常见四类 |
| 文本抽取 | 内容流算子 + ToUnicode;无 OCR,缺 CMap 的字体无法还原 |
| 页面重组 | 复制原始压缩流、按文档隔离对象映射;不搬书签、表单与文档级结构 |
| 旋转与重排 | 改写 /Rotate 与页树顺序;内容流不变,文字仍可选中 |
| 图片转 PDF | PNG 完整解码含 SMask,JPEG 直嵌;不支持隔行扫描与 WebP/GIF |
| 加密 | RC4 40/128 位,权限位可配;AES 明确拒绝,带打开口令的输出自身不可读 |
| 路径授权 | 对话框是唯一授权入口,内置两目录不可撤销;字符串前缀比较,不是系统沙箱 |
| 输出流程 | 先在内存生成、确认后落盘;另有按目录批量写入用于拆分单页 |
| 持久化 | 偏好与会话分文件保存,allowedRoots 由主进程独占 |
| 桌面界面 | 六面板、三栏固定布局、自定义关于浮层;无键盘快捷键 |
本次最关键的三个经验:
- 把“改写结构”与“重绘内容”分开。 旋转、重排、合并都只搬移和重写结构,内容流原样复制,因此文字仍可选中、字体不变;代价是文档级结构不随之保留,功能说明必须写到页面这一层,不能写成“完整文档克隆”。
- 让能力边界在代码里就说清楚。 AES 不支持、扫描件无文本层、带口令文件打不开,这三条都在引擎里返回中文原因而不是静默降级。与其事后在文档里补,不如让返回值本身成为边界说明。
- 内存里的输出需要配套的体积与校验策略。 不落盘的设计让试错成本很低,但也让 64 MB 上限、base64 放大与渲染层常驻字节同时存在;真机验收时必须用接近上限的真实文件跑一次完整链路,而不是只用几 KB 的样例。
本文完成的是当前实现的技术梳理、有限引擎验证与素材归档。源码中尚存的边界均如实保留,未据此宣称完整移植、全功能验收或已完成鸿蒙上架。
更多推荐



所有评论(0)