4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d15187b730
ReadViewSDK/Doc/FeatureSolution/ReflowableEPUB_WXReadRenderer_Design.md

15 KiB
Raw Blame History

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