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手动输入参考页数并入 #672page-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 EPUB3nav 文档中的 page-list在 packages/foliate-js/epub.js 的parseNav中解析器遍历 nav 文档中所有nav元素按epub:type属性分类toc→ 目录page-list→ 页表存为book.pageListlandmarks→ 地标。对应代码epub.jsconst 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 EPUB2NCX 的 pageList有条件的回退EPUB2 的 NCX 文件中同样可以携带pageListpageTarget列表见parseNCX中的getSingle(pageList, pageTarget)epub.js。关键在于回退的触发条件NCX pageList仅在不存在可导航的 nav 文档目录时才被解析epub.jsconst 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 一旦有可导航 hrefNCX 的 pageList 就被跳过了。2.5 当前页码锚点view.js 的 pageItem阅读位置的当前页来自 packages/foliate-js/view.js 的#pageProgress每次 relocate 时调用this.#pageProgress?.getProgress(index, range)得到pageItem并随relocate事件一起派发view.jsconst 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。它有三个输入来源按优先级处理书籍自带的pageListEPUB 页表用户手动输入的referencePageCount两者都没有时返回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 特例完整索引页表用物理页数#5951PDF 的页表与 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.tsprogressStyle: percentage | fraction | reference; referencePageCount: number;设计记录强调它是**仅按书生效per-book-only**的 viewSettings 字段保存时使用saveViewSettings(..., skipGlobaltrue)因此即使用户对某本书执行保存为全局设置手输的物理页数也不会泄漏进globalViewSettings。加载时通过{ ...global, ...perBook }合并保证单书配置覆盖全局默认值。五、跨设备同步resolveReferencePageCount 合并策略#5716参考页数描述的是这本书的纸质版因此它必须跨设备传播——这是 viewSettings 中少数需要同步的键。两个同步后端共用同一套合并策略 resolveReferencePageCount确保两端永不漂移云同步侧useProgressSync.applyRemoteProgress在拉取远端配置后调用useProgressSync.ts文件同步侧mergeBookConfig调用同一函数services/sync/file/merge.ts。合并规则reference-pages.test.ts 中有完整用例本机无值、对端有值无条件采用对端——常见场景是对端先输入了页数本机只是最近读过这本书双方都有值较新的配置胜出remoteIsNewer必须是严格remote local比较时间戳相等时保留本机值平局很常见因为远端胜出会把远端updatedAt复制到本机配置上对端缺失值绝不清除本机已输入的数值——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 999PDF 完整索引页表用物理条数含波斯数字、长标签混合的 16 页样本手输页数的线性映射fraction0→ 第 1 页fraction1→ 末页无页表且无手输页数时返回nullresolveReferencePageCount的 5 组合并策略用例。7.2 验证用 EPUBissue #672 评论中提供Calebs CrossingEPUB3 nav page-list419 页——验证 EPUB3 路径Count ZeroEPUB2 NCX pageList 同时携带 page-map.xml346 页且Text/c2.html从name22开始可作为精确匹配的判定基准oracle——读到该章节时应显示第 22 页。这两本书可用于手动复现把书导入 Readest将进度样式切到 reference翻页对比页码标签与物理书的对应关系。八、开发与 e2e 技巧8.1 开发用 Web 导入注入dev-web e2e功能开发期需要在 dev-web 环境注入 EPUB 文件以验证页表逻辑。设计记录给出了可复现的做法将测试 EPUB 暂存到public/目录在.library-page元素上派发一个合成的DragEvent(drop)并携带真实的DataTransfer通过dt.items.add(new File(...))加入文件剩下的由useDragDropImport接管导入流程。同时记录了一个工具链陷阱chrome-MCP 的javascript_tool不支持顶层 awaitawait 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 页码功能形成了一条完整链路解析层foliate-jsEPUB3 navpage-list/ EPUB2 NCXpageList→book.pageListview.js的#pageProgress在每次 relocate 派发pageItem算法层ReadestgetReferencePageInfo判定总数最高数字标签 / 全罗马回退条目数 / PDF 物理条数与当前页pageItem 原样展示或分数线性估算配置层progressStyle: reference 按书保存的referencePageCountskipGlobaltrue同步层resolveReferencePageCount的无值随对端、双值取新、缺失不清除策略云同步与文件同步共用UI 层ProgressBar、PageJumpInput消费结果竖排用·、横排用/分隔当前页与总页数。已知局限EPUB3 nav 有 TOC 无 page-list 时不回退 NCX、page-map.xml 不解析也已明确记录在案可作为后续改进方向。对于想复现或贡献的开发者reference-pages.test.ts 与两颗验证书Calebs 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考