Files
wpep/tools/gp/docs/build-js.md
T

5.6 KiB
Raw Blame History

build.js 开发指南

build.js 是完整 HTML 组装后的同步处理钩子,用于调整 DOM、样式或当前构建配置。 它由 DocuBuilder.as_html_page() 执行,具体实现见 pdf_builder/docu_builder.ts。

build.js 执行流程

编辑 draw.io 源图。

配置与执行时机

[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 组装都会执行一次脚本。

格式 是否执行 后续步骤
PDF 是 浏览器分页、目录定位及合并、书签和后处理
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