Readest 参考页码（reference progress style）实现解析：物理书页码在 EPUB/PDF 阅读器中的落地与同步实战

Readest 参考页码（reference progress style）实现解析：物理书页码在 EPUB/PDF 阅读器中的落地与同步实战

【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest

导读

本文围绕 Readest 阅读器中的progressStyle: 'reference'这一进度样式展开，讲解它如何让底部进度栏直接显示"物理书页码"（即纸质版印刷页码，而非电子书重排后的屏幕页码）。你将理解 foliate-js 如何解析 EPUB 页表（page-list）与 NCX pageList、Readest 侧getReferencePageInfo的总页数判定算法、手动输入页码（referencePageCount）的按书保存策略，以及该字段跨设备同步时的合并策略。文末还附带 e2e 注入导入与 locale 冲突处理的工程经验，可直接复用于类似功能的开发与验证。

一、功能背景：为什么进度需要"参考页码"

电子书的页码由重排引擎实时计算，不同设备、不同字号下页码完全不同；而纸质版的印刷页码是固定的，读者引用、讨论、做笔记时依赖的是它。Readest 通过将进度样式切换为reference，让阅读器借用书籍自身携带的页表数据（或用户手输的参考页数），把阅读位置映射回物理书页码。

该功能由 PR #4549 合并落地：它把 #4542（手动输入参考页数）并入 #672（page-list/page-map 支持），最终以progressStyle: 'reference'的形式同时呈现在ProgressBar（底部进度栏）等进度 UI 中。核心结论记录在 apps/readest-app/.claude/memory/reference-pages-672-4542.md，本文的源码佐证均来自当前仓库。

二、数据从哪来：foliate-js 的 pageList 与 pageItem

参考页码的"硬骨头"——解析页表——在 packages/foliate-js 中早已完成，Readest 在此之前从未消费过这些数据。

2.1 EPUB3：nav 文档中的 page-list

在 packages/foliate-js/epub.js 的parseNav中，解析器遍历 nav 文档中所有<nav>元素，按epub:type属性分类：

• toc→ 目录；
• page-list→ 页表，存为book.pageList；
• landmarks→ 地标。

对应代码（epub.js）：

