Readest 阅读器功能修复知识库解读:PDF 渲染、文本选择、词典、工具栏与 RSVP 的工程速查

原创2026-10-09 22:50:531,649 阅读
文章标签:桌面应用跨平台移动开发前端国际化AI 应用

Readest 阅读器功能修复知识库解读:PDF 渲染、文本选择、词典、工具栏与 RSVP 的工程速查

本文是对 Readest 开源电子书阅读器仓库内 apps/readest-app/.claude/memory/reader-feature-fixes.md 这份"阅读器功能修复"聚合索引的深度解读。该索引汇总了 PDF 查看器、文本选择、即时词典、工具栏定制、RSVP 速读、小组件与杂项 UI 等领域一批已解决/已稳定的工程记忆,每条记忆对应具体的 GitHub issue 编号、合并 PR 与关键技术结论。读完本文,你可以快速定位阅读器各功能模块的已知问题、根因与修复方案,并借助仓库源码理解这些结论背后的实现细节。

这份文档是什么:一张"已解决修复"的导航图

reader-feature-fixes.md 本身是一个 聚合索引(aggregator index):它不重复存储修复细节,而是每行一条、以 issue 编号 + 记忆文件名 的形式指向 apps/readest-app/.claude/memory/ 目录下的独立记忆文件,打开链接文件才能看到完整细节。其 description 元数据明确说明了覆盖范围:

Aggregator index for resolved/stable reader-feature memories (PDF viewer, selection, dict, toolbar, RSVP, widgets, misc UI)

索引从 MEMORY.md 迁移而来,目的是保持索引文件短小。因此在阅读本仓库时,正确的用法是:先看这份索引找到条目,再打开对应记忆文件获取根因与修复细节,最后回到源码/测试验证。本文即按此路径,将索引中的条目按主题整理成可检索的速查手册。

PDF 查看器:滚动性能、捏合缩放与固定版式

PDF 是阅读器中最复杂的渲染场景之一,索引中 PDF 相关条目最多,且大量修复发生在 packages/foliate-js/(以子模块方式维护的渲染内核)。

