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

refactor: 添加中文注释 + 优化模块结构

Browse Source 
- 给全部 78 个 Swift 源文件添加详细的中文注释（文件级、类级、方法级）
- 删除 LegacyRDReaderController/ 死代码目录（16 文件 4592 行）
- 根目录翻页容器文件移入 ReaderView/ 目录
- Resources/ 移入 EPUBCore/Resources/（与使用者归属一致）
- RDEPUBTextIndexTable.swift 移入 EPUBTextRendering/（消除反向依赖）
- RDURLReaderController.swift 移入 EPUBUI/（入口控制器归入 UI 层）
- 更新 podspec 资源路径
This commit is contained in:
shen
2026-05-25 10:19:14 +08:00
parent 5af90c1148
commit 54798ba578
88 changed files with 2492 additions and 4469 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift
+92 -14
View File
@@ -5,11 +5,29 @@ import UIKit
import DTCoreText
#endif
/// CoreText 分页引擎：将富文本按页面尺寸拆分为多帧（每帧对应一页）。
///
/// 分页策略优先级（从高到低）：
/// 1. avoidPageBreakInside — 不在保护块内分页（对标 WXRead 的行级回退扫描）
/// 2. keepWithNext — 标题等元素需与下一段同页
/// 3. 语义边界 — pageBreakBefore/After 等显式分页标记
/// 4. pageRelate — 微信读书式的跨页关联元素
/// 5. 附件边界 — 块级附件应整体移到下一页
/// 6. 帧限制 — 默认按 CoreText 可视范围分页
///
/// 支持两条渲染路径：
/// - DTCoreText 路径（首选）：DTCoreTextLayouter → DTCoreTextLayoutFrame
/// - CoreText 回退路径：CTFramesetterCreateFrame
struct RDEPUBTextLayouter {
/// 待分页的富文本
private let attributedString: NSAttributedString
/// 页面尺寸（决定每帧能容纳多少内容）
private let pageSize: CGSize
/// CoreText 帧设置器
private let framesetter: CTFramesetter
/// 页面矩形路径（用于 CTFrame 排版）
private let path: CGPath
/// 布局配置（avoidPageBreakInside、孤行控制等）
private let config: RDEPUBTextLayoutConfig
init(attributedString: NSAttributedString, pageSize: CGSize, config: RDEPUBTextLayoutConfig = .default) {
@@ -20,6 +38,8 @@ struct RDEPUBTextLayouter {
self.path = CGPath(rect: CGRect(origin: .zero, size: pageSize), transform: nil)
}
/// 执行分页，返回布局帧列表（每帧对应一页）。
/// 根据编译环境选择 DTCoreText 或 CoreText 路径。
func layoutFrames(fragmentOffsets: [String: Int] = [:]) -> [RDEPUBTextLayoutFrame] {
guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
return []
@@ -32,6 +52,11 @@ struct RDEPUBTextLayouter {
#endif
}
// MARK: - CoreText 分页路径（回退方案）
/// 使用原生 CoreText API 进行分页。
///
/// 流程：CTFramesetterCreateFrame → 获取可视范围 → 语义边界调整 → 记录帧
private func layoutFramesUsingCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
return []
@@ -49,7 +74,7 @@ struct RDEPUBTextLayouter {
let proposedRange = NSRange(location: location, length: visibleRange.length)
// Line-level avoidPageBreakInside (WXRead approach: scan CTFrame lines backward)
// 行级 avoidPageBreakInside 处理（WXRead 方案：从最后一行向前扫描）
let avoidAdjusted = trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
let lineAdjusted = trimmedRangeForKeepWithNext(from: frame, proposed: avoidAdjusted)
let lineRanges = lineRanges(from: frame)
@@ -89,7 +114,10 @@ struct RDEPUBTextLayouter {
return frames
}
// MARK: - DTCoreText 分页路径（首选方案）
#if canImport(DTCoreText)
/// 使用 DTCoreTextLayouter 进行分页，提供更精确的行级语义处理。
private func layoutFramesUsingDTCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
guard let layouter = DTCoreTextLayouter(attributedString: attributedString) else {
return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
@@ -152,6 +180,18 @@ struct RDEPUBTextLayouter {
}
#endif
// MARK: - 语义边界调整
/// 对 CoreText 提出的分页范围进行语义边界调整。
///
/// 调整优先级：
/// 1. 若已达章节末尾，直接返回 chapterEnd
/// 2. 优先在语义边界（pageBreakBefore/After）分页
/// 3. 其次在 pageRelate 跨页关联点分页
/// 4. 再次在附件边界分页（块级附件需整体移动）
/// 5. 以上都不满足时，使用原始帧限制分页
///
/// 最小分页长度约束：不低于原始范围的 55%，避免单页内容过少。
private func adjustedRange(
from proposedRange: NSRange,
totalLength: Int,
@@ -193,6 +233,7 @@ struct RDEPUBTextLayouter {
)
}
// 最小分页长度：原始范围的 55%
let minLength = max(Int(Double(proposedRange.length) * 0.55), 1)
let minimumEnd = proposedRange.location + minLength
@@ -203,6 +244,7 @@ struct RDEPUBTextLayouter {
let currentSemanticHints = proposedSemanticHints
let currentAttachmentPlacements = proposedAttachmentPlacements
// 1. 语义边界（pageBreakBefore/After）
if let semanticBoundary = preferredSemanticBoundary(
in: proposedRange,
minimumEnd: minimumEnd
@@ -230,6 +272,7 @@ struct RDEPUBTextLayouter {
)
}
// 2. pageRelate 跨页关联边界
if let pageRelateBoundary = preferredPageRelateBoundary(
after: proposedRange,
minimumEnd: minimumEnd,
@@ -258,6 +301,7 @@ struct RDEPUBTextLayouter {
)
}
// 3. 附件边界（块级附件整体移动）
if let attachmentBoundary = preferredAttachmentBoundary(
in: proposedRange,
minimumEnd: minimumEnd
@@ -284,6 +328,7 @@ struct RDEPUBTextLayouter {
)
}
// 4. 帧限制（默认分页）
return (
range: proposedRange,
breakReason: .frameLimit,
@@ -305,6 +350,11 @@ struct RDEPUBTextLayouter {
)
}
// MARK: - 语义边界查找
/// 在指定范围内查找最优的语义分页点（pageBreakBefore / pageBreakAfter）。
///
/// 只有当边界位置超过 minimumEnd（最小分页长度约束）时才有效。
private func preferredSemanticBoundary(
in range: NSRange,
minimumEnd: Int
@@ -337,6 +387,8 @@ struct RDEPUBTextLayouter {
return boundary
}
/// 查找附件边界：只有块级附件（.attachment 或 .centered）才触发分页，
/// 行内脚注图标等不应导致整段移动。
private func preferredAttachmentBoundary(in range: NSRange, minimumEnd: Int) -> Int? {
var boundary: Int?
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, attributeRange, stop in
@@ -346,9 +398,8 @@ struct RDEPUBTextLayouter {
let placement = attachmentPlacement(at: location)
let blockKind = blockKind(at: location)
// Mirror WXRead more closely: only block-level attachments should
// push the entire block to the next page. Inline footnote icons and
// other inline attachments must not cause a whole paragraph to move.
// 对标 WXRead：只有块级附件才应将整个块推到下一页。
// 行内脚注图标等行内附件不应导致整段移动。
let isBlockLevelAttachment = blockKind == .attachment || placement == .centered
guard isBlockLevelAttachment else { return }
@@ -361,6 +412,8 @@ struct RDEPUBTextLayouter {
return boundary
}
/// 查找 pageRelate 跨页关联边界：当下一页起始是一个 pageRelate 块且
/// 该块恰好是当前页最后一行时，将最后一行移到下一页。
private func preferredPageRelateBoundary(
after range: NSRange,
minimumEnd: Int,
@@ -384,6 +437,9 @@ struct RDEPUBTextLayouter {
return lastLineStart
}
// MARK: - 属性查询工具
/// 获取指定位置的块级元素范围
private func blockRange(at location: Int) -> NSRange? {
guard location >= 0, location < attributedString.length else { return nil }
let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -393,6 +449,7 @@ struct RDEPUBTextLayouter {
return nil
}
/// 获取指定位置的块级元素类型
private func blockKind(at location: Int) -> RDEPUBTextBlockKind? {
guard location >= 0, location < attributedString.length else { return nil }
let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -400,6 +457,7 @@ struct RDEPUBTextLayouter {
return RDEPUBTextBlockKind(rawValue: rawValue)
}
/// 获取指定位置的附件布局方式
private func attachmentPlacement(at location: Int) -> RDEPUBTextAttachmentPlacement? {
guard location >= 0, location < attributedString.length else { return nil }
let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -407,6 +465,7 @@ struct RDEPUBTextLayouter {
return RDEPUBTextAttachmentPlacement(rawValue: rawValue)
}
/// 获取包含指定位置的段落范围
private func paragraphRange(containing location: Int) -> NSRange {
let source = attributedString.string as NSString
guard source.length > 0 else { return NSRange(location: 0, length: 0) }
@@ -414,6 +473,7 @@ struct RDEPUBTextLayouter {
return source.paragraphRange(for: NSRange(location: safeLocation, length: 0))
}
/// 获取指定范围内的所有附件字符范围
private func attachmentRanges(in range: NSRange) -> [NSRange] {
var results: [NSRange] = []
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, attributeRange, _ in
@@ -423,6 +483,7 @@ struct RDEPUBTextLayouter {
return results
}
/// 获取指定位置的语义提示列表
private func semanticHints(at location: Int) -> [RDEPUBTextSemanticHint] {
guard location >= 0, location < attributedString.length else { return [] }
let attributes = attributedString.attributes(at: location, effectiveRange: nil)
@@ -432,6 +493,7 @@ struct RDEPUBTextLayouter {
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
}
/// 获取指定范围内的附件类型列表（去重）
private func attachmentKinds(in range: NSRange) -> [RDEPUBTextAttachmentKind] {
var kinds: [RDEPUBTextAttachmentKind] = []
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: range) { value, _, _ in
@@ -445,6 +507,7 @@ struct RDEPUBTextLayouter {
return kinds
}
/// 获取指定范围内的块级元素类型列表（去重）
private func blockKinds(in range: NSRange) -> [RDEPUBTextBlockKind] {
var kinds: [RDEPUBTextBlockKind] = []
attributedString.enumerateAttribute(.rdPageBlockKind, in: range) { value, _, _ in
@@ -458,6 +521,7 @@ struct RDEPUBTextLayouter {
return kinds
}
/// 获取指定范围内的语义提示列表（去重）
private func semanticHints(in range: NSRange) -> [RDEPUBTextSemanticHint] {
var hints: [RDEPUBTextSemanticHint] = []
attributedString.enumerateAttribute(.rdPageSemanticHints, in: range) { value, _, _ in
@@ -469,6 +533,7 @@ struct RDEPUBTextLayouter {
return hints
}
/// 获取指定范围内的附件布局方式列表（去重）
private func attachmentPlacements(in range: NSRange) -> [RDEPUBTextAttachmentPlacement] {
var placements: [RDEPUBTextAttachmentPlacement] = []
attributedString.enumerateAttribute(.rdPageAttachmentPlacement, in: range) { value, _, _ in
@@ -482,6 +547,7 @@ struct RDEPUBTextLayouter {
return placements
}
/// 查找指定位置之前最近的 fragment ID（用于阅读位置恢复）
private func nearestTrailingFragmentID(
endingAt location: Int,
fragmentOffsets: [String: Int]
@@ -492,11 +558,11 @@ struct RDEPUBTextLayouter {
.key
}
// MARK: - Line-level avoidPageBreakInside (WXRead approach)
// MARK: - 行级 avoidPageBreakInside（WXRead 方案）
/// Scans CTFrame lines backward from the last line, removing trailing lines
/// that fall inside an avoidPageBreakInside block. Mirrors WXRead's
/// WRCoreTextLayoutFrame.avoidPageBreakInsideByRemovingLastLinesIfNeeded.
/// 从 CTFrame 最后一行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行。
/// 对标 WXRead 的 WRCoreTextLayoutFrame.avoidPageBreakInsideByRemovingLastLinesIfNeeded。
/// 最多移除 3 行（kMaxLinesToRemove），避免因保护块过大导致整页内容被清空。
private func trimmedRangeForAvoidPageBreakInside(
from frame: CTFrame,
proposed: NSRange
@@ -509,8 +575,8 @@ struct RDEPUBTextLayouter {
var origins = [CGPoint](repeating: .zero, count: lines.count)
CTFrameGetLineOrigins(frame, CFRangeMake(0, 0), &origins)
// Scan backward: count consecutive trailing lines inside protected blocks
// kMaxLinesToRemove = 3 (same as WXRead)
// 从最后一行向前扫描，统计落在保护块内的连续尾部行数
// kMaxLinesToRemove = 3（与 WXRead 一致）
let kMaxLinesToRemove = 3
var linesToRemove = 0
@@ -521,8 +587,7 @@ struct RDEPUBTextLayouter {
if lineIsInAvoidPageBreakInsideBlock(lineNSRange) {
linesToRemove += 1
if linesToRemove >= kMaxLinesToRemove {
// Don't remove more than kMaxLinesToRemove; stop here
// (line at index i stays, so linesToRemove stays at kMaxLinesToRemove)
// 不超过 kMaxLinesToRemove 行，停在这里
linesToRemove = kMaxLinesToRemove
break
}
@@ -535,7 +600,7 @@ struct RDEPUBTextLayouter {
let validLineCount = lines.count - linesToRemove
guard validLineCount > 0 else {
// All lines are in protected blocks; fall back to proposed
// 所有行都在保护块内，回退到原始范围
return proposed
}
@@ -549,6 +614,7 @@ struct RDEPUBTextLayouter {
return NSRange(location: proposed.location, length: adjustedLength)
}
/// CoreText 路径的 keepWithNext 处理：从最后行向前扫描
private func trimmedRangeForKeepWithNext(
from frame: CTFrame,
proposed: NSRange
@@ -561,7 +627,10 @@ struct RDEPUBTextLayouter {
return trimmedRangeForKeepWithNext(proposed: proposed, lineRanges: lineRanges)
}
// MARK: - DTCoreText 行级处理
#if canImport(DTCoreText)
/// DTCoreText 路径的 avoidPageBreakInside 处理
private func trimmedRangeForAvoidPageBreakInside(
from layoutFrame: DTCoreTextLayoutFrame,
proposed: NSRange
@@ -603,6 +672,7 @@ struct RDEPUBTextLayouter {
return NSRange(location: proposed.location, length: adjustedLength)
}
/// DTCoreText 路径的 keepWithNext 处理
private func trimmedRangeForKeepWithNext(
from layoutFrame: DTCoreTextLayoutFrame,
proposed: NSRange
@@ -615,6 +685,8 @@ struct RDEPUBTextLayouter {
}
#endif
/// 从最后行向前扫描，移除落在 keepWithNext 保护块内的尾部行。
/// 最多移除 3 行。
private func trimmedRangeForKeepWithNext(
proposed: NSRange,
lineRanges: [NSRange]
@@ -648,7 +720,7 @@ struct RDEPUBTextLayouter {
return NSRange(location: proposed.location, length: adjustedLength)
}
/// Checks if a line's string range intersects with an avoidPageBreakInside block.
/// 检查某行是否落在 avoidPageBreakInside 保护块内
private func lineIsInAvoidPageBreakInsideBlock(_ lineRange: NSRange) -> Bool {
var found = false
let probeRange = NSRange(location: lineRange.location, length: max(lineRange.length, 1))
@@ -665,6 +737,7 @@ struct RDEPUBTextLayouter {
return found
}
/// 检查某行是否落在 keepWithNext 保护块内
private func lineIsInKeepWithNextBlock(_ lineRange: NSRange) -> Bool {
var found = false
let probeRange = NSRange(location: lineRange.location, length: max(lineRange.length, 1))
@@ -681,6 +754,7 @@ struct RDEPUBTextLayouter {
return found
}
/// 获取 CTFrame 中所有行的字符范围
private func lineRanges(from frame: CTFrame) -> [NSRange] {
let lines = CTFrameGetLines(frame) as! [CTLine]
return lines.map {
@@ -690,6 +764,7 @@ struct RDEPUBTextLayouter {
}
#if canImport(DTCoreText)
/// 获取 DTCoreTextLayoutFrame 中所有行的字符范围
private func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
return []
@@ -698,6 +773,9 @@ struct RDEPUBTextLayouter {
}
#endif
// MARK: - 诊断日志
/// 生成分页诊断日志，记录分页原因、范围和语义信息
private func diagnostics(
reason: RDEPUBTextPageBreakReason,
range: NSRange,