shen 1efb9d172f feat(reader): 增强阅读器功能与 UI 测试支持

- 新增字体选择（系统/宋体/圆体/等宽）与暗色图片柔化配置
- 文本选择改为自定义手势+操作栏（拷贝/高亮/批注）
- 添加 accessibilityIdentifier 支持自动化 UI 测试
- 新增 UITests 覆盖阅读器打开/关闭、工具栏、设置面板、批注等
- 添加 Demo 测试用 EPUB 书源（宝山辽墓材料与释读）
- 新增文档：UI 自动化测试、功能开发计划、阅读器规划

2026-05-31 23:56:54 +08:00

9.5 KiB

Raw Blame History

阅读器规划：从架构重构到商业版的差距

背景

渲染内核的架构对齐（WXRead 拆分类重构）解决的是"代码可维护性"问题。本文档梳理从"能用的阅读器"到"能上架的商业阅读器"还需要补齐哪些能力。

每项能力标注了三方状态：当前 ReadViewSDK 实现情况、WXRead（微信读书）反编译源码中的实现情况。

一、渲染质量（最直接影响用户体验）

三方对比总览

缺失项	严重度	ReadViewSDK	WXRead	差距说明
竖排文字	高	❌ 未实现	❌ 未实现	双方均无 `writing-mode` 支持。WXRead 同样不支持，不是对标项
Ruby 注音	高	❌ 未实现	❌ 未实现	双方均无 `<ruby>`/`<rt>` 处理。DTCoreText 限制，需 WebView 回退
数学公式	中	❌ 未实现	⚠️ 仅字体回退	我们无任何支持。WXRead 打包 mathFonts.bundle 做数学符号字体回退，但无 MathML 解析
复杂图文分页质量	高	✅ 已实现	✅ 已实现	双方均已实现，见下方详情对比
字体选择器	中	✅ 已实现	⚠️ 管线完备，UI 未见	我们已支持系统/宋体/圆体/等宽四档字体选择、持久化、重新分页和缓存隔离。WXRead 有 15+ 内置字体，后续差距主要是字体包数量
连字/断字	中	⚠️ 仅配置标记	⚠️ 仅属性声明	双方均未实际实现断字逻辑
多语言排版回退	中	⚠️ 语言检测有，简繁转换无	✅ 已实现	我们有拉丁/CJK 分轨 CSS。WXRead 额外有简繁转换和更完善的字体回退

逐项详情

1. 复杂图文分页质量

双方均已实现，核心能力对齐情况：

子项	ReadViewSDK	WXRead
`avoidPageBreakInside`	✅ 反向扫描行，`kMaxLinesToRemove=3`，保护 table/code/list/blockquote	✅ 同算法，`kMaxLinesToRemove=3`，保护同类元素
`pageBreakBefore` / `pageBreakAfter`	✅ 语义标记注入 + 分页引擎消费	✅ U+2028 LINE SEPARATOR + DTPageBreakBefore/AfterAttribute
`pageRelate` 跨页关联	✅ `weread-page-relate` 语义注入	✅ `weread-page-relate:true` CSS 属性
`keepWithNext`	✅ `trimmedRangeForKeepWithNext` 实现	❌ 未实现（我们反而领先）
图片垂直居中	✅ `wr-vertical-center-style:2` + bodyPic 包装	✅ 同机制
图片缩放	✅ 动态 `imageMaxHeightRatio=0.85`	✅ 四档 full/half/third/quarter + 1080x1920 上限
暗色模式图片处理	✅ 已实现	✅ 图片与主题背景色 85% 混合
孤行/寡行控制	⚠️ 配置标记有，分页逻辑未引用	⚠️ `avoidOrphans`/`avoidWidows` 声明，实际机制未完全还原

结论：图文分页质量双方基本对齐，我们甚至在 keepWithNext 上领先。暗色模式图片处理已补齐，后续主要是继续扩充分页回归基准和更多真实书籍样本。

2. 字体选择器

子项	ReadViewSDK	WXRead
字号调节	✅ A-/A+ 按钮	✅ A-/A+ 按钮，12-36pt
`fontFamily` 持久化	✅ `RDEPUBReaderFontChoice` 持久化	✅ NSUserDefaults `WRTypesetterFontFamily`
CSS / 排版动态生成	✅ 渲染样式、分页缓存签名和重新分页均接入当前字体	✅ `_WRBuildUserSettingsCSS` 动态生成 `font-family` CSS
内置字体	⚠️ 系统/宋体/圆体/等宽四档	✅ 15+（思源宋体、方正兰亭黑、OpenDyslexic 等）
字体选择面板 UI	✅ 设置面板分段控件	⚠️ 反编译代码中未见，可能在未包含的模块

当前实现状态：字体选择器已可用，切换字体会触发重新分页，并纳入分页缓存 key，避免不同字体复用旧分页。后续如果继续对标 WXRead，重点是引入更多内置字体包和字体预览样式。

3. 多语言排版

