# build.js 开发指南 build.js 是完整 HTML 组装后的同步处理钩子,用于调整 DOM、样式或当前构建配置。 它由 `DocuBuilder.as_html_page()` 执行,具体实现见 [`pdf_builder/docu_builder.ts`](../pdf_builder/docu_builder.ts)。 ![build.js 执行流程](diagrams/build-js-workflow.svg) [编辑 draw.io 源图](diagrams/build-js-workflow.drawio)。 ## 配置与执行时机 ```toml [settings.journal] build_js_script = "../../templates/computer_template/build.js" ``` 路径相对于进程工作目录解析,通常为 `tools/gp`,不相对于模板目录。 禁用时应显式配置: ```toml 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: ```js 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); } ``` 脚本末尾由运行器追加: ```js return document?.documentElement?.outerHTML ?? html; ``` 也可显式返回完整 HTML 字符串,覆盖默认序列化,例如: ```js return html.replaceAll("旧刊名", "新刊名"); ``` 自行返回时要保留布局、章节容器和 PDF 定位链接;返回非字符串没有运行时校验, 会使后续输出行为不可靠。修改 `pages` 后需要 `return pages.join("\n")` 才能生效, 这会绕过 `document` 上的修改。默认的 `outerHTML` 不包含原始 doctype。 ## 配置修改与索引 现有 printable 模板设置: ```js 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` 运行: ```sh nix develop -c deno test -A nix develop -c deno check main.ts document/mod.ts pdf_builder/worker.ts ```