5.9 KiB
5.9 KiB
架构分析：WXRead 参考 vs ReadViewSDK 当前
分析日期： 2026-05-23
分析基础： Doc/WXRead/decompiled-doc.md、Doc/WXRead/resources-doc.md、Doc/WXRead/读书EPUB阅读器实现架构.md
状态： Decisions captured
## 分析范围
对比读书 (WeRead v10.0.3) 逆向架构与当前 ReadViewSDK 项目的结构性差距，聚焦四大方向：分页引擎集成、CSS 处理、渲染架构、字体系统。
读书 EPUB 渲染的核心架构特征：
- Path A (EPUB): 纯 CoreText 渲染 —
WRPageView.drawRect:→CTFrameDraw，不用 UITextView/UILabel - 4 级语义断页：
WRCoreTextLayouter+WRCoreTextLayoutFrame(语义边界 > 附件边界 > 块边界 > 帧限制) - 5 层 CSS 级联：
default.css < replace.css < dark.css < EPUB 内嵌 < 用户设置 - 字符级位置精度：
WREpubPositionConverter(fileIndex, row, column) ↔ 全局字符偏移 - 标注直接在 CTFrame 层叠加绘制，搜索高亮同理
Area 1: 分页引擎集成（P0）
| 决策 | 说明 |
|---|---|
将 RDEPUBTextLayouter 集成到 RDEPUBTextBookBuilder |
内部调用 rd_paginatedFrames(size:) 替代旧的 ss_pageRanges(size:)，外部 API 不变 |
分页元数据暴露到 RDEPUBTextPage |
新增 metadata: RDEPUBTextPageMetadata 字段（含 breakReason/blockKinds/semanticHints），对外暴露分页质量数据 |
RDEPUBTextChapterPaginationDiagnostic 增强 |
透传 RDEPUBTextLayoutFrame 的诊断信息 |
| 分页缓存 | 按 bookID + fontSize + lineHeightMultiple + contentInsets 生成缓存 key，缓存完整 RDEPUBTextBook 到磁盘 |
Area 2: CSS <link> 外部样式表处理（P0）
| 决策 | 说明 |
|---|---|
| 预处理内联 CSS | 渲染前扫描 HTML 中 <link> 标签，从 EPUB 解压目录读取 CSS 内容，注入 <style> 替换 <link> |
| 实现 5 层 CSS 级联 | RDEPUBTextStyleSheetBuilder 实现 default < replace < dark < epub-embedded < user 五层合并，使用已定义的 RDEPUBTextStyleSheetPackage/RDEPUBTextStyleSheetLayer |
Area 3: CoreText 直接绘制迁移（P1 — 大架构变更）
| 决策 | 说明 |
|---|---|
| 直接替换 UITextView | 新实现完全替代 RDEPUBTextContentView，不保留 UITextView 渐进迁移路径 |
| CoreText 原生选区 | CTLineGetStringIndexForPosition 坐标 hit test + 自定义选区绘制，不依赖 UITextView 选区 |
| 标注渲染：CGContext 装饰层 | drawRect 中 CTFrameDraw 绘制文本后，遍历当前页 RDEPUBHighlight，CGContext 绘制背景矩形（highlight）/ 下划线（underline） |
| 搜索高亮：CGContext 叠加绘制 | 不修改底层 attributedString，在 drawRect 中根据匹配范围直接绘制高亮背景 |
Area 4: 字体系统（P1 — 延迟到后续版本）
| 决策 | 说明 |
|---|---|
| 方案：内嵌固定字体集 | SDK bundle 内嵌常用中文字体，Settings 面板新增字体选择。不做 CDN 动态下载 |
| 本版本范围：暂不做 | 字体切换功能延迟到后续迭代 |
<canonical_refs>
关键参考文档
WXRead 逆向参考（必须阅读）：
Doc/WXRead/decompiled-doc.md— 44 个逆向文件的职责说明Doc/WXRead/resources-doc.md— CSS/JS 资源文件清单与职责Doc/WXRead/读书EPUB阅读器实现架构.md— 双渲染引擎架构总览Doc/WXRead/decompiled/WRCoreTextLayoutFrame.m— 跨页避让、装饰元素、搜索高亮实现Doc/WXRead/decompiled/WRCoreTextLayouter.m— 4 级语义断页配置Doc/WXRead/decompiled/WRPageView.m— CoreText 直接绘制参考Doc/WXRead/decompiled/WREpubTypesetter.m— CSS 级联合并参考Doc/WXRead/resources/css/replace.css— 5 层 CSS 参考
当前项目代码（已有的基础设施）：
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift— 已实现 4 级语义断页，待集成Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift— 帧模型，含 breakReason/semanticHintsSources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift— 已定义RDEPUBTextStyleSheetPackage/RDEPUBTextStyleSheetLayer，未完全使用Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift— 当前可能仍在用旧的ss_pageRangesSources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift— UITextView 实现，待替换为 CoreText
</canonical_refs>
<roadmap_mapping>
与现有 Roadmap 的映射
| 决策 | 对应 Phase | 说明 |
|---|---|---|
| RDEPUBTextLayouter 集成 | Phase 8 (08-02) | 分页质量改善的核心 |
| 分页元数据暴露 | Phase 8 (08-03) | 分页诊断输出的一部分 |
| 分页缓存 | Phase 8 (08-01) | 缓存键与失效策略 |
CSS <link> 内联 |
Phase 7 范畴外 | 当前 Roadmap 未覆盖，需新增 phase 或合并到 Phase 8 |
| 5 层 CSS 级联 | Phase 7 + Phase 8 | Phase 7 已完成属性闭环，级联是后续增强 |
| CoreText 直接绘制 | v1.2 或 v2.0 | 超出 v1.1 Roadmap，需要独立 milestone |
| CoreText 原生选区 | 随 CoreText 迁移 | 同上 |
| 标注 CGContext 绘制 | 随 CoreText 迁移 | 同上 |
| 字体系统 | 未来版本 | 延迟 |
关键发现： CoreText 直接绘制迁移是最大的架构变更，超出 v1.1 的增量改进范围。建议作为 v1.2 独立 milestone 规划。
</roadmap_mapping>
## 延迟事项- 字体系统：内嵌固定字体集方案已决，延迟到后续版本
- 位置精度提升（字符级锚点）：P2，与 CoreText 迁移关联
- 章节数据模型内聚（WRChapterData 模式）：P2，架构清晰度改进
- TTS / DRM / Pencil / 多栏排版：P3，独立功能模块
- 翻页控制器健壮性（UIPageViewController crash patch）：P2，当前未遇到相关崩溃
分析范围：WXRead 逆向文档 → ReadViewSDK 架构差距 产出：4 个 Area、14 项决策、1 项延迟