ReadViewSDK/Sources/RDReaderView/EPUBUI/RDEPUBReaderDelegate.swift

import UIKit

// MARK: - 阅读器委托协议

/// EPUB 阅读器的委托协议
/// 用于向调用方通知阅读器的各种状态变更事件
/// 所有方法均提供默认空实现，调用方可选择性实现感兴趣的方法
public protocol RDEPUBReaderDelegate: AnyObject {
    /// 阅读器成功打开书籍时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - publication: 解析后的出版物对象
    func epubReader(_ reader: UIViewController, didOpen publication: RDEPUBPublication)

    /// 阅读位置更新时调用（翻页、跳转等）
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - location: 新的阅读位置
    func epubReader(_ reader: UIViewController, didUpdateLocation location: RDEPUBLocation)

    /// 阅读器翻到书籍末尾时调用
    /// - Parameter reader: 阅读器控制器
    func epubReaderDidReachEnd(_ reader: UIViewController)

    /// 用户选中文本发生变化时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - selection: 当前选中文本，nil 表示取消选中
    func epubReader(_ reader: UIViewController, didChangeSelection selection: RDEPUBSelection?)

    /// 高亮标注列表更新时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - highlights: 当前所有高亮
    func epubReader(_ reader: UIViewController, didUpdateHighlights highlights: [RDEPUBHighlight])

    /// 书签列表更新时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - bookmarks: 当前所有书签
    func epubReader(_ reader: UIViewController, didUpdateBookmarks bookmarks: [RDEPUBBookmark])

    /// 搜索结果更新时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - result: 搜索结果摘要，nil 表示无搜索
    func epubReader(_ reader: UIViewController, didUpdateSearchResult result: RDEPUBSearchResult?)

    /// 当前搜索匹配项变化时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - match: 当前匹配项，nil 表示无匹配
    func epubReader(_ reader: UIViewController, didChangeCurrentSearchMatch match: RDEPUBSearchMatch?)

    /// 当前所在目录项更新时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - item: 当前目录项
    func epubReader(_ reader: UIViewController, didUpdateCurrentTableOfContentsItem item: RDEPUBReaderTableOfContentsItem?)

    /// 用户点击外部链接时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - url: 外部链接 URL
    func epubReader(_ reader: UIViewController, didActivateExternalLink url: URL)

    /// 外部链接打开前的拦截钩子，返回 false 可阻止打开
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - url: 外部链接 URL
    /// - Returns: 是否允许打开该链接
    func epubReader(_ reader: UIViewController, shouldOpenExternalURL url: URL) -> Bool

    /// 阅读器发生错误时调用
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - error: 错误对象
    func epubReader(_ reader: UIViewController, didFailWithError error: Error)

    /// 允许调用方自定义顶部工具栏
    /// 在 viewDidLoad 时调用，可在工具栏上添加自定义按钮
    /// - Parameters:
    ///   - reader: 阅读器控制器
    ///   - topToolView: 顶部工具栏视图
    func epubReader(_ reader: UIViewController, configureTopToolView topToolView: RDEPUBReaderTopToolView)
}

// MARK: - 默认空实现

/// 所有委托方法的默认空实现，调用方可只实现需要的方法
public extension RDEPUBReaderDelegate {
    func epubReader(_ reader: UIViewController, didOpen publication: RDEPUBPublication) {}
    func epubReader(_ reader: UIViewController, didUpdateLocation location: RDEPUBLocation) {}
    func epubReaderDidReachEnd(_ reader: UIViewController) {}
    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) {}
    func epubReader(_ reader: UIViewController, shouldOpenExternalURL url: URL) -> Bool { true }
    func epubReader(_ reader: UIViewController, didFailWithError error: Error) {}
    func epubReader(_ reader: UIViewController, configureTopToolView topToolView: RDEPUBReaderTopToolView) {}
}