4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cdc74e5ad9
ReadViewSDK/.planning/REQUIREMENTS-v1.1-WXRead-next.md

6.5 KiB
Raw Blame History

需求：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