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/EPUBTextRendering/BuildPipeline/RDEPUBBuildDiagnosticsReporter.swift
+7 -1
View File
@@ -1,16 +1,18 @@
import Foundation
/// Builds diagnostics and human-readable summaries for a text book build.
struct RDEPUBBuildDiagnosticsReporter {
func phase7SemanticSummary(
title: String?,
diagnostics: [RDEPUBTextChapterPaginationDiagnostic]
) -> String? {
guard !diagnostics.isEmpty else { return nil }
let blockKinds = uniqueValues(from: diagnostics.flatMap(\.blockKinds))
let semanticHints = uniqueValues(from: diagnostics.flatMap(\.semanticHints))
let attachmentPlacements = uniqueValues(from: diagnostics.flatMap(\.attachmentPlacements))
let note = diagnostics
.flatMap(\.sampleNotes)
.first(where: { $0.contains("semantic") || $0.contains("attachment") || $0.contains("block kinds") })
@@ -22,6 +24,7 @@ struct RDEPUBBuildDiagnosticsReporter {
semanticHints.isEmpty ? nil : "hints [\(semanticHints.map(\.rawValue).joined(separator: ","))]",
attachmentPlacements.isEmpty ? nil : "placements [\(attachmentPlacements.map(\.rawValue).joined(separator: ","))]"
].compactMap { $0 }
if let note {
parts.append(note)
}
@@ -38,11 +41,14 @@ struct RDEPUBBuildDiagnosticsReporter {
title: title,
pageCount: pages.count,
breakReasons: pages.map(\.metadata.breakReason),
attachmentPageCount: pages.filter { !$0.metadata.attachmentKinds.isEmpty }.count,
blockAdjustedPageCount: pages.filter { $0.metadata.breakReason == .blockBoundary || $0.metadata.breakReason == .attachmentBoundary }.count,
blockKinds: uniqueValues(from: pages.flatMap(\.metadata.blockKinds)),
semanticHints: uniqueValues(from: pages.flatMap(\.metadata.semanticHints)),
attachmentPlacements: uniqueValues(from: pages.flatMap(\.metadata.attachmentPlacements)),
sampleNotes: Array(pages.flatMap(\.metadata.diagnostics).prefix(4))
)
}
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBChapterTailNormalizer.swift
+9 -1
View File
@@ -1,12 +1,13 @@
import Foundation
/// Normalizes suspicious trailing or whitespace-only page frames after pagination.
struct RDEPUBChapterTailNormalizer {
func normalize(
_ frames: [RDEPUBTextLayoutFrame],
content: NSAttributedString,
href: String
) -> [RDEPUBTextLayoutFrame] {
guard frames.count > 1 else { return frames }
var normalized = frames
@@ -16,10 +17,12 @@ struct RDEPUBChapterTailNormalizer {
for frame in normalized {
if shouldDropWhitespaceOnlyFrame(frame, in: content) {
let note = "normalized: dropped whitespace-only intermediate page \(NSStringFromRange(frame.contentRange))"
if var previous = compacted.popLast() {
previous.diagnostics.append(note)
compacted.append(previous)
} else {
#if DEBUG
print("[EPUB][Pagination] href=\(href) dropped leading/intermediate whitespace frame \(NSStringFromRange(frame.contentRange))")
#endif
@@ -73,6 +76,7 @@ struct RDEPUBChapterTailNormalizer {
previousFrame: RDEPUBTextLayoutFrame,
in content: NSAttributedString
) -> Bool {
guard trailingFrame.contentRange.length > 0,
NSMaxRange(previousFrame.contentRange) == trailingFrame.contentRange.location else {
return false
@@ -80,6 +84,7 @@ struct RDEPUBChapterTailNormalizer {
let visibleCount = visibleCharacterCount(in: content, range: trailingFrame.contentRange)
let trailingAttachmentCount = attachmentCount(in: content, range: trailingFrame.contentRange)
guard visibleCount <= 2,
trailingFrame.contentRange.length <= 2,
visibleCount > 0 || trailingAttachmentCount > 0 else {
@@ -94,6 +99,7 @@ struct RDEPUBChapterTailNormalizer {
_ previousFrame: RDEPUBTextLayoutFrame,
with trailingFrame: RDEPUBTextLayoutFrame
) -> RDEPUBTextLayoutFrame {
let mergedRange = NSRange(
location: previousFrame.contentRange.location,
length: NSMaxRange(trailingFrame.contentRange) - previousFrame.contentRange.location
@@ -109,6 +115,7 @@ struct RDEPUBChapterTailNormalizer {
semanticHints: uniqueValues(from: previousFrame.semanticHints + trailingFrame.semanticHints),
attachmentPlacements: uniqueValues(from: previousFrame.attachmentPlacements + trailingFrame.attachmentPlacements),
trailingFragmentID: trailingFrame.trailingFragmentID ?? previousFrame.trailingFragmentID,
diagnostics: previousFrame.diagnostics
+ trailingFrame.diagnostics
+ ["normalized: merged short trailing page \(NSStringFromRange(trailingFrame.contentRange)) into previous page"]
@@ -121,6 +128,7 @@ struct RDEPUBChapterTailNormalizer {
) -> Int {
guard range.length > 0 else { return 0 }
let string = content.attributedSubstring(from: range).string
let filteredScalars = string.unicodeScalars.filter { scalar in
!CharacterSet.whitespacesAndNewlines.contains(scalar)
&& !CharacterSet.controlCharacters.contains(scalar)
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBPaginationCacheCoordinator.swift
+4 -1
View File
@@ -1,8 +1,9 @@
import UIKit
/// Keeps pagination cache key generation and cache IO in one BuildPipeline role.
struct RDEPUBPaginationCacheCoordinator {
private let cache: RDEPUBTextBookCache?
private let layoutConfig: RDEPUBTextLayoutConfig
init(cache: RDEPUBTextBookCache?, layoutConfig: RDEPUBTextLayoutConfig) {
@@ -32,11 +33,13 @@ struct RDEPUBPaginationCacheCoordinator {
func save(chapters: [RDEPUBTextChapter], key: String?) {
guard let key else { return }
let paginationCache = chapters.map { chapter in
RDEPUBTextChapterPaginationCache(
href: chapter.href,
pageRanges: chapter.pages.map(\.contentRange),
breakReasons: chapter.pages.map(\.metadata.breakReason),
semanticHints: Array(Set(chapter.pages.flatMap(\.metadata.semanticHints)))
)
}
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookBuilder.swift
+13 -39
View File
@@ -1,6 +1,5 @@
import UIKit
/// EPUB 文本书籍构建器，负责将 EPUB publication 渲染、分页并组装为 `RDEPUBTextBook`。
public final class RDEPUBTextBookBuilder {
private let renderer: RDEPUBTextRenderer
private let cache: RDEPUBTextBookCache?
@@ -12,20 +11,14 @@ public final class RDEPUBTextBookBuilder {
private let cacheCoordinator: RDEPUBPaginationCacheCoordinator
private let diagnosticsReporter: RDEPUBBuildDiagnosticsReporter
/// 最后一次构建的资源引用诊断（样式表、图片等）
public private(set) var lastBuildResourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic] = []
/// 最后一次构建的分页诊断（每章一页的分页原因、附件统计等）
public private(set) var lastBuildPaginationDiagnostics: [RDEPUBTextChapterPaginationDiagnostic] = []
/// 最后一次构建的性能采样数据
public private(set) var lastBuildPerformanceSamples: [RDEPUBTextPerformanceSample] = []
/// 最后一次构建的缓存命中/未命中统计
public private(set) var lastBuildCacheStats: (hits: Int, misses: Int) = (0, 0)
/// 创建书籍构建器。
/// - Parameters:
/// - renderer: 文本渲染器
/// - cache: 分页缓存（可选）
/// - layoutConfig: 页面布局配置
public init(
renderer: RDEPUBTextRenderer,
cache: RDEPUBTextBookCache? = nil,
@@ -42,7 +35,6 @@ public final class RDEPUBTextBookBuilder {
self.diagnosticsReporter = RDEPUBBuildDiagnosticsReporter()
}
/// 默认构造器，使用 DTCoreText 渲染器
public convenience init() {
self.init(renderer: RDEPUBDTCoreTextRenderer())
}
@@ -51,7 +43,6 @@ public final class RDEPUBTextBookBuilder {
ProcessInfo.processInfo.arguments.contains("--demo-pagination-debug")
}
/// 生成最近一次构建的语义摘要，用于 Phase 7 质量检测日志
public func phase7SemanticSummary(title: String? = nil) -> String? {
diagnosticsReporter.phase7SemanticSummary(
title: title,
@@ -59,16 +50,6 @@ public final class RDEPUBTextBookBuilder {
)
}
/// 核心构建方法：从 EPUB publication 构建分页书籍。
///
/// 流程：
/// 1. 生成缓存键，尝试加载分页缓存
/// 2. 遍历 spine 中的线性 HTML 章节
/// 3. 渲染每章 HTML → NSAttributedString
/// 4. 跳过空白的封面/扉页章节
/// 5. 分页：缓存命中则使用缓存的页范围，否则调用 CoreText 分页引擎
/// 6. 尾页规范化：丢弃纯空白尾页、合并过短尾页
/// 7. 构建 RDEPUBTextBook 并保存分页缓存
public func build(
parser: RDEPUBParser,
publication: RDEPUBPublication,
@@ -88,7 +69,6 @@ public final class RDEPUBTextBookBuilder {
let buildStart = CFAbsoluteTimeGetCurrent()
// 缓存查询 — WXRead 模式：只加载每章的页范围，不缓存富文本
let bookID = publication.metadata.identifier ?? publication.metadata.title
let cacheKey = cacheCoordinator.cacheKey(bookID: bookID, pageSize: pageSize, style: style)
let cachedPagination = cacheCoordinator.load(key: cacheKey)
@@ -134,7 +114,6 @@ public final class RDEPUBTextBookBuilder {
sampler.totalBuildDuration = CFAbsoluteTimeGetCurrent() - buildStart
// 保存分页缓存（只缓存页范围和分页原因，不缓存富文本）
cacheCoordinator.save(chapters: chapters, key: cacheKey)
#if DEBUG
@@ -145,7 +124,6 @@ public final class RDEPUBTextBookBuilder {
return book
}
/// 构建指定 spine 章节，用于大书快速首屏和后台增量补齐。
public func buildChapter(
parser: RDEPUBParser,
publication: RDEPUBPublication,
@@ -192,6 +170,7 @@ public final class RDEPUBTextBookBuilder {
let request = RDEPUBTextTypesetterPipeline().makeRequest(
from: RDEPUBTypesettingInput(
href: item.href,
spineIndex: spineIndex,
title: chapterTitle,
rawHTML: rawHTML,
baseURL: parser.fileURL(forRelativePath: item.href)?.deletingLastPathComponent(),
@@ -281,11 +260,13 @@ public final class RDEPUBTextBookBuilder {
}
let paginateDuration = CFAbsoluteTimeGetCurrent() - paginateStart
let normalizedFrames = tailNormalizer.normalize(
layoutFrames,
content: content,
href: item.href
)
let effectiveFrames = normalizedFrames.isEmpty && content.length > 0
? [
RDEPUBTextLayoutFrame(
@@ -339,6 +320,12 @@ public final class RDEPUBTextBookBuilder {
title: chapterTitle,
attributedContent: chapterAttributedContent,
fragmentOffsets: rendered.fragmentOffsets,
cfiMap: RDEPUBCFITextNodeMapBuilder.makeMap(
href: item.href,
rawHTML: rawHTML,
chapterText: chapterAttributedContent.string,
fragmentOffsets: rendered.fragmentOffsets
),
pageBreakReasons: pages.map(\.metadata.breakReason),
pages: pages
)
@@ -365,9 +352,6 @@ public final class RDEPUBTextBookBuilder {
)
}
// MARK: - 章节标题解析
/// 从目录表中查找章节标题，找不到则回退到 spine item 的 title 或 href
private func resolvedChapterTitle(for item: RDEPUBSpineItem, toc: [EPUBTableOfContentsItem]) -> String {
if let title = flattenedTOCItems(from: toc).first(where: { tocItem in
tocItem.href.components(separatedBy: "#").first == item.href
@@ -378,16 +362,12 @@ public final class RDEPUBTextBookBuilder {
return trimmedTitle.isEmpty ? item.href : trimmedTitle
}
/// 递归展开嵌套目录为扁平列表
private func flattenedTOCItems(from items: [EPUBTableOfContentsItem]) -> [EPUBTableOfContentsItem] {
items.flatMap { item in
[item] + flattenedTOCItems(from: item.children)
}
}
// MARK: - 章节过滤
/// 判断是否应跳过该章节（空白的封面/扉页，无文本且无附件）
private func shouldSkipChapter(item: RDEPUBSpineItem, content: NSAttributedString, text: String) -> Bool {
let lowercasedHref = item.href.lowercased()
var hasAttachment = false
@@ -404,9 +384,6 @@ public final class RDEPUBTextBookBuilder {
return false
}
// MARK: - 附件统计
/// 统计富文本中的附件数量
private func attachmentCount(in content: NSAttributedString) -> Int {
guard content.length > 0 else { return 0 }
var count = 0
@@ -418,7 +395,6 @@ public final class RDEPUBTextBookBuilder {
return count
}
/// 获取富文本中所有附件的 NSRange 列表
private func attachmentRanges(in content: NSAttributedString) -> [NSRange] {
guard content.length > 0 else { return [] }
var ranges: [NSRange] = []
@@ -430,9 +406,6 @@ public final class RDEPUBTextBookBuilder {
return ranges
}
// MARK: - 封面章节检测
/// 判断是否为纯图片封面章节（href 包含 cover 且有附件但几乎无文本）
private func isAttachmentOnlyCoverChapter(
item: RDEPUBSpineItem,
content: NSAttributedString,
@@ -445,6 +418,7 @@ public final class RDEPUBTextBookBuilder {
}
private func debugPreview(for content: NSAttributedString, limit: Int) -> String {
let collapsed = content.string
.replacingOccurrences(of: "\n", with: " ")
.replacingOccurrences(of: "\r", with: " ")
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookCache.swift
+12 -50
View File
@@ -1,19 +1,14 @@
import Foundation
import CryptoKit
// MARK: - 分页缓存数据模型（WXRead 模式：只缓存页范围，不缓存富文本）
/// 单个章节的分页元数据缓存，用于磁盘持久化。
///
/// 对标 WXRead 的 WRChapterPageCount 缓存策略：只存储每页的 NSRange + 分页原因，
/// 不缓存完整的 NSAttributedString。缓存命中时重新渲染 HTML，但跳过 CoreText 分页步骤。
public struct RDEPUBTextChapterPaginationCache: Equatable {
/// 章节文件相对路径
public var href: String
/// 每页在章节富文本中的字符范围
public var pageRanges: [NSRange]
/// 每页的分页原因（语义边界、帧限制等）
public var breakReasons: [RDEPUBTextPageBreakReason]
public var semanticHints: [RDEPUBTextSemanticHint]
public init(
@@ -29,11 +24,8 @@ public struct RDEPUBTextChapterPaginationCache: Equatable {
}
}
// MARK: - NSCoding 归档层（只使用字符串和整数类型）
/// 整本书的分页缓存归档，用于 NSKeyedArchiver 序列化。
/// 包含所有章节的分页归档数据。
final class PaginationCacheArchive: NSObject, NSSecureCoding {
static var supportsSecureCoding: Bool { true }
let chapters: [ChapterPaginationArchive]
@@ -52,20 +44,20 @@ final class PaginationCacheArchive: NSObject, NSSecureCoding {
}
}
/// 单个章节的分页归档，将 NSRange 拆分为 location/length 数组以便 NSSecureCoding 编码。
final class ChapterPaginationArchive: NSObject, NSSecureCoding {
static var supportsSecureCoding: Bool { true }
let href: String
/// 页范围的起始位置数组（与 rangeLengths 一一对应）
let rangeLocations: [NSNumber]
/// 页范围的长度数组
let rangeLengths: [NSNumber]
/// 分页原因的原始字符串数组
let breakReasons: [String]
/// 语义提示的原始字符串数组
let semanticHints: [String]
/// 从缓存模型构建归档对象
init(from cache: RDEPUBTextChapterPaginationCache) {
self.href = cache.href
self.rangeLocations = cache.pageRanges.map { NSNumber(value: $0.location) }
@@ -97,7 +89,6 @@ final class ChapterPaginationArchive: NSObject, NSSecureCoding {
self.semanticHints = semanticHints
}
/// 将归档数据转换回缓存模型
func toCache() -> RDEPUBTextChapterPaginationCache {
let pageRanges = zip(rangeLocations, rangeLengths).map { loc, len in
NSRange(location: loc.intValue, length: len.intValue)
@@ -111,28 +102,14 @@ final class ChapterPaginationArchive: NSObject, NSSecureCoding {
}
}
// MARK: - 分页缓存管理器
/// 磁盘持久化的分页缓存层，对标 WXRead 的 WRChapterPageCount 缓存模式。
///
/// 缓存策略：
/// - 缓存键 = SHA256(书籍ID + 字号 + 行距 + 内边距 + 页面尺寸 + schema版本)
/// - 缓存值 = 每章的页 NSRange 列表 + 分页原因（NSKeyedArchiver 序列化）
/// - 富文本不缓存：缓存命中时重新渲染 HTML，但跳过 CoreText 分页步骤
/// - 线程安全：所有读写操作通过 serial DispatchQueue 串行执行
public final class RDEPUBTextBookCache {
/// 缓存模式版本号，变更时旧缓存自动失效
// 分页算法调整后需要提升版本，避免继续复用旧页范围缓存。
public var schemaVersion: Int = 6
/// 串行队列，保证缓存读写的线程安全
private let queue = DispatchQueue(label: "com.rdreader.textbookcache", qos: .utility)
/// 缓存文件目录
private let cacheDirectory: URL
/// 初始化缓存管理器，自动创建缓存目录
/// - Parameter subdirectory: Caches 目录下的子目录名
public init(subdirectory: String = "RDEPUBTextBookCache") {
let baseURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
.appendingPathComponent(subdirectory, isDirectory: true)
@@ -141,13 +118,6 @@ public final class RDEPUBTextBookCache {
try? FileManager.default.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
}
// MARK: - 缓存键生成
// 对标 WRChapterPageCount.currentCacheKeyWithBookId：
// 编码 bookID + fontSize + lineHeightMultiple + contentInsets + pageSize
/// 生成缓存文件名（SHA256 哈希 + ".cache" 后缀）。
///
/// 任意布局参数变更都会导致缓存键不同，从而自动失效。
public func cacheKey(
bookID: String,
fontSize: CGFloat,
@@ -162,10 +132,6 @@ public final class RDEPUBTextBookCache {
return hex + ".cache"
}
// MARK: - 加载/保存（只缓存分页元数据）
/// 从磁盘加载缓存的分页元数据，返回以章节 href 为键的字典。
/// 缓存未命中或反序列化失败时返回 nil。
public func load(key: String) -> [String: RDEPUBTextChapterPaginationCache]? {
queue.sync {
let fileURL = cacheDirectory.appendingPathComponent(key)
@@ -203,7 +169,6 @@ public final class RDEPUBTextBookCache {
}
}
/// 将分页元数据保存到磁盘（原子写入，防止损坏）
public func save(_ chapters: [RDEPUBTextChapterPaginationCache], key: String) {
queue.sync {
let fileURL = cacheDirectory.appendingPathComponent(key)
@@ -223,9 +188,6 @@ public final class RDEPUBTextBookCache {
}
}
// MARK: - 缓存失效
/// 清除所有缓存文件
public func invalidateAll() {
queue.sync {
let fileManager = FileManager.default
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBookModels.swift
+42 -50
View File
@@ -1,93 +1,99 @@
import UIKit
// MARK: - 章节分页诊断数据
/// 单个章节的分页诊断信息，用于调试和质量检测。
/// 记录页数、分页原因、附件/块级元素统计等。
public struct RDEPUBTextChapterPaginationDiagnostic: Equatable {
public var href: String
public var title: String
public var pageCount: Int
/// 每页的分页原因列表
public var breakReasons: [RDEPUBTextPageBreakReason]
/// 包含附件的页数
public var attachmentPageCount: Int
/// 因块级/附件边界调整而分页的页数
public var blockAdjustedPageCount: Int
public var blockKinds: [RDEPUBTextBlockKind]
public var semanticHints: [RDEPUBTextSemanticHint]
public var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
/// 采样诊断日志（最多 4 条）
public var sampleNotes: [String]
}
// MARK: - 章节构建结果
/// 单章构建结果，用于大书快速进入阅读器和后台增量补齐。
public struct RDEPUBTextChapterBuildResult {
public var chapter: RDEPUBTextChapter
public var resourceDiagnostics: [RDEPUBTextResourceReferenceDiagnostic]
public var paginationDiagnostic: RDEPUBTextChapterPaginationDiagnostic
public var performanceSample: RDEPUBTextPerformanceSample
public var cacheHit: Bool
}
// MARK: - 页面数据模型
/// 分页后的单页数据，包含全书绝对页码、所属章节、内容范围等。
///
/// 每个 `RDEPUBTextPage` 由 `RDEPUBTextLayoutFrame` 生成，
/// `contentRange` 标记了该页在章节富文本中的字符范围。
public struct RDEPUBTextPage: Equatable {
/// 全书绝对页码（从 0 开始）
public var absolutePageIndex: Int
public var chapterIndex: Int
public var spineIndex: Int
public var href: String
public var chapterTitle: String
/// 该页在所属章节中的相对页码（从 0 开始）
public var pageIndexInChapter: Int
public var totalPagesInChapter: Int
/// 所属章节的完整富文本内容（用于跨页查询）
public var chapterContent: NSAttributedString
/// 该页的富文本片段
public var content: NSAttributedString
/// 该页在章节富文本中的范围
public var contentRange: NSRange
public var pageStartOffset: Int
public var pageEndOffset: Int
/// 页的元数据（分页原因、附件、语义标记等）
public var metadata: RDEPUBTextPageMetadata
}
// MARK: - 章节数据模型
/// 渲染并分页后的单个章节，包含完整富文本和分页结果。
public struct RDEPUBTextChapter: Equatable {
public var chapterIndex: Int
public var spineIndex: Int
public var href: String
public var title: String
/// 章节完整富文本内容
public var attributedContent: NSAttributedString
/// fragment ID → 字符偏移量映射（用于锚点定位）
public var fragmentOffsets: [String: Int]
public var cfiMap: RDEPUBCFIMap?
public var pageBreakReasons: [RDEPUBTextPageBreakReason]
public var pages: [RDEPUBTextPage]
}
// MARK: - 分页书籍模型
/// 整本 EPUB 的分页书籍模型，包含所有章节、页面和全局索引表。
///
/// 这是 EPUBTextRendering 层的最终产物，由 `RDEPUBTextBookBuilder.build()` 生成。
/// 通过 `chapterData(for:)` 或 `chapterData(atChapterIndex:)` 获取 `RDEPUBChapterData` 进行查询。
public struct RDEPUBTextBook {
public var chapters: [RDEPUBTextChapter]
public var pages: [RDEPUBTextPage]
/// 全局索引表：fileIndex/row/column → 绝对字符偏移量
public let indexTable: RDEPUBTextIndexTable
/// 对标 WXRead 的位置转换器（文件位置 <-> 全书字符位置 <-> 页码）
public var positionConverter: RDEPUBTextPositionConverter {
RDEPUBTextPositionConverter(book: self)
}
@@ -102,31 +108,26 @@ public struct RDEPUBTextBook {
lhs.chapters == rhs.chapters && lhs.pages == rhs.pages
}
/// 按 href 获取章节的数据访问层（包含索引表）
public func chapterData(for href: String) -> RDEPUBChapterData? {
guard let chapter = chapters.first(where: { $0.href == href }) else { return nil }
return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
}
/// 按 spine 索引获取章节的数据访问层。
public func chapterData(forSpineIndex spineIndex: Int) -> RDEPUBChapterData? {
guard let chapter = chapters.first(where: { $0.spineIndex == spineIndex }) else { return nil }
return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
}
/// 按章节序号获取章节的数据访问层
public func chapterData(atChapterIndex index: Int) -> RDEPUBChapterData? {
guard chapters.indices.contains(index) else { return nil }
return RDEPUBChapterData(chapter: chapters[index], indexTable: indexTable)
}
/// 按绝对页码（从 1 开始）获取章节的数据访问层。
public func chapterData(forPageNumber pageNumber: Int) -> RDEPUBChapterData? {
guard let page = page(at: pageNumber) else { return nil }
return chapterData(forSpineIndex: page.spineIndex)
}
/// 根据持久化位置解析所属章节的数据访问层。
public func chapterData(
for location: RDEPUBLocation,
resolver: RDEPUBResourceResolver,
@@ -138,7 +139,6 @@ public struct RDEPUBTextBook {
return chapterData(for: normalizedLocation.href)
}
/// 全书章节信息快照；对标 WXRead 由章节模型直接提供章节元数据。
public var chapterInfos: [EPUBChapterInfo] {
chapters.map { chapter in
EPUBChapterInfo(
@@ -149,7 +149,6 @@ public struct RDEPUBTextBook {
}
}
/// 按页码（从 1 开始）获取对应页面
public func page(at pageNumber: Int) -> RDEPUBTextPage? {
guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else {
return nil
@@ -157,12 +156,6 @@ public struct RDEPUBTextBook {
return pages[pageNumber - 1]
}
/// 根据持久化位置计算对应页码（从 1 开始）。
///
/// 解析优先级：
/// 1. rangeAnchor 锚点定位
/// 2. fragment 片段 ID
/// 3. navigationProgression 进度百分比回退
public func pageNumber(for location: RDEPUBLocation, resolver: RDEPUBResourceResolver, bookIdentifier: String?) -> Int? {
guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier),
let chapterData = chapterData(for: normalizedLocation.href) else {
@@ -182,7 +175,6 @@ public struct RDEPUBTextBook {
return chapterData.pageNumber(for: normalizedLocation)
}
/// 根据页码生成持久化位置（RDEPUBLocation），包含起止锚点
public func location(forPageNumber pageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
guard let chapterData = chapterData(forPageNumber: pageNumber),
let page = page(at: pageNumber) else {
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextBuildPipelineInterfaces.swift
+1 -19
View File
@@ -1,10 +1,8 @@
// RDEPUBTextBuildPipelineInterfaces.swift
// EPUB 文本构建管线接口定义，包括全书构建、章节渲染与分页管线。
import UIKit
/// EPUB 全书文本构建接口，将 EPUB 出版物解析为可分页的文本书籍。
protocol RDEPUBTextBookBuilding {
func build(
parser: RDEPUBParser,
publication: RDEPUBPublication,
@@ -13,41 +11,25 @@ protocol RDEPUBTextBookBuilding {
) throws -> RDEPUBTextBook
}
/// 章节渲染管线，将章节渲染请求委托给底层文本渲染器。
struct RDEPUBChapterRenderPipeline {
private let renderer: RDEPUBTextRenderer
/// 初始化渲染管线。
/// - Parameter renderer: 文本渲染器实例
init(renderer: RDEPUBTextRenderer) {
self.renderer = renderer
}
/// 渲染单个章节，返回渲染后的富文本内容。
/// - Parameter request: 章节渲染请求
/// - Returns: 渲染完成的章节内容
func render(_ request: RDEPUBTextChapterRenderRequest) throws -> RDEPUBRenderedChapterContent {
try renderer.renderChapter(request: request)
}
}
/// 章节分页管线，将渲染后的富文本按页面尺寸拆分为文本帧数组。
struct RDEPUBChapterPaginationPipeline {
private let frameFactory: RDEPUBPageFrameBuilding
/// 初始化分页管线。
/// - Parameter frameFactory: 页面帧工厂，默认使用 CoreText 实现
init(frameFactory: RDEPUBPageFrameBuilding = RDEPUBCoreTextPageFrameFactory()) {
self.frameFactory = frameFactory
}
/// 将富文本内容分页，返回页面帧数组。
/// - Parameters:
/// - content: 待分页的富文本
/// - pageSize: 页面尺寸
/// - config: 排版配置
/// - fragmentOffsets: fragment 锚点偏移映射
/// - Returns: 页面帧数组
func frames(
for content: NSAttributedString,
pageSize: CGSize,
Sources/RDReaderView/EPUBTextRendering/BuildPipeline/RDEPUBTextPerformanceSampler.swift
+8 -21
View File
@@ -1,20 +1,17 @@
import Foundation
// MARK: - 性能采样数据模型
/// 单个章节的性能采样数据，记录渲染和分页的耗时。
public struct RDEPUBTextPerformanceSample: Equatable {
/// 章节文件路径
public var chapterHref: String
/// HTML 渲染耗时（秒）
public var renderDuration: TimeInterval
/// CoreText 分页耗时（秒）
public var paginateDuration: TimeInterval
/// 分页后的页数
public var pageCount: Int
/// 富文本字符长度
public var attributedStringLength: Int
/// 是否命中分页缓存
public var cacheHit: Bool
public init(
@@ -34,21 +31,14 @@ public struct RDEPUBTextPerformanceSample: Equatable {
}
}
// MARK: - 性能采样器
/// 书籍构建过程的性能采样器，用于监控每章的渲染和分页耗时。
///
/// 由 `RDEPUBTextBookBuilder` 在构建过程中使用，每章记录一个采样点，
/// 构建完成后输出汇总报告。
public final class RDEPUBTextPerformanceSampler {
/// 所有章节的采样数据列表
public private(set) var samples: [RDEPUBTextPerformanceSample] = []
/// 整本书构建的总耗时（秒）
public var totalBuildDuration: TimeInterval = 0
public init() {}
/// 记录单个章节的性能采样，并输出日志
public func record(_ sample: RDEPUBTextPerformanceSample) {
samples.append(sample)
#if DEBUG
@@ -56,7 +46,6 @@ public final class RDEPUBTextPerformanceSampler {
#endif
}
/// 生成性能汇总报告，包含总渲染/分页耗时和缓存命中率
public func summary() -> String {
let totalRender = samples.reduce(0) { $0 + $1.renderDuration }
let totalPaginate = samples.reduce(0) { $0 + $1.paginateDuration }
@@ -64,13 +53,11 @@ public final class RDEPUBTextPerformanceSampler {
return "[PERF] chapters=\(samples.count) render=\(formatMS(totalRender)) paginate=\(formatMS(totalPaginate)) total=\(formatMS(totalBuildDuration)) cacheHits=\(hitCount)/\(samples.count)"
}
/// 重置所有采样数据
public func reset() {
samples.removeAll()
totalBuildDuration = 0
}
/// 将秒转换为毫秒格式字符串
private func formatMS(_ duration: TimeInterval) -> String {
String(format: "%.0fms", duration * 1000)
}