266 lines
15 KiB
Markdown
266 lines
15 KiB
Markdown
# Reflowable EPUB 使用 WXRead 风格原生渲染：详细设计
|
||
|
||
> 文档目的：讨论并固化“将 ReadViewSDK 的 reflowable EPUB 渲染/排版/分页改为参考 Doc/WXRead 的读书（WXRead）原生渲染方式”的可落地设计，供后续开发与回归使用。
|
||
> 版本：v0（设计草案）
|
||
> 日期：2026-05-21
|
||
|
||
## 0. 背景与结论（先说人话）
|
||
|
||
ReadViewSDK 当前对 EPUB 有三类渲染路径：
|
||
|
||
- `RDEPUBReadingProfile.webFixedLayout`：Fixed Layout EPUB → `WKWebView`（保持不变）
|
||
- `RDEPUBReadingProfile.webInteractive`：交互式 EPUB（JS/音视频/表单/iframe/外链/bridge）→ `WKWebView`（保持不变）
|
||
- `RDEPUBReadingProfile.textReflowable`：普通 reflowable EPUB → **当前走 DTCoreText → NSAttributedString → CoreText 分页 → 原生文本视图**（这是我们要“升级成 WXRead 风格”的主战场）
|
||
|
||
本次改造的最小可落地方向是：**保留三分流策略不变**，只增强 `.textReflowable` 分支，使其在“CSS 分层、样式一致性、资源解析、分页稳定性”等方面更接近 `Doc/WXRead/analysis/EPUB渲染管线详解.md` 所描述的 WXRead 管线，而不是引入新的 WebView 渲染。
|
||
|
||
## 1. 目标 / 非目标
|
||
|
||
### 1.1 目标（In Scope）
|
||
|
||
- G1：reflowable EPUB 的正文渲染/排版/分页改为“WXRead 风格原生渲染管线”：
|
||
- XHTML/HTML →（CSS 分层 + 解析 + 后处理）→ `NSAttributedString`
|
||
- `NSAttributedString` →（CoreText 分页）→ 单页内容
|
||
- 单页内容 → 原生绘制/展示
|
||
- G2：保持 Fixed Layout 与交互式 EPUB 的 `WKWebView` 路径不回归。
|
||
- G3：不破坏 `RDURLReaderController` 打开 `.epub` / `.txt` 的主流程。
|
||
- G4：Demo 可用于验证：至少 2-3 本典型 reflowable EPUB 在段落/标题/图片/链接等常见内容下可稳定阅读。
|
||
|
||
### 1.2 非目标（Out of Scope）
|
||
|
||
- N1：Fixed Layout EPUB 切换为原生渲染（明确不做）。
|
||
- N2：交互式 EPUB 切换为原生渲染（明确不做）。
|
||
- N3：一次性复刻 WXRead 对 DTCoreText 的所有深度魔改（例如自定义 CSS 属性体系、复杂后处理、分页避断规则等）——本次先按“问题驱动”逐步对齐。
|
||
|
||
## 2. 关键事实核验（当前代码真实路径）
|
||
|
||
> 纠偏说明：项目初始化时曾把”reflowable EPUB 当前路径”概括为偏 `WKWebView` 的历史性表述。经本次代码核验，当前真实主路径是 `.textReflowable` → `RDEPUBTextBookBuilder` → `RDEPUBDTCoreTextRenderer` → CoreText 分页 → `RDEPUBTextContentView`。本设计以代码事实为准，并默认后续实现都按此理解推进。
|
||
|
||
### 2.1 渲染路径分流（已存在）
|
||
|
||
- 判定在 `Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift`：
|
||
- `metadata.layout == .fixed` → `.webFixedLayout`
|
||
- `hasInteractiveContent() == true` → `.webInteractive`
|
||
- 否则 → `.textReflowable`
|
||
|
||
### 2.2 `.textReflowable` 当前实现（已存在，且是正确切入点）
|
||
|
||
`Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`：
|
||
|
||
- `publication.readingProfile == .textReflowable` 时：
|
||
- 使用 `RDEPUBTextBookBuilder(renderer: resolvedTextRenderer())`
|
||
- 默认 renderer 是 `RDEPUBDTCoreTextRenderer`（`#if canImport(DTCoreText)`）
|
||
- 分页使用 `NSAttributedString.ss_pageRanges(size:)`（`CTFramesetterCreateFrame` + `CTFrameGetVisibleStringRange`）
|
||
- UI 展示使用 `RDEPUBTextContentView`
|
||
|
||
结论：我们不需要“新起一个阅读器”，只要把 `.textReflowable` 的 **渲染（typesetter）层**与部分 **分页策略**升级即可。
|
||
|
||
## 3. WXRead 参考模型（我们要对齐的最小子集）
|
||
|
||
来自 `Doc/WXRead/analysis/EPUB渲染管线详解.md` 的管线：
|
||
|
||
1) `WREpubParser`：解析 EPUB 结构（spine、manifest、resourceMap）
|
||
2) `WREpubTypesetter`：XHTML → `NSAttributedString`（CSS 级联 + HTML 解析 + 后处理）
|
||
3) `WRCoreTextLayouter`：`NSAttributedString` → 分页布局（`CTTypesetter` + 分页算法）
|
||
4) `WRCoreTextLayoutFrame`：单页 layout frame
|
||
5) `WRPageView`：绘制到屏幕
|
||
|
||
本次设计对齐重点（最小集合）：
|
||
|
||
- A：**CSS 分层与合成**（default/replace/dark/epub/user）并注入到渲染输入
|
||
- B：**资源解析**（图片/CSS 的相对路径 baseURL）与稳定性保障
|
||
- C：在现有分页基础上逐步迭代（先可用，后对齐“避免断页”等高级策略）
|
||
|
||
### 3.1 第一阶段实施假设（必须遵守）
|
||
|
||
- H1：**第一期只对齐“管线形态”和“CSS 分层策略”**，即把现有 `.textReflowable` renderer 增强为更接近 WXRead 的 typesetter 输入与样式组织方式。
|
||
- H2：**第一期不实现 WXRead 对 DTCoreText 的深度魔改**，包括但不限于自定义 CSS 属性体系、复杂附件布局规则、完整的 `WRCoreTextLayouter` / `WRCoreTextLayoutFrame` 等价分页器。
|
||
- H3：当开发过程中遇到图片断页、复杂样式缺失、附件布局异常等问题时，默认先作为“第二阶段问题清单”记录；只有在它阻塞 `REND-01` / `STAB-02` 的最小验收时，才允许做局部补丁，而不是扩展为全面重写分页引擎。
|
||
|
||
## 4. 是否能直接使用 Doc/WXRead 中的 JS/CSS？
|
||
|
||
结论：**不建议、也不应该直接把“来自读书 App bundle 的私有 JS/CSS”拷贝进 SDK 作为产品代码**；但可以按以下原则“选择性使用”：
|
||
|
||
### 4.1 可以使用的情况（需满足其一）
|
||
|
||
- 文件本身带有明确开源许可证声明，且我们按许可证要求引入（保留 license、署名、NOTICE 等），并建议从官方 upstream 获取：
|
||
- 例如 `Doc/WXRead/resources/js/rangy-core.js` 明确标注 MIT
|
||
- 例如 `Doc/WXRead/resources/js/Readability.js` 明确标注 Apache-2.0
|
||
|
||
> 建议：即便文件里有 license 头，也优先从其原始开源仓库拉取对应版本，而不是从逆向提取的副本直接入库，以降低合规风险。
|
||
|
||
### 4.2 不建议/不能直接使用的情况
|
||
|
||
- 无明确许可证头、看起来是读书私有逻辑/样式（例如 `weread-highlighter.js`、`MediaPlatform.js`、`replace.css` 等）：默认视为私有作品，不应直接拷贝使用。
|
||
- 即便是“Safari 默认样式”类文件（例如 `default.css` 的注释提到 Safari），也不建议直接照搬；我们可以根据需求写一份“SDK 自己的 default.css / replace.css”，只实现必要规则。
|
||
|
||
### 4.3 对本次需求的实际影响
|
||
|
||
本次 reflowable EPUB 走原生渲染，不依赖 WebView，因此 **JS 不是本次必需**。
|
||
CSS 方面我们需要的是“分层策略”和一小部分通用排版规则，可在 SDK 内重写为“WXRead 风格的默认样式集合”。
|
||
|
||
## 5. 详细设计（核心）
|
||
|
||
### 5.1 总体架构：在现有 `.textReflowable` 上增量替换 renderer
|
||
|
||
新增一个 renderer（实现 `RDEPUBTextRenderer`）：
|
||
|
||
- `RDEPUBWXReadTextRenderer`（新）
|
||
- 输入：`html: String`, `baseURL: URL?`, `style: RDEPUBTextRenderStyle`
|
||
- 输出：`RDEPUBRenderedChapterContent`（`NSAttributedString` + `fragmentOffsets`）
|
||
- 内部职责：
|
||
1) 读取/生成 CSS 各层（default/replace/dark/user）
|
||
2) 与 EPUB 自带 CSS 共同作用（通过 HTML 注入 + baseURL）
|
||
3) 调用 DTCoreText builder 生成 attributedString
|
||
4) 做最小后处理（段落间距/字体/颜色标准化、fragment marker 提取等）
|
||
|
||
切换点：
|
||
|
||
- 在 `RDEPUBReaderController.resolvedTextRenderer()`（或其配置位置）增加策略：当开关启用时选择 `RDEPUBWXReadTextRenderer()`，否则沿用 `RDEPUBDTCoreTextRenderer()`。
|
||
- 建议默认先提供“实验开关”（仅 Demo / debug 可见），降低回归风险。
|
||
|
||
### 5.2 CSS 分层策略（WXRead 风格）
|
||
|
||
我们在 SDK 内实现与 `Doc/WXRead/analysis/EPUB渲染管线详解.md` 一致的分层概念，但不直接照搬其私有样式文件：
|
||
|
||
- Layer 1：`default.css`（SDK 自己维护的基础排版规则）
|
||
- Layer 2：`replace.css`（SDK 自己维护的替换/增强规则：标题、代码块、图片最大宽度等）
|
||
- Layer 3：`dark.css`（暗色主题覆盖，仅在暗色主题启用）
|
||
- Layer 4：EPUB 嵌入 CSS（书籍自带，DTCoreText 解析 HTML 时自然生效；相对路径靠 baseURL）
|
||
- Layer 5：用户设置 CSS（由 `RDEPUBTextRenderStyle` 动态生成：字体、字号、行高、背景色、文字色等）
|
||
|
||
实现方式（建议）：
|
||
|
||
1) 新增 `RDEPUBWXReadStyleSheetBuilder`：
|
||
- `func makeDefaultCSS() -> String`
|
||
- `func makeReplaceCSS() -> String`
|
||
- `func makeDarkCSS(theme: RDEPUBTheme) -> String?`
|
||
- `func makeUserCSS(style: RDEPUBTextRenderStyle, theme: RDEPUBTheme) -> String`
|
||
- `func composeCSS(...) -> String`（按层拼接，后层覆盖前层）
|
||
|
||
2) 在 renderer 中将合成后的 CSS 注入到 HTML：
|
||
- 若存在 `<head>`：插入 `<style id="rd-wxread-layered-style">...`
|
||
- 若不存在：在 `<html>` 后插入 `<head>...`
|
||
- 保持原 HTML 内容尽量不改动（外部脚本/交互内容已被 readingProfile 判定剔除到 web 分支）
|
||
|
||
### 5.3 baseURL 与资源解析
|
||
|
||
目前 `RDEPUBTextBookBuilder` 传入：
|
||
|
||
- `baseURL: parser.fileURL(forRelativePath: item.href)?.deletingLastPathComponent()`
|
||
|
||
原则：
|
||
|
||
- baseURL 必须是“章节文件所在目录”，以确保：
|
||
- `<img src="...">` 相对路径可解析
|
||
- `<link href="...">` CSS 相对路径可解析（如果 DTCoreText 支持）
|
||
|
||
待核验点（实现时做小实验）：
|
||
|
||
- DTCoreText 对 `<link rel="stylesheet">` 的解析策略是否完整；若不完整：
|
||
- 兜底策略：在渲染前解析 HTML 中的 `<link rel="stylesheet">`，读取 CSS 内容并内联到 `<style>`（仅限 `file://` 且位于 EPUB 解压目录内）。
|
||
|
||
### 5.4 分页策略（阶段性）
|
||
|
||
现状：
|
||
|
||
- `NSAttributedString.ss_pageRanges(size:)` 使用 `CTFramesetterCreateFrame` + `CTFrameGetVisibleStringRange`，属于“最小可用分页”。
|
||
|
||
WXRead 的更高阶策略（参考 `Doc/WXRead/analysis/DTCoreText自定义修改分析.md`）可能包含：
|
||
|
||
- 避免孤行/断页
|
||
- 图片/附件的分页边界处理
|
||
- 特定块元素的分页规则
|
||
|
||
本次建议：
|
||
|
||
- Phase 2：先保持现有分页算法，只要渲染输入（CSS 分层 + 后处理）到位，就能显著改善一致性。
|
||
- Phase 3：针对真实书籍出现的问题，逐条补齐分页规则（问题驱动），避免一开始就引入复杂分页器导致风险扩大。
|
||
|
||
> 范围约束：如果某个分页问题需要引入“新的复杂分页器”或大规模模拟 `WRCoreTextLayouter` / `WRCoreTextLayoutFrame`，应先暂停并回到方案讨论，不默认并入第一期实现。
|
||
|
||
### 5.5 与现有高亮/搜索/位置映射的兼容
|
||
|
||
当前 `.textReflowable` 路径：
|
||
|
||
- 高亮/搜索依赖 `RDEPUBTextBook` 的 `fragmentOffsets` 与 `location/progression` 映射（见 `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` 与 `RDEPUBTextBook` 的 `pageNumber(for:)` / `location(forPageNumber:)`）。
|
||
|
||
兼容策略：
|
||
|
||
- 继续使用现有的 fragment marker 注入与提取：
|
||
- `RDEPUBTextRendererSupport.injectFragmentMarkers(...)`
|
||
- `RDEPUBTextRendererSupport.extractFragmentOffsets(...)`
|
||
- renderer 只改变“CSS 注入与 DTCoreText options/后处理”，不改变 marker 体系与 `RDEPUBTextBook` 数据结构，以降低 UI 层回归。
|
||
|
||
## 6. 开发落点（文件 / 类型 / 目录）
|
||
|
||
### 6.1 新增文件（建议位置）
|
||
|
||
放在 `Sources/RDReaderView/EPUBTextRendering/`（因为它是 textReflowable 的渲染与分页域）：
|
||
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadTextRenderer.swift`（新）
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadStyleSheetBuilder.swift`（新）
|
||
- （可选）`Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadHTMLPreprocessor.swift`（新：仅当需要内联 `<link>` CSS 时）
|
||
|
||
资源文件（建议）：
|
||
|
||
- `Sources/RDReaderView/Resources/WXRead/default.css`（新，SDK 自己写）
|
||
- `Sources/RDReaderView/Resources/WXRead/replace.css`（新，SDK 自己写）
|
||
- `Sources/RDReaderView/Resources/WXRead/dark.css`（新，SDK 自己写）
|
||
|
||
> 注意：这些资源需被 `RDReaderView.podspec` 的 resource bundle 覆盖到（当前资源 bundle 为 `RDReaderViewAssets`，来源 `Sources/RDReaderView/Resources/**`）。
|
||
|
||
### 6.2 改动文件（建议最小改动）
|
||
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
|
||
- 在 `resolvedTextRenderer()` 或相邻配置处增加选择逻辑（开关 / 版本策略）
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
- 如需内联 link CSS：在获取 `rawHTML` 后做预处理（保持接口不变）
|
||
|
||
## 7. 验收标准与验证方式（对应 REQUIREMENTS）
|
||
|
||
### 对应 REND-01 / REND-03
|
||
|
||
- 在 Demo 中打开 reflowable EPUB：
|
||
- 正文渲染不依赖 `WKWebView`（可通过日志/断点确认不走 `RDEPUBWebContentView`）
|
||
- CSS 分层生效：默认样式可控、主题/字号/行高变化可控
|
||
- 图片/链接至少可正确显示/响应（链接行为按现有 text 内容策略）
|
||
|
||
### 对应 REND-02
|
||
|
||
- Fixed Layout EPUB：仍走 `.webFixedLayout` → `WKWebView` 路径
|
||
- 交互式 EPUB：仍走 `.webInteractive` → `WKWebView` 路径（桥接与外链不回归）
|
||
|
||
### 对应 STAB-01 / STAB-02
|
||
|
||
- `RDURLReaderController` 打开 `.epub` / `.txt` 主流程不回归
|
||
- 至少使用以下 3 类 reflowable EPUB 样本进行回归：
|
||
- 样本 A：纯文本/小说类章节为主，验证基础段落、标题、分页与阅读位置恢复
|
||
- 样本 B：包含内嵌图片与多段样式的章节，验证图片显示、图片前后分页、基础 CSS 生效
|
||
- 样本 C：包含外链与多个 CSS 文件引用的章节，验证 baseURL、样式解析与链接呈现稳定性
|
||
- 对以上样本的共同要求：不崩溃、不白屏、不无限加载；分页/翻页可用
|
||
|
||
## 8. 风险清单与降级策略
|
||
|
||
### 8.1 主要风险
|
||
|
||
- R1：DTCoreText 对 EPUB 内嵌 CSS / `<link>` CSS 支持不足，导致样式缺失
|
||
- R2：分页质量不足（断页不美观、图片分页异常）
|
||
- R3：`hasInteractiveContent()` 判定过宽，导致大量书被误判为 `.webInteractive`，覆盖率不足
|
||
|
||
### 8.2 降级/灰度（建议）
|
||
|
||
- D1：增加一个“渲染引擎开关”（仅 debug 或 demo 可配置），可在出现严重问题时快速回退到现有 `RDEPUBDTCoreTextRenderer`
|
||
- D2：对 `hasInteractiveContent()` 的判定提供可配置白名单/黑名单（例如按 manifest properties、按 tag 命中级别）
|
||
|
||
## 9. 下一步（交接到开发）
|
||
|
||
建议按 `Doc/ARCHITECTURE-CONTEXT.md` 中的架构决策逐步推进：
|
||
|
||
- 先基于 `Doc/WXRead/analysis/*` 提炼“我们要实现的 CSS 分层最小集合”
|
||
- 再在 `.textReflowable` renderer 里实现“分层 CSS 注入 + baseURL/资源解析兜底”
|
||
- 最后用 Demo 书籍做回归，按问题驱动补齐分页/样式细节
|
||
|
||
---
|
||
*Last updated: 2026-05-21 after discuss-feature-solution*
|