feat: EPUB阅读器搜索、注释、CFI模块及大书远距跳转优化

- 实现EPUB阅读器搜索功能及选中注释功能 - 优化CFI模块，修复代码审查发现的11个问题 - 实现大书远距目录跳转与后台补全优化方案 - 优化设置面板与章节运行时联动 - 重构及大量改进优化
2026-06-22 20:26:34 +08:00
parent f50495ad91
commit c65c190b71
178 changed files with 11380 additions and 6728 deletions
@@ -0,0 +1,483 @@
+# 公开 API 参考手册
+
+> 最后更新：2026-06-18
+
+本文档列出 ReadViewSDK 所有公开 API 的完整签名、参数说明和使用方法。
+
+---
+
+## 1. RDEPUBReaderController — 入口控制器
+
+**文件**：`Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` 及扩展
+
+### 1.1 初始化
+
+```swift
+// EPUB 文件初始化
+init(
+    epubURL: URL,                           // EPUB 文件路径
+    configuration: RDEPUBReaderConfiguration = .default,  // 阅读配置
+    persistence: RDEPUBReaderPersistence? = nil,          // 持久化实现
+    dependencies: RDEPUBReaderDependencies? = nil         // 依赖注入
+)
+
+// 预构建 TextBook 初始化（如 .txt 文件）
+init(
+    textBook: RDEPUBTextBook,               // 预构建的文本书籍
+    bookIdentifier: String,                 // 书籍唯一标识
+    title: String,                          // 书籍标题
+    textFileURL: URL? = nil,                // 原始文件路径
+    configuration: RDEPUBReaderConfiguration = .default,
+    persistence: RDEPUBReaderPersistence? = nil,
+    dependencies: RDEPUBReaderDependencies? = nil
+)
+```
+
+### 1.2 公开属性
+
+| 属性 | 类型 | 读写 | 说明 |
+|------|------|------|------|
+| `delegate` | `RDEPUBReaderDelegate?` | 读写 | 委托代理 |
+| `configuration` | `RDEPUBReaderConfiguration` | 读写 | 阅读配置，设置后触发重新分页 |
+| `currentLocation` | `RDEPUBLocation?` | 只读 | 当前阅读位置 |
+| `currentPageNumber` | `Int?` | 只读 | 当前页码（1-based） |
+| `currentSelection` | `RDEPUBSelection?` | 只读 | 当前文本选区 |
+| `highlights` | `[RDEPUBHighlight]` | 只读 | 所有高亮标注 |
+| `bookmarks` | `[RDEPUBBookmark]` | 只读 | 所有书签 |
+| `annotations` | `[RDEPUBAnnotation]` | 只读 | 合并排序后的统一标注列表 |
+| `tableOfContents` | `[EPUBTableOfContentsItem]` | 只读 | 目录树（嵌套结构） |
+| `flattenedTableOfContents` | `[RDEPUBReaderTableOfContentsItem]` | 只读 | 扁平化目录列表 |
+| `currentTableOfContentsItem` | `RDEPUBReaderTableOfContentsItem?` | 只读 | 当前所在目录项 |
+
+### 1.3 导航方法
+
+```swift
+/// 重新加载书籍
+func reloadBook()
+
+/// 跳转到指定位置
+func go(to location: RDEPUBLocation)
+
+/// 跳转到指定页码（1-based）
+/// - Returns: 是否跳转成功
+@discardableResult
+func go(toPageNumber pageNumber: Int, animated: Bool = false) -> Bool
+
+/// 跳转到目录项（EPUBTableOfContentsItem）
+@discardableResult
+func go(toTableOfContentsItem item: EPUBTableOfContentsItem, animated: Bool = true) -> Bool
+
+/// 跳转到目录项（RDEPUBReaderTableOfContentsItem）
+@discardableResult
+func go(toTableOfContentsItem item: RDEPUBReaderTableOfContentsItem, animated: Bool = true) -> Bool
+
+/// 跳转到目录 href（支持 fragment，如 "chapter1.xhtml#section2"）
+@discardableResult
+func go(toTableOfContentsHref href: String, animated: Bool = true) -> Bool
+
+/// 跳转到指定高亮位置
+@discardableResult
+func go(toHighlightID id: String, animated: Bool = true) -> Bool
+
+/// 跳转到指定书签位置
+@discardableResult
+func go(toBookmarkID id: String, animated: Bool = true) -> Bool
+```
+
+### 1.4 高亮方法
+
+```swift
+/// 添加高亮（使用当前选区或指定选区）
+/// - Parameters:
+///   - selection: 选区信息，nil 时使用 currentSelection
+///   - color: 高亮颜色（十六进制），默认 "#F8E16C"
+///   - note: 可选备注
+/// - Returns: 创建的高亮对象，失败返回 nil
+@discardableResult
+func addHighlight(
+    from selection: RDEPUBSelection? = nil,
+    color: String = "#F8E16C",
+    note: String? = nil
+) -> RDEPUBHighlight?
+
+/// 添加标注（支持高亮和下划线样式）
+@discardableResult
+func addAnnotation(
+    from selection: RDEPUBSelection? = nil,
+    style: RDEPUBHighlightStyle,
+    color: String = "#F8E16C",
+    note: String? = nil
+) -> RDEPUBHighlight?
+
+/// 更新或插入高亮
+@discardableResult
+func upsertHighlight(_ highlight: RDEPUBHighlight) -> RDEPUBHighlight?
+
+/// 删除高亮
+@discardableResult
+func removeHighlight(id: String) -> RDEPUBHighlight?
+
+/// 更新高亮备注
+@discardableResult
+func updateHighlightNote(id: String, note: String?) -> RDEPUBHighlight?
+
+/// 删除所有高亮
+func removeAllHighlights()
+
+/// 根据 ID 查找高亮
+func highlight(withID id: String) -> RDEPUBHighlight?
+```
+
+### 1.5 书签方法
+
+```swift
+/// 添加书签（使用当前位置）
+@discardableResult
+func addBookmark(note: String? = nil) -> RDEPUBBookmark?
+
+/// 切换书签状态（已存在则删除，不存在则添加）
+@discardableResult
+func toggleBookmark(note: String? = nil) -> RDEPUBBookmark?
+
+/// 删除书签
+@discardableResult
+func removeBookmark(id: String) -> RDEPUBBookmark?
+
+/// 根据 ID 查找书签
+func bookmark(withID id: String) -> RDEPUBBookmark?
+```
+
+### 1.6 搜索方法
+
+```swift
+/// 开始搜索
+func search(keyword: String)
+
+/// 跳转到下一个匹配
+/// - Returns: 是否有下一个匹配
+@discardableResult
+func searchNext() -> Bool
+
+/// 跳转到上一个匹配
+@discardableResult
+func searchPrevious() -> Bool
+
+/// 清除搜索
+func clearSearch()
+```
+
+### 1.7 其他方法
+
+```swift
+/// 清除当前文本选区
+func clearSelection()
+
+/// 获取当前页面的语义摘要（调试用）
+func nativeTextSemanticSummary() -> String?
+```
+
+---
+
+## 2. RDEPUBReaderDelegate — 委托协议
+
+**文件**：`Sources/RDReaderView/EPUBUI/RDEPUBReaderDelegate.swift`
+
+所有方法均有默认空实现，可按需实现。
+
+```swift
+public protocol RDEPUBReaderDelegate: AnyObject {
+
+    /// 书籍打开完成
+    func epubReader(_ reader: UIViewController, didOpen publication: RDEPUBPublication)
+
+    /// 阅读位置变化
+    func epubReader(_ reader: UIViewController, didUpdateLocation location: RDEPUBLocation)
+
+    /// 到达书籍末尾
+    func epubReaderDidReachEnd(_ reader: UIViewController)
+
+    /// 文本选区变化（nil 表示取消选中）
+    func epubReader(_ reader: UIViewController, didChangeSelection selection: RDEPUBSelection?)
+
+    /// 高亮列表变化
+    func epubReader(_ reader: UIViewController, didUpdateHighlights highlights: [RDEPUBHighlight])
+
+    /// 书签列表变化
+    func epubReader(_ reader: UIViewController, didUpdateBookmarks bookmarks: [RDEPUBBookmark])
+
+    /// 搜索结果更新
+    func epubReader(_ reader: UIViewController, didUpdateSearchResult result: RDEPUBSearchResult?)
+
+    /// 当前搜索匹配项变化
+    func epubReader(_ reader: UIViewController, didChangeCurrentSearchMatch match: RDEPUBSearchMatch?)
+
+    /// 当前目录项变化
+    func epubReader(_ reader: UIViewController, didUpdateCurrentTableOfContentsItem item: RDEPUBReaderTableOfContentsItem?)
+
+    /// 外部链接被点击
+    func epubReader(_ reader: UIViewController, didActivateExternalLink url: URL)
+
+    /// 是否允许打开外部链接（返回 false 拦截）
+    func epubReader(_ reader: UIViewController, shouldOpenExternalURL url: URL) -> Bool
+
+    /// 错误回调
+    func epubReader(_ reader: UIViewController, didFailWithError error: Error)
+
+    /// 配置顶部工具栏（自定义按钮等）
+    func epubReader(_ reader: UIViewController, configureTopToolView topToolView: RDEPUBReaderTopToolView)
+}
+```
+
+---
+
+## 3. RDEPUBReaderPersistence — 持久化协议
+
+**文件**：`Sources/RDReaderView/EPUBUI/RDEPUBReaderPersistence.swift`
+
+```swift
+public protocol RDEPUBReaderPersistence: AnyObject {
+
+    func loadLocation(for bookIdentifier: String) -> RDEPUBLocation?
+    func saveLocation(_ location: RDEPUBLocation, for bookIdentifier: String)
+
+    func loadBookmarks(for bookIdentifier: String) -> [RDEPUBBookmark]
+    func saveBookmarks(_ bookmarks: [RDEPUBBookmark], for bookIdentifier: String)
+
+    func loadHighlights(for bookIdentifier: String) -> [RDEPUBHighlight]
+    func saveHighlights(_ highlights: [RDEPUBHighlight], for bookIdentifier: String)
+
+    func loadReaderSettings() -> RDEPUBReaderSettings?
+    func saveReaderSettings(_ settings: RDEPUBReaderSettings)
+}
+```
+
+默认实现 `RDEPUBUserDefaultsPersistence` 使用 UserDefaults 存储：
+
+| 数据 | Key 格式 |
+|------|----------|
+| 阅读位置 | `ssreader.epub.location.{bookID}` |
+| 书签 | `ssreader.epub.bookmarks.{bookID}` |
+| 高亮 | `ssreader.epub.highlights.{bookID}` |
+| 全局设置 | `ssreader.epub.settings` |
+
+---
+
+## 4. RDEPUBReaderConfiguration — 配置模型
+
+**文件**：`Sources/RDReaderView/EPUBUI/Settings/RDEPUBReaderConfiguration.swift`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fontSize` | `CGFloat` | `15` | 字体大小（pt） |
+| `lineHeightMultiple` | `CGFloat` | `1.6` | 行距倍数 |
+| `fontChoice` | `RDEPUBReaderFontChoice` | `.system` | 字体选择（system/serif/rounded/monospaced） |
+| `numberOfColumns` | `Int` | `1` | 每页列数（1 或 2） |
+| `columnGap` | `CGFloat` | `20` | 列间距 |
+| `displayType` | `RDReaderView.DisplayType` | `.pageCurl` | 翻页模式 |
+| `landscapeDualPageEnabled` | `Bool` | `true` | 横屏双页 |
+| `showsTableOfContents` | `Bool` | `true` | 显示目录 |
+| `allowsHighlights` | `Bool` | `true` | 允许高亮 |
+| `showsSettingsPanel` | `Bool` | `true` | 显示设置面板 |
+| `reflowableContentInsets` | `UIEdgeInsets` | `(40,16,40,16)` | 重排内容内边距 |
+| `fixedContentInset` | `UIEdgeInsets` | `.zero` | 固定布局内边距 |
+| `theme` | `RDEPUBReaderTheme` | `.light` | 阅读主题 |
+| `darkImageAdjustmentEnabled` | `Bool` | `true` | 暗色模式图片调整 |
+| `darkImageBlendRatio` | `CGFloat` | `0.15` | 暗色图片混合比例（0-0.35） |
+| `fixedLayoutFit` | `RDEPUBFixedLayoutFit` | `.page` | 固定布局适配方式 |
+| `fixedLayoutSpreadMode` | `RDEPUBFixedLayoutSpreadMode` | `.automatic` | 固定布局跨页模式 |
+| `textRenderingEngine` | `RDEPUBTextRenderingEngine` | `.dtCoreText` | 文本渲染引擎 |
+| `onDemandChapterWindowSize` | `Int` | `3` | 按需加载窗口大小（奇数，3-15） |
+| `metadataParsingConcurrency` | `Int` | CPU 核心数 | 后台解析并发数 |
+| `jumpSessionPolicy` | `RDEPUBJumpSessionPolicy` | `.default` | 远距跳转策略 |
+| `allowedExternalURLSchemes` | `Set<String>` | `["https"]` | 允许的外部 URL 协议 |
+| `requiresExternalLinkConfirmation` | `Bool` | `true` | 外部链接需确认 |
+| `allowsInspectableWebViews` | `Bool` | `false` | WebView 可调试 |
+| `enablesVerboseWebViewLogging` | `Bool` | `false` | WebView 详细日志 |
+
+**计算属性**：
+- `chapterWindowRadius: Int` — 内存缓存窗口半径（`onDemandChapterWindowSize / 2`）
+
+---
+
+## 5. 翻页容器协议
+
+**文件**：`Sources/RDReaderView/ReaderView/RDReaderViewProtocols.swift`
+
+### 5.1 RDReaderPageProvider（推荐）
+
+```swift
+@objc public protocol RDReaderPageProvider: NSObjectProtocol {
+
+    /// 总页数
+    func numberOfPages(in readerView: RDReaderView) -> Int
+
+    /// 返回指定页的视图
+    /// - Parameters:
+    ///   - index: 页码索引（0-based）
+    ///   - reusableView: 可复用的旧视图（可能为 nil）
+    func readerView(_ readerView: RDReaderView, viewForPageAt index: Int, reusableView: UIView?) -> UIView
+
+    /// 页面标识符（用于缓存去重）
+    @objc optional func pageIdentifier(in readerView: RDReaderView, index: Int) -> String?
+
+    /// 顶部工具栏视图
+    @objc optional func readerViewTopChrome(_ readerView: RDReaderView) -> UIView?
+
+    /// 底部工具栏视图
+    @objc optional func readerViewBottomChrome(_ readerView: RDReaderView) -> UIView?
+}
+```
+
+### 5.2 RDReaderDelegate
+
+```swift
+@objc public protocol RDReaderDelegate: NSObjectProtocol {
+
+    /// 页面变化回调
+    func pageNum(readerView: RDReaderView, pageNum: Int)
+
+    /// 屏幕方向即将变化
+    @objc optional func readerViewOrientationWillChange(readerView: RDReaderView, isLandscape: Bool)
+}
+```
+
+### 5.3 RDReaderPageNavigating
+
+```swift
+public protocol RDReaderPageNavigating: AnyObject {
+
+    /// 当前页码
+    var currentPage: Int { get }
+
+    /// 重新加载所有页面
+    func reloadPages()
+
+    /// 跳转到指定页
+    func transition(to page: Int, animated: Bool)
+}
+```
+
+### 5.4 RDReaderDataSource（遗留）
+
+```swift
+@objc public protocol RDReaderDataSource: NSObjectProtocol {
+    func pageCountOfReaderView(readerView: RDReaderView) -> Int
+    func pageContentView(readerView: RDReaderView, pageNum: Int, containerView: UIView?) -> UIView
+    func pageIdentifier(readerView: RDReaderView, pageNum: Int) -> String?
+    @objc optional func topToolView(readerView: RDReaderView) -> UIView?
+    @objc optional func bottomToolView(readerView: RDReaderView) -> UIView?
+}
+```
+
+通过 `RDReaderLegacyDataSourceAdapter` 自动适配到 `RDReaderPageProvider`。
+
+---
+
+## 6. 数据模型速查
+
+### 6.1 RDEPUBLocation
+
+```swift
+public struct RDEPUBLocation: Codable, Equatable {
+    public var bookIdentifier: String?  // 书籍标识
+    public var href: String             // 章节文件路径
+    public var progression: Double      // 章节内进度（0.0-1.0）
+    public var lastProgression: Double? // 上次进度（用于恢复方向）
+    public var fragment: String?        // 片段 ID（如 #section1）
+    public var rangeAnchor: RDEPUBTextRangeAnchor?  // 文本范围锚点
+}
+```
+
+### 6.2 RDEPUBBookmark
+
+```swift
+public struct RDEPUBBookmark: Codable, Equatable, Identifiable {
+    public let id: String               // 唯一标识
+    public let bookIdentifier: String?
+    public let location: RDEPUBLocation
+    public let chapterTitle: String?
+    public let note: String?
+    public let createdAt: Date
+}
+```
+
+### 6.3 RDEPUBHighlight
+
+```swift
+public struct RDEPUBHighlight: Codable, Equatable, Identifiable {
+    public let id: String
+    public let bookIdentifier: String?
+    public let location: RDEPUBLocation
+    public let text: String             // 高亮文本内容
+    public let style: RDEPUBHighlightStyle  // .highlight / .underline
+    public let color: String            // 十六进制颜色
+    public let note: String?
+    public let rangeInfo: String?       // CoreText 选区范围信息
+    public let createdAt: Date
+    public var uiColor: UIColor { ... } // 计算属性
+}
+```
+
+### 6.4 RDEPUBAnnotation
+
+```swift
+public struct RDEPUBAnnotation: Codable, Equatable, Identifiable {
+    public let id: String
+    public let bookIdentifier: String?
+    public let kind: RDEPUBAnnotationKind  // .bookmark / .highlight / .underline
+    public let location: RDEPUBLocation
+    public let text: String?
+    public let rangeInfo: String?
+    public let chapterTitle: String?
+    public let createdAt: Date
+    public var bookmark: RDEPUBBookmark? { ... }   // kind == .bookmark 时有值
+    public var highlight: RDEPUBHighlight? { ... } // kind == .highlight/.underline 时有值
+}
+```
+
+### 6.5 RDEPUBSelection
+
+```swift
+public struct RDEPUBSelection: Equatable {
+    public let bookIdentifier: String?
+    public let location: RDEPUBLocation
+    public let text: String             // 选中文本
+    public let rangeInfo: String?       // CoreText 选区范围
+    public let createdAt: Date
+}
+```
+
+### 6.6 EPUBPage / EPUBChapterInfo
+
+```swift
+public struct EPUBPage: Equatable {
+    public let spineIndex: Int
+    public let chapterIndex: Int
+    public let pageIndexInChapter: Int
+    public let totalPagesInChapter: Int
+    public let chapterTitle: String
+    public let fixedSpread: EPUBFixedSpread?
+}
+
+public struct EPUBChapterInfo: Equatable {
+    public let spineIndex: Int
+    public let title: String
+    public let pageCount: Int
+}
+```
+
+### 6.7 RDEPUBSearchResult / RDEPUBSearchMatch
+
+```swift
+public struct RDEPUBSearchResult: Equatable {
+    public let keyword: String
+    public let matches: [RDEPUBSearchMatch]
+}
+
+public struct RDEPUBSearchMatch: Equatable {
+    public let spineIndex: Int
+    public let progression: Double
+    public let previewText: String
+    public let rangeAnchor: RDEPUBTextRangeAnchor?
+}
+```