refactor: 添加中文注释 + 优化模块结构
- 给全部 78 个 Swift 源文件添加详细的中文注释（文件级、类级、方法级） - 删除 LegacyRDReaderController/ 死代码目录（16 文件 4592 行） - 根目录翻页容器文件移入 ReaderView/ 目录 - Resources/ 移入 EPUBCore/Resources/（与使用者归属一致） - RDEPUBTextIndexTable.swift 移入 EPUBTextRendering/（消除反向依赖） - RDURLReaderController.swift 移入 EPUBUI/（入口控制器归入 UI 层） - 更新 podspec 资源路径
This commit is contained in:
shen
@@ -1,6 +1,29 @@
|
||||
import UIKit
|
||||
|
||||
// MARK: - 文件说明
|
||||
|
||||
/// EPUB 阅读器主控制器
|
||||
/// EPUBUI 层的核心入口，提供开箱即用的完整阅读器体验
|
||||
/// 调用方只需传入 EPUB 文件 URL 或已构建的 TextBook，即可呈现完整的阅读界面
|
||||
///
|
||||
/// **架构位置：** EPUBUI（最顶层）→ Core → Parser → Foundation
|
||||
///
|
||||
/// **核心职责：**
|
||||
/// - EPUB 解析与分页（支持流式排版和固定布局）
|
||||
/// - 阅读位置的持久化与恢复
|
||||
/// - 高亮、书签的增删改查
|
||||
/// - 工具栏、目录、设置等 UI 面板的协调管理
|
||||
/// - 搜索功能（全文搜索、前后跳转）
|
||||
///
|
||||
/// **打开流程：** init(epubURL:) → viewDidLoad → RDEPUBParser.parse → paginatePublication → readerView.reloadData → restoreLocation
|
||||
|
||||
// MARK: - 阅读器主控制器
|
||||
|
||||
public final class RDEPUBReaderController: UIViewController {
|
||||
// MARK: - 内部辅助类型
|
||||
|
||||
/// 视口签名结构体，用于检测视口尺寸或安全区是否发生显著变化
|
||||
/// 当变化超过阈值时触发重新分页
|
||||
private struct RDEPUBViewportSignature: Equatable {
|
||||
let width: CGFloat
|
||||
let height: CGFloat
|
||||
@@ -19,6 +42,7 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
}
|
||||
}
|
||||
|
||||
/// 视口变化的原因枚举，用于决定延迟处理的策略
|
||||
private enum RDEPUBViewportChangeReason {
|
||||
case viewLayout
|
||||
case orientationTransition
|
||||
@@ -27,8 +51,12 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
|
||||
private typealias NativeTextSnapshot = (pages: [EPUBPage], chapters: [EPUBChapterInfo])
|
||||
|
||||
// MARK: - 公开属性
|
||||
|
||||
/// 阅读器委托，用于接收阅读状态变更通知
|
||||
public weak var delegate: RDEPUBReaderDelegate?
|
||||
|
||||
/// 阅读器配置，修改后自动判断是否需要重新分页或刷新内容
|
||||
public var configuration: RDEPUBReaderConfiguration {
|
||||
didSet {
|
||||
persistReaderSettingsIfNeeded()
|
||||
@@ -54,38 +82,49 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
}
|
||||
}
|
||||
|
||||
/// 当前阅读位置
|
||||
public var currentLocation: RDEPUBLocation? {
|
||||
currentVisibleLocation()
|
||||
}
|
||||
|
||||
/// 当前页码（从 1 开始），nil 表示尚未加载
|
||||
public var currentPageNumber: Int? {
|
||||
guard readerView.currentPage >= 0 else { return nil }
|
||||
return readerView.currentPage + 1
|
||||
}
|
||||
|
||||
/// 当前用户选中的文本（只读），用于创建高亮/批注
|
||||
public private(set) var currentSelection: RDEPUBSelection?
|
||||
|
||||
/// 所有高亮标注
|
||||
public var highlights: [RDEPUBHighlight] {
|
||||
activeHighlights
|
||||
}
|
||||
|
||||
/// 所有书签
|
||||
public var bookmarks: [RDEPUBBookmark] {
|
||||
activeBookmarks
|
||||
}
|
||||
|
||||
/// 原始目录树结构
|
||||
public var tableOfContents: [EPUBTableOfContentsItem] {
|
||||
publication?.tableOfContents ?? []
|
||||
}
|
||||
|
||||
/// 展平后的目录列表（用于目录面板展示，每个条目附带页码）
|
||||
public var flattenedTableOfContents: [RDEPUBReaderTableOfContentsItem] {
|
||||
guard let publication else { return [] }
|
||||
return flattenedTableOfContentsItems(from: publication.tableOfContents)
|
||||
}
|
||||
|
||||
/// 当前阅读位置所在的目录项
|
||||
public var currentTableOfContentsItem: RDEPUBReaderTableOfContentsItem? {
|
||||
resolvedCurrentTableOfContentsItem()
|
||||
}
|
||||
|
||||
// MARK: - 私有属性
|
||||
|
||||
/// EPUB 文件 URL
|
||||
private let epubURL: URL
|
||||
fileprivate let persistence: RDEPUBReaderPersistence?
|
||||
private let readerView = RDReaderView()
|
||||
@@ -131,6 +170,14 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
/// 外部 TextBook 的原始文件 URL（用于重建 TextBook）
|
||||
private var textFileURL: URL?
|
||||
|
||||
// MARK: - 初始化
|
||||
|
||||
/// 使用 EPUB 文件 URL 初始化阅读器
|
||||
/// 会自动从持久化存储中恢复用户的阅读偏好设置
|
||||
/// - Parameters:
|
||||
/// - epubURL: EPUB 文件的本地 URL
|
||||
/// - configuration: 阅读器配置，默认使用 .default
|
||||
/// - persistence: 持久化策略，默认使用 UserDefaults
|
||||
public init(
|
||||
epubURL: URL,
|
||||
configuration: RDEPUBReaderConfiguration = .default,
|
||||
@@ -149,7 +196,15 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
fatalError("init(coder:) has not been implemented")
|
||||
}
|
||||
|
||||
/// 使用已构建的 TextBook 初始化，跳过 EPUB 解析流程（用于 TXT 等纯文本文件）
|
||||
/// 使用已构建的 TextBook 初始化，跳过 EPUB 解析流程
|
||||
/// 适用于 TXT 等纯文本文件，调用方需自行构建 TextBook
|
||||
/// - Parameters:
|
||||
/// - textBook: 已分页的 TextBook 实例
|
||||
/// - bookIdentifier: 书籍唯一标识符，用于持久化
|
||||
/// - title: 书籍标题
|
||||
/// - textFileURL: 原始文本文件 URL，用于重建 TextBook
|
||||
/// - configuration: 阅读器配置
|
||||
/// - persistence: 持久化策略
|
||||
public convenience init(
|
||||
textBook: RDEPUBTextBook,
|
||||
bookIdentifier: String,
|
||||
@@ -244,6 +299,9 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 公开 API
|
||||
|
||||
/// 重新加载书籍，重置所有状态并重新解析 EPUB
|
||||
public func reloadBook() {
|
||||
didStartInitialLoad = false
|
||||
parser = nil
|
||||
@@ -263,11 +321,18 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
startInitialLoadIfNeeded()
|
||||
}
|
||||
|
||||
/// 跳转到指定阅读位置
|
||||
/// - Parameter location: 目标阅读位置
|
||||
public func go(to location: RDEPUBLocation) {
|
||||
guard publication != nil else { return }
|
||||
restoreReadingLocation(location)
|
||||
}
|
||||
|
||||
/// 跳转到指定页码
|
||||
/// - Parameters:
|
||||
/// - pageNumber: 目标页码（从 1 开始）
|
||||
/// - animated: 是否动画过渡
|
||||
/// - Returns: 是否跳转成功
|
||||
@discardableResult
|
||||
public func go(toPageNumber pageNumber: Int, animated: Bool = false) -> Bool {
|
||||
guard pageNumber > 0 else { return false }
|
||||
@@ -289,6 +354,7 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
return true
|
||||
}
|
||||
|
||||
/// 清除当前文本选中状态
|
||||
public func clearSelection() {
|
||||
updateCurrentSelection(nil)
|
||||
}
|
||||
@@ -321,6 +387,12 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
return parts.joined(separator: " · ")
|
||||
}
|
||||
|
||||
/// 添加高亮标注，从当前选中文本或指定选区创建
|
||||
/// - Parameters:
|
||||
/// - selection: 文本选区，默认使用 currentSelection
|
||||
/// - color: 高亮颜色（CSS 格式），默认黄色
|
||||
/// - note: 可选批注文字
|
||||
/// - Returns: 创建的高亮对象，重复时返回 nil
|
||||
@discardableResult
|
||||
public func addHighlight(
|
||||
from selection: RDEPUBSelection? = nil,
|
||||
@@ -1285,6 +1357,8 @@ public final class RDEPUBReaderController: UIViewController {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 书签管理
|
||||
|
||||
extension RDEPUBReaderController {
|
||||
@discardableResult
|
||||
public func addBookmark(note: String? = nil) -> RDEPUBBookmark? {
|
||||
@@ -1456,6 +1530,10 @@ extension RDEPUBReaderController {
|
||||
return trimmed.isEmpty ? nil : trimmed
|
||||
}
|
||||
|
||||
// MARK: - 搜索功能
|
||||
|
||||
/// 执行全文搜索，自动跳转到第一个匹配项
|
||||
/// - Parameter keyword: 搜索关键词，空字符串会清除搜索
|
||||
public func search(keyword: String) {
|
||||
let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
guard !normalizedKeyword.isEmpty else {
|
||||
@@ -1622,6 +1700,8 @@ extension RDEPUBReaderController {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - RDReaderView 数据源与代理
|
||||
|
||||
extension RDEPUBReaderController: RDReaderDataSource, RDReaderDelegate {
|
||||
public func pageCountOfReaderView(readerView: RDReaderView) -> Int {
|
||||
textBook?.pages.count ?? activePages.count
|
||||
@@ -1724,6 +1804,8 @@ extension RDEPUBReaderController: RDReaderDataSource, RDReaderDelegate {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Web 内容视图代理（EPUB 固定布局/Web 渲染路径）
|
||||
|
||||
extension RDEPUBReaderController: RDEPUBWebContentViewDelegate {
|
||||
func epubWebContentView(_ contentView: RDEPUBWebContentView, didUpdateLocation location: RDEPUBLocation, spineIndex: Int) {
|
||||
guard readerView.currentPage >= 0,
|
||||
@@ -1780,6 +1862,8 @@ extension RDEPUBReaderController: RDEPUBWebContentViewDelegate {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 文本内容视图代理（Native Text 渲染路径）
|
||||
|
||||
extension RDEPUBReaderController: RDEPUBTextContentViewDelegate {
|
||||
func textContentView(_ contentView: RDEPUBTextContentView, didChangeSelection selection: RDEPUBSelection?) {
|
||||
guard let selection else {
|
||||
@@ -1902,6 +1986,8 @@ extension RDEPUBReaderController: RDEPUBTextContentViewDelegate {
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - 手势识别器代理（用于 NavigationController 返回手势）
|
||||
|
||||
extension RDEPUBReaderController: UIGestureRecognizerDelegate {
|
||||
public func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
|
||||
true
|
||||
|
||||
Reference in New Issue
Block a user