子项	ReadViewSDK	WXRead
拉丁/CJK 语言检测	✅ `prefersLatinLanguageCSS`	✅ `isLatinLanguageBook`
分轨 CSS	✅ `wxread-replace.css` / `wxread-replace-latin.css`	✅ `replace.css` / `replaceForLatinLanguageBook.css`
简繁转换	❌ 无	✅ `CFStringTransform` Hans→Latin→Hant
`lang` 属性处理	✅ 提取语言代码	✅ `DTHTMLElement.lang`
`direction` (ltr/rtl)	✅ `RDEPUBReadingProgression`	✅ `DTHTMLElement.direction`

4. Hyphenation 断字

子项	ReadViewSDK	WXRead
配置标记	✅ `hyphenation: Bool = true`	✅ `BOOL hyphenation = YES`
实际断字逻辑	❌ 未应用 `NSParagraphStyle.hyphenationFactor`	❌ 未使用，行分割仍用 `CTTypesetterSuggestLineBreak`

结论：双方状态一致，都是声明了但未实现。

5. 未实现且 WXRead 也未实现的项

项	ReadViewSDK	WXRead	建议
竖排文字	❌	❌	非核心需求，双方均未做
Ruby 注音	❌	❌	DTCoreText 限制，需 WebView 回退方案
数学公式	❌	⚠️ 仅字体	非原生渲染范畴，需 WebView 回退

二、功能完整度

缺失项	严重度	说明
书架/书库管理	高	SDK 只能打开单本书，无书架 UI、阅读历史、分类管理
批注导出/分享	高	高亮/笔记只有本地存储，无导出、分享、复制到剪贴板
阅读统计	中	无阅读时长追踪、阅读速度、连续阅读天数
TTS 朗读	中	微信读书核心功能之一，当前无任何语音相关代码
全局搜索	中	当前搜索只在单本书内，无跨书搜索
离线/云端同步	高	无 iCloud/自建同步，阅读进度和笔记只在本地
夜间模式定时切换	低	有暗色主题但不能跟随系统或定时切换

三、工程成熟度

缺失项	严重度	说明
自动化测试	高	✅ UI 自动化测试已启动并接入 Demo 流程，覆盖打开书籍、阅读器基础交互、工具栏、设置面板、字体选择、暗色主题切换等。仍缺单元测试和分页回归基准
性能基线	高	有 `RDEPUBTextPerformanceSampler` 但无持续监控。大书（100MB+）首屏时间、内存峰值无基准
崩溃防护	中	有 pageCurl 崩溃检测和异步恢复，但无全局异常捕获和上报
内存管理	中	无显式内存预算，大书场景下无章节级内存释放策略
增量构建	中	全书一次性分页，无章节级增量重建能力
缓存管理	中	UserDefaults 存储有限，无磁盘缓存大小控制和淘汰策略

四、可访问性与合规

缺失项	严重度	说明
VoiceOver	高	有 accessibility identifier 但无阅读内容的 VoiceOver 流程
Dynamic Type	中	不响应系统字体大小设置
高对比度	低	主题固定，不跟随系统 trait
DRM	看业务	需求文档已声明不在此范围，但商业分发通常需要

五、按优先级排序的建议路线

P0 — 影响商业发布

分页回归基准（Phase 9 后续）— UI 自动化测试已启动，下一步需要把分页结果、首屏时间、截图差异纳入回归基准
字体选择器增强 — 基础字体选择器已实现。后续需补：更多内置字体包、字体预览、字体资源加载失败兜底
书架/书库管理 — 商业阅读器的入口，没有书架就没有产品形态
暗色模式图片处理增强 — 基础处理已实现。后续可补：按图片亮度自适应混合比例、真实书籍样本回归

P1 — 影响用户留存

批注导出/分享 — 深度阅读用户的核心需求
阅读统计/时长追踪 — 用户粘性和产品数据的基础
性能基线与大书优化 — 大书卡顿是用户流失的主要原因
简繁转换 — WXRead 有 CFStringTransform 简繁转换，面向港澳台用户需要

P2 — 提升竞争力

TTS 朗读 — 通勤场景、无障碍场景刚需
云端同步 — 多设备用户的基本需求
VoiceOver 完善 — 合规和品牌形象
全局搜索 — 藏书量大时的效率工具

不需要对标 WXRead 的项

以下项 WXRead 自身也未实现，不属于必须补齐的能力：

项	ReadViewSDK	WXRead	建议
竖排文字	❌	❌	非核心需求，可延后
Ruby 注音	❌	❌	DTCoreText 限制，需 WebView 回退方案
数学公式	❌	⚠️ 仅字体	非原生渲染范畴，需 WebView 回退
Hyphenation 断字	⚠️ 仅标记	⚠️ 仅标记	双方均未实现，中文场景影响小

ReadViewSDK 领先 WXRead 的项

项	说明
`keepWithNext`	我们实现了 `trimmedRangeForKeepWithNext`，WXRead 反编译代码中未找到对应实现

六、总结

经过三方对比，渲染质量层面的真实差距比最初评估要小：

图文分页质量：双方基本对齐，我们甚至在 keepWithNext 上领先
真正的差距：字体包数量、分页回归基准、简繁转换
WXRead 也没做的：竖排、ruby、公式、hyphenation——这些不是必须对齐的

如果目标是"能上架的商业阅读器"，当前已补齐字体选择器、暗色模式图片处理和基础 UI 自动化测试。下一步最值得投入的是分页回归基准、更多字体资源和书架/书库管理。

9.5 KiB Raw Blame History Unescape Escape