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

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

Browse Source 
- 实现EPUB阅读器搜索功能及选中注释功能
- 优化CFI模块，修复代码审查发现的11个问题
- 实现大书远距目录跳转与后台补全优化方案
- 优化设置面板与章节运行时联动
- 重构及大量改进优化
This commit is contained in:
shenlei
2026-06-22 20:26:34 +08:00
parent f50495ad91
commit c65c190b71
178 changed files with 11380 additions and 6728 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/RDReaderView/EPUBUI/Settings/RDEPUBReaderConfiguration.swift
+26 -87
View File
@@ -1,26 +1,18 @@
import UIKit
// MARK: - 文本渲染引擎
/// EPUB 文本渲染引擎枚举
/// 定义了当前支持的文本渲染方式，未来可扩展为多引擎选择
public enum RDEPUBTextRenderingEngine: Equatable {
/// 基于 DTCoreText 的渲染引擎，将 HTML/CSS 转换为 NSAttributedString
case dtCoreText
}
// MARK: - 阅读字体
/// 阅读器内置字体选项。
/// 第一版优先使用系统授权字体，后续可扩展为 bundle 内置字体注册。
public enum RDEPUBReaderFontChoice: String, Codable, CaseIterable, Equatable {
/// 系统默认无衬线字体
case system
/// 系统衬线字体
case serif
/// 系统圆体字体
case rounded
/// 系统等宽字体
case monospaced
public var displayName: String {
@@ -54,108 +46,58 @@ public enum RDEPUBReaderFontChoice: String, Codable, CaseIterable, Equatable {
}
}
// MARK: - 阅读器配置
/// EPUB 阅读器的完整配置结构体
/// 作为 EPUBUI 层的入口配置，控制阅读器的外观、行为和功能开关
/// 调用方在创建 RDEPUBReaderController 前可自定义此配置
public struct RDEPUBReaderConfiguration: Equatable {
// MARK: 阅读排版参数
/// 正文字号（单位：pt），默认 15
public var fontSize: CGFloat
/// 行距倍数，默认 1.6（即行距为字号的 1.6 倍）
public var lineHeightMultiple: CGFloat
/// 正文字体，默认系统字体
public var fontChoice: RDEPUBReaderFontChoice
/// 栏数，默认单栏
public var numberOfColumns: Int
/// 栏间距，默认 20pt
public var columnGap: CGFloat
/// 翻页显示模式：.pageCurl（仿真翻页）或 .scroll（滚动阅读）
public var displayType: RDReaderView.DisplayType
/// 横屏时是否启用双页显示，默认开启
public var landscapeDualPageEnabled: Bool
// MARK: UI 功能开关
/// 是否显示目录入口，默认开启
public var showsTableOfContents: Bool
/// 是否允许文本高亮功能，默认开启
public var allowsHighlights: Bool
/// 是否显示设置面板入口，默认开启
public var showsSettingsPanel: Bool
// MARK: 内容内边距
/// 流式排版（reflowable）内容的内边距，上下 40pt、左右 16pt
public var reflowableContentInsets: UIEdgeInsets
/// 固定布局（fixed layout）内容的内边距，默认为零
public var fixedContentInset: UIEdgeInsets
// MARK: 主题与布局
/// 当前阅读主题（浅色/深色/护眼等），默认 .light
public var theme: RDEPUBReaderTheme
/// 暗色主题下是否柔化正文图片，降低夜间阅读刺眼感
public var darkImageAdjustmentEnabled: Bool
/// 暗色主题图片柔化混合比例，0 表示不处理，推荐 0.12 ~ 0.2
public var darkImageBlendRatio: CGFloat
/// 固定布局的适配模式：按页适配或按宽度适配
public var fixedLayoutFit: RDEPUBFixedLayoutFit
/// 固定布局的跨页模式：自动/单页/双页
public var fixedLayoutSpreadMode: RDEPUBFixedLayoutSpreadMode
/// 文本渲染引擎，默认使用 DTCoreText
public var textRenderingEngine: RDEPUBTextRenderingEngine
/// 章节按需加载窗口大小（总章节数，包含当前章），默认 3，范围 3...15，偶数自动向上取奇
public var onDemandChapterWindowSize: Int
/// 后台元数据解析并发数，默认为 CPU 核心数。
/// 若 profiling 显示 renderTotalMs ≈ wallClockMs（渲染受限），维持核心数即可；
/// 若 writeTotalMs 占比显著（I/O 等待），可试探 cpuCount * 1.25~1.5 以填充 I/O 等待间隙。
public var metadataParsingConcurrency: Int
// MARK: JumpSession 策略
/// JumpSession 策略配置
public var jumpSessionPolicy: RDEPUBJumpSessionPolicy
// MARK: 安全策略
/// 允许直接打开的外部 URL scheme 集合，默认仅允许 https
public var allowedExternalURLSchemes: Set<String>
/// 打开外部链接前是否需要用户确认，默认 true
public var requiresExternalLinkConfirmation: Bool
/// 是否允许正文和离屏分页 WebView 开启 inspectable，默认 false
public var allowsInspectableWebViews: Bool
/// 是否允许输出完整 WebView 消息体日志，默认 false
public var enablesVerboseWebViewLogging: Bool
// MARK: 初始化
/// 创建阅读器配置，所有参数均提供合理的默认值
/// - Parameters:
/// - fontSize: 正文字号，默认 15pt
/// - lineHeightMultiple: 行距倍数，默认 1.6
/// - fontChoice: 正文字体，默认系统字体
/// - displayType: 翻页模式，默认 .pageCurl
/// - landscapeDualPageEnabled: 横屏双页，默认 true
/// - showsTableOfContents: 显示目录入口，默认 true
/// - allowsHighlights: 允许高亮，默认 true
/// - showsSettingsPanel: 显示设置面板，默认 true
/// - reflowableContentInsets: 流式排版内边距
/// - fixedContentInset: 固定布局内边距
/// - theme: 阅读主题，默认 .light
/// - darkImageAdjustmentEnabled: 暗色主题下是否柔化正文图片
/// - darkImageBlendRatio: 暗色主题图片柔化混合比例
/// - fixedLayoutFit: 固定布局适配模式
/// - fixedLayoutSpreadMode: 固定布局跨页模式
/// - textRenderingEngine: 文本渲染引擎
/// - onDemandChapterWindowSize: 章节按需加载窗口大小（总章节数 3...15，偶数自动向上取奇）
/// - metadataParsingConcurrency: 后台元数据解析并发数，默认 CPU 核心数
/// - allowedExternalURLSchemes: 允许直接打开的外部 URL scheme 集合，默认仅 https
/// - requiresExternalLinkConfirmation: 打开外部链接前是否需要确认，默认 true
/// - allowsInspectableWebViews: 是否允许开启 inspectable，默认 false
/// - enablesVerboseWebViewLogging: 是否允许输出完整 WebView 消息体日志，默认 false
public init(
fontSize: CGFloat = 15,
lineHeightMultiple: CGFloat = 1.6,
@@ -210,11 +152,11 @@ public struct RDEPUBReaderConfiguration: Equatable {
self.enablesVerboseWebViewLogging = enablesVerboseWebViewLogging
}
/// 默认配置实例，使用所有参数的默认值
public static let `default` = RDEPUBReaderConfiguration()
}
extension RDEPUBReaderConfiguration {
static func normalizedChapterWindowSize(_ size: Int) -> Int {
let clamped = max(3, min(15, size))
return clamped % 2 == 0 ? clamped + 1 : clamped
@@ -225,11 +167,8 @@ extension RDEPUBReaderConfiguration {
}
}
// MARK: - 配置转换
extension RDEPUBReaderConfiguration {
/// 将用户可见的配置转换为底层排版引擎所需的 RDEPUBPreferences
/// - Returns: 排版偏好设置实例，供 Core 层的渲染管道使用
func makePreferences() -> RDEPUBPreferences {
RDEPUBPreferences(
fontSize: fontSize,
Sources/RDReaderView/EPUBUI/Settings/RDEPUBReaderSettings.swift
+16 -48
View File
@@ -1,20 +1,15 @@
import UIKit
// MARK: - 翻页显示模式
/// 阅读器翻页显示模式枚举
/// 用于持久化存储用户的翻页偏好设置，与 RDReaderView.DisplayType 相互转换
public enum RDEPUBReaderDisplayMode: String, Codable, Equatable {
/// 仿真翻页模式（纸张翻转效果）
case pageCurl
/// 水平滚动模式
case horizontalScroll
/// 垂直滚动模式
case verticalScroll
/// 水平覆盖式滚动模式（类似电子杂志翻页效果）
case horizontalCoverScroll
/// 从底层 DisplayType 转换为 UI 层的 DisplayMode
init(displayType: RDReaderView.DisplayType) {
switch displayType {
case .pageCurl:
@@ -26,8 +21,6 @@ public enum RDEPUBReaderDisplayMode: String, Codable, Equatable {
}
}
/// 转换为底层 RDReaderView 所需的 DisplayType
/// 注意：horizontalCoverScroll 会被映射为 horizontalScroll
var displayType: RDReaderView.DisplayType {
switch self {
case .pageCurl:
@@ -40,25 +33,20 @@ public enum RDEPUBReaderDisplayMode: String, Codable, Equatable {
}
}
// MARK: - 主题预设
/// 阅读器主题预设枚举
/// 将 RDEPUBReaderTheme 映射为可序列化的枚举值，用于持久化存储和设置面板展示
public enum RDEPUBReaderThemePreset: String, Codable, CaseIterable, Equatable {
/// 浅色主题
case light
/// 黄色护眼主题
case yellow
/// 绿色护眼主题
case green
/// 粉色主题
case pink
/// 蓝色主题
case blue
/// 深色/夜间主题
case dark
/// 将预设枚举转换为主题配置实例
public var theme: RDEPUBReaderTheme {
switch self {
case .light:
@@ -76,8 +64,6 @@ public enum RDEPUBReaderThemePreset: String, Codable, CaseIterable, Equatable {
}
}
/// 从主题配置实例反向查找对应的预设枚举
/// 自定义主题（非内置预设）会返回 nil
public init?(theme: RDEPUBReaderTheme) {
switch theme {
case .light:
@@ -98,30 +84,22 @@ public enum RDEPUBReaderThemePreset: String, Codable, CaseIterable, Equatable {
}
}
// MARK: - 阅读器用户设置
/// 阅读器的可持久化用户设置
/// 用于保存用户在设置面板中调整的阅读偏好（字号、行距、翻页模式、主题等）
/// 所有属性均为可选类型，只覆盖用户实际修改过的配置项
public struct RDEPUBReaderSettings: Codable, Equatable {
// MARK: 可调参数
/// 屏幕亮度（0.0 ~ 1.0），nil 表示使用系统亮度
public var brightness: CGFloat?
/// 用户选择的正文字号（pt），nil 表示使用默认值
public var fontSize: CGFloat?
/// 用户选择的正文字体，nil 表示使用默认值
public var fontChoice: RDEPUBReaderFontChoice?
/// 用户选择的行距倍数，nil 表示使用默认值
public var lineHeightMultiple: CGFloat?
/// 用户选择的栏数，nil 表示使用默认值
public var numberOfColumns: Int?
/// 用户选择的翻页模式，nil 表示使用默认值
public var displayMode: RDEPUBReaderDisplayMode?
/// 用户选择的主题预设，nil 表示使用默认值
public var themePreset: RDEPUBReaderThemePreset?
/// 初始化用户设置，所有参数默认为 nil
public init(
brightness: CGFloat? = nil,
fontSize: CGFloat? = nil,
@@ -140,10 +118,6 @@ public struct RDEPUBReaderSettings: Codable, Equatable {
self.themePreset = themePreset
}
/// 将用户设置覆盖到基础配置上，得到最终生效的阅读器配置
/// nil 属性不会覆盖基础配置的对应值
/// - Parameter configuration: 基础配置（通常来自 RDEPUBReaderConfiguration.default）
/// - Returns: 合并后的完整配置
public func applying(to configuration: RDEPUBReaderConfiguration) -> RDEPUBReaderConfiguration {
var resolvedConfiguration = configuration
@@ -169,12 +143,6 @@ public struct RDEPUBReaderSettings: Codable, Equatable {
return resolvedConfiguration
}
/// 从当前配置和亮度值捕获一份完整的用户设置快照
/// 亮度值会被限制在 0.0 ~ 1.0 范围内
/// - Parameters:
/// - configuration: 当前生效的阅读器配置
/// - brightness: 当前屏幕亮度
/// - Returns: 完整的用户设置实例
public static func capture(
configuration: RDEPUBReaderConfiguration,
brightness: CGFloat
Sources/RDReaderView/EPUBUI/Settings/RDEPUBReaderSettingsViewController.swift
+19 -19
View File
@@ -1,33 +1,23 @@
import UIKit
// MARK: - 设置面板
/// EPUB 阅读器的设置面板控制器
/// 提供亮度、字号、行距、翻页方式、主题的调节功能
/// 支持 iOS 13+ SF Symbols 和低版本文字回退
final class RDEPUBReaderSettingsViewController: UIViewController {
// MARK: 回调闭包
/// 亮度变化回调（0.0 ~ 1.0）
var onBrightnessChange: ((CGFloat) -> Void)?
/// 字号变化回调（pt 值）
var onFontSizeChange: ((CGFloat) -> Void)?
/// 字体变化回调
var onFontChoiceChange: ((RDEPUBReaderFontChoice) -> Void)?
/// 行距倍数变化回调
var onLineHeightChange: ((CGFloat) -> Void)?
/// 栏数变化回调
var onColumnCountChange: ((Int) -> Void)?
/// 翻页模式变化回调
var onDisplayTypeChange: ((RDReaderView.DisplayType) -> Void)?
/// 主题变化回调
var onThemeChange: ((RDEPUBReaderTheme) -> Void)?
/// 设置页面关闭回调
var onDismiss: (() -> Void)?
// MARK: 主题预设枚举
/// 设置面板中的主题预设枚举，用于按钮显示和主题切换
private enum ThemePreset: Int, CaseIterable {
case light
case yellow
@@ -60,20 +50,30 @@ final class RDEPUBReaderSettingsViewController: UIViewController {
}
private let scrollView = UIScrollView()
private let contentStack: UIStackView = {
let stackView = UIStackView()
stackView.axis = .vertical
stackView.spacing = 20
return stackView
}()
private let brightnessSlider = UISlider()
private let fontValueLabel = UILabel()
private let decreaseFontButton = UIButton(type: .system)
private let increaseFontButton = UIButton(type: .system)
private let fontChoiceControl = UISegmentedControl(items: RDEPUBReaderFontChoice.allCases.map(\.displayName))
private let lineHeightControl = UISegmentedControl(items: ["紧凑", "标准", "宽松"])
private let columnCountControl = UISegmentedControl(items: ["单栏", "双栏"])
private let displayTypeControl = UISegmentedControl(items: ["仿真", "横滑", "竖滑"])
private let themeStackView: UIStackView = {
let stackView = UIStackView()
stackView.axis = .horizontal
@@ -81,11 +81,11 @@ final class RDEPUBReaderSettingsViewController: UIViewController {
stackView.spacing = 12
return stackView
}()
private var themeButtons: [UIButton] = []
/// 行距选项对应的倍数值（紧凑 1.3、标准 1.6、宽松 1.9）
private let lineHeightValues: [CGFloat] = [1.3, 1.6, 1.9]
/// 当前配置的本地副本，修改后通过回调通知控制器
private var currentConfiguration: RDEPUBReaderConfiguration
init(configuration: RDEPUBReaderConfiguration, brightness: CGFloat) {
Sources/RDReaderView/EPUBUI/Settings/RDEPUBReaderTheme.swift
+5 -34
View File
@@ -1,37 +1,19 @@
import UIKit
// MARK: - 阅读器主题
/// EPUB 阅读器主题配置结构体
/// 定义阅读器内容区域和工具栏的颜色方案
/// 内置浅色、深色、黄色、绿色、粉色、蓝色六套预设主题
public struct RDEPUBReaderTheme: Equatable {
// MARK: 内容区颜色
/// 内容区域的背景色
public var contentBackgroundColor: UIColor
/// 内容区域的正文文字颜色
public var contentTextColor: UIColor
// MARK: 工具栏颜色
/// 工具栏背景色
public var toolBackgroundColor: UIColor
/// 工具栏控件文字/图标颜色
public var toolControlTextColor: UIColor
/// 工具栏控件未选中状态的边框颜色
public var toolControlBorderUnselectColor: UIColor
/// 工具栏中分隔线的颜色
public var toolLineColor: UIColor
/// 初始化主题配置
/// - Parameters:
/// - contentBackgroundColor: 内容区背景色
/// - contentTextColor: 内容区文字颜色
/// - toolBackgroundColor: 工具栏背景色
/// - toolControlTextColor: 工具栏控件颜色
/// - toolControlBorderUnselectColor: 控件未选中边框色
/// - toolLineColor: 分隔线颜色
public init(
contentBackgroundColor: UIColor,
contentTextColor: UIColor,
@@ -48,9 +30,6 @@ public struct RDEPUBReaderTheme: Equatable {
self.toolLineColor = toolLineColor
}
// MARK: 内置预设主题
/// 浅色主题：白底黑字，适合日间阅读
public static let light = RDEPUBReaderTheme(
contentBackgroundColor: .white,
contentTextColor: .black,
@@ -60,7 +39,6 @@ public struct RDEPUBReaderTheme: Equatable {
toolLineColor: UIColor.lightGray.withAlphaComponent(0.5)
)
/// 深色主题：黑底白字，适合夜间阅读
public static let dark = RDEPUBReaderTheme(
contentBackgroundColor: .black,
contentTextColor: .white,
@@ -70,7 +48,6 @@ public struct RDEPUBReaderTheme: Equatable {
toolLineColor: UIColor.lightGray.withAlphaComponent(0.5)
)
/// 黄色护眼主题：暖色调背景，减少蓝光刺激
public static let yellow = RDEPUBReaderTheme(
contentBackgroundColor: UIColor(red: 0.89, green: 0.87, blue: 0.79, alpha: 1),
contentTextColor: .black,
@@ -80,7 +57,6 @@ public struct RDEPUBReaderTheme: Equatable {
toolLineColor: UIColor.lightGray.withAlphaComponent(0.5)
)
/// 绿色护眼主题：模拟纸质书的柔和绿色背景
public static let green = RDEPUBReaderTheme(
contentBackgroundColor: UIColor(red: 0.87, green: 0.91, blue: 0.82, alpha: 1),
contentTextColor: .black,
@@ -90,7 +66,6 @@ public struct RDEPUBReaderTheme: Equatable {
toolLineColor: UIColor.lightGray.withAlphaComponent(0.5)
)
/// 粉色主题：柔和粉色背景
public static let pink = RDEPUBReaderTheme(
contentBackgroundColor: UIColor(red: 1, green: 0.89, blue: 0.91, alpha: 1),
contentTextColor: .black,
@@ -100,7 +75,6 @@ public struct RDEPUBReaderTheme: Equatable {
toolLineColor: UIColor.lightGray.withAlphaComponent(0.5)
)
/// 蓝色主题：冷色调蓝色背景
public static let blue = RDEPUBReaderTheme(
contentBackgroundColor: UIColor(red: 0.8, green: 0.84, blue: 0.89, alpha: 1),
contentTextColor: .black,
@@ -111,15 +85,12 @@ public struct RDEPUBReaderTheme: Equatable {
)
}
// MARK: - CSS 颜色转换
extension RDEPUBReaderTheme {
/// 将内容区背景色转换为 CSS 颜色字符串，注入 EPUB 的 HTML 中
var themeBackgroundColorCSS: String {
contentBackgroundColor.ss_cssString
}
/// 将内容区文字颜色转换为 CSS 颜色字符串，注入 EPUB 的 HTML 中
var themeTextColorCSS: String {
contentTextColor.ss_cssString
}