4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(epub): complete wxread parity scope

Browse Source
This commit is contained in:
shen
2026-05-26 09:19:37 +08:00
parent 23182e8b5a
commit 0e7d952fe5
31 changed files with 2619 additions and 1533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/架构对比分析_WXRead_vs_ReadViewSDK.md
+62 -70
View File
@@ -7,6 +7,7 @@
> - `✅ 已实现`：当前代码已经按接近 WXRead 的路径落地
> - `⚠️ 有差异/有问题`：已经实现一部分，但仍与 WXRead 有结构差异，或仍有已知问题
> - `❌ 未实现`：当前代码中仍缺失
> - `❌ 明确不实现`：经确认不纳入当前 EPUB 阅读器复刻范围
---
@@ -19,14 +20,12 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
- 5 层 CSS 级联
- `<link>` 样式表内联
- 页面级 hit test / 选区 / 高亮 / 批注
- 字符锚点与 `fileIndex/row/column` 语义的初步位置模型
- 字符锚点与 `fileIndex/row/column` 语义的完整位置模型
和 WXRead 现在的主要差距，已经从“能不能工作”收缩成“是否完全同构”：
核查结论：在当前约定范围内，ReadViewSDK 已经完成 EPUB 阅读器对 WXRead 文档主链路的复刻。当前文档里不再保留主链路级 `⚠️` 项，剩余仅有两类：
1. 页面几何模型还没完全等价 `WRCoreTextLayoutFrame`
2. 章节数据模型还没完全收口成 `WRChapterData`
3. 位置模型已进入字符级锚点阶段，但还不是完整 `WREpubPositionConverter`
4. 翻页稳定性、预加载、预测翻页、显示切换一致性已经接入主链路，但还没完全补齐到 WXRead 同构
1. `replaceForMPChapter.css` 这类公众号文章专用资源，对 EPUB 主链路不适用
2. 繁简转换、TTS / DRM / Pencil 这类已明确排除在本次复刻范围之外的外围能力
---
@@ -44,23 +43,16 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
- 分页器已经补上 inline footnote attachment 不整段挪页、标题 `keepWithNext`、`weread-page-relate` 页首借行这几类 WXRead 风格规则。
- 章节尾部“仅空白/段落分隔符”的尾页丢弃，以及极短尾页回并已经落地，`宝山辽墓材料与释读` 第 31 页空白问题已修复。
- `RDEPUBTextLayoutConfig` 已补齐到 WXRead 同级配置面：`frameWidth/frameHeight/edgeInsets/numberOfColumns/columnGap/avoidOrphans/avoidWidows/hyphenation`，并已接入分页入口与缓存键。
- `RDEPUBChapterData` 已统一承载章节分页结果、位置查询、搜索/高亮回查与目录语义，章节模型主链路已经收口。
### ⚠️ 有差异/有问题
- `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
- 繁简转换（明确不实现）
- TTS / DRM / Pencil（明确不实现）
---
@@ -74,7 +66,7 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 标注绘制 | `CTFrame` 层叠加绘制（CGContext） | CoreText / WebView 两条链路都已收口到原生页面装饰层绘制 | ✅ 已实现 |
| 搜索高亮 | `WRCoreTextLayoutFrame.highlightSearchResults:` 直接绘制 | CoreText / WebView 两条链路都已统一为原生页面装饰对象绘制 | ✅ 已实现 |
**结论：** 渲染层里“页面级绘制 + 页面装饰对象收口”这一块已经完成，当前剩余差距不再是标注/搜索高亮链路。
**结论：** 渲染层里“页面级绘制 + 页面装饰对象收口”这一块已经完成，页面几何回查也已经补到与 WXRead 同一路径的页面快照闭环。
---
@@ -92,7 +84,7 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 分页配置 | `WRCoreTextLayoutConfig`（含多栏等） | `RDEPUBTextLayoutConfig` 已补齐同级参数，并接入分页入口/缓存键/列路径构建 | ✅ 已实现 |
| 缓存 | 按书籍 + 排版设置缓存 | 已有 `RDEPUBTextBookCache` 磁盘缓存 | ✅ 已实现 |
**结论：** 当前分页质量问题已经进入问题书细抠阶段，不再是“缺分页器”的阶段；章节尾部空白页这类系统性问题也已经开始按 WXRead 规则收口。
**结论：** 分页主链路已经按 WXRead 收口，当前差异不再落在分页引擎或分页配置能力面上。
---
@@ -114,12 +106,12 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 维度 | 读书 | ReadViewSDK | 核查 |
|------|---------|-------------|------|
| 主模型 | `WREpubPositionConverter` `(fileIndex, row, column)` | `RDEPUBTextAnchor` + `rangeAnchor` + `RDEPUBTextIndexTable` | ⚠️ 有差异/有问题 |
| 恢复精度 | 字符级双向恢复 | 已优先按 anchor 恢复，弱化 `progression` | ⚠️ 有差异/有问题 |
| 主模型 | `WREpubPositionConverter` `(fileIndex, row, column)` | `RDEPUBTextPositionConverter` + `RDEPUBTextAnchor/rangeAnchor`，已补齐全书字符位置与页码双向转换 | ✅ 已实现 |
| 恢复精度 | 字符级双向恢复 | 当前位置、选区、高亮、搜索命中都已优先走 `rangeAnchor` / `fileIndex-row-column` 恢复，`progression` 仅作回退 | ✅ 已实现 |
| 旧数据兼容 | 兼容历史位置模型 | 已兼容旧 `spineIndex` 等旧字段解码 | ✅ 已实现 |
| 全量双向转换 | 文件位置 <-> 全书字符位置 <-> 页码 | 已有一部分，但还不是完整 `WREpubPositionConverter` | ⚠️ 有差异/有问题 |
| 全量双向转换 | 文件位置 <-> 全书字符位置 <-> 页码 | `RDEPUBTextPositionConverter` / `RDEPUBTextIndexTable` 已补齐 `fileIndex,row,column <-> chapterOffset <-> globalOffset <-> pageNumber <-> location` | ✅ 已实现 |
**结论：** 这一块已经从 `❌` 进入 `⚠️`，但还没有达到“WXRead 同构”。
**结论：** 位置模型这条链路已经按 WXRead 的 `PositionConverter` 思路收口，当前不再是位置恢复能力缺失的问题。
---
@@ -127,13 +119,13 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 维度 | 读书 | ReadViewSDK | 核查 |
|------|---------|-------------|------|
| 核心模型 | `WRChapterData` 一体化承载渲染结果 + 标注 + 搜索 + 目录 | `RDEPUBChapterData` 已存在，但职责仍未完全收拢 | ⚠️ 有差异/有问题 |
| 核心模型 | `WRChapterData` 一体化承载渲染结果 + 标注 + 搜索 + 目录 | `RDEPUBChapterData` 现已统一承载章节分页结果、位置查询、搜索/高亮回查与目录语义 | ✅ 已实现 |
| 页内高亮查询 | 章节对象直接提供 | `RDEPUBChapterData.highlights(on:from:)` 已提供 | ✅ 已实现 |
| 页内搜索查询 | 章节对象直接提供 | `RDEPUBChapterData.searchResults(on:from:)` 已提供 | ✅ 已实现 |
| 页码/位置查询 | 章节对象内聚 | 已部分迁入 `RDEPUBChapterData`，仍有一部分散在 controller/book | ⚠️ 有差异/有问题 |
| 目录与章节语义 | 基于章节数据统一管理 | 仍大量依赖独立 TOC 解析与 controller 调度 | ⚠️ 有差异/有问题 |
| 页码/位置查询 | 章节对象内聚 | `RDEPUBChapterData` 已统一提供 chapter/page/location/searchMatch 双向回查 | ✅ 已实现 |
| 目录与章节语义 | 基于章节数据统一管理 | 已由 `RDEPUBChapterData` 统一提供 TOC 命中、主目录项解析与章节页码定位 | ✅ 已实现 |
**结论：** 章节对象已经不是空白，但也还没收口成 WXRead 那种唯一章节语义中心。
**结论：** 章节对象这条链路已经按 WXRead 的 `WRChapterData` 思路收口，章节分页、位置、搜索、高亮与目录语义现在都围绕 `RDEPUBChapterData` 统一组织。
---
@@ -142,12 +134,12 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 维度 | 读书 | ReadViewSDK | 核查 |
|------|---------|-------------|------|
| 翻页动画 | curl / slide / fade / none | 已有多种翻页模式 | ✅ 已实现 |
| `UIPageViewController` crash patch | 3 个以上专项 patch | 已有 pageCurl fault detect + 异步重建 | ⚠️ 有差异/有问题 |
| 预加载 | `WRForecastUtils` 预测 + 后台准备 | 已围绕当前页与预测方向预热相邻页视图 | ⚠️ 有差异/有问题 |
| 预测翻页 | 基于用户方向预测预建内容 | 已按可见 spread 和预测方向预热缓存 | ⚠️ 有差异/有问题 |
| 显示切换一致性 | 翻页模式/单双页/方向切换稳定恢复 | 已接入切换前记录 location、切换后按位置回落 | ⚠️ 有差异/有问题 |
| `UIPageViewController` crash patch | 3 个以上专项 patch | 已补 pageCurl 异常检测、转场期间跳转排队、动画后校验与异步重建恢复 | ✅ 已实现 |
| 预加载 | `WRForecastUtils` 预测 + 后台准备 | 已围绕当前页、当前 spread 和可见方向预热相邻页视图，并在布局环境变化时裁剪缓存 | ✅ 已实现 |
| 预测翻页 | 基于用户方向预测预建内容 | 已按手势/滚动方向和 pending target 预测下一屏，优先向预测方向额外预热一屏 | ✅ 已实现 |
| 显示切换一致性 | 翻页模式/单双页/方向切换稳定恢复 | 已补切换前位置快照、切换后按 location 恢复，以及横竖屏过渡期间的延迟恢复链路 | ✅ 已实现 |
**结论：** Phase 6 已进入“有实现、继续细抠”的阶段，不再是空白；但离 WXRead 的完整宿主层稳定性还有差距。
**结论：** 翻页控制器与宿主层这条链路已经按 WXRead 的主实现思路收口，pageCurl 稳定性、预测预加载和显示切换恢复现在都走统一闭环。
---
@@ -161,18 +153,18 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| `replace.css` | 标题、图片、引用、分页控制 | 已以内置资源镜像接入 | ✅ 已实现 |
| `dark.css` | 暗色主题 | 已以内置资源镜像接入，并保留主题色覆盖层 | ✅ 已实现 |
| `replaceForLatinLanguageBook.css` | 拉丁语言字体 | 已接入章节语言自动切换 | ✅ 已实现 |
| `replaceForMPChapter.css` | 公众号文章专用 | EPUB 主链路不需要 | ❌ 未实现（暂不需要） |
| `replaceForMPChapter.css` | 公众号文章专用 | EPUB 主链路不需要 | ✅ EPUB 主链路不适用 |
### JS
| 文件 | 读书职责 | ReadViewSDK 状态 | 核查 |
|------|-------------|-----------------|------|
| `weread-highlighter.js` | Web 高亮引擎 | `epub-bridge.js` 现只负责 rect 解析与桥接，最终由原生 overlay 绘制 | ✅ 已实现 |
| `rangy-*` | 选区/高亮库 | CoreText 路径不需要，Web 路径也未采用 | ⚠️ 有差异/有问题 |
| `cssInjector.js` | 动态 CSS 注入 | 现为原生侧静态注入 | ⚠️ 有差异/有问题 |
| `WeReadApi.js` | JS-Native 桥接 | `window.RDReaderBridge` | ⚠️ 有差异/有问题 |
| `rangy-*` | 选区/高亮库 | CoreText 路径不需要；`webInteractive` / `webFixedLayout` 已接入 `rangy-core.js` + `rangy-serializer.js` 等价层，统一负责 DOM range 序列化与 iframe 文档回放 | ✅ 已实现 |
| `cssInjector.js` | 动态 CSS 注入 | 已接入 `cssInjector.js`，由 `WeReadApi` 在 `webInteractive` / `webFixedLayout` 路径按需向主文档和 iframe 文档注入主题/分页样式 | ✅ 已实现 |
| `WeReadApi.js` | JS-Native 桥接 | 已接入 `WeReadApi.js`，并由 `window.WeReadApi` 统一封装分页、主题、搜索、高亮和 progression bridge | ✅ 已实现 |
**结论：** CSS 资源层已经按 WXRead 的文件级职责收口；剩余差距主要在 JS 桥接策略，而不是 CSS 处理能力。
**结论：** CoreText 路径不需要 `rangy` / `cssInjector` / `WeReadApi`；但 `webInteractive` 和 `webFixedLayout` 两条 Web 路径都需要。当前资源体系已经把这套 Web 资源层完整接回 SDK，JS 侧职责也已按 WXRead 思路收口。
---
@@ -180,17 +172,12 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 能力 | 核查 | 当前优先级 |
|------|------|-----------|
| 页面几何模型完全等价 `WRCoreTextLayoutFrame` | ⚠️ 有差异/有问题 | P1 |
| `RDEPUBChapterData` 最终内聚 | ⚠️ 有差异/有问题 | P2 |
| 完整字符级位置转换器 | ⚠️ 有差异/有问题 | P2 |
| 翻页 crash patch 完整版 | ⚠️ 有差异/有问题 | P3 |
| 预加载 | ⚠️ 有差异/有问题 | P3 |
| 预测翻页 | ⚠️ 有差异/有问题 | P3 |
| 显示切换一致性 | ⚠️ 有差异/有问题 | P3 |
| 多栏排版 | ⚠️ 引擎配置与列路径已接入，阅读器侧未暴露切换 | P4 |
| 字体动态加载 | ❌ 未实现 | P4 |
| 繁简转换 | ❌ 未实现 | P4 |
| TTS / DRM / Pencil | ❌ 未实现 | P4 |
| 页面几何模型完全等价 `WRCoreTextLayoutFrame` | ✅ 已实现 | - |
| `WRBookmark` 统一标注模型 | ✅ 已实现 | - |
| 多栏排版 | ✅ 已实现 | - |
| 字体动态加载 | ✅ 已实现 | - |
| 繁简转换 | ❌ 明确不实现 | - |
| TTS / DRM / Pencil | ❌ 明确不实现 | - |
---
@@ -198,36 +185,34 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
### P1：页面几何与分页行为闭环
- `RDEPUBPageLayoutSnapshot` 继续补齐到更接近 `WRCoreTextLayoutFrame`
- overlay / decoration / selection 回查能力继续统一
- 继续结合问题书压平标题、脚注段、`weread-page-relate`、attachment、缩进段等分页细节
- `RDEPUBPageLayoutSnapshot` 已补齐 line/run/attachment/contentBounds 与 absoluteRange 命中闭环
- overlay / decoration / selection 回查已经统一到页面快照层
- 问题书分页细节已回收到现有分页规则，不再构成架构缺口
当前状态：`⚠️ 进行中`
当前状态：`✅ 已实现`
### P2：位置模型与章节数据内聚
- 把 `rangeAnchor` / `fileIndex/row/column` 继续收成完整位置转换器
- 把 controller / book 层散落的正文语义继续迁入 `RDEPUBChapterData`
- `rangeAnchor` / `fileIndex/row/column` 双向位置转换已完成
- `RDEPUBChapterData` 章节语义内聚已完成
- `RDEPUBAnnotation` 已把书签/高亮统一收口到单一标注语义层
当前状态：`⚠️ 进行中`
当前状态：`✅ 已实现`
### P3：宿主层稳定性
- `pageCurl` crash patch 完整化
- 预加载细化
- 预测翻页细化
- 显示切换一致性继续压平
- 宿主层 pageCurl 修复、预测预加载和显示切换恢复已完成
- 剩余工作不再是主链路缺失，而是问题书和极端交互场景的持续回归
当前状态：`⚠️ 进行中`
当前状态：`✅ 已实现`
### P4：外围能力
- 多栏阅读器开关 / UI 暴露
- 字体系统
- 繁简转换
- TTS / DRM / Pencil
- 多栏阅读器开关 / UI 暴露已完成
- EPUB 内嵌字体动态注册已完成
- 繁简转换、TTS / DRM / Pencil 明确不实现，不纳入收口范围
当前状态：`⚠️ 进行中`
当前状态：`✅ 范围内已实现`
---
@@ -236,15 +221,15 @@ ReadViewSDK 当前已经不是“旧 UITextView 阅读器”了，文本主链
| 类名 | 职责 | ReadViewSDK 对应 | 核查 |
|------|------|-----------------|------|
| `WRReaderViewController` | 阅读器主控制器 | `RDEPUBReaderController` | ✅ 已有对应 |
| `WRPageViewController` | 翻页控制器 + crash patch | `RDReaderView` | ⚠️ 有差异/有问题 |
| `WRPageViewController` | 翻页控制器 + crash patch | `RDReaderView` | ✅ 已实现 |
| `WRPageView` | CoreText 直接绘制页面 | `RDEPUBTextContentView` + `RDEPUBDirectCoreTextPageView` | ✅ 已实现 |
| `WREpubTypesetter` | HTML → NSAttributedString（CSS 级联） | `RDEPUBDTCoreTextRenderer` | ✅ 已实现 |
| `WRCoreTextLayouter` | CoreText 排版引擎 | `RDEPUBTextLayouter` | ✅ 已实现 |
| `WRCoreTextLayoutFrame` | 排版帧（绘制/选区/搜索/装饰） | `RDEPUBTextLayoutFrame` + snapshot/interaction/overlay | ⚠️ 有差异/有问题 |
| `WRChapterData` | 章节数据模型 | `RDEPUBChapterData` | ⚠️ 有差异/有问题 |
| `WRCoreTextLayoutFrame` | 排版帧（绘制/选区/搜索/装饰） | `RDEPUBTextLayoutFrame` + snapshot/interaction/overlay | ✅ 已实现 |
| `WRChapterData` | 章节数据模型 | `RDEPUBChapterData` | ✅ 已实现 |
| `WRChapterPageCount` | 分页计算 + 缓存 key | `RDEPUBTextBookBuilder` + `RDEPUBTextBookCache` | ✅ 已实现 |
| `WREpubPositionConverter` | 字符级位置双向转换 | `RDEPUBTextAnchor` + `RDEPUBTextIndexTable` | ⚠️ 有差异/有问题 |
| `WRBookmark` | 标注统一模型 | `RDEPUBHighlight` + `RDEPUBBookmark` | ⚠️ 有差异/有问题 |
| `WREpubPositionConverter` | 字符级位置双向转换 | `RDEPUBTextPositionConverter` + `RDEPUBTextIndexTable` | ✅ 已实现 |
| `WRBookmark` | 标注统一模型 | `RDEPUBAnnotation`（兼容 `RDEPUBHighlight` / `RDEPUBBookmark`） | ✅ 已实现 |
| `DTHTMLAttributedStringBuilder` | HTML DOM → NSAttributedString | 同（复用 DTCoreText） | ✅ 已实现 |
---
@@ -270,9 +255,16 @@ EPUB 文件
webInteractive:
-> RDEPUBPaginator
-> RDEPUBWebContentView
-> rangy-core.js / rangy-serializer.js
-> cssInjector.js
-> WeReadApi.js
-> epub-bridge.js
webFixedLayout:
-> RDEPUBWebContentView
-> rangy-core.js / rangy-serializer.js
-> cssInjector.js
-> WeReadApi.js
-> epub-bridge.js
```
---