Epub阅读器0.0.1

2026-05-21 19:40:51 +08:00
commit daa36d8fe7
559 changed files with 106266 additions and 0 deletions
@@ -0,0 +1,264 @@
+# EPUBTextRendering 功能实现逻辑
+
+## 1. 范围与目标
+
+- 代码范围：`Sources/RDReaderView/EPUBTextRendering/`（6 个 Swift 文件）
+- 目标：说明文本渲染路径如何将 EPUB HTML 转换为 NSAttributedString、按字符范围分页、构建书籍模型，并支持全文搜索与 textReflowable 标注定位。
+- 主链路关键词：`RDEPUBParser HTML -> DTCoreText 渲染 -> 片段标记注入/提取 -> CoreText 分页 -> RDEPUBTextBook -> 页面查找/位置转换`。
+- 适用范围：仅用于 `textReflowable` 阅读配置文件（纯文本可重排 EPUB，如小说）。固定版式和交互式 EPUB 使用 WebView 渲染路径。
+
+## 2. 关键对象职责
+
+### 2.1 渲染协议 `RDEPUBTextRenderer`
+
+- 文件：`EPUBTextRendering/RDEPUBTextRenderer.swift`
+- 职责：
+  - 定义单方法协议：`renderChapter(html:baseURL:style:) throws -> RDEPUBRenderedChapterContent`
+  - 作为渲染后端的抽象点，当前仅 `RDEPUBDTCoreTextRenderer` 一个实现
+
+### 2.2 DTCoreText 渲染器 `RDEPUBDTCoreTextRenderer`
+
+- 文件：`EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift`
+- 职责：
+  - 实现 `RDEPUBTextRenderer` 协议
+  - 使用 `DTHTMLAttributedStringBuilder` 将 HTML 转为 NSAttributedString
+  - 渲染后处理：提取片段标记、统一字体/行间距/颜色
+  - DTCoreText 不可用时回退到纯文本渲染
+
+### 2.3 渲染支持工具 `RDEPUBTextRendererSupport`
+
+- 文件：`EPUBTextRendering/RDEPUBTextRendererSupport.swift`
+- 职责：
+  - 片段标记注入：扫描 HTML 中带 `id` 属性的元素，在其前注入 `${id=<fragmentID>}` 不可见标记
+  - 片段偏移提取：从 NSAttributedString 中提取标记位置并删除标记
+  - 字体标准化：保留 HTML 中的粗体/斜体 trait，统一使用配置的基础字体族和字号
+  - 段落样式创建：强制应用配置的行间距和段间距
+  - 兜底渲染：DTCoreText 不可用时从原始 HTML 字符串生成纯文本 NSAttributedString
+
+### 2.4 分页支持 `NSAttributedString.ss_pageRanges(size:)`
+
+- 文件：`EPUBTextRendering/RDEPUBTextPaginationSupport.swift`
+- 职责：
+  - 基于 CoreText framesetter 的分页
+  - 从位置 0 开始，反复创建 CTFrame 测量可见字符范围
+  - 返回 `[NSRange]`，每个 range 对应一页
+  - 安全保护：`visibleRange.length == 0` 时 break 防止死循环
+
+### 2.5 书籍构建器 `RDEPUBTextBookBuilder`
+
+- 文件：`EPUBTextRendering/RDEPUBTextBookBuilder.swift`
+- 职责：
+  - 遍历 publication 的 linear spine 项（仅 HTML/XHTML 类型）
+  - 对每项：HTML 标准化 → 渲染 → 跳过空白封面/标题页 → 分页 → 构建 `RDEPUBTextPage` 数组
+  - 汇总所有章节为 `RDEPUBTextBook`
+  - 后台队列执行，主线程回调结果
+
+### 2.6 全文搜索引擎 `RDEPUBTextSearchEngine`
+
+- 文件：`EPUBTextRendering/RDEPUBTextSearchEngine.swift`
+- 职责：
+  - 实现 `RDEPUBSearchEngine` 协议
+  - 在已渲染的 NSAttributedString 纯文本上执行线性搜索
+  - 返回 `RDEPUBSearchMatch` 数组（含 href、progression、预览文本、匹配位置）
+
+## 3. 主流程（代码级）
+
+### 3.1 完整渲染-分页流程
+
+1. 入口：`RDEPUBTextBookBuilder.build(parser:publication:pageSize:style:)`
+2. 遍历 `publication.spine` 中 `item.linear == true` 的项
+3. 过滤仅处理 mediaType 包含 "html" 或 "xhtml" 的项
+4. 读取 `parser.htmlString(forRelativePath: item.href)` 获取原始 HTML
+5. HTML 标准化：
+   - 移除中文分页标记：`<hr lang="zh-CN">分页符</hr>`
+   - `\r` 替换为 `\n`
+   - 连续 `\n` 合并为单个
+6. 检查是否跳过（空白且 href 包含 "cover" 或 "title"）
+7. 调用 `renderer.renderChapter(html:baseURL:style:)` 渲染
+
+### 3.2 DTCoreText 渲染管线
+
+1. 片段标记注入：`RDEPUBTextRendererSupport.injectFragmentMarkers(into: html)`
+   - 正则 `(<[^>]+\sid="([^"]+)"[^>]*>)` 匹配带 id 的元素
+   - 在匹配标签前插入 `${id=<fragmentID>}` 文本标记
+2. UTF-8 编码为 Data
+3. `DTHTMLAttributedStringBuilder(html:options:documentAttributes:)` 执行渲染
+4. DTCoreText 选项：
+   - `NSTextSizeMultiplierDocumentOption: 1.0`
+   - `DTDefaultFontFamily` / `DTDefaultFontName` / `DTDefaultFontSize`：来自 `style.font`
+   - `DTDefaultLineHeightMultiplier`：`(font.lineHeight + lineSpacing) / max(font.lineHeight, 1)`
+   - `DTUseiOS6Attributes: true`：生成 UIKit 兼容属性
+   - `NSBaseURLDocumentOption`：资源相对路径解析
+   - `DTDefaultTextColor`：可选文本颜色
+5. 后处理：
+   - 提取片段偏移并删除标记
+   - `normalizeReadingAttributes`：遍历每个属性 run，统一字体（保留粗/斜体 trait）、强制行间距/段间距、覆盖前景色
+
+### 3.3 CoreText 分页算法
+
+1. 从 `NSAttributedString` 创建 `CTFramesetter`
+2. 创建页面大小的 `CGPath`
+3. 从 location = 0 开始循环：
+   - 创建 CTFrame（range 从当前 location 到字符串末尾）
+   - `CTFrameGetVisibleStringRange(frame)` 获取可见字符数
+   - 追加 `NSRange(location: currentLocation, length: visibleRange.length)`
+   - location += visibleRange.length
+4. 循环终止条件：`location + visibleRange.length >= attributedString.length`
+5. 安全保护：`visibleRange.length == 0` 时 break
+
+### 3.4 页面与位置互转
+
+**Location → Page Number**（`RDEPUBTextBook.pageNumber(for:resolver:bookIdentifier:)`）：
+1. 有 fragment 时：用 `fragmentOffsets` 查找字符偏移，再定位到对应页面
+2. 无 fragment 时：用 `navigationProgression`（progression 和 lastProgression 的中点）计算字符偏移
+3. 遍历 pages 找到 `pageStartOffset <= offset < pageEndOffset` 的页面
+
+**Page Number → Location**（`RDEPUBTextBook.location(forPageNumber:bookIdentifier:)`）：
+1. 通过 page number 查找 `RDEPUBTextPage`
+2. 计算 `progression = pageStartOffset / totalCharacters`
+3. 计算 `lastProgression = pageEndOffset / totalCharacters`
+4. 构建 `RDEPUBLocation`（href + progression + lastProgression）
+
+### 3.5 标注定位与恢复
+
+textReflowable 路径不复用 WebView 的 DOM range，而使用章节字符偏移作为精确锚点：
+
+```json
+{
+  "kind": "text-offset",
+  "href": "chapter.xhtml",
+  "start": 1234,
+  "end": 1260
+}
+```
+
+1. `RDEPUBTextContentView` 保留当前 `RDEPUBTextPage`，从 `page.pageStartOffset` 将页内 `UITextView.selectedRange` 映射为章节全局 `start/end`
+2. 生成 `RDEPUBSelection` 后回传 `RDEPUBReaderController`，共享层继续负责创建、去重、持久化、列表和跳转
+3. 页面重绘时，`RDEPUBTextContentView` 仅消费 `kind == "text-offset"` 的 rangeInfo，计算当前页 `[pageStartOffset, pageEndOffset]` 与标注 `[start, end)` 的重叠
+4. `highlight` 样式叠加 `.backgroundColor`，`underline` 样式叠加 `.underlineStyle` 和 `.underlineColor`
+5. 字号、行高、主题变化导致重新分页后，标注仍以章节全局字符偏移恢复到新的页面切片
+
+## 4. 异常与边界处理
+
+- `RDEPUBTextRenderingError.htmlEncodingFailed`：HTML 字符串无法编码为 UTF-8 Data（极罕见）
+- DTCoreText builder 返回 nil：回退到 `fallbackAttributedString`，生成纯文本（含 HTML 标签原文），降级体验
+- 空白章节跳过：href 包含 "cover" 或 "title" 且渲染后文本为空的章节被跳过
+- 分页零结果兜底：`pageRanges` 为空但 content 非空时，整个章节作为一页
+- CoreText 零高度安全保护：`visibleRange.length == 0` 时 break 防止无限循环
+- Token 取消：`paginationToken`（UUID）防止异步完成后的过期结果污染 UI
+
+## 5. 数据结构与字段映射
+
+### 5.1 渲染配置
+
+```swift
+RDEPUBTextRenderStyle
+  ├── font: UIFont              // 基础字体
+  ├── lineSpacing: CGFloat      // 额外行间距
+  ├── textColor: UIColor?       // 文本颜色（nil 时保持 HTML 原始颜色）
+  └── backgroundColor: UIColor? // 背景色
+```
+
+### 5.2 渲染输出
+
+```swift
+RDEPUBRenderedChapterContent
+  ├── attributedString: NSAttributedString  // 渲染后的富文本
+  └── fragmentOffsets: [String: Int]        // fragment ID -> 字符偏移映射
+```
+
+### 5.3 页面模型
+
+```swift
+RDEPUBTextPage
+  ├── absolutePageIndex: Int       // 全局页码
+  ├── chapterIndex: Int            // 章节索引
+  ├── spineIndex: Int              // spine 索引
+  ├── href: String                 // 章节 href
+  ├── chapterTitle: String?        // 章节标题
+  ├── pageIndexInChapter: Int      // 章节内页码
+  ├── totalPagesInChapter: Int     // 章节总页数
+  ├── content: NSAttributedString  // 本页的富文本切片
+  ├── contentRange: NSRange        // 在整章富文本中的 range
+  ├── pageStartOffset: Int         // 起始字符偏移
+  └── pageEndOffset: Int           // 结束字符偏移
+```
+
+### 5.4 章节模型
+
+```swift
+RDEPUBTextChapter
+  ├── chapterIndex: Int
+  ├── spineIndex: Int
+  ├── href: String
+  ├── title: String?
+  ├── attributedContent: NSAttributedString  // 整章渲染后的富文本
+  ├── fragmentOffsets: [String: Int]
+  └── pages: [RDEPUBTextPage]
+```
+
+### 5.5 书籍模型
+
+```swift
+RDEPUBTextBook
+  ├── chapters: [RDEPUBTextChapter]
+  ├── pages: [RDEPUBTextPage]          // 扁平化页面列表
+  ├── page(at:) -> RDEPUBTextPage?     // 1-based 页码查找
+  ├── pageNumber(for:resolver:bookIdentifier:) -> Int?  // Location -> 页码
+  └── location(forPageNumber:bookIdentifier:) -> RDEPUBLocation?  // 页码 -> Location
+```
+
+## 6. 与 EPUBCore 层的集成
+
+### 消费的数据
+
+| 来源 | 数据 | 用途 |
+|------|------|------|
+| `RDEPUBParser` | `htmlString(forRelativePath:)` | 读取章节 HTML 内容 |
+| `RDEPUBParser` | `fileURL(forRelativePath:)` | 计算 DTCoreText 的 baseURL |
+| `RDEPUBPublication` | `spine` | 遍历 linear HTML/XHTML 项 |
+| `RDEPUBPublication` | `tableOfContents` | 匹配章节标题 |
+| `RDEPUBSpineItem` | `href`, `mediaType`, `linear`, `title` | 过滤和标识章节 |
+| `RDEPUBResourceResolver` | `normalizedLocation` / `normalizedHref` | 位置查找时标准化 href |
+| `RDEPUBLocation` | `href`, `fragment`, `navigationProgression` | 页面定位 |
+| `RDEPUBSearchEngine` | 协议接口 | `RDEPUBTextSearchEngine` 实现此协议 |
+| `RDEPUBHighlight` | `style`, `rangeInfo`, `color`, `note` | text-offset 标注恢复与页内绘制 |
+
+## 7. 配置参数
+
+- **字号**：`RDEPUBReaderConfiguration.fontSize`，默认 15pt
+- **行高倍数**：`lineHeightMultiple`，默认 1.6（行间距 = font.lineHeight * 0.6，最低 4pt）
+- **内容边距**：`reflowableContentInsets`，默认 (40, 16, 40, 16)，影响有效页面尺寸
+- **主题色**：通过 `RDEPUBReaderTheme` 的 `contentTextColor` / `contentBackgroundColor` 传入
+- **渲染引擎**：`RDEPUBTextRenderingEngine`，当前仅 `.dtCoreText`
+
+## 8. 性能特征
+
+- **全文渲染**：每章一次性渲染为完整的 NSMutableAttributedString，无分块/懒加载
+- **内存**：`RDEPUBTextBook` 同时持有 chapters（含完整 attributedContent）和 pages（含子串切片），存在一定程度的内存重复
+- **后台执行**：`build` 方法在 `DispatchQueue.global(qos: .userInitiated)` 执行，不阻塞主线程
+- **搜索性能**：线性扫描每章的 `attributedContent.string`，无索引，搜索时间与总文本量线性相关
+- **无分页缓存**：字号/行高变化时全书重新渲染和分页，无增量更新
+
+## 9. 联调与排查建议
+
+- 排查 1：渲染后文本为空
+  - 检查 `parser.htmlString(forRelativePath:)` 是否返回非 nil
+  - 检查 spine 项的 mediaType 是否包含 "html" 或 "xhtml"
+  - 空白封面/标题页会被 `shouldSkipChapter` 跳过
+- 排查 2：分页页数不正确
+  - 检查 `pageSize` 计算是否正确（viewport - contentInsets）
+  - 检查 DTCoreText 行高倍数是否正确应用
+  - 检查 CoreText 分页是否有 `visibleRange.length == 0` 的异常情况
+- 排查 3：字体/颜色不正确
+  - 检查 `RDEPUBTextRenderStyle` 配置
+  - 检查 `normalizeReadingAttributes` 是否正确保留粗/斜体 trait
+  - 检查 `foregroundColor` 覆盖逻辑
+- 排查 4：Fragment 定位失败
+  - 检查 `injectFragmentMarkers` 是否正确注入标记
+  - 检查 `extractFragmentOffsets` 是否正确提取偏移
+  - 确认标记在 DTCoreText 渲染后仍存在于 attributed string 中
+- 排查 5：搜索结果不准确
+  - 搜索基于已渲染的纯文本（去 HTML 标签），非原始 HTML
+  - 确认 `attributedContent.string` 包含预期的文本内容
+  - 搜索为大小写不敏感的线性扫描