const parseNav = (doc, resolve = f => f) => { // ... const $$nav = $$$(doc, 'nav') let toc = null, pageList = null, landmarks = null, others = [] for (const $nav of $$nav) { const type = $nav.getAttributeNS(NS.EPUB, 'type')?.split(/\s/) ?? [] if (type.includes('toc')) toc ??= parseNav($nav) else if (type.includes('page-list')) pageList ??= parseNav($nav) else if (type.includes('landmarks')) landmarks ??= parseNav($nav, true) // ... } return { toc, pageList, landmarks, others } }

每个<li>条目被解析为{ label, href, subitems }结构（label 即页面标签，如 "1"、"ii"）。

2.2 EPUB2：NCX 的 pageList（有条件的回退）

EPUB2 的 NCX 文件中同样可以携带pageList（pageTarget列表），见parseNCX中的getSingle('pageList', 'pageTarget')（epub.js）。

关键在于回退的触发条件：NCX pageList仅在不存在可导航的 nav 文档目录时才被解析（epub.js）：

const hasNavigableHref = items => Array.isArray(items) && items.some( it => (it && (it.href || hasNavigableHref(it.subitems)))) if (!hasNavigableHref(this.toc) && ncxPath) try { const resolve = url => resolveURL(url, ncxPath) const ncx = parseNCX(await this.#loadXML(ncxPath), resolve) this.toc = ncx.toc this.pageList = ncx.pageList } catch(e) { /* ... */ }

（hasNavigableHref的递归检查还修复了一个边界：nav 中全是纯文本<li>、没有<a href>时不能跳过 NCX 回退，否则读者会得到空的可用目录。）

2.3 Adobe page-map.xml：明确不解析

设计记录明确指出：Adobe 的page-map.xml不会被解析。但由于携带page-map.xml的书（如验证用书 Count Zero）通常同时携带 NCX pageList，实际阅读场景中参考页码依然可用。

2.4 已知缺口（Gap）

存在一个已知局限："EPUB3 nav 中有 TOC 但没有 page-list"的书永远不会回退到 NCX pageList——因为 NCX 回退被hasNavigableHref(this.toc)拦截，而 nav TOC 一旦有可导航 href，NCX 的 pageList 就被跳过了。

2.5 当前页码锚点：view.js 的 pageItem

阅读位置的"当前页"来自 packages/foliate-js/view.js 的#pageProgress：每次 relocate 时调用this.#pageProgress?.getProgress(index, range)得到pageItem，并随relocate事件一起派发（view.js）：

const pageItem = this.#pageProgress?.getProgress(index, range) this.lastLocation = { ...progress, tocItem, pageItem, cfi, range } this.#emit('relocate', this.lastLocation)

Readest 的BookProgress类型中对应字段为pageItem?: { label?: string; href?: string } | null（见 apps/readest-app/src/types/book.ts），它记录了当前所在的物理页标签。

三、核心算法：getReferencePageInfo 如何判定总页数

Readest 侧的核心逻辑集中在 apps/readest-app/src/utils/progress.ts 的getReferencePageInfo。它有三个输入来源，按优先级处理：

1. 书籍自带的pageList（EPUB 页表）；
2. 用户手动输入的referencePageCount；
3. 两者都没有时返回null（进度栏回退到普通百分比/分数样式）。

3.1 总页数 = 最高数字标签，而非最后一条目

设计记录强调：总页数取所有数字标签的最大值，而不是列表最后一项的标签。原因在于真实书籍的页表末尾常带有罗马数字的索引页——例如正文到第 553 页后跟一个标为 "XII" 的索引页，若取最后一条目，总页数会被污染成 "XII"。这一 bug 正是在 #672 的评论中报告的。

实现（progress.ts）的关键分支：

const labels = collectLabels(pageList).filter(Boolean) const hasPhysicalPageIndexes = pageList.every((item, index) => item.index === index) const numericLabels = labels.filter((label) => /^\d+$/.test(label)) const total = hasPhysicalPageIndexes ? pageList.length : numericLabels.length ? Math.max(...numericLabels.map(Number)) : labels.length const current = pageItem?.label?.trim() || String(estimatePage(fraction, total)) return { current, total }

规则汇总：

• 有数字标签：total = max(数字标签)，忽略尾部 "XII" 之类的非数字索引条目（553 后跟 XII，总页数仍是 553）；
• 全是罗马数字（无任何纯数字标签）：回退为条目数（labels.length）；
• 当前页：优先取pageItem.label原样展示——因此封面页、正文前罗马数字（"ii"）会被原样显示，不会被强制换算成数字；
• 无 pageItem（如尚未解析出页锚点）：按阅读分数线性估算Math.min(total, Math.max(1, Math.ceil(fraction * total)))。

3.2 PDF 特例：完整索引页表用物理页数（#5951）

PDF 的页表与 EPUB 语义不同：PDF 页表每个顶层条目对应一个物理页，且保留零基索引（item.index === index），其标签可能重启编号甚至切换数字体系（如 i..iv、1..n、阿拉伯/波斯数字混排、带长标签的条目）。此时以物理条目数为权威总数（pageList.length），而非最高数字标签。这一分支由hasPhysicalPageIndexes判定。

3.3 手动参考页数：线性映射

没有页表、但用户填了参考页数时，直接把阅读分数映射上去：

if (referencePageCount && referencePageCount > 0) { return { current: String(estimatePage(fraction, referencePageCount)), total: referencePageCount, }; }

estimatePage保证fraction = 0时显示第 1 页、fraction = 1时显示最后一页，且值域被钳制在[1, total]。

四、手动参考页数（#4542）：按书保存，绝不泄漏到全局

referencePageCount是ViewConfig中的一个字段（apps/readest-app/src/types/book.ts）：

progressStyle: 'percentage' | 'fraction' | 'reference'; referencePageCount: number;

设计记录强调它是**仅按书生效（per-book-only）**的 viewSettings 字段：保存时使用saveViewSettings(..., skipGlobal=true)，因此即使用户对某本书执行"保存为全局设置"，手输的物理页数也不会泄漏进globalViewSettings。加载时通过{ ...global, ...perBook }合并，保证单书配置覆盖全局默认值。

五、跨设备同步：resolveReferencePageCount 合并策略（#5716）

参考页数描述的是"这本书的纸质版"，因此它必须跨设备传播——这是 viewSettings 中少数需要同步的键。两个同步后端共用同一套合并策略 resolveReferencePageCount，确保两端永不漂移：

• 云同步侧：useProgressSync.applyRemoteProgress在拉取远端配置后调用（useProgressSync.ts）；
• 文件同步侧：mergeBookConfig调用同一函数（services/sync/file/merge.ts）。

合并规则（reference-pages.test.ts 中有完整用例）：

1. 本机无值、对端有值：无条件采用对端——常见场景是对端先输入了页数，本机只是最近读过这本书；
2. 双方都有值：较新的配置胜出；remoteIsNewer必须是严格remote > local比较，时间戳相等时保留本机值（平局很常见，因为"远端胜出"会把远端updatedAt复制到本机配置上）；
3. 对端缺失值：绝不清除本机已输入的数值——serializeConfig会把等于全局默认值的设置全部丢弃（默认是 0），线上无法区分"用户主动清除"与"对端是旧版本客户端"，静默抹掉用户手输的数字是更糟的失败。代价是清除操作本身不会传播，用户需在另一台设备上重新清除。

services/sync/file/wire.ts 的注释也印证了这一约定：缺失的计数被视为"没有意见"（no opinion）。

六、消费方：ProgressBar 与跳页输入

6.1 ProgressBar 底部进度栏

apps/readest-app/src/app/reader/components/ProgressBar.tsx 是reference样式的主要消费方：当readingProgressStyle === 'reference'时调用getReferencePageInfo，把bookData.bookDoc.pageList、progress.pageItem、阅读分数与viewSettings.referencePageCount喂给算法：

const referenceInfo = readingProgressStyle === 'reference' ? getReferencePageInfo({ pageList: bookData?.bookDoc?.pageList, pageItem: progress?.pageItem, fraction: pageInfo && pageInfo.total > 0 ? (pageInfo.current + 1) / pageInfo.total : 0, referencePageCount: viewSettings.referencePageCount, }) : null; const progressInfo = referenceInfo ? `${referenceInfo.current}${isVertical ? ' · ' : ' / '}${referenceInfo.total}` : formatProgress(pageInfo?.current, pageInfo?.total, template, localize, lang);

得到的读数是 "175 / 350" 这样的"当前物理页 / 总物理页"格式（竖排模式用·分隔）。其pageList与toc数据来自bookDoc，与章节刻度（getChapterTickFractions）共用同一数据源。

6.2 跳页输入

apps/readest-app/src/app/reader/components/footerbar/PageJumpInput.tsx 同样导入并使用getReferencePageInfo，说明在 reference 样式下，跳页面板也以物理页码为语义单位。

七、验证：测试用例与验证书

7.1 单测

apps/readest-app/src/tests/utils/reference-pages.test.ts 覆盖了全部关键分支：

• 使用页表时取最高数字标签为总数（['1','2','3','4','5']→ total 5）；
• 保留非数字当前标签（前置罗马数字 "ii" 原样显示）；
• 忽略尾部非数字标签（['551','552','553','XII']→ total 553，即 #672 报告的回归场景）；
• 全罗马数字页表回退到条目数；
• 递归统计subitems嵌套条目；
• 无 pageItem 时按分数估算当前页；
• 页表优先于手输页数（即使referencePageCount = 999）；
• PDF 完整索引页表用物理条数（含波斯数字、长标签混合的 16 页样本）；
• 手输页数的线性映射（fraction=0→ 第 1 页，fraction=1→ 末页）；
• 无页表且无手输页数时返回null；
• resolveReferencePageCount的 5 组合并策略用例。

7.2 验证用 EPUB（issue #672 评论中提供）

• Caleb's Crossing：EPUB3 nav page-list，419 页——验证 EPUB3 路径；
• Count Zero：EPUB2 NCX pageList + 同时携带 page-map.xml，346 页；且Text/c2.html从name="22"开始，可作为精确匹配的判定基准（oracle）——读到该章节时应显示第 22 页。

这两本书可用于手动复现：把书导入 Readest，将进度样式切到 reference，翻页对比页码标签与物理书的对应关系。

八、开发与 e2e 技巧

8.1 开发用 Web 导入注入（dev-web e2e）

功能开发期需要在 dev-web 环境注入 EPUB 文件以验证页表逻辑。设计记录给出了可复现的做法：

1. 将测试 EPUB 暂存到public/目录；
2. 在.library-page元素上派发一个合成的DragEvent('drop')，并携带真实的DataTransfer（通过dt.items.add(new File(...))加入文件）；
3. 剩下的由useDragDropImport接管导入流程。

同时记录了一个工具链陷阱：chrome-MCP 的javascript_tool不支持顶层 await（"await only valid in async functions"），且会收集返回的 Promise。正确的写法是用异步 IIFE把结果写入window.__result，外部再轮询读取：

(() => { (async () => { // 构造 DataTransfer 并派发 drop 事件... window.__result = 'done' })() })()

8.2 Locale 文件 rebase 冲突处理

每个功能 PR 都会在全部 33 个translation.json尾部追加键，导致 rebase 时大量冲突。设计记录明确不要手工合并，标准流程是：

git checkout --ours -- public/locales pnpm i18n:extract # 重新运行翻译脚本 git add git rebase --continue

九、小结：reference 进度样式的一整套链路

从数据到 UI 再到同步，reference 页码功能形成了一条完整链路：

1. 解析层（foliate-js）：EPUB3 navpage-list/ EPUB2 NCXpageList→book.pageList；view.js的#pageProgress在每次 relocate 派发pageItem；
2. 算法层（Readest）：getReferencePageInfo判定总数（最高数字标签 / 全罗马回退条目数 / PDF 物理条数）与当前页（pageItem 原样展示或分数线性估算）；
3. 配置层：progressStyle: 'reference'+ 按书保存的referencePageCount（skipGlobal=true）；
4. 同步层：resolveReferencePageCount的"无值随对端、双值取新、缺失不清除"策略，云同步与文件同步共用；
5. UI 层：ProgressBar、PageJumpInput消费结果，竖排用·、横排用/分隔当前页与总页数。

已知局限（EPUB3 nav 有 TOC 无 page-list 时不回退 NCX、page-map.xml 不解析）也已明确记录在案，可作为后续改进方向。对于想复现或贡献的开发者，reference-pages.test.ts 与两颗验证书（Caleb's Crossing、Count Zero）是最佳的起点。

【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest