4v5u09Z5a4Yuc/ReadViewSDK

Fork 0

shen 23182e8b5a feat(epub): align wxread css and overlay pagination behavior

2026-05-25 22:15:24 +08:00

15 KiB

Raw Blame History

架构对比分析：读书 vs ReadViewSDK

基于读书 v10.0.3 (Build 79) 逆向文档，与当前 ReadViewSDK 代码在 2026-05-24 的核查结果整合。本文档已吸收原 WXRead剩余问题修复计划.md 的阶段方案，后续以本文档作为单一真值。

标注说明:

✅ 已实现：当前代码已经按接近 WXRead 的路径落地

⚠️ 有差异/有问题：已经实现一部分，但仍与 WXRead 有结构差异，或仍有已知问题

❌ 未实现：当前代码中仍缺失

核心结论

ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链路已经收口到：

CoreText 页面直绘
RDEPUBTextLayouter 分页
5 层 CSS 级联
<link> 样式表内联
页面级 hit test / 选区 / 高亮 / 批注
字符锚点与 fileIndex/row/column 语义的初步位置模型

和 WXRead 现在的主要差距，已经从“能不能工作”收缩成“是否完全同构”：

页面几何模型还没完全等价 WRCoreTextLayoutFrame
章节数据模型还没完全收口成 WRChapterData
位置模型已进入字符级锚点阶段，但还不是完整 WREpubPositionConverter
翻页稳定性、预加载、预测翻页、显示切换一致性已经接入主链路，但还没完全补齐到 WXRead 同构

核查摘要

✅ 已实现

文本页已经改成页面级 CoreText 直绘。
RDEPUBTextLayouter 已接入 RDEPUBTextBookBuilder / RDPlainTextBookBuilder。
4 级语义断页、avoidPageBreakInside 页尾回退、分页缓存都已经落地。
5 层 CSS 级联和 EPUB <link> 外部样式表内联都已经落地。
CoreText 页面 hit test、长按选区、菜单锚点、复制/高亮/批注主链路已经接入页面几何。
CoreText 路径的高亮、注释、搜索命中已经走页面装饰层，而不是继续改正文布局真值。
WebView 路径的标注绘制、搜索高亮已经改成“JS 产出 rect，原生 overlay 负责 CGContext 绘制”，不再依赖 DOM 包裹着色。
分页器已经补上 inline footnote attachment 不整段挪页、标题 keepWithNext、weread-page-relate 页首借行这几类 WXRead 风格规则。
章节尾部“仅空白/段落分隔符”的尾页丢弃，以及极短尾页回并已经落地，宝山辽墓材料与释读 第 31 页空白问题已修复。
RDEPUBTextLayoutConfig 已补齐到 WXRead 同级配置面：frameWidth/frameHeight/edgeInsets/numberOfColumns/columnGap/avoidOrphans/avoidWidows/hyphenation，并已接入分页入口与缓存键。

⚠️ 有差异/有问题

RDEPUBPageLayoutSnapshot、overlay、decoration 的对象边界还没完全等价 WRCoreTextLayoutFrame。
RDEPUBSelectionOverlayView.absoluteRange(at:) 一类回查能力仍不完整，页面几何闭环还差最后一段。
位置模型虽然已经有 rangeAnchor 和 fileIndex/row/column 语义，但还不是完整的 WXRead 双向位置转换器。
RDEPUBChapterData 已承担页内高亮/搜索/页码查询职责，但还没完全吸收 controller/book 层的章节语义。
RDReaderView 已有 pageCurl fault patch、预加载、预测翻页和显示切换位置恢复，但还不是 WXRead 那种完整宿主层补丁集。
default.css / replace.css / dark.css / replaceForLatinLanguageBook.css 已切到内置资源镜像，并接入章节语言分支选择。

❌ 未实现

完整 WRChapterData 同构模型
完整 WREpubPositionConverter 同构模型
预加载、预测翻页、显示切换一致性的完整宿主层方案
字体动态加载、繁简转换
TTS / DRM / Pencil

1. 渲染路径对比

维度	读书	ReadViewSDK	核查
EPUB 文本渲染	`WRPageView.drawRect:` → `CTFrameDraw` 到 CGContext	`RDEPUBTextContentView` → `RDEPUBDirectCoreTextPageView.draw(_:)` + `DTCoreTextLayoutFrame.draw(in:)` 页面级直绘	✅ 已实现
WebView 路径	WKWebView（公众号/文集文章）	WKWebView（interactive/fixed-layout EPUB）	✅ 已实现
文本选区	`CTLineGetStringIndexForPosition` 坐标级 hit test	`RDEPUBPageInteractionController` + `RDEPUBSelectionOverlayView` 已接入主链路	✅ 已实现
标注绘制	`CTFrame` 层叠加绘制（CGContext）	CoreText / WebView 两条链路都已收口到原生页面装饰层绘制	✅ 已实现
搜索高亮	`WRCoreTextLayoutFrame.highlightSearchResults:` 直接绘制	CoreText / WebView 两条链路都已统一为原生页面装饰对象绘制	✅ 已实现

结论： 渲染层里“页面级绘制 + 页面装饰对象收口”这一块已经完成，当前剩余差距不再是标注/搜索高亮链路。

2. 分页引擎对比

维度	读书	ReadViewSDK	核查
分页核心	`WRCoreTextLayouter` + `WRCoreTextLayoutFrame`	`RDEPUBTextLayouter` + `RDEPUBTextLayoutFrame`	✅ 已实现
断页策略	4 级语义断页	已启用 4 级语义断页	✅ 已实现
`avoidPageBreakInside`	页尾最多回退若干行避免破碎	已实现页尾最多回退 3 行	✅ 已实现
inline footnote	行内脚注不应触发整段挪页	已修正为仅块级 attachment 参与整块挪页	✅ 已实现
标题 keep-with-next	标题不能孤悬页尾	已补 `keepWithNext` 语义与页尾回退	✅ 已实现
`weread-page-relate`	页首关联块需要借上一页一行	已补页首 `pageRelate` 借行规则	✅ 已实现
章节尾页收口	丢弃空白尾页、合并极短尾页	已补尾页空白丢弃与超短尾页回并	✅ 已实现
分页配置	`WRCoreTextLayoutConfig`（含多栏等）	`RDEPUBTextLayoutConfig` 已补齐同级参数，并接入分页入口/缓存键/列路径构建	✅ 已实现
缓存	按书籍 + 排版设置缓存	已有 `RDEPUBTextBookCache` 磁盘缓存	✅ 已实现

结论： 当前分页质量问题已经进入问题书细抠阶段，不再是“缺分页器”的阶段；章节尾部空白页这类系统性问题也已经开始按 WXRead 规则收口。

3. CSS 处理对比

维度	读书	ReadViewSDK	核查
CSS 级联层级	5 级：`default < replace < dark < epub < user`	`RDEPUBTextStyleSheetPackage` 已实际生成并注入 5 层	✅ 已实现
EPUB `<link>` CSS	解析前级联合并外部样式	已实现抽取、内联、URL 重写与诊断	✅ 已实现
自定义 CSS 属性	`wr-vertical-center-style`、`weread-page-relate`、断页相关私有属性	已按 WXRead 语义接入 `wr-vertical-center-style`、`weread-page-relate`、`page-break-* / break-*`、`avoidPageBreakInside` 与 attachment placement	✅ 已实现
WXRead 私有 CSS 文件	使用 WeRead 自带 `default/replace/dark/...`	已把 `default/replace/dark` 作为 SDK 内置资源镜像注入 5 层级联	✅ 已实现
`replaceForLatinLanguageBook.css`	拉丁语言专项字体规则	已按章节语言 / 正文拉丁字符占比自动切换 Latin replace 层	✅ 已实现

结论： CSS 主机制、私有资源层和拉丁语言分支都已经按 WXRead 路径收口；这一节当前不再是剩余差距。

4. 位置模型对比

维度	读书	ReadViewSDK	核查
主模型	`WREpubPositionConverter` `(fileIndex, row, column)`	`RDEPUBTextAnchor` + `rangeAnchor` + `RDEPUBTextIndexTable`	⚠️ 有差异/有问题
恢复精度	字符级双向恢复	已优先按 anchor 恢复，弱化 `progression`	⚠️ 有差异/有问题
旧数据兼容	兼容历史位置模型	已兼容旧 `spineIndex` 等旧字段解码	✅ 已实现
全量双向转换	文件位置 <-> 全书字符位置 <-> 页码	已有一部分，但还不是完整 `WREpubPositionConverter`	⚠️ 有差异/有问题

结论： 这一块已经从 ❌ 进入 ⚠️，但还没有达到“WXRead 同构”。

5. 章节数据模型对比

维度	读书	ReadViewSDK	核查
核心模型	`WRChapterData` 一体化承载渲染结果 + 标注 + 搜索 + 目录	`RDEPUBChapterData` 已存在，但职责仍未完全收拢	⚠️ 有差异/有问题
页内高亮查询	章节对象直接提供	`RDEPUBChapterData.highlights(on:from:)` 已提供	✅ 已实现
页内搜索查询	章节对象直接提供	`RDEPUBChapterData.searchResults(on:from:)` 已提供	✅ 已实现
页码/位置查询	章节对象内聚	已部分迁入 `RDEPUBChapterData`，仍有一部分散在 controller/book	⚠️ 有差异/有问题
目录与章节语义	基于章节数据统一管理	仍大量依赖独立 TOC 解析与 controller 调度	⚠️ 有差异/有问题

结论： 章节对象已经不是空白，但也还没收口成 WXRead 那种唯一章节语义中心。

6. 翻页控制器与宿主层对比

维度	读书	ReadViewSDK	核查
翻页动画	curl / slide / fade / none	已有多种翻页模式	✅ 已实现
`UIPageViewController` crash patch	3 个以上专项 patch	已有 pageCurl fault detect + 异步重建	⚠️ 有差异/有问题
预加载	`WRForecastUtils` 预测 + 后台准备	已围绕当前页与预测方向预热相邻页视图	⚠️ 有差异/有问题
预测翻页	基于用户方向预测预建内容	已按可见 spread 和预测方向预热缓存	⚠️ 有差异/有问题
显示切换一致性	翻页模式/单双页/方向切换稳定恢复	已接入切换前记录 location、切换后按位置回落	⚠️ 有差异/有问题

结论： Phase 6 已进入“有实现、继续细抠”的阶段，不再是空白；但离 WXRead 的完整宿主层稳定性还有差距。

7. 资源体系对比

CSS

文件	读书职责	ReadViewSDK 状态	核查
`default.css`	基础 HTML 标签样式	已以内置资源镜像接入	✅ 已实现
`replace.css`	标题、图片、引用、分页控制	已以内置资源镜像接入	✅ 已实现
`dark.css`	暗色主题	已以内置资源镜像接入，并保留主题色覆盖层	✅ 已实现
`replaceForLatinLanguageBook.css`	拉丁语言字体	已接入章节语言自动切换	✅ 已实现
`replaceForMPChapter.css`	公众号文章专用	EPUB 主链路不需要	❌ 未实现（暂不需要）

JS

文件	读书职责	ReadViewSDK 状态	核查
`weread-highlighter.js`	Web 高亮引擎	`epub-bridge.js` 现只负责 rect 解析与桥接，最终由原生 overlay 绘制	✅ 已实现
`rangy-*`	选区/高亮库	CoreText 路径不需要，Web 路径也未采用	⚠️ 有差异/有问题
`cssInjector.js`	动态 CSS 注入	现为原生侧静态注入	⚠️ 有差异/有问题
`WeReadApi.js`	JS-Native 桥接	`window.RDReaderBridge`	⚠️ 有差异/有问题

结论： CSS 资源层已经按 WXRead 的文件级职责收口；剩余差距主要在 JS 桥接策略，而不是 CSS 处理能力。

8. 缺失能力清单

能力	核查	当前优先级
页面几何模型完全等价 `WRCoreTextLayoutFrame`	⚠️ 有差异/有问题	P1
`RDEPUBChapterData` 最终内聚	⚠️ 有差异/有问题	P2
完整字符级位置转换器	⚠️ 有差异/有问题	P2
翻页 crash patch 完整版	⚠️ 有差异/有问题	P3
预加载	⚠️ 有差异/有问题	P3
预测翻页	⚠️ 有差异/有问题	P3
显示切换一致性	⚠️ 有差异/有问题	P3
多栏排版	⚠️ 引擎配置与列路径已接入，阅读器侧未暴露切换	P4
字体动态加载	❌ 未实现	P4
繁简转换	❌ 未实现	P4
TTS / DRM / Pencil	❌ 未实现	P4

