4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步 Doc 文档与当前代码状态

Browse Source 
- 更新模块文件数（EPUBCore 31+2, EPUBTextRendering 13, ReaderView 5, EPUBUI 19）
- 更新 Swift 版本（5.10）、iOS 版本（15.0）、行数等基本信息
- 补充新增文件文档（TextAnchor, RenderRequest, WebViewDebug, AssetRepository,
  TextIndexTable, TextPerformanceSampler, ChapterData, PageInteractionController 等）
- 更新 RDEPUBLocation 模型（新增 rangeAnchor 字段）
- 更新 RDEPUBReaderConfiguration（13 项配置）、Delegate 签名、Persistence（8 方法）
- 修正 RDURLReaderController 归属（ReaderView → EPUBUI）
- 移除过时的 LegacyRDReaderController 引用
- 标记 SS→RD 命名迁移为已完成
This commit is contained in:
shen
2026-05-25 20:31:10 +08:00
parent 54798ba578
commit c0aac56083
8 changed files with 208 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Doc/EPUBUI_功能实现逻辑.md
+44 -31
View File
@@ -2,7 +2,7 @@
## 1. 范围与目标
- 代码范围：`Sources/RDReaderView/EPUBUI/`（16 个 Swift 文件）
- 代码范围：`Sources/RDReaderView/EPUBUI/`（19 个 Swift 文件）
- 目标：说明 EPUBUI 如何作为开箱即用的阅读器 UI 层，协调 EPUBCore 解析、EPUBTextRendering 文本渲染、RDReaderView 分页容器，提供完整的阅读体验（工具栏、目录、高亮批注、设置面板、阅读位置持久化、搜索）。
- 主链路关键词：`RDEPUBReaderController.init -> 解析 EPUB -> 分页 -> 渲染 -> 用户交互（翻页/工具栏/设置/高亮/搜索）-> 持久化`。
@@ -10,7 +10,7 @@
### 2.1 主控制器 `RDEPUBReaderController`
- 文件：`EPUBUI/RDEPUBReaderController.swift`（~1255 行）
- 文件：`EPUBUI/RDEPUBReaderController.swift`（~1995 行）
- 入口方法：
- `init(epubURL:configuration:persistence:)` — 标准 EPUB 阅读入口
- `init(textBook:bookIdentifier:title:textFileURL:configuration:)` — 纯文本书籍阅读入口（由 `RDPlainTextBookBuilder` 构建 `RDEPUBTextBook` 后传入）
@@ -29,7 +29,7 @@
- `fontSize`（默认 15）、`lineHeightMultiple`（默认 1.6）
- `displayType`（默认 .pageCurl）、`landscapeDualPageEnabled`（默认 true）
- `showsTableOfContents`（默认 true）、`allowsHighlights`（默认 true）、`showsSettingsPanel`（默认 true）
- `reflowableContentInsets`（默认 40/16/40/16）、`fixedContentInset`（默认 .zero）
- `reflowableContentInsets`（默认 top:40 left:16 bottom:40 right:16）、`fixedContentInset`（默认 .zero）
- `theme`（默认 .light）
- `fixedLayoutFit`（默认 .page）、`fixedLayoutSpreadMode`（默认 .automatic）
- `textRenderingEngine`（默认 .dtCoreText）
@@ -41,45 +41,47 @@
- 文件：`EPUBUI/RDEPUBReaderDelegate.swift`
- 12 个可选方法（全部有默认空实现）：
- `didOpen`：成功打开出版物
- `didUpdateLocation`：翻页或滚动时位置更新
- `didReachEnd`：到达最后一页
- `didChangeSelection`：文本选择变化或清除
- `didUpdateHighlights`：高亮增删改
- `didUpdateBookmarks`：书签增删改
- `didUpdateSearchResult`：搜索状态变化
- `didChangeCurrentSearchMatch`：当前搜索匹配项变化
- `didUpdateCurrentTableOfContentsItem`：翻页时匹配的目录项
- `didActivateExternalLink`：外部链接点击
- `didFailWithError`：解析或分页错误
- `configureTopToolView`：自定义顶部工具栏
- `epubReader(_:didOpen:)`：成功打开出版物
- `epubReader(_:didUpdateLocation:)`：翻页或滚动时位置更新
- `epubReaderDidReachEnd(_:)`：到达最后一页
- `epubReader(_:didChangeSelection:)`：文本选择变化或清除
- `epubReader(_:didUpdateHighlights:)`：高亮增删改
- `epubReader(_:didUpdateBookmarks:)`：书签增删改
- `epubReader(_:didUpdateSearchResult:)`：搜索状态变化
- `epubReader(_:didChangeCurrentSearchMatch:)`：当前搜索匹配项变化
- `epubReader(_:didUpdateCurrentTableOfContentsItem:)`：翻页时匹配的目录项
- `epubReader(_:didActivateExternalLink:)`：外部链接点击
- `epubReader(_:didFailWithError:)`：解析或分页错误
- `epubReader(_:configureTopToolView:)`：自定义顶部工具栏
### 2.4 持久化 `RDEPUBReaderPersistence`
- 文件：`EPUBUI/RDEPUBReaderPersistence.swift`
- 协议定义 6 个方法：loadLocation / saveLocation / loadHighlights / saveHighlights / loadReaderSettings / saveReaderSettings
- 协议定义 8 个方法：loadLocation / saveLocation / loadHighlights / saveHighlights / loadBookmarks / saveBookmarks / loadReaderSettings / saveReaderSettings
- 默认实现 `RDEPUBUserDefaultsPersistence`：
- 位置：`ssreader.epub.location.<bookIdentifier>`（JSON 编码）
- 高亮：`ssreader.epub.highlights.<bookIdentifier>`（JSON 编码）
- 书签：`ssreader.epub.bookmarks.<bookIdentifier>`（JSON 编码）
- 设置：`ssreader.epub.settings`（全局，非按书）
### 2.5 主题 `RDEPUBReaderTheme`
- 文件：`EPUBUI/RDEPUBReaderTheme.swift`
- 文件：`EPUBUI/RDEPUBReaderTheme.swift`（~125 行）
- 6 个颜色属性：contentBackgroundColor、contentTextColor、toolBackgroundColor、toolControlTextColor、toolControlBorderUnselectColor、toolLineColor
- 6 个内置预设：`.light`、`.dark`、`.yellow`、`.green`、`.pink`、`.blue`
- `RDEPUBReaderThemePreset` 枚举将预设映射为可序列化值，用于持久化
- 计算属性 `themeBackgroundColorCSS` / `themeTextColorCSS` 用于 Web 渲染路径
### 2.6 设置面板 `RDEPUBReaderSettingsViewController`
- 文件：`EPUBUI/RDEPUBReaderSettingsViewController.swift`
- 文件：`EPUBUI/RDEPUBReaderSettingsViewController.swift`（~311 行）
- 5 个控制项：
- 亮度滑块（0-1）
- 字号 A-/A+（范围 12-36，步长 1）
- 行高分段（紧凑 1.3 / 标准 1.6 / 宽松 1.9）
- 显示模式分段（仿真 / 横滑 / 竖滑 / 覆盖）
- 主题选择（6 个圆形色块按钮）
- 所有变更通过闭包实时回调
- 所有变更通过闭包实时回调：onBrightnessChange / onFontSizeChange / onLineHeightChange / onDisplayTypeChange / onThemeChange
### 2.7 内容视图
@@ -88,10 +90,17 @@
### 2.8 其他 UI 组件
- `RDEPUBReaderTopToolView`：顶部导航栏（返回按钮 + 标题）
- `RDEPUBReaderBottomToolView`：底部工具栏（目录 / 批注 / 标注 / 设置 4 个按钮）
- `RDEPUBReaderToolView`（`EPUBUI/RDEPUBReaderToolView.swift`）：工具栏基类，提供分隔线和主题适配的通用逻辑
- `RDEPUBReaderTopToolView`：顶部导航栏（返回按钮 + 书签切换 + 标题）
- `RDEPUBReaderBottomToolView`：底部工具栏（目录 / 书签 / 标注 / 设置 4 个按钮）
- `RDEPUBReaderChapterListController`：目录列表（modal UITableViewController，当前项高亮 systemBlue）
- `RDEPUBReaderHighlightsViewController`：标注管理（全部 / 批注 / 划线过滤，列表 + 编辑备注 + 删除 + 跳转，空态按过滤条件提示）
- `RDEPUBReaderSettings`（`EPUBUI/RDEPUBReaderSettings.swift`）：可持久化用户设置模型（brightness / fontSize / lineHeightMultiple / displayMode / themePreset），含 `RDEPUBReaderDisplayMode` 和 `RDEPUBReaderThemePreset` 枚举
- `RDEPUBReaderTableOfContentsItem`（`EPUBUI/RDEPUBReaderTableOfContentsItem.swift`）：展平后的目录条目（title / href / depth / pageNumber）
- `RDEPUBPageInteractionController`（`EPUBUI/RDEPUBPageInteractionController.swift`）：CoreText 页面级交互控制器，处理文本选区和高亮装饰
- `RDEPUBSelectionOverlayView`（`EPUBUI/RDEPUBSelectionOverlayView.swift`）：选区覆盖视图，显示选中文本的高亮装饰
- `RDEPUBPageLayoutSnapshot`（`EPUBUI/RDEPUBPageLayoutSnapshot.swift`）：页面几何模型，存储 CoreText 渲染的页面布局信息
- `RDURLReaderController`（`EPUBUI/RDURLReaderController.swift`，~221 行）：最简 URL 入口，传入 URL 即可打开书籍（.epub → RDEPUBReaderController，其他 → RDPlainTextBookBuilder 构建后传入），分页失败时回退到纯 UITextView 展示
## 3. 主流程（代码级）
@@ -229,22 +238,26 @@
| 书签列表 | `ssreader.epub.bookmarks.<bookIdentifier>` | JSON → `[RDEPUBBookmark]` |
| 阅读设置 | `ssreader.epub.settings` | JSON → `RDEPUBReaderSettings` |
### 5.2 Book Identifier
- 优先使用 `parser.metadata.identifier`
- 回退使用 `epubURL.lastPathComponent`
### 5.3 设置快照
### 5.2 设置模型
```swift
RDEPUBReaderSettings (Codable)
├── brightness: CGFloat
├── fontSize: CGFloat
├── lineHeightMultiple: CGFloat
├── displayMode: RDEPUBReaderDisplayMode
├── brightness: CGFloat?
├── fontSize: CGFloat?
├── lineHeightMultiple: CGFloat?
├── displayMode: RDEPUBReaderDisplayMode?
└── themePreset: RDEPUBReaderThemePreset?
```
`RDEPUBReaderDisplayMode`：可序列化的翻页模式枚举（pageCurl / horizontalScroll / verticalScroll / horizontalCoverScroll），与 `RDReaderView.DisplayType` 相互转换。
`RDEPUBReaderThemePreset`：可序列化的主题预设枚举（light / yellow / green / pink / blue / dark），与 `RDEPUBReaderTheme` 相互转换。
### 5.3 Book Identifier
- 优先使用 `parser.metadata.identifier`
- 回退使用 `epubURL.lastPathComponent`
### 5.4 目录扁平化项
```swift