5.6 KiB
build.js 开发指南
build.js 是完整 HTML 组装后的同步处理钩子,用于调整 DOM、样式或当前构建配置。
它由 DocuBuilder.as_html_page() 执行,具体实现见
pdf_builder/docu_builder.ts。
配置与执行时机
[settings.journal]
build_js_script = "../../templates/computer_template/build.js"
路径相对于进程工作目录解析,通常为 tools/gp,不相对于模板目录。
禁用时应显式配置:
build_js_script = false
当前判断是 build_js_script != false;省略字段不会自动禁用,而会尝试读取
undefined 路径,因此不要省略。脚本在章节模板和 Markdown 已渲染、HTML
布局已组装、 本地章节图片已处理之后执行;PDF 的临时定位链接也已加入。
同一中间文档被多次导出时,每次 HTML 组装都会执行一次脚本。
| 格式 | 是否执行 | 后续步骤 |
|---|---|---|
| 是 | 浏览器分页、目录定位及合并、书签和后处理 | |
| HTML | 是 | 写入组装后的 HTML |
| Markdown | 是 | 去除样式与脚本,再由 Turndown 转换 |
| TXT | 是 | 转换 Markdown,再去除 Markdown 标记 |
| EPUB | 否 | 独立从章节 HTML 打包,未接入该钩子 |
注入参数
脚本作为 new Function("html", "document", "pages", "cfg", source)
的函数体执行。 这些变量由运行器注入,不需要也不能使用模块 import / export
声明来获取:
| 名称 | 实际值 | 修改效果 |
|---|---|---|
html |
全部片段以换行拼接的字符串 | 仅重新赋值不会改变已经解析的 DOM;需要显式返回新的字符串 |
document |
DOMParser.parseFromString(html, "text/html") 结果,可能为 null |
修改 DOM 会反映到默认序列化结果 |
pages |
组装片段数组的浅复制 | 直接改数组不会自动更新 DOM;需要自行合并并返回 |
cfg |
当前 DocuBuilder 的配置对象 | 可修改本次组装所使用的配置,传播边界见下文 |
优先使用运行时的 DOMParser;不可用时动态加载 deno_dom。它是 HTML 解析器,
不是浏览器页面:这里没有排版坐标、最终页码、浏览器事件或可依赖的 window。
最终页码应由 PDF 链接标记定位。
DOM 修改与返回值
通常直接修改 document,无需 return:
if (document) {
for (const image of document.querySelectorAll("img")) {
image.setAttribute("loading", "eager");
}
const style = document.createElement("style");
style.textContent = ".passages { overflow-wrap: anywhere; }";
document.head?.appendChild(style);
}
脚本末尾由运行器追加:
return document?.documentElement?.outerHTML ?? html;
也可显式返回完整 HTML 字符串,覆盖默认序列化,例如:
return html.replaceAll("旧刊名", "新刊名");
自行返回时要保留布局、章节容器和 PDF 定位链接;返回非字符串没有运行时校验,
会使后续输出行为不可靠。修改 pages 后需要 return pages.join("\n") 才能生效,
这会绕过 document 上的修改。默认的 outerHTML 不包含原始 doctype。
配置修改与索引
现有 printable 模板设置:
cfg.indexSearch = { mode: "sequential" };
索引默认优先读取临时文章链接,只有缺失标记时才使用全文搜索配置。 搜索支持
single_jump、sequential、window;窗口模式可指定
beforePages、afterPages。
新输出适配器会为 DocuBuilder 浅复制配置。顶层赋值(如 cfg.indexSearch = ...)
不会自动同步回流水线原始配置;嵌套对象仍可能共享引用。因此不要依赖脚本修改顶层
配置来控制 PDF 后续索引或后处理。需要可靠配置时,在调用 PdfOutput 前设置
实际传入的配置;现有 printable 的脚本赋值在新适配器路径下存在这一传播限制。
脚本适合处理 HTML,转换流程配置应由调用方明确传入。
PDF 中 https://wpep.invalid/article-start-编号 是定位用链接:不要删除、重排为
与章节数组不一致的顺序,或将文章标题整体替换到丢失这些链接。目录合并阶段会清除
临时文章链接,保留正常读者链接。未添加目录的 PDF 当前不会经过该清理阶段。
运行规则与验证
脚本同步执行,不支持顶层 await;不要返回 Promise。该钩子不是沙箱:它在 Deno
进程内执行,具有进程已获准的能力。异常会中断导出,不会静默跳过。
先用小规模出版物验证 DOM 和最终输出,再检查 PDF 分页。对 HTML 的结构变更应确认:
专栏标题与首篇文章关系、后续文章分页、图片显示、文章定位链接,以及普通链接仍正确。
修改共享行为后在 tools/gp 运行:
nix develop -c deno test -A
nix develop -c deno check main.ts document/mod.ts pdf_builder/worker.ts