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

121 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```