111 lines
6.5 KiB
Markdown
111 lines
6.5 KiB
Markdown
# 需求：ReadViewSDK v1.1（WXRead 深化对齐）
|
||
|
||
**定义日期：** 2026-05-22
|
||
**核心价值：** 在已完成的 reflowable EPUB 原生化基础上，继续补齐 WXRead 风格的页面级排版能力、阅读交互精度与回归可验证性。
|
||
|
||
## 背景
|
||
|
||
v1 已完成以下主目标：
|
||
|
||
- reflowable EPUB 已具备 WXRead 风格的五层 CSS 组织与章节级 render context
|
||
- 分页器已具备 block / attachment 边界感知与页面元数据输出
|
||
- reader 主流程、高亮、搜索、位置恢复、主题/字号/行高重分页已接回
|
||
- fixed layout / interactive EPUB 继续保持 `WKWebView` 路径
|
||
|
||
与 `Doc/WXRead/analysis/` 对照后，当前主要差距已不在“是否走原生管线”，而在以下深化能力：
|
||
|
||
- 页面级 layout frame 的几何查询与绘制能力不足
|
||
- 自定义 CSS / attributed string 属性到分页器的闭环仍不完整
|
||
- 分页质量、缓存、复杂块元素规则与自动化验证仍弱于 WXRead
|
||
|
||
## v1.1 需求（本次范围）
|
||
|
||
### 页面级布局与几何能力
|
||
|
||
- [ ] **LAYOUT-01**：为 native text 分页结果补齐页面级 layout frame 几何查询能力，至少包括字符串范围矩形查询、矩形反查文本范围、截断检测、命中定位所需的基础 API
|
||
- [ ] **LAYOUT-02**：阅读器侧的高亮、搜索命中、选区、点击定位等行为应优先建立在 layout frame 几何能力之上，而不是继续强依赖 `UITextView` 的黑盒行为
|
||
- [ ] **LAYOUT-03**：页面级模型需要继续保留并兼容 `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 等既有语义
|
||
|
||
### WXRead 自定义属性闭环
|
||
|
||
- [ ] **ATTR-01**：补齐一条从章节 HTML / CSS 到 `NSAttributedString` 再到分页器的自定义属性闭环，至少覆盖 `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate`
|
||
- [ ] **ATTR-02**：图片与附件相关排版需要支持类似 `wr-vertical-center-style` 的语义输入，并在分页 / 展示阶段保留可消费的信息
|
||
- [ ] **ATTR-03**：复杂块元素至少要能区分代码块、表格、列表、引用块等类别，以支持更精细的分页边界控制与诊断
|
||
|
||
### 分页质量与性能收敛
|
||
|
||
- [ ] **QUAL-01**：为 layout frame / 分页结果增加缓存机制，避免同一章节在相同视口与排版配置下重复全量排版
|
||
- [ ] **QUAL-02**：复杂图文章节的分页质量要进一步提升，减少不合理断页、孤行/寡行、图片前后留白异常、代码块/表格被粗暴截断等问题
|
||
- [ ] **QUAL-03**：图片与附件的尺寸策略、暗色模式适配、页面背景类信息需要具备可验证的处理规则，而不是依赖默认 DTCoreText 行为
|
||
- [ ] **QUAL-04**：分页深化后不能显著恶化首屏时间、重分页耗时或交互流畅度；若无法立即建立硬性指标，至少要输出稳定的诊断与采样数据
|
||
|
||
### 稳定性与自动化验证
|
||
|
||
- [ ] **AUTO-01**：建立覆盖 native reflowable 主路径的自动化回归能力，至少覆盖打开书籍、分页完成、搜索命中、主题/字号切换、位置恢复
|
||
- [ ] **AUTO-02**：样本矩阵需要持续覆盖复杂图文、代码/表格/列表、附件密集、fixed/interactive WebKit、TXT 五类路径
|
||
- [ ] **AUTO-03**：每项核心能力都应尽量附着到可重复证据：日志、断言、诊断摘要、UI 自动化步骤或稳定的人工检查清单
|
||
|
||
## 成功标准
|
||
|
||
以下结论必须全部为 TRUE：
|
||
|
||
1. native reflowable 路径拥有可复用的页面几何查询能力，reader 交互不再主要依赖 `UITextView` 推断页面几何
|
||
2. 至少一组 WXRead 风格自定义分页属性已形成端到端闭环，并对复杂块元素分页产生可见收益
|
||
3. 同一批复杂样本在新一轮分页器深化后，分页质量优于当前 v1 完成态，而不是仅增加结构复杂度
|
||
4. 自动化或半自动化验证覆盖到 native text 的关键交互，不再主要依赖单次手工 spot check
|
||
5. fixed layout、interactive EPUB、TXT 和既有 `RDReaderView` 翻页容器不回归
|
||
|
||
## 非目标（本次明确不做）
|
||
|
||
| 功能 | 原因 |
|
||
|---|---|
|
||
| 重写或替换 `RDReaderView` 翻页容器 | 本次继续只深化 native reflowable 内核与页面几何能力 |
|
||
| 复刻 WXRead 的完整业务层能力（翻译/双语、免费试读、网络协议、DRM） | 这些属于业务闭环，不是当前 SDK 与 WXRead 的主要技术差距 |
|
||
| 将 fixed layout / interactive EPUB 改为原生渲染 | 仍保持 `WKWebView` 路径以控制风险 |
|
||
| 直接拷贝读书私有 CSS / JS / 私有实现代码 | 仅参考设计思路，不直接搬运私有实现 |
|
||
| 一次性完整重写成自绘 `WRPageView` 等价体系 | 风险过大，优先通过 layout frame 几何层与局部 reader 接线演进 |
|
||
|
||
## 风险与约束
|
||
|
||
- `RDReaderView`、现有 page curl / horizontal / vertical 交互逻辑继续视为稳定容器契约
|
||
- `RDEPUBReaderController` / `RDURLReaderController` 公开入口必须保持兼容
|
||
- 所有分页深化都必须保留 offset-based 兼容语义，避免破坏现有高亮、搜索、恢复位置数据
|
||
- 若要引入自绘或替换 `UITextView` 页面展示，需要以“先引入几何能力、再最小替换”的顺序推进
|
||
- 若性能采样显示分页深化明显拖慢主流程，应优先做缓存与局部优化，而不是继续扩展特性面
|
||
|
||
## 建议优先级
|
||
|
||
1. `LAYOUT-*`：先补 layout frame 几何能力
|
||
2. `ATTR-*`：再补自定义属性到分页器闭环
|
||
3. `QUAL-*`：随后做分页质量与缓存收敛
|
||
4. `AUTO-*`：最后把运行时验证补成自动化或稳定半自动化
|
||
|
||
## 候选 Phase 映射
|
||
|
||
| 需求 | 建议 Phase | 说明 |
|
||
|---|---:|---|
|
||
| LAYOUT-01 | Phase 6 | layout frame 几何 API 与截断检测 |
|
||
| LAYOUT-02 | Phase 6 | reader 交互从 `UITextView` 推断迁移到几何层 |
|
||
| LAYOUT-03 | Phase 6 | 保持 offset / fragment 兼容契约 |
|
||
| ATTR-01 | Phase 7 | 自定义分页属性闭环 |
|
||
| ATTR-02 | Phase 7 | 图片 / 附件布局语义 |
|
||
| ATTR-03 | Phase 7 | block type 分类与分页规则 |
|
||
| QUAL-01 | Phase 8 | layout frame / pagination cache |
|
||
| QUAL-02 | Phase 8 | 复杂样本分页质量提升 |
|
||
| QUAL-03 | Phase 8 | 图片暗色与页面背景类规则 |
|
||
| QUAL-04 | Phase 8 | 诊断与性能采样 |
|
||
| AUTO-01 | Phase 9 | native reflowable 自动化回归 |
|
||
| AUTO-02 | Phase 9 | 样本矩阵扩展 |
|
||
| AUTO-03 | Phase 9 | 证据标准化 |
|
||
|
||
**覆盖统计：**
|
||
- v1.1 需求总数：13
|
||
- 页面级布局：3
|
||
- 属性闭环：3
|
||
- 质量与性能：4
|
||
- 自动化验证：3
|
||
|
||
---
|
||
*Requirements defined: 2026-05-22*
|
||
*Last updated: 2026-05-22 after WXRead gap analysis*
|