9. 收口路线（整合原修复计划）

P1：页面几何与分页行为闭环

RDEPUBPageLayoutSnapshot 继续补齐到更接近 WRCoreTextLayoutFrame
overlay / decoration / selection 回查能力继续统一
继续结合问题书压平标题、脚注段、weread-page-relate、attachment、缩进段等分页细节

当前状态：⚠️ 进行中

P2：位置模型与章节数据内聚

把 rangeAnchor / fileIndex/row/column 继续收成完整位置转换器
把 controller / book 层散落的正文语义继续迁入 RDEPUBChapterData

当前状态：⚠️ 进行中

P3：宿主层稳定性

pageCurl crash patch 完整化
预加载细化
预测翻页细化
显示切换一致性继续压平

当前状态：⚠️ 进行中

P4：外围能力

多栏阅读器开关 / UI 暴露
字体系统
繁简转换
TTS / DRM / Pencil

当前状态：⚠️ 进行中

10. 读书关键类职责速查

类名	职责	ReadViewSDK 对应	核查
`WRReaderViewController`	阅读器主控制器	`RDEPUBReaderController`	✅ 已有对应
`WRPageViewController`	翻页控制器 + crash patch	`RDReaderView`	⚠️ 有差异/有问题
`WRPageView`	CoreText 直接绘制页面	`RDEPUBTextContentView` + `RDEPUBDirectCoreTextPageView`	✅ 已实现
`WREpubTypesetter`	HTML → NSAttributedString（CSS 级联）	`RDEPUBDTCoreTextRenderer`	✅ 已实现
`WRCoreTextLayouter`	CoreText 排版引擎	`RDEPUBTextLayouter`	✅ 已实现
`WRCoreTextLayoutFrame`	排版帧（绘制/选区/搜索/装饰）	`RDEPUBTextLayoutFrame` + snapshot/interaction/overlay	⚠️ 有差异/有问题
`WRChapterData`	章节数据模型	`RDEPUBChapterData`	⚠️ 有差异/有问题
`WRChapterPageCount`	分页计算 + 缓存 key	`RDEPUBTextBookBuilder` + `RDEPUBTextBookCache`	✅ 已实现
`WREpubPositionConverter`	字符级位置双向转换	`RDEPUBTextAnchor` + `RDEPUBTextIndexTable`	⚠️ 有差异/有问题
`WRBookmark`	标注统一模型	`RDEPUBHighlight` + `RDEPUBBookmark`	⚠️ 有差异/有问题
`DTHTMLAttributedStringBuilder`	HTML DOM → NSAttributedString	同（复用 DTCoreText）	✅ 已实现

11. 当前数据流

EPUB 文件
  -> RDEPUBParser.parse (container.xml -> OPF -> spine)
  -> readingProfile 分流:
      textReflowable:
        -> RDEPUBDTCoreTextRenderer
           -> 5 层 CSS 级联
           -> <link> CSS 内联
           -> 自定义分页语义注入
        -> RDEPUBTextBookBuilder
           -> RDEPUBTextLayouter
           -> RDEPUBTextBookCache
        -> RDEPUBTextContentView
           -> RDEPUBDirectCoreTextPageView
           -> RDEPUBPageInteractionController
           -> RDEPUBSelectionOverlayView
      webInteractive:
        -> RDEPUBPaginator
        -> RDEPUBWebContentView
        -> epub-bridge.js
      webFixedLayout:
        -> RDEPUBWebContentView

分析基础：读书 v10.0.3 (Build 79) 逆向文档 当前代码核查日期：2026-05-24

15 KiB Raw Blame History Unescape Escape

架构对比分析：读书 vs ReadViewSDK

核心结论

核查摘要

✅ 已实现

⚠️ 有差异/有问题

❌ 未实现

1. 渲染路径对比

2. 分页引擎对比

3. CSS 处理对比

4. 位置模型对比

5. 章节数据模型对比

6. 翻页控制器与宿主层对比

7. 资源体系对比

CSS

JS

8. 缺失能力清单

9. 收口路线（整合原修复计划）

P1：页面几何与分页行为闭环

P2：位置模型与章节数据内聚

P3：宿主层稳定性

P4：外围能力

10. 读书关键类职责速查

11. 当前数据流

15 KiB

Raw Blame History