ReadViewSDK

这是什么

ReadViewSDK 是一个 iOS 阅读 SDK（RDReaderView），提供 EPUB/TXT 的打开、分页与阅读器 UI，并包含一个用于演示集成的 Demo 工程（ReadViewDemo）。当前项目面向 brownfield（已有代码），目标是对现有 reflowable EPUB 阅读内核做一次直接重构：在旧引擎基础上演进为参考微信读书（WXRead）的原生渲染方案，而不是保留并行的第二套原生引擎。

核心价值

稳定可用的 EPUB/TXT 阅读体验。

Current State

已完成 v1.0：现有 reflowable EPUB native path 已完成一轮 WXRead 风格原生化演进。
chapter-level CSS 分层、页面元数据、复杂分页、reader restore/search/highlight 回接，以及 demo 样本矩阵都已落地。
Fixed Layout / interactive EPUB 仍保持 WKWebView 路径，RDReaderView 仍保持既有分页容器契约。

需求

已验证（现有能力）

✓ 支持通过 RDURLReaderController 以 URL 打开 .epub / .txt 并进入阅读器（现有）
✓ 具备 RDEPUBReaderController 作为主阅读器控制器，负责加载/分页/状态管理（现有）
✓ 具备 RDReaderView 作为分页容器视图，支持翻页/滚动等呈现模式（现有）
✓ reflowable EPUB 当前主路径已是基于 DTCoreText / NSAttributedString / CoreText 的原生文本渲染与分页；但其样式分层、资源解析与分页策略仍较基础，本次将增强为更接近 WXRead 的实现（现有实现；本次将改造）
✓ 固定版式（Fixed Layout）与交互式内容存在 WKWebView 相关能力与桥接（现有）
✓ TXT 通过 RDPlainTextBookBuilder / RDEPUBTextBook 路径进入同一阅读器 UX（现有）
✓ 默认使用 UserDefaults 进行部分阅读器状态/设置持久化（现有）
✓ v1.0 已完成 native reflowable 原生化基础：CSS 分层、页面级 metadata、分页器强化、reader 回接与样本矩阵验证（v1.0）

进行中（本次范围）

v1.1 继续补齐 WXRead 深化对齐：layout frame 几何能力、自定义分页属性闭环、分页质量/缓存、以及更强的自动化验证

不做（明确排除）

Fixed Layout EPUB：继续使用 WKWebView，不切换到 WXRead 渲染方式
交互式 EPUB（含 JS / 音视频 / 表单 / iframe / 外链 / 脚本桥接等）：继续使用 WKWebView，不切换到 WXRead 渲染方式
当前翻页代码（包括 RDReaderView 及其现有翻页模式/翻页交互逻辑）：不做修改
直接拷贝使用微信读书私有 JS/CSS/私有实现代码：不做
同时保留两套 reflowable 原生引擎：不做

背景与上下文

仓库形态：iOS SDK + Demo App；Demo 通过 CocoaPods 以本地 :path 引入 SDK。
当前分层：EPUBCore（解析/分页/状态）、EPUBUI（阅读器 UX）、EPUBTextRendering（TXT/TextBook / reflowable 原生文本渲染）、以及 LegacyRDReaderController（历史实现并存）。
WXRead 参考资料位于 Doc/WXRead/，包含对微信读书 EPUB 阅读器的逆向分析文档与相关符号/源码片段。
当前 .textReflowable 主路径已基于 DTCoreText / NSAttributedString / CoreText 分页，但分页能力、页面语义、自定义属性体系与复杂块元素处理仍远弱于 WXRead。

约束

平台：iOS 15+（Podspec 声明 iOS 15.0；工程中常见 15.6）— 现有基线
语言与风格：代码标识符保持英文；文档/计划使用中文（见 CONTEXT.md）— 项目约束
依赖管理：CocoaPods 为主（RDReaderView.podspec、Podfile、ReadViewDemo/Podfile）— 现状约束
引擎策略：必须基于现有旧引擎直接演进，不新增并行原生引擎 — 本次关键约束
范围控制：仅重构 reflowable EPUB 原生渲染内核；Fixed Layout 与交互式内容保持 WKWebView — 本次目标边界
翻页边界：不修改当前翻页代码（RDReaderView 及现有 page curl / scroll 交互逻辑）— 新内核必须适配现有翻页容器
兼容性：阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页必须继续可用 — 核心功能约束
稳定性优先：任何改造需以“可回归验证、不破坏现有打开/阅读主流程”为前提 — 核心价值驱动

关键决策

决策	原因	结果
reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染	需要页面级排版能力，而不是继续在轻量 renderer 外壳上打补丁	✓ Good
Fixed Layout 与交互式 EPUB 继续使用 `WKWebView`	降低风险与范围，避免破坏既有能力	✓ Good
不保留并行 reflowable 原生引擎	避免双引擎长期维护成本，把演进压力集中在现有主路径上	✓ Good
不修改当前翻页代码	控制改动半径，避免把阅读容器与翻页交互回归风险卷入本次内核重构	✓ Good

Next Milestone Goals

补齐 native text layout frame 几何查询能力，减少 reader 交互对 UITextView 黑盒的依赖
建立 WXRead 风格自定义分页属性从 HTML/CSS 到 paginator 的闭环
提升复杂图文章节分页质量，并增加缓存与性能采样
把 native reflowable 主路径的验证从 runtime spot-check 提升到自动化或稳定半自动化

演进

本文件会在阶段切换与里程碑完成时持续演进。

每个 Phase 完成后（通过 $gsd-transition）：

有需求被证伪 → 移到“不做”并说明原因
有需求被验证 → 移到“已验证”并记录来源 Phase
出现新需求 → 加到“进行中”
产生关键决策 → 追加到“关键决策”
“这是什么”是否仍准确 → 如有漂移及时更新

每个 Milestone 完成后（通过 $gsd-complete-milestone）：

全面复查所有章节
核心价值是否仍是最高优先级
“不做”是否需要调整边界与理由
更新背景与上下文到当前真实状态

Last updated: 2026-05-22 after v1.0 milestone completion

6.0 KiB Raw Blame History Unescape Escape