docs: 补充注释、修正过时文档、清理重复内容

源码注释:
- 为 ~60 个 Swift 文件补充缺失的 doc comment(file header、类型、属性、方法)
- 修正 4 处错误注释:翻页模式数量、搜索行为描述、手势识别器描述、悬空文档块

文档维护:
- 删除重复文档:WXRead/读书EPUB阅读器实现架构.md(与微信读书版完全一致)
- 合并重叠文档:阅读器规划.md → 阅读器功能开发计划.md(单一真值)
- 修正过时内容:所有文档中"四种翻页模式"→"三种",移除 horizontalCoverScroll
- 更新架构图:补齐 EPUBUI/ReaderController、Paging/、Typesetter/ 等子目录
- 更新 index.md 索引:新增开发计划和架构对比文档引用
This commit is contained in:
shen
2026-06-01 09:33:23 +08:00
parent 1efb9d172f
commit 948004eed1
56 changed files with 1691 additions and 792 deletions
@@ -1,5 +1,12 @@
import UIKit
/// EPUB 阅读器标注协调器:负责高亮、批注和书签的增删改查操作。
///
/// 职责:
/// - 管理高亮(highlight)与批注(annotation)的创建、更新和删除
/// - 管理书签(bookmark)的添加、切换和删除
/// - 处理文本选中后的菜单操作(复制、高亮、批注)
/// - 弹出高亮管理器和书签管理器界面
final class RDEPUBReaderAnnotationCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -11,16 +18,19 @@ final class RDEPUBReaderAnnotationCoordinator {
context.controller
}
/// 根据 ID 查找书签。
func bookmark(withID id: String) -> RDEPUBBookmark? {
guard let controller else { return nil }
return controller.activeBookmarks.first { $0.id == id }
}
/// 根据 ID 查找高亮。
func highlight(withID id: String) -> RDEPUBHighlight? {
guard let controller else { return nil }
return controller.activeHighlights.first { $0.id == id }
}
/// 更新当前文本选区状态,并同步刷新底部工具栏的高亮按钮可用性。
func updateCurrentSelection(_ selection: RDEPUBSelection?) {
guard let controller else { return }
controller.currentSelection = selection?.isEmpty == false ? selection : nil
@@ -34,6 +44,7 @@ final class RDEPUBReaderAnnotationCoordinator {
controller.delegate?.epubReader(controller, didChangeSelection: controller.currentSelection)
}
/// 基于当前选区添加高亮标记,自动去重并持久化。
@discardableResult
func addHighlight(
from selection: RDEPUBSelection? = nil,
@@ -43,6 +54,7 @@ final class RDEPUBReaderAnnotationCoordinator {
addAnnotation(from: selection, style: .highlight, color: color, note: note)
}
/// 基于选区创建标注(高亮/划线/批注),支持指定样式、颜色和备注。
@discardableResult
func addAnnotation(
from selection: RDEPUBSelection? = nil,
@@ -85,6 +97,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return newHighlight
}
/// 插入或更新高亮(upsert),按 ID 匹配已有记录。
@discardableResult
func upsertHighlight(_ highlight: RDEPUBHighlight) -> RDEPUBHighlight? {
guard let controller else { return nil }
@@ -101,6 +114,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return scopedHighlight
}
/// 根据 ID 删除高亮并持久化。
@discardableResult
func removeHighlight(id: String) -> RDEPUBHighlight? {
guard let controller else { return nil }
@@ -112,6 +126,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return removed
}
/// 更新指定高亮的批注备注内容。
@discardableResult
func updateHighlightNote(id: String, note: String?) -> RDEPUBHighlight? {
guard let controller else { return nil }
@@ -123,6 +138,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return controller.activeHighlights[index]
}
/// 跳转到指定高亮所在位置。
@discardableResult
func go(toHighlightID id: String, animated: Bool = true) -> Bool {
guard let controller else { return false }
@@ -132,6 +148,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return controller.restoreReadingLocation(highlight.location, animated: animated)
}
/// 清除所有高亮标记。
func removeAllHighlights() {
guard let controller else { return }
guard !controller.activeHighlights.isEmpty else { return }
@@ -139,6 +156,7 @@ final class RDEPUBReaderAnnotationCoordinator {
persistHighlightsAndRefreshContent()
}
/// 将选区位置相对于指定 spine 索引进行规范化。
func scopedSelection(
_ selection: RDEPUBSelection,
relativeToSpineIndex spineIndex: Int?
@@ -166,6 +184,7 @@ final class RDEPUBReaderAnnotationCoordinator {
)
}
/// 弹出高亮管理器,支持查看、编辑备注和删除高亮。
func presentHighlightsManager() {
guard let controller else { return }
guard controller.configuration.allowsHighlights else { return }
@@ -196,6 +215,7 @@ final class RDEPUBReaderAnnotationCoordinator {
controller.present(navigationController, animated: true)
}
/// 弹出标注创建面板(高亮/划线/批注选择)。
func presentAnnotationCreation() {
guard let controller else { return }
guard controller.configuration.allowsHighlights,
@@ -205,6 +225,7 @@ final class RDEPUBReaderAnnotationCoordinator {
presentAnnotationActionSheet(for: currentSelection)
}
/// 处理文本选中后的菜单操作:复制、高亮、批注。
func handleSelectionMenuAction(_ action: RDEPUBAnnotationMenuAction, selection: RDEPUBSelection?) {
guard let selection else { return }
switch action {
@@ -218,6 +239,7 @@ final class RDEPUBReaderAnnotationCoordinator {
}
}
/// 在当前位置添加书签,自动去重。
@discardableResult
func addBookmark(note: String? = nil) -> RDEPUBBookmark? {
guard let controller else { return nil }
@@ -239,6 +261,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return newBookmark
}
/// 切换当前位置的书签状态:已存在则移除,不存在则添加。
@discardableResult
func toggleBookmark(note: String? = nil) -> RDEPUBBookmark? {
guard let controller else { return nil }
@@ -254,6 +277,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return addBookmark(note: note)
}
/// 根据 ID 删除书签并持久化。
@discardableResult
func removeBookmark(id: String) -> RDEPUBBookmark? {
guard let controller else { return nil }
@@ -265,6 +289,7 @@ final class RDEPUBReaderAnnotationCoordinator {
return removed
}
/// 跳转到指定书签所在位置。
@discardableResult
func go(toBookmarkID id: String, animated: Bool = true) -> Bool {
guard let controller else { return false }
@@ -274,12 +299,14 @@ final class RDEPUBReaderAnnotationCoordinator {
return controller.restoreReadingLocation(bookmark.location, animated: animated)
}
/// 同步顶部书签按钮和底部书签列表按钮的 UI 状态。
func updateBookmarkChrome() {
guard let controller else { return }
controller.topToolView.setBookmarkSelected(currentBookmark() != nil)
controller.bottomToolView.setBookmarksEnabled(!controller.activeBookmarks.isEmpty)
}
/// 弹出书签管理器,支持查看、跳转和删除书签。
func presentBookmarksManager() {
guard let controller else { return }
guard !controller.activeBookmarks.isEmpty else { return }
@@ -1,5 +1,11 @@
import UIKit
/// EPUB 阅读器界面组装协调器:负责阅读器初次启动时的 UI 搭建。
///
/// 职责:
/// - 组装阅读器视图层次结构(readerView、loadingIndicator、errorLabel)
/// - 注册内容视图类型
/// - 处理外部纯文本图书的启动收尾逻辑
final class RDEPUBReaderAssemblyCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -7,6 +13,7 @@ final class RDEPUBReaderAssemblyCoordinator {
self.context = context
}
/// 组装阅读器界面:添加 readerView、loadingIndicator、errorLabel 到控制器视图,并配置顶部工具栏。
func assembleInterface() {
guard let controller = context.controller,
let readerView = context.readerView else { return }
@@ -18,6 +25,7 @@ final class RDEPUBReaderAssemblyCoordinator {
controller.delegate?.epubReader(controller, configureTopToolView: controller.topToolView)
}
/// 外部纯文本图书启动时,加载已保存的书签、高亮和阅读位置,完成分页收尾。
func finishExternalTextBookLaunchIfNeeded() {
guard let runtime = context.runtime,
context.isExternalTextBook else {
@@ -1,5 +1,13 @@
import UIKit
/// EPUB 阅读器 Chrome 协调器:负责顶部/底部工具栏的创建、更新和交互处理。
///
/// 职责:
/// - 创建并配置顶部工具栏(返回、书签按钮)
/// - 创建并配置底部工具栏(目录、书签、高亮、设置按钮)
/// - 同步工具栏的主题和状态
/// - 弹出设置面板和目录面板
/// - 处理返回按钮的关闭逻辑
final class RDEPUBReaderChromeCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -11,6 +19,7 @@ final class RDEPUBReaderChromeCoordinator {
context.controller
}
/// 创建顶部工具栏视图,绑定返回和书签切换回调。
func makeTopToolView() -> RDEPUBReaderTopToolView {
let toolView = RDEPUBReaderTopToolView()
toolView.onBack = { [weak self] in
@@ -22,6 +31,7 @@ final class RDEPUBReaderChromeCoordinator {
return toolView
}
/// 创建底部工具栏视图,绑定目录、书签、高亮、设置等回调。
func makeBottomToolView() -> RDEPUBReaderBottomToolView {
let toolView = RDEPUBReaderBottomToolView()
toolView.onShowTableOfContents = { [weak self] in
@@ -42,6 +52,7 @@ final class RDEPUBReaderChromeCoordinator {
return toolView
}
/// 同步更新顶部和底部工具栏的主题、标题、按钮可用性等状态。
func updateReaderChrome() {
guard let controller else { return }
controller.topToolView.apply(theme: controller.configuration.theme)
@@ -67,6 +78,7 @@ final class RDEPUBReaderChromeCoordinator {
controller.updateBookmarkChrome()
}
/// 弹出阅读设置面板(字号、字体、行距、分栏、主题、亮度等)。
func presentSettings() {
guard let controller else { return }
guard controller.configuration.showsSettingsPanel else { return }
@@ -101,6 +113,7 @@ final class RDEPUBReaderChromeCoordinator {
controller.present(navigationController, animated: true)
}
/// 弹出目录列表面板,支持点击跳转到指定章节。
func presentTableOfContents() {
guard let controller else { return }
guard controller.configuration.showsTableOfContents else { return }
@@ -124,6 +137,7 @@ final class RDEPUBReaderChromeCoordinator {
controller.present(navigationController, animated: true)
}
/// 处理返回按钮点击,自动判断 pop 或 dismiss 方式关闭阅读器。
func handleBackAction() {
guard let controller else { return }
close(controller)
@@ -11,37 +11,61 @@ import UIKit
final class RDEPUBReaderContext {
// MARK: - 引用
/// 弱引用阅读器控制器,用于 UIKit 呈现操作。
weak var controller: RDEPUBReaderController?
/// 弱引用阅读器视图,用于布局和页面状态查询。
weak var readerView: RDReaderView?
/// 依赖注入容器,提供解析器、分页器等工厂方法。
var dependencies: RDEPUBReaderDependencies = .live
/// 便捷访问当前控制器的运行时协调器集合。
var runtime: RDEPUBReaderRuntime? {
controller?.runtime
}
// MARK: - 业务状态
/// EPUB 解析器实例。
var parser: RDEPUBParser?
/// 解析后的出版物模型。
var publication: RDEPUBPublication?
/// 当前阅读会话,管理页面和章节状态。
var readingSession: RDEPUBReadingSession?
/// 原生文本排版生成的图书模型(仅文本重排模式)。
var textBook: RDEPUBTextBook?
/// 当前书籍的所有书签。
var activeBookmarks: [RDEPUBBookmark] = []
/// 当前书籍的所有高亮标注。
var activeHighlights: [RDEPUBHighlight] = []
/// 当前打开书籍的唯一标识。
var currentBookIdentifier: String?
/// 分页操作令牌,用于取消过期的异步分页任务。
var paginationToken = UUID()
/// Web 内容分页计算器。
var paginator: RDEPUBPaginator?
/// 全文搜索状态。
var searchState: RDEPUBSearchState?
/// 上次文本分页时的页面尺寸,用于检测是否需要重新分页。
var lastTextPaginationPageSize: CGSize?
/// 当前用户文本选区。
var currentSelection: RDEPUBSelection?
// MARK: - 控制器状态(从 controller 下沉)
/// 阅读器配置(字号、字体、主题等)。
var configuration: RDEPUBReaderConfiguration = .default
/// 持久化策略,负责书签、高亮、阅读位置的存取。
var persistence: RDEPUBReaderPersistence?
/// 当前打开的 EPUB 文件 URL。
var epubURL: URL = URL(string: "about:blank")!
/// 是否正在重新分页。
var isRepaginating: Bool = false
/// 是否已完成首次加载。
var didStartInitialLoad: Bool = false
/// 是否为外部传入的纯文本图书。
var isExternalTextBook: Bool = false
/// 外部纯文本文件的 URL。
var textFileURL: URL?
/// 文本图书缓存,避免重复排版。
var textBookCache = RDEPUBTextBookCache()
// MARK: - 初始化
@@ -53,6 +77,7 @@ final class RDEPUBReaderContext {
// MARK: - 便捷方法
/// 根据当前 readerView 和控制器尺寸构建布局上下文。
func currentLayoutContext() -> RDEPUBNavigatorLayoutContext {
let containerSize = readerView?.bounds.size ?? .zero
let viewSize = controller?.view.bounds.size ?? containerSize
@@ -66,10 +91,12 @@ final class RDEPUBReaderContext {
)
}
/// 根据当前配置生成阅读偏好设置。
func currentPreferences() -> RDEPUBPreferences {
configuration.makePreferences()
}
/// 获取当前文本排版的单页尺寸,优先从 readerView 解析,兜底用布局上下文。
func currentTextPageSize() -> CGSize {
let pageNum = (readerView?.currentPage ?? -1) >= 0 ? readerView?.currentPage : nil
if let readerView, let pageNum {
@@ -81,6 +108,7 @@ final class RDEPUBReaderContext {
return currentLayoutContext().viewportSize
}
/// 根据当前配置生成文本渲染样式(字体、行距、颜色)。
func currentTextRenderStyle() -> RDEPUBTextRenderStyle {
let font = configuration.fontChoice.font(ofSize: configuration.fontSize)
let lineSpacing = max(font.lineHeight * (configuration.lineHeightMultiple - 1), 4)
@@ -92,6 +120,7 @@ final class RDEPUBReaderContext {
)
}
/// 根据页面尺寸和配置生成文本排版参数。
func currentTextLayoutConfig(pageSize: CGSize) -> RDEPUBTextLayoutConfig {
return RDEPUBTextLayoutConfig(
frameWidth: max(pageSize.width, 1),
@@ -108,61 +137,75 @@ final class RDEPUBReaderContext {
)
}
/// 获取当前配置对应的文本渲染器实例。
func resolvedTextRenderer() -> RDEPUBTextRenderer {
dependencies.makeTextRenderer(configuration.textRenderingEngine)
}
/// 当前活跃的页面列表。
var activePages: [EPUBPage] {
readingSession?.activePages ?? []
}
/// 当前活跃的章节信息列表。
var activeChapters: [EPUBChapterInfo] {
readingSession?.activeChapters ?? []
}
/// 屏幕亮度代理属性,读写均转发给系统环境。
var currentBrightness: CGFloat {
get { dependencies.environment.currentBrightness }
set { dependencies.environment.currentBrightness = newValue }
}
/// 用新快照替换当前活跃的分页快照。
func replaceActiveSnapshot(_ snapshot: RDEPUBReadingSession.PaginationSnapshot) {
readingSession?.setActiveSnapshot(snapshot)
}
/// 清除当前活跃快照,重置运行时状态。
func clearActiveSnapshot() {
readingSession?.resetRuntimeState()
}
/// 工厂方法:创建 EPUB 解析器。
func makeParser() -> RDEPUBParser {
dependencies.makeParser()
}
/// 工厂方法:创建 Web 内容分页计算器。
func makePaginator() -> RDEPUBPaginator {
dependencies.makePaginator()
}
/// 工厂方法:创建 EPUB 文本图书构建器。
func makeTextBookBuilder(layoutConfig: RDEPUBTextLayoutConfig) -> RDEPUBTextBookBuilder {
dependencies.makeTextBookBuilder(resolvedTextRenderer(), textBookCache, layoutConfig)
}
/// 工厂方法:创建纯文本图书构建器。
func makePlainTextBookBuilder(layoutConfig: RDEPUBTextLayoutConfig) -> RDPlainTextBookBuilder {
dependencies.makePlainTextBookBuilder(resolvedTextRenderer(), layoutConfig)
}
/// 获取当前可见页面的阅读位置。
func currentVisibleLocation() -> RDEPUBLocation? {
controller?.currentVisibleLocation()
}
/// 从持久化存储加载上次保存的阅读位置。
func persistenceLocation() -> RDEPUBLocation? {
guard let currentBookIdentifier else { return nil }
return persistence?.loadLocation(for: currentBookIdentifier)
}
/// 将阅读位置持久化到存储。
func persist(location: RDEPUBLocation) {
guard let currentBookIdentifier else { return }
persistence?.saveLocation(location, for: currentBookIdentifier)
}
/// 根据规范化 href 获取文本章节数据。
func textChapterData(forNormalizedHref href: String) -> RDEPUBChapterData? {
guard let textBook, let publication else { return nil }
let normalizedHref = publication.resourceResolver.normalizedHref(href) ?? href
@@ -171,38 +214,47 @@ final class RDEPUBReaderContext {
.flatMap { textBook.chapterData(for: $0.href) }
}
/// 显示加载指示器。
func showLoading() {
controller?.showLoading()
}
/// 隐藏加载指示器。
func hideLoading() {
controller?.hideLoading()
}
/// 将错误转发给控制器处理。
func handle(error: Error) {
controller?.handle(error: error)
}
/// 触发工具栏状态更新。
func updateReaderChrome() {
controller?.updateReaderChrome()
}
/// 刷新可见内容并保持当前阅读位置不变。
func refreshVisibleContentPreservingLocation() {
controller?.refreshVisibleContentPreservingLocation()
}
/// 恢复到指定阅读位置。
func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
controller?.restoreReadingLocation(location, animated: animated) ?? false
}
/// 重新分页并保持当前阅读位置。
func repaginatePreservingCurrentLocation() {
controller?.repaginatePreservingCurrentLocation()
}
/// 将当前配置应用到阅读器视图。
func applyReaderViewConfiguration() {
controller?.applyReaderViewConfiguration()
}
/// 同步书签按钮的 UI 状态。
func updateBookmarkChrome() {
controller?.updateBookmarkChrome()
}
@@ -1,10 +1,17 @@
// RDEPUBReaderDependencies.swift
// EPUB 阅读器依赖注入配置,定义显示环境协议与核心组件工厂
import UIKit
/// 阅读器显示环境协议,抽象屏幕亮度和视口尺寸以支持测试和多平台适配
public protocol RDEPUBReaderDisplayEnvironment: AnyObject {
/// 当前屏幕亮度,取值范围 0.0 ~ 1.0
var currentBrightness: CGFloat { get set }
/// 后备视口尺寸,用于无法获取实际视图尺寸时的布局计算
var fallbackViewportSize: CGSize { get }
}
/// 基于 UIScreen 的默认显示环境实现,直接读写系统屏幕亮度
public final class RDEPUBUIScreenEnvironment: RDEPUBReaderDisplayEnvironment {
public init() {}
@@ -18,14 +25,29 @@ public final class RDEPUBUIScreenEnvironment: RDEPUBReaderDisplayEnvironment {
}
}
/// EPUB 阅读器核心依赖容器,通过工厂闭包注入各组件以便替换和测试
public struct RDEPUBReaderDependencies {
/// 显示环境实例
public var environment: any RDEPUBReaderDisplayEnvironment
/// EPUB 解析器工厂
public var makeParser: () -> RDEPUBParser
/// 分页器工厂
public var makePaginator: () -> RDEPUBPaginator
/// 富文本书籍构建器工厂
public var makeTextBookBuilder: (RDEPUBTextRenderer, RDEPUBTextBookCache?, RDEPUBTextLayoutConfig) -> RDEPUBTextBookBuilder
/// 纯文本书籍构建器工厂
public var makePlainTextBookBuilder: (RDEPUBTextRenderer, RDEPUBTextLayoutConfig) -> RDPlainTextBookBuilder
/// 文本渲染器工厂
public var makeTextRenderer: (RDEPUBTextRenderingEngine) -> RDEPUBTextRenderer
/// 初始化依赖容器
/// - Parameters:
/// - environment: 显示环境实例
/// - makeParser: EPUB 解析器工厂闭包
/// - makePaginator: 分页器工厂闭包
/// - makeTextBookBuilder: 富文本书籍构建器工厂闭包
/// - makePlainTextBookBuilder: 纯文本书籍构建器工厂闭包
/// - makeTextRenderer: 文本渲染器工厂闭包
public init(
environment: any RDEPUBReaderDisplayEnvironment,
makeParser: @escaping () -> RDEPUBParser,
@@ -42,6 +64,7 @@ public struct RDEPUBReaderDependencies {
self.makeTextRenderer = makeTextRenderer
}
/// 默认生产环境依赖,使用系统屏幕环境和标准组件实现
public static var live: RDEPUBReaderDependencies {
RDEPUBReaderDependencies(
environment: RDEPUBUIScreenEnvironment(),
@@ -1,5 +1,11 @@
import Foundation
/// EPUB 阅读器加载协调器:负责 EPUB 文件的解析和出版物初始化。
///
/// 职责:
/// - 判断是否需要执行首次加载
/// - 后台解析 EPUB 文件并构建 Publication 模型
/// - 将解析结果应用到阅读器上下文并触发分页
final class RDEPUBReaderLoadCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -7,6 +13,7 @@ final class RDEPUBReaderLoadCoordinator {
self.context = context
}
/// 检查条件后启动首次加载,确保只执行一次且视图已布局。
func startInitialLoadIfNeeded() {
guard let controller = context.controller,
let readerView = context.readerView,
@@ -19,6 +26,7 @@ final class RDEPUBReaderLoadCoordinator {
loadPublication()
}
/// 后台解析 EPUB 文件,加载书签、高亮和阅读位置,完成后回调主线程。
func loadPublication() {
guard let controller = context.controller else { return }
context.showLoading()
@@ -57,6 +65,7 @@ final class RDEPUBReaderLoadCoordinator {
}
}
/// 将解析完成的出版物应用到上下文,设置书签/高亮/会话,并触发分页。
func applyParsedPublication(
parser: RDEPUBParser,
publication: RDEPUBPublication,
@@ -1,5 +1,12 @@
import Foundation
/// EPUB 阅读器位置协调器:负责阅读位置的恢复、查询和持久化。
///
/// 职责:
/// - 根据保存的位置恢复阅读进度
/// - 获取当前可见页面的阅读位置
/// - 从持久化存储加载已保存位置
/// - 持久化当前位置并通知委托
final class RDEPUBReaderLocationCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -7,6 +14,7 @@ final class RDEPUBReaderLocationCoordinator {
self.context = context
}
/// 恢复到指定阅读位置,返回是否成功跳转。
@discardableResult
func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
guard let controller = context.controller,
@@ -30,6 +38,7 @@ final class RDEPUBReaderLocationCoordinator {
return true
}
/// 获取当前可见页面对应的阅读位置。
func currentVisibleLocation() -> RDEPUBLocation? {
guard let controller = context.controller,
let readerView = context.readerView else {
@@ -41,6 +50,7 @@ final class RDEPUBReaderLocationCoordinator {
return context.readingSession?.currentReadingLocation(bookIdentifier: context.currentBookIdentifier)
}
/// 从持久化存储加载上次保存的阅读位置。
func persistenceLocation() -> RDEPUBLocation? {
guard let controller = context.controller,
let currentBookIdentifier = context.currentBookIdentifier else {
@@ -49,6 +59,7 @@ final class RDEPUBReaderLocationCoordinator {
return controller.persistence?.loadLocation(for: currentBookIdentifier)
}
/// 持久化阅读位置,并通知委托更新目录项和书签状态。
func persist(location: RDEPUBLocation) {
guard let controller = context.controller,
let currentBookIdentifier = context.currentBookIdentifier else { return }
@@ -1,5 +1,13 @@
import Foundation
/// EPUB 阅读器分页协调器:负责出版物的分页计算和页面数据更新。
///
/// 职责:
/// - 根据出版物类型(文本重排/Fixed Layout/Web 内容)选择分页策略
/// - 后台构建文本图书模型并应用分页快照
/// - 重新分页时保持当前阅读位置
/// - 刷新可见内容并保持位置
/// - 重建外部纯文本图书
final class RDEPUBReaderPaginationCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -7,6 +15,7 @@ final class RDEPUBReaderPaginationCoordinator {
self.context = context
}
/// 对出版物执行分页:文本重排走 TextBookBuilder,Fixed Layout 直接生成快照,Web 内容走 Paginator。
func paginatePublication(restoreLocation: RDEPUBLocation?) {
guard let controller = context.controller,
let parser = context.parser,
@@ -79,6 +88,7 @@ final class RDEPUBReaderPaginationCoordinator {
}
}
/// 应用文本图书模型:生成分页快照并完成分页流程。
func applyTextBook(_ textBook: RDEPUBTextBook, restoreLocation: RDEPUBLocation?) {
guard let controller = context.controller else { return }
context.textBook = textBook
@@ -93,6 +103,7 @@ final class RDEPUBReaderPaginationCoordinator {
finishPagination(restoreLocation: restoreLocation)
}
/// 应用分页快照(Fixed Layout 或 Web 内容),并完成分页流程。
func applyPaginationSnapshot(
_ snapshot: (pages: [EPUBPage], chapters: [EPUBChapterInfo]),
restoreLocation: RDEPUBLocation?
@@ -109,6 +120,7 @@ final class RDEPUBReaderPaginationCoordinator {
finishPagination(restoreLocation: restoreLocation)
}
/// 分页完成后的收尾:刷新视图、恢复阅读位置、处理待定视口变更。
func finishPagination(restoreLocation: RDEPUBLocation?) {
guard let controller = context.controller,
let readerView = context.readerView else { return }
@@ -125,6 +137,7 @@ final class RDEPUBReaderPaginationCoordinator {
context.runtime?.viewportMonitor.processPendingChangeAfterPagination()
}
/// 重新分页并保持当前阅读位置(优先使用待恢复位置,其次当前位置,最后持久化位置)。
func repaginatePreservingCurrentLocation() {
guard context.publication != nil else { return }
let restoreLocation = context.runtime?.viewportMonitor.consumePendingPresentationRestoreLocation()
@@ -133,6 +146,7 @@ final class RDEPUBReaderPaginationCoordinator {
paginatePublication(restoreLocation: restoreLocation)
}
/// 刷新可见内容并保持当前阅读位置不变。
func refreshVisibleContentPreservingLocation() {
guard let readerView = context.readerView else { return }
let restoreLocation = context.currentVisibleLocation() ?? context.persistenceLocation()
@@ -142,6 +156,7 @@ final class RDEPUBReaderPaginationCoordinator {
}
}
/// 重建外部纯文本图书(布局变更后重新排版)。
func rebuildExternalTextBook() {
guard let controller = context.controller,
let textFileURL = controller.textFileURL else { return }
@@ -1,5 +1,8 @@
import UIKit
/// EPUB 阅读器运行时总协调器。
/// 统一持有并分发给加载、分页、定位、搜索、工具栏、批注、视口监测等子协调器,
/// 作为阅读器控制器的门面(Facade),简化外部调用。
final class RDEPUBReaderRuntime {
private unowned let context: RDEPUBReaderContext
@@ -15,18 +18,22 @@ final class RDEPUBReaderRuntime {
self.context = context
}
/// 创建顶部工具栏视图
func makeTopToolView() -> RDEPUBReaderTopToolView {
chromeCoordinator.makeTopToolView()
}
/// 创建底部工具栏视图
func makeBottomToolView() -> RDEPUBReaderBottomToolView {
chromeCoordinator.makeBottomToolView()
}
/// 若尚未加载则启动首次加载流程
func startInitialLoadIfNeeded() {
loadCoordinator.startInitialLoadIfNeeded()
}
/// 重新加载当前书籍,清空解析器、分页、批注等状态后从头初始化
func reloadBook() {
guard let readerView = context.readerView else { return }
context.didStartInitialLoad = false
@@ -44,10 +51,20 @@ final class RDEPUBReaderRuntime {
startInitialLoadIfNeeded()
}
/// 跳转到指定阅读位置
/// - Parameters:
/// - location: 目标位置
/// - animated: 是否动画过渡
/// - Returns: 跳转是否成功
func go(to location: RDEPUBLocation, animated: Bool = false) -> Bool {
locationCoordinator.restoreReadingLocation(location, animated: animated)
}
/// 跳转到指定页码
/// - Parameters:
/// - pageNumber: 目标页码(从 1 开始)
/// - animated: 是否动画过渡
/// - Returns: 跳转是否成功
@discardableResult
func go(toPageNumber pageNumber: Int, animated: Bool = false) -> Bool {
guard let controller = context.controller,
@@ -73,6 +90,7 @@ final class RDEPUBReaderRuntime {
return true
}
/// 清除当前选区
func clearSelection() {
annotationCoordinator.updateCurrentSelection(nil)
}
@@ -168,20 +186,24 @@ final class RDEPUBReaderRuntime {
annotationCoordinator.handleSelectionMenuAction(action, selection: selection)
}
/// 按关键词搜索全文
func search(keyword: String) {
searchCoordinator.search(keyword: keyword)
}
/// 跳转到下一个搜索匹配项
@discardableResult
func searchNext() -> Bool {
searchCoordinator.searchNext()
}
/// 跳转到上一个搜索匹配项
@discardableResult
func searchPrevious() -> Bool {
searchCoordinator.searchPrevious()
}
/// 清除搜索状态
func clearSearch() {
searchCoordinator.clearSearch()
}
@@ -190,26 +212,32 @@ final class RDEPUBReaderRuntime {
searchCoordinator.searchPresentation(for: page)
}
/// 更新阅读器工具栏显示状态
func updateReaderChrome() {
chromeCoordinator.updateReaderChrome()
}
/// 弹出阅读设置面板
func presentSettings() {
chromeCoordinator.presentSettings()
}
/// 弹出目录面板
func presentTableOfContents() {
chromeCoordinator.presentTableOfContents()
}
/// 处理返回操作
func handleBackAction() {
chromeCoordinator.handleBackAction()
}
/// 启动 Publication 加载流程
func loadPublication() {
loadCoordinator.loadPublication()
}
/// 将已解析的 Publication 应用到控制器
func applyParsedPublication(
parser: RDEPUBParser,
publication: RDEPUBPublication,
@@ -228,14 +256,17 @@ final class RDEPUBReaderRuntime {
)
}
/// 对 Publication 执行分页计算
func paginatePublication(restoreLocation: RDEPUBLocation?) {
paginationCoordinator.paginatePublication(restoreLocation: restoreLocation)
}
/// 应用外部 TextBook 并恢复阅读位置
func applyTextBook(_ textBook: RDEPUBTextBook, restoreLocation: RDEPUBLocation?) {
paginationCoordinator.applyTextBook(textBook, restoreLocation: restoreLocation)
}
/// 应用分页快照并恢复阅读位置
func applyPaginationSnapshot(
_ snapshot: (pages: [EPUBPage], chapters: [EPUBChapterInfo]),
restoreLocation: RDEPUBLocation?
@@ -243,35 +274,43 @@ final class RDEPUBReaderRuntime {
paginationCoordinator.applyPaginationSnapshot(snapshot, restoreLocation: restoreLocation)
}
/// 完成分页流程并恢复阅读位置
func finishPagination(restoreLocation: RDEPUBLocation?) {
paginationCoordinator.finishPagination(restoreLocation: restoreLocation)
}
/// 重新分页并保持当前阅读位置不变
func repaginatePreservingCurrentLocation() {
paginationCoordinator.repaginatePreservingCurrentLocation()
}
/// 刷新当前可见内容,保持阅读位置不变
func refreshVisibleContentPreservingLocation() {
paginationCoordinator.refreshVisibleContentPreservingLocation()
}
/// 重建外部 TextBook 数据
func rebuildExternalTextBook() {
paginationCoordinator.rebuildExternalTextBook()
}
/// 恢复到指定阅读位置
@discardableResult
func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
locationCoordinator.restoreReadingLocation(location, animated: animated)
}
/// 获取当前可见页面的阅读位置
func currentVisibleLocation() -> RDEPUBLocation? {
locationCoordinator.currentVisibleLocation()
}
/// 获取当前视口签名快照
func currentViewportSignature() -> RDEPUBViewportSignature? {
viewportMonitor.currentViewportSignature()
}
/// 视口变化时检查是否需要重新分页
func handleViewportChangeIfNeeded(
reason: RDEPUBViewportChangeReason,
viewportSignature: RDEPUBViewportSignature? = nil
@@ -1,5 +1,6 @@
import Foundation
/// 搜索协调器,负责管理全文搜索的执行、结果导航和搜索状态通知。
final class RDEPUBReaderSearchCoordinator {
private unowned let context: RDEPUBReaderContext
@@ -11,6 +12,8 @@ final class RDEPUBReaderSearchCoordinator {
context.controller
}
/// 按关键词执行全文搜索,匹配结果自动导航到首个命中位置
/// - Parameter keyword: 搜索关键词
func search(keyword: String) {
guard let controller else { return }
let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -34,16 +37,21 @@ final class RDEPUBReaderSearchCoordinator {
}
}
/// 跳转到下一个搜索匹配项
/// - Returns: 是否成功跳转
@discardableResult
func searchNext() -> Bool {
advanceSearch(by: 1)
}
/// 跳转到上一个搜索匹配项
/// - Returns: 是否成功跳转
@discardableResult
func searchPrevious() -> Bool {
advanceSearch(by: -1)
}
/// 清除搜索状态并刷新当前可见内容
func clearSearch() {
guard let controller else { return }
controller.searchState = nil
@@ -51,6 +59,9 @@ final class RDEPUBReaderSearchCoordinator {
controller.refreshVisibleContentPreservingLocation()
}
/// 构建指定页面的搜索结果展示信息,用于高亮渲染
/// - Parameter page: 目标页面
/// - Returns: 搜索展示数据,若无搜索状态则返回 nil
func searchPresentation(for page: EPUBPage) -> RDEPUBSearchPresentation? {
guard let controller else { return nil }
guard let searchState = controller.searchState,
@@ -1,5 +1,7 @@
import UIKit
/// 视口监测器,监听视图布局和屏幕旋转等视口变化事件,
/// 检测变化是否显著,必要时触发重新分页或内容重建。
final class RDEPUBReaderViewportMonitor {
private unowned let context: RDEPUBReaderContext
@@ -16,6 +18,7 @@ final class RDEPUBReaderViewportMonitor {
context.controller
}
/// 视图布局完成后检查视口是否发生变化,首次布局时触发初始加载
func viewDidLayoutSubviews() {
guard let controller else { return }
guard let viewportSignature = currentViewportSignature() else { return }
@@ -38,6 +41,8 @@ final class RDEPUBReaderViewportMonitor {
handleViewportChangeIfNeeded(reason: .viewLayout, viewportSignature: viewportSignature)
}
/// 屏幕旋转前捕获当前阅读位置,旋转完成后检测视口变化并处理
/// - Parameter coordinator: 转场协调器
func viewWillTransition(with coordinator: UIViewControllerTransitionCoordinator) {
guard let controller else { return }
guard controller.didStartInitialLoad else { return }
@@ -52,6 +57,7 @@ final class RDEPUBReaderViewportMonitor {
}
}
/// 重置所有视口状态,用于重新加载书籍
func resetForReload() {
lastAppliedViewportSignature = currentViewportSignature()
pendingViewportChangeReason = nil
@@ -59,16 +65,19 @@ final class RDEPUBReaderViewportMonitor {
isWaitingForViewportTransitionCompletion = false
}
/// 消费并返回待恢复的阅读位置(一次性读取后清空)
func consumePendingPresentationRestoreLocation() -> RDEPUBLocation? {
defer { pendingPresentationRestoreLocation = nil }
return pendingPresentationRestoreLocation
}
/// 主动捕获当前阅读位置到待恢复队列,供后续视口变化后恢复使用
func capturePendingPresentationRestoreLocation() {
guard let controller else { return }
pendingPresentationRestoreLocation = controller.currentVisibleLocation() ?? controller.persistenceLocation()
}
/// 分页完成后处理挂起的视口变化(如有),避免分页过程中重复触发
func processPendingChangeAfterPagination() {
guard let pendingReason = pendingViewportChangeReason else { return }
pendingViewportChangeReason = nil
@@ -77,6 +86,7 @@ final class RDEPUBReaderViewportMonitor {
}
}
/// 获取当前视口签名,包含容器尺寸和安全区域信息
func currentViewportSignature() -> RDEPUBViewportSignature? {
guard let controller else { return nil }
let containerSize = controller.readerView.bounds.size == .zero ? controller.view.bounds.size : controller.readerView.bounds.size
@@ -92,6 +102,7 @@ final class RDEPUBReaderViewportMonitor {
)
}
/// 检测视口签名是否发生显著变化,若变化则触发重新分页或重建外部 TextBook
func handleViewportChangeIfNeeded(
reason: RDEPUBViewportChangeReason,
viewportSignature: RDEPUBViewportSignature? = nil