滚动模式渲染延迟(#4795)

Android 上 PDF 滚动模式出现空白页。根因通过真机 CDP(Chrome DevTools Protocol)实测得出:单页渲染(canvas 栅格 + 文本层 + 注解层)约 415ms(未缓存)/ 65ms(已缓存),而滚动模式的 IntersectionObserver 只有 rootMargin: '50% 0px'(约半页提前量),且加载无并发上限、无视口优先级,导致快速滚动时渲染永远追不上。修复在 fixed-layout.js:

  • 观察器加宽到 rootMargin: '200% 0px'(约 2 个视口提前量),观察器只负责标记 page.visible;
  • 新增纯函数 planScrollModePages({pages, currentIndex, maxLoaded, maxConcurrent, loadingCount}),优先加载离当前页最近的可视/空闲页,并以 #scrollMaxLoaded = 12(画布内存上限)、#scrollMaxConcurrent = 3 约束并发,驱逐最远的非可视已加载页且永不驱逐可视页;
  • 单页加载失败置为 error 态而非 idle,避免失败页被无限重试;
  • pdf.js 的 MAX_CACHED_PAGES 从 8 提升到 16。

调度器有独立单元测试 fixed-layout-scroll-scheduler.test.ts 保护。索引还总结了滚动 PDF 的缓存最佳实践:两层有界缓存(活动画布上限=硬内存天花板,解码页缓存稍大)、距离/视口感知的 LRU、及时释放位图(canvas.width=0),以及低端设备上最有效的杠杆——限制有效 DPR(画布内存与 DPR 平方成正比)。

滚动 PDF 实时捏合缩放(#4817)

滚动模式下的捏合缩放修复同样全部位于 foliate-js(readest 侧仅子模块 bump + 一个单元测试)。核心架构结论非常关键:跨页捏合与原生文本选择互斥——每个页面是独立 iframe,Android 会在手指落到第二个 iframe 时对第一个 iframe 发送 touchcancel,跨页手势只能由宿主接管全部触摸,但这要求 iframe pointer-events: none,会杀死原生选择。用户最终选择了原生选择、放弃跨页捏合。同页捏合在滚动模式会整体缩放 .scroll-container,pinchEnd 时以中心页 getBoundingClientRect 为锚点重渲染回滚,且页间距必须随缩放联动(margin: calc(var(--scroll-page-gap,4px) * var(--scroll-zoom,1))),否则预览与提交会出现位移。

跨页选择、复制与菜单行为

  • PDF 跨页选择(#5809,已合并 #5831):Chrome 与 Xiaomi 真机验证通过,iOS 未覆盖——修复记录明确标注了验证边界。
  • PDF 复制拼接换行(#5814,已合并 #5828):复制时跨行文本会拼接,未缩进的最后一行仍会被合并。
  • 滑动平移误触发菜单(#5142):PDF 滑动平移会误开/误关菜单栏,修复要点记录在 pdf-swipe-pan-toggles-menu-5142.md。
  • 固定版式书籍横向滚动(#4995,foliate#65 + readest#5485 均已合并):新增 scroll-direction 属性(vertical|horizontal),与 flow="scrolled" 正交;direction: rtl 必须挂在宿主滚动元素而非 .scroll-container 上,否则滚动锚点恢复会"瞬移";横向模式下的滚轮平移由 computeScrollWheelDelta 处理,且 CDP 合成手势无法测试该路径(无滚动轴时根本不派发 wheel 事件),只能靠真实硬件或 vitest 浏览器测试。
  • 侧栏拖拽改 PDF 尺寸(#5043,已合并 #5198):拖拽侧栏后 PDF 尺寸不更新,修复为 FXL iframe 中 PE:auto 会击败 body 的 PE-none,改用 shield overlay 方案。

PDF/CBZ 对比度调节(View 菜单)

为固定版式/图像文档(PDF/CBZ/FXL-EPUB)在 View 菜单新增 Contrast 步进器,细节见 pdf-cbz-contrast-view-menu.md:

  • contrast: number 存入 BookStyle(默认 100,范围 50–300,步长 10);
  • 过滤样式在 style.ts 的 applyFixedlayoutStyles() 中应用于 img, canvas 规则,CSS filter 是单一属性,第二条 filter: 会覆盖第一条,因此必须把 invert(100%) 与 contrast(${c}%) 拼进同一条声明(两者可交换,顺序无关);浅色模式下对比度同样生效;
  • 通过 saveViewSettings(envConfig, bookKey, 'contrast', value, /*skipGlobal*/ true, ...) 只写当前文档,不进全局。

另有 pdf-scroll-lag-preload-4795.md 记录了 CDP 调试发布包的要点:WebView 远程调试被 devtools Cargo feature 门控,需 pnpm dev-android(release + --features devtools)构建安装;CDP webSocketDebuggerUrl 返回无端口的 ws://localhost/devtools/...,需改写为 ws://127.0.0.1:9222<path>。

文本选择与点击交互:跨页、键盘与 Instant Highlight

选择相关

点击/双击

Instant Highlight(即时高亮)

  • 吞掉点按/滑动翻页(#4795 配套):Android 用户开启即时高亮快捷动作后,点按正文无法翻页。根因是 useTextSelector.handlePointerDown 对每个指针按下都 preventDefault() 并立即开始高亮,压制了驱动翻页的原生 click。修复在 useTextSelector.ts:触摸/笔输入引入 300ms 静止保持门限(INSTANT_HOLD_MS = 300)与 10px 移动容忍(INSTANT_HOLD_MOVE_PX = 10)——点按先释放、滑动先移动,都走原生翻页;只有静止保持才触发高亮。鼠标路径不变(点击与按压拖拽本身无歧义)。
  • 孤儿高亮(#4773):instant-highlight-delete-orphan-4773.md。
  • 取消注释时的空高亮泄漏(#4791):empty-highlight-leak-on-annotate-cancel-4791.md。

Instant Highlight 的 iOS 侧有一个值得复用的经验:WebKit 的文本选择识别器无法从 JS 层面击败——user-select: none 在 iOS 上会让 caretRangeFromPoint 返回 null(破坏选择/高亮 API),selectstart 的 preventDefault 是死路(iOS 长按选择根本不触发 selectstart)。最终方案是原生门控 TextSelectionSuppressor.swift(swizzle WKContentView 的选择手势 gate),驱动链路为 set_text_selection_suppressed(Rust)→ bridge.ts 的 setTextSelectionSuppressed。

注解与 Overlayer

词典、Word Lens 与语言排版

词典弹出框

Word Lens(行内注释)

Kindle 风格的 Word Lens 是阅读器的一大特色,完整设计见 wordlens-feature.md:

  • CEFR 词频滑块:A1–C2 六档映射到词频排名截断值,定义在 difficulty.ts:英文用 FREQUENCY = [1000, 2000, 4000, 8000, 14000, 24000],中文按 HSK 级别×3000 类比;isDifficult(rank, cutoff) 判定"该词是否难到需要注释"。
  • CFI 安全的 DOM 注入(核心技术):注释以 <ruby class="wl-gloss" cfi-skip>word<rt cfi-inert>gloss</rt></ruby> 注入活动 iframe 文档。foliate 的 epubcfi.js 会把 cfi-skip 包装器的子节点上提、移除 cfi-inert 子树,使 CFI 与纯文本逐字节一致——高亮、书签、进度不受影响,KOSync 同样安全(xcfi.ts 遵循相同属性)。
  • 与 TTS/搜索/注解隔离:TTS 拒绝过滤器已含 tags:<a href="https://link.gitcode.com/i/cc7b82dc93c9cfa455043e4ddf7cdd71" target="_blank">'rt'];globalAnnotations 的 findTextRanges 拒绝 rt/rp;[wordHighlight.ts 增加 isInertText 跳过逻辑并导出 rangeTextExcludingInert(否则 Edge TTS 词边界偏移会漂移);搜索 SearchBar.tsx 对 rt 之外补充了 attributes:['cfi-inert']。
  • R2 运行时分发:数据包不随安装包分发,源在 apps/readest-app/data/wordlens/(含 manifest.json,记录 pair/source/target/file/bytes/sha256/entries),由 scripts/sync-wordlens-r2.mjs(pnpm wordlens:sync,env WORDLENS_R2_BUCKET)上传到 cdn.readest.com R2;运行时 glossPacks.ts 负责 fetchManifest→resolvePack→ensurePack(sha256 校验、单飞、?v=<sha8> 缓存破坏)→loadGlossIndex。
  • 构建数据:node scripts/build-wordlens-data.mjs en-zh <ecdict.csv> [topN](ECDICT,难度取 COCA frq 排名)与 zh-en <cedict.txt> <hsk.json> [topN](CC-CEDICT + HSK)。注意陷阱:kaikki 的 <code>-extract.jsonl.gz 是单语词典(同语言释义),英语注释在 kaikki.org/dictionary/<Language>/...jsonl(0.9–3GB)中。

RTL、波斯语与西里尔文本

  • RSVP 的 RTL 词显示(#4630):RSVP 的 ORP 焦点字母布局按字符索引把词切成 wordBefore/orpChar/wordAfter 三段并排布在 LTR span 中,这会破坏阿拉伯语字母连写(علم 显示成 ل م ع)并颠倒视觉顺序。修复为:新增 isRTLText(RTL_PATTERN = /[\u0590-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF]/,覆盖希伯来/阿拉伯/叙利亚/塔纳/NKo 等),检测到 RTL 就复用 CJK 的整词渲染分支并加 dir='rtl'。通用教训:任何复杂连写/bidi 文字都不能按字符索引拆 span。
  • 波斯语 RLM 半空格(#5216/#5651):rlm-bidi-mark-shaping-5216.md(真因是字体回退 shaping,非 sanitizer)与 persian-rlm-halfspace-zwnj-5651.md(U+0600–06FF 含数字,数字间交换会翻转视觉顺序)。
  • 俄语悬挂前置词 NBSP(#4769):russian-hanging-prepositions-nbsp-4769.md。
  • TTS 日语 ruby 读音(#5539,已合并 #5546 + foliate-js#67):TTS 应朗读 <rt> 注音而非让引擎猜汉字读音。交换必须在节点过滤器层完成(绝不能改写文本,否则高亮 CFI 漂移),判据是 <rt> 是否为纯假名(isKanaReading) 而非书语言;配套两个 foliate 补丁:fragmentToSSML 要过滤文本节点(组 ruby 的 base 是 <ruby> 的裸文本子节点)、Overlayer.#splitRange 不再收集 rt/rp/rtc/[cfi-inert] 的矩形(furigana 永不参与高亮)。

工具栏定制、注解中心与设置同步

Customize Toolbar 全局化(#4760)

"Customize Toolbar"(注解栏,源自 #4014,v0.11.12 发布)的修改只对当前书生效、不全局生效。根因在 serializer.ts:serializeConfig 用 globalViewSettings<a href="https://link.gitcode.com/i/5a2e5bff7e7c3f1e5f05bd24c1122823" target="_blank">key] !== value 的引用比较决定哪些 per-book 设置需要持久化为覆盖项,而函数先 JSON.parse(JSON.stringify(config)) 深拷贝,导致任何数组/对象值(如 annotationToolbarItems,潜伏的还有 paragraphMode、proofreadRules、ttsHighlightOptions、noteExportConfig)都是新引用 ≠ 全局 → 每次保存都写成 per-book 覆盖项,重新打开后旧覆盖项遮蔽全局修改。修复最小且通用:新增 isSameViewSettingValue(a,b) = a===b || JSON.stringify(a)===JSON.stringify(b),仅用于 viewSettings 的 reduce(searchConfig 保留 !==,因为它含函数/大 results)。测试见 [serializer.test.ts。已知限制:旧版(有 bug 的 v0.11.12)已写入的、内容与当前全局不同的覆盖项不会被追溯清除。

注解中心(Annotations Hub,#5398/#3870,已合并 #5448)

侧栏 Annotations 标签页成为 per-book 注解中心。关键决策:filterBooknotes(notes, {kind, query, excludedColors?, excludedStyles?}) 与 collectAnnotationFacets 由 hub、Notebook 搜索栏、过滤器导出组共享;工具栏改为"图标行 + 过滤下拉"(search/funnel/3-dot);过滤面板必须合并 Dropdown 注入的 menuClassName(no-triangle mt-1),否则旧三角缺口会渲染;最近滚动抑制效果与 lastScrolledCfiRef 交互,清空过滤时若不清该引用会把列表"搁浅"。详见 annotations-hub-5398-3870.md。

其他工具栏/UI 条目

RSVP 速读、自动滚动与光标

RSVP

自动滚动

  • 中键自动滚动(#4951,已合并 #4955):桌面 Tauri 滚动模式中键自动滚动,无设置开关、默认开启。核心是 autoscroller.ts 的纯 Autoscroller 类(RAF 循环、12px 死区、10 px/s 每 px 线性速度、上限 4000、整像素发射 + 小数进位、held→sticky/drag 状态机),滚动走 renderer.containerPosition += delta 原生滚动路径(section 预加载照常工作)。iframe 事件处理器在父 realm 维护 armed 注册表,让 handleMousedown 对中键 preventDefault(压制 WebView2 原生自动滚动,避免双重驱动)。
  • 提词器 Auto Scroll(#4998,已合并 #4999):仅滚动模式的提词器式自动滚动,View 菜单切换(Shift+A)。PacedScroller 与中键 Autoscroller 同文件:恒定速度、整像素 + 小数进位、PACED_SCROLL_MAX_FRAME_MS 帧间隔钳制(后台标签恢复);速度 autoScrollSpeed 存 BookLayout(默认 100 = 20 px/s 基础,25–500 步长 25);会话态镜像到 readerStore viewState.autoScrollEnabled,会话不持久化、速度持久化。停顿检测:containerPosition 连续 ≥800ms 不变 → view.next() 跳节或显示 "End of book" toast。
  • 速度滑动调节(#5206)与恢复续滚(#5631,已合并 #5710):auto-scroll-speed-swipe-5206.md(镜像左缘亮度手势,仅会话内启用)、autoscroll-resume-on-reopen-5631.md(per-book autoScrollRunning)。

光标与滚动条

  • 自动隐藏光标(#5178,已合并 #5404):foliate-js 本就带完整的 CursorAutohider(在 view.js,门控 autohide-cursor 属性,挂在 view 元素而非 renderer 上,每次 mousemove 惰性重查),readest 只是接线:FoliateViewer 初始化时 view.toggleAttribute('autohide-cursor', !isMobile && setting);autohideCursor 从 ReadSettings 移到顶层 SystemSettings(按设备而非同步字段,不在 SETTINGS_WHITELIST)。注意:默认值为 true,桌面用户更新后即生效(PR 中已提请维护者决策)。
  • 选择过程中光标被隐藏(foliate-js#68 + #5557):cursor-autohide-blanked-during-selection.md。
  • 底部页脚药丸变黑(#5342,已合并 #5347):药丸背景与 mix-blend-difference 不能共存,见 footer-pill-vs-blend-5342.md。
  • Home/End 跳转(#5660,已合并 #5673):goToFraction(0|1) 单次调用 + inited 守卫;页脚 "66 / 68" 是对的,见 home-end-book-jump-5660.md。
  • 页脚页码跳变(#3392,已合并 #5524):page-number-jump-3392.md。

阅读器内搜索

  • 搜索模式(#4560,Calibre 对标):在 foliate-js search.js 内新增 regex 与 nearby-words 模式(regexSearch/nearbyWordsSearch/mode 分发),per-word cfis + 注解去重在 view.js;BookSearchConfig.mode/nearbyWords + BookSearchMatch.cfis + SearchExcerpt.segments 进 types/book.ts,schema v2→v3 在 serializer.ts(ensureSearchMode 从旧布尔 matchWholeWords 推导,nearbyWords 默认 10 词)。侧栏模式选择器 + 灰色修饰符 + "within N words" 步进器 + searchError 态 + 分段摘录。原计划的 Turso 缓存引擎与 searchBook agent 工具被 /autoplan 评审砍掉、分期进行。
  • 500 条上限(#5724,已合并 #5728):书内搜索在 500 条匹配处静默停止,因为 #5389 把阅读器搜索接到了 searchLibraryBooks(其 per-book 上限 MAX_BOOK_SEARCH_RESULTS = 500 是为防止一本书淹没全库扫描)。修复:LibrarySearchOptions.maxResultsPerBook 默认 500(库扫描用),SearchBar.tsx 传 Infinity。所有 matcher 本就以 Infinity 为无限制默认,无需改动。代价提示:侧栏结果列表无虚拟化,常用词在长书中会物化全部 DOM 匹配。

版式、小组件与平台杂项

段落模式(Paragraph Mode)

Webtoon 模式与 D-pad

  • Webtoon Mode(#3647):图像书(CBZ/漫画/PDF/固定版式 EPUB)的无缝滚动:滚动流 + 0 页间距 + 适配宽度。关键架构事实:foliate-js 固定版式滚动渲染器天然按宽度适配(#renderScrollMode 按 hostWidth/vpWidth * scaleFactor 缩放、忽略 zoom 属性),唯一破坏适配宽度的是 scale-factor ≠ 100,所以 Webtoon 模式强制 zoomLevel=100;4px 页间距原本硬编码在 .scroll-page { margin: 4px 0 },改为 --scroll-page-gap CSS 变量(默认 4px),toggle 时捕获/恢复滚动锚点防跳变。
  • D-pad 导航(Android TV/蓝牙遥控器 + 桌面方向键):dpad-navigation.md。自研 useSpatialNavigation(阅读器工具栏版 + 书库网格版,同名不同目录),弃用第三方库(init 时序问题 + 与 useShortcuts 冲突)。关键坑:Android WebView 内置空间导航会截获方向键,需给非交互浮层元素加 tabIndex={-1};可见性检测不能用 offsetParent(fixed 容器内恒为 null),改用 focus-probe(btn.focus() 后检查 document.activeElement);方向键必须在容器层 stopPropagation,否则冒泡到 window 被 useShortcuts 当成翻页。

小组件与平台

OPDS/WebDAV 与封面

工程方法与实践:这份索引教给我们的调试范式

通读索引及其背后的记忆文件,可以提炼出 Readest 团队稳定的工程方法论,这些对任何复杂跨端阅读器项目都有借鉴价值:

  1. 真机 CDP 验证是默认纪律:大量修复标注 "CDP-verified on Xiaomi 13 (fuxi)"、"Xiaomi verified",且明确区分"合成触摸可测/不可测"(CDP 合成触摸不触发 WebView 长按选择手势;CDP 无法测试横向滚轮平移)。索引中还有专门的 feedback-always-verify-on-xiaomi.md。
  2. 内存文件即"设计决策 + 坑"的记录体:每条记忆都包含 root cause、final design、gotcha、验证方式,且互相链接([[related-memory]]),形成可导航的知识图。
  3. 子模块 PR 流程:foliate-js 是子模块,搜索/滚动/选择等内核改动必须先在子模块提交 PR(git push git@github.com:readest/foliate-js.git HEAD:refs/heads/<branch> + gh pr create --repo readest/foliate-js),readest 侧只 bump 指针;squash 合并后要重瞄指针。
  4. "宁可修根因,不搞特例":如 #4760 拒绝 GLOBAL_ONLY_VIEW_SETTINGS 特例清单,最终落在通用的值比较修复;#5724 拒绝在 matcher 层加新 cap,提示"要虚拟化列表而不是重新引入上限"。
  5. 测试锚定行为:调度器(fixed-layout-scroll-scheduler.test.ts)、序列化器(serializer.test.ts)、RTL 检测(jsdom 断言整词 span + dir)、自动滚动(注入 raf/now 的 autoscroller.test.ts)、光标自动隐藏契约测试(autohide-cursor.test.ts)等,都用单测锁定修复语义。

结语

reader-feature-fixes.md 是 Readest 阅读器工程知识的高度浓缩入口:它以一行一条的形式,把 PDF 渲染性能、跨页选择、即时词典、工具栏全局化、RSVP 的 RTL 处理、自动滚动、注解中心等数十个已解决问题的结论与记忆文件对应起来。对于想要深入理解或二次开发 Readest 阅读器的工程师,建议按"索引 → 记忆文件 → 源码/测试"的路径逐条追读;文中引用的 fixed-layout.js 滚动调度器、serializer.ts 值比较、rsvp/utils.ts 的 RTL 检测与 SearchBar.tsx 的 maxResultsPerBook: Infinity 等实现,都可以作为理解这些修复如何落地的第一手证据。

登录后查看全文
readest