947 lines
39 KiB
Swift
947 lines
39 KiB
Swift
import CoreText
|
||
import UIKit
|
||
|
||
#if canImport(DTCoreText)
|
||
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
|
||
/// DTCoreText 路径可直接消费的单矩形布局区域
|
||
private let dtLayoutRect: CGRect
|
||
/// 布局配置（avoidPageBreakInside、孤行控制等）
|
||
private let config: RDEPUBTextLayoutConfig
|
||
|
||
init(attributedString: NSAttributedString, pageSize: CGSize, config: RDEPUBTextLayoutConfig = .default) {
|
||
self.attributedString = attributedString
|
||
self.pageSize = pageSize
|
||
self.config = config
|
||
self.framesetter = CTFramesetterCreateWithAttributedString(attributedString)
|
||
self.dtLayoutRect = config.contentRect(fallback: pageSize)
|
||
self.path = Self.makeLayoutPath(pageSize: pageSize, config: config)
|
||
}
|
||
|
||
/// 执行分页，返回布局帧列表（每帧对应一页）。
|
||
/// 根据编译环境选择 DTCoreText 或 CoreText 路径。
|
||
func layoutFrames(fragmentOffsets: [String: Int] = [:]) -> [RDEPUBTextLayoutFrame] {
|
||
guard attributedString.length > 0, pageSize.width > 0, pageSize.height > 0 else {
|
||
return []
|
||
}
|
||
|
||
#if canImport(DTCoreText)
|
||
return layoutFramesUsingDTCoreText(fragmentOffsets: fragmentOffsets)
|
||
#else
|
||
return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
|
||
#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 []
|
||
}
|
||
|
||
var frames: [RDEPUBTextLayoutFrame] = []
|
||
var location = 0
|
||
let resolvedSize = config.resolvedFrameSize(fallback: pageSize)
|
||
let usableWidth = resolvedSize.width - config.edgeInsets.left - config.edgeInsets.right
|
||
let usableHeight = resolvedSize.height - config.edgeInsets.top - config.edgeInsets.bottom
|
||
|
||
guard usableWidth > 0, usableHeight > 0 else {
|
||
return []
|
||
}
|
||
|
||
while location < attributedString.length {
|
||
let framePath = CGMutablePath()
|
||
// 对齐 WXRead WRChapterPageCount：
|
||
// CoreText 分页路径使用 bottom inset 作为 y 原点，而不是 UIKit 语义的 top inset。
|
||
let pageRect = CGRect(
|
||
x: config.edgeInsets.left,
|
||
y: config.edgeInsets.bottom,
|
||
width: usableWidth,
|
||
height: usableHeight
|
||
)
|
||
framePath.addRect(pageRect)
|
||
let frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(location, 0), framePath, nil)
|
||
let proposedRange = proposedRangeUsingWXReadPageCount(
|
||
from: frame,
|
||
start: location,
|
||
usableHeight: usableHeight,
|
||
totalLength: attributedString.length
|
||
)
|
||
guard proposedRange.length > 0 else {
|
||
break
|
||
}
|
||
|
||
// 行级 avoidPageBreakInside 处理（WXRead 方案：从最后一行向前扫描）
|
||
let avoidAdjusted = trimmedRangeForAvoidPageBreakInside(from: frame, proposed: proposedRange)
|
||
let lineRanges = lineRanges(from: frame)
|
||
|
||
let adjusted = adjustedRange(
|
||
from: avoidAdjusted,
|
||
totalLength: attributedString.length,
|
||
lineRanges: lineRanges
|
||
)
|
||
let trailingFragmentID = nearestTrailingFragmentID(
|
||
endingAt: adjusted.range.location + adjusted.range.length,
|
||
fragmentOffsets: fragmentOffsets
|
||
)
|
||
frames.append(
|
||
RDEPUBTextLayoutFrame(
|
||
contentRange: adjusted.range,
|
||
breakReason: adjusted.breakReason,
|
||
blockRange: adjusted.blockRange,
|
||
attachmentRanges: adjusted.attachmentRanges,
|
||
attachmentKinds: adjusted.attachmentKinds,
|
||
blockKinds: adjusted.blockKinds,
|
||
semanticHints: adjusted.semanticHints,
|
||
attachmentPlacements: adjusted.attachmentPlacements,
|
||
trailingFragmentID: trailingFragmentID,
|
||
diagnostics: adjusted.diagnostics
|
||
)
|
||
)
|
||
|
||
let nextLocation = adjusted.range.location + adjusted.range.length
|
||
guard nextLocation > location else {
|
||
location += max(proposedRange.length, 1)
|
||
continue
|
||
}
|
||
location = nextLocation
|
||
}
|
||
|
||
return frames
|
||
}
|
||
|
||
// MARK: - DTCoreText 分页路径（首选方案）
|
||
|
||
#if canImport(DTCoreText)
|
||
/// 使用 DTCoreTextLayouter 进行分页，提供更精确的行级语义处理。
|
||
private func layoutFramesUsingDTCoreText(fragmentOffsets: [String: Int]) -> [RDEPUBTextLayoutFrame] {
|
||
guard config.numberOfColumns == 1 else {
|
||
return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
|
||
}
|
||
|
||
guard let layouter = DTCoreTextLayouter(attributedString: attributedString) else {
|
||
return layoutFramesUsingCoreText(fragmentOffsets: fragmentOffsets)
|
||
}
|
||
|
||
layouter.shouldCacheLayoutFrames = false
|
||
|
||
var frames: [RDEPUBTextLayoutFrame] = []
|
||
var location = 0
|
||
let pageRect = dtLayoutRect
|
||
|
||
while location < attributedString.length {
|
||
guard let layoutFrame = layouter.layoutFrame(with: pageRect, range: NSRange(location: location, length: 0)) else {
|
||
break
|
||
}
|
||
|
||
let visibleRange = layoutFrame.visibleStringRange()
|
||
guard visibleRange.length > 0 else {
|
||
break
|
||
}
|
||
|
||
let proposedRange = NSRange(location: location, length: visibleRange.length)
|
||
let avoidAdjusted = trimmedRangeForAvoidPageBreakInside(from: layoutFrame, proposed: proposedRange)
|
||
let lineAdjusted = trimmedRangeForKeepWithNext(from: layoutFrame, proposed: avoidAdjusted)
|
||
let lineRanges = lineRanges(from: layoutFrame)
|
||
let adjusted = adjustedRange(
|
||
from: lineAdjusted,
|
||
totalLength: attributedString.length,
|
||
lineRanges: lineRanges
|
||
)
|
||
let verifiedRange: NSRange
|
||
if adjusted.breakReason == .attachmentBoundary {
|
||
verifiedRange = verifiedDisplayRange(for: adjusted.range)
|
||
} else {
|
||
verifiedRange = adjusted.range
|
||
}
|
||
let trailingFragmentID = nearestTrailingFragmentID(
|
||
endingAt: verifiedRange.location + verifiedRange.length,
|
||
fragmentOffsets: fragmentOffsets
|
||
)
|
||
let diagnostics = verifiedRange == adjusted.range
|
||
? adjusted.diagnostics
|
||
: adjusted.diagnostics + ["verified-display-range \(NSStringFromRange(adjusted.range)) -> \(NSStringFromRange(verifiedRange))"]
|
||
|
||
frames.append(
|
||
RDEPUBTextLayoutFrame(
|
||
contentRange: verifiedRange,
|
||
breakReason: adjusted.breakReason,
|
||
blockRange: blockRange(at: max(verifiedRange.location, verifiedRange.location + verifiedRange.length - 1)),
|
||
attachmentRanges: attachmentRanges(in: verifiedRange),
|
||
attachmentKinds: attachmentKinds(in: verifiedRange),
|
||
blockKinds: blockKinds(in: verifiedRange),
|
||
semanticHints: semanticHints(in: verifiedRange),
|
||
attachmentPlacements: attachmentPlacements(in: verifiedRange),
|
||
trailingFragmentID: trailingFragmentID,
|
||
diagnostics: diagnostics
|
||
)
|
||
)
|
||
|
||
let nextLocation = verifiedRange.location + verifiedRange.length
|
||
guard nextLocation > location else {
|
||
location += max(visibleRange.length, 1)
|
||
continue
|
||
}
|
||
location = nextLocation
|
||
}
|
||
|
||
return frames
|
||
}
|
||
|
||
private func verifiedDisplayRange(for range: NSRange) -> NSRange {
|
||
guard let clampedRange = clampedRange(range),
|
||
clampedRange.length > 0,
|
||
!attachmentRanges(in: clampedRange).isEmpty else {
|
||
return range
|
||
}
|
||
|
||
let pageContent = attributedString.attributedSubstring(from: clampedRange)
|
||
guard let layouter = DTCoreTextLayouter(attributedString: pageContent) else {
|
||
return clampedRange
|
||
}
|
||
|
||
layouter.shouldCacheLayoutFrames = false
|
||
guard let layoutFrame = layouter.layoutFrame(with: dtLayoutRect, range: NSRange(location: 0, length: 0)) else {
|
||
return clampedRange
|
||
}
|
||
|
||
let visibleRange = layoutFrame.visibleStringRange()
|
||
guard visibleRange.length > 0, visibleRange.length < clampedRange.length else {
|
||
return clampedRange
|
||
}
|
||
|
||
return NSRange(location: clampedRange.location, length: visibleRange.length)
|
||
}
|
||
#endif
|
||
|
||
private static func makeLayoutPath(pageSize: CGSize, config: RDEPUBTextLayoutConfig) -> CGPath {
|
||
let columnRects = config.columnRects(fallback: pageSize)
|
||
guard columnRects.count > 1 else {
|
||
return CGPath(rect: columnRects.first ?? CGRect(origin: .zero, size: pageSize), transform: nil)
|
||
}
|
||
|
||
let path = CGMutablePath()
|
||
for rect in columnRects {
|
||
path.addRect(rect)
|
||
}
|
||
return path
|
||
}
|
||
|
||
// MARK: - 语义边界调整
|
||
|
||
/// 对 CoreText 提出的分页范围进行语义边界调整。
|
||
///
|
||
/// 调整优先级：
|
||
/// 1. 若已达章节末尾，直接返回 chapterEnd
|
||
/// 2. 优先在语义边界（pageBreakBefore/After）分页
|
||
/// 3. 其次在 pageRelate 跨页关联点分页
|
||
/// 4. 再次在附件边界分页（块级附件需整体移动）
|
||
/// 5. 以上都不满足时，使用原始帧限制分页
|
||
///
|
||
/// 最小分页长度约束：不低于原始范围的 55%，避免单页内容过少。
|
||
private func adjustedRange(
|
||
from proposedRange: NSRange,
|
||
totalLength: Int,
|
||
lineRanges: [NSRange]
|
||
) -> (
|
||
range: NSRange,
|
||
breakReason: RDEPUBTextPageBreakReason,
|
||
blockRange: NSRange?,
|
||
attachmentRanges: [NSRange],
|
||
attachmentKinds: [RDEPUBTextAttachmentKind],
|
||
blockKinds: [RDEPUBTextBlockKind],
|
||
semanticHints: [RDEPUBTextSemanticHint],
|
||
attachmentPlacements: [RDEPUBTextAttachmentPlacement],
|
||
diagnostics: [String]
|
||
) {
|
||
let pageEnd = proposedRange.location + proposedRange.length
|
||
let proposedBlockKinds = blockKinds(in: proposedRange)
|
||
let proposedSemanticHints = semanticHints(in: proposedRange)
|
||
let proposedAttachmentPlacements = attachmentPlacements(in: proposedRange)
|
||
guard pageEnd < totalLength else {
|
||
return (
|
||
range: proposedRange,
|
||
breakReason: .chapterEnd,
|
||
blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
|
||
attachmentRanges: attachmentRanges(in: proposedRange),
|
||
attachmentKinds: attachmentKinds(in: proposedRange),
|
||
blockKinds: proposedBlockKinds,
|
||
semanticHints: proposedSemanticHints,
|
||
attachmentPlacements: proposedAttachmentPlacements,
|
||
diagnostics: diagnostics(
|
||
reason: .chapterEnd,
|
||
range: proposedRange,
|
||
attachmentRanges: attachmentRanges(in: proposedRange),
|
||
blockRange: blockRange(at: max(proposedRange.location, pageEnd - 1)),
|
||
blockKinds: proposedBlockKinds,
|
||
semanticHints: proposedSemanticHints,
|
||
attachmentPlacements: proposedAttachmentPlacements
|
||
)
|
||
)
|
||
}
|
||
|
||
let currentBlockRange = blockRange(at: max(proposedRange.location, pageEnd - 1))
|
||
let currentAttachmentRanges = attachmentRanges(in: proposedRange)
|
||
let currentAttachmentKinds = attachmentKinds(in: proposedRange)
|
||
let currentBlockKinds = proposedBlockKinds
|
||
let currentSemanticHints = proposedSemanticHints
|
||
let currentAttachmentPlacements = proposedAttachmentPlacements
|
||
|
||
// 对齐 WXRead：默认按 CTFrame 已经容纳的行数分页，仅保留 pageRelate 这种
|
||
// 微信读书特有的跨页关联规则；其他 keepWithNext/attachmentBoundary/通用语义边界
|
||
// 先不参与截断，避免提前裁短页尾内容。
|
||
if let pageRelateBoundary = preferredPageRelateBoundary(
|
||
after: proposedRange,
|
||
minimumEnd: proposedRange.location + 1,
|
||
lineRanges: lineRanges
|
||
) {
|
||
let adjustedRange = NSRange(location: proposedRange.location, length: pageRelateBoundary - proposedRange.location)
|
||
return (
|
||
range: adjustedRange,
|
||
breakReason: .semanticBoundary,
|
||
blockRange: currentBlockRange,
|
||
attachmentRanges: currentAttachmentRanges,
|
||
attachmentKinds: currentAttachmentKinds,
|
||
blockKinds: currentBlockKinds,
|
||
semanticHints: currentSemanticHints,
|
||
attachmentPlacements: currentAttachmentPlacements,
|
||
diagnostics: diagnostics(
|
||
reason: .semanticBoundary,
|
||
range: adjustedRange,
|
||
attachmentRanges: currentAttachmentRanges,
|
||
blockRange: currentBlockRange,
|
||
blockKinds: currentBlockKinds,
|
||
semanticHints: currentSemanticHints,
|
||
attachmentPlacements: currentAttachmentPlacements,
|
||
trigger: RDEPUBTextSemanticHint.pageRelate.rawValue
|
||
)
|
||
)
|
||
}
|
||
|
||
// 4. 帧限制（默认分页）
|
||
return (
|
||
range: proposedRange,
|
||
breakReason: .frameLimit,
|
||
blockRange: currentBlockRange,
|
||
attachmentRanges: currentAttachmentRanges,
|
||
attachmentKinds: currentAttachmentKinds,
|
||
blockKinds: currentBlockKinds,
|
||
semanticHints: currentSemanticHints,
|
||
attachmentPlacements: currentAttachmentPlacements,
|
||
diagnostics: diagnostics(
|
||
reason: .frameLimit,
|
||
range: proposedRange,
|
||
attachmentRanges: currentAttachmentRanges,
|
||
blockRange: currentBlockRange,
|
||
blockKinds: currentBlockKinds,
|
||
semanticHints: currentSemanticHints,
|
||
attachmentPlacements: currentAttachmentPlacements
|
||
)
|
||
)
|
||
}
|
||
|
||
// MARK: - 语义边界查找
|
||
|
||
/// 在指定范围内查找最优的语义分页点（pageBreakBefore / pageBreakAfter）。
|
||
///
|
||
/// 只有当边界位置超过 minimumEnd（最小分页长度约束）时才有效。
|
||
private func preferredSemanticBoundary(
|
||
in range: NSRange,
|
||
minimumEnd: Int
|
||
) -> (location: Int, trigger: String)? {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return nil
|
||
}
|
||
var boundary: (location: Int, trigger: String)?
|
||
attributedString.enumerateAttribute(.rdPageSemanticHints, in: safeRange) { value, attributeRange, stop in
|
||
guard let rawValue = value as? String else { return }
|
||
let hints = rawValue
|
||
.split(separator: ",")
|
||
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
|
||
guard !hints.isEmpty else { return }
|
||
|
||
if hints.contains(.pageBreakBefore),
|
||
attributeRange.location > safeRange.location,
|
||
attributeRange.location >= minimumEnd {
|
||
boundary = (attributeRange.location, RDEPUBTextSemanticHint.pageBreakBefore.rawValue)
|
||
stop.pointee = true
|
||
return
|
||
}
|
||
|
||
let attributeEnd = attributeRange.location + attributeRange.length
|
||
if hints.contains(.pageBreakAfter),
|
||
attributeEnd > minimumEnd,
|
||
attributeEnd < safeRange.location + safeRange.length {
|
||
boundary = (attributeEnd, RDEPUBTextSemanticHint.pageBreakAfter.rawValue)
|
||
stop.pointee = true
|
||
return
|
||
}
|
||
}
|
||
return boundary
|
||
}
|
||
|
||
/// 查找附件边界：只有块级附件（.attachment 或 .centered）才触发分页，
|
||
/// 行内脚注图标等不应导致整段移动。
|
||
private func preferredAttachmentBoundary(in range: NSRange, minimumEnd: Int) -> Int? {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return nil
|
||
}
|
||
var boundary: Int?
|
||
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, attributeRange, stop in
|
||
guard value != nil else { return }
|
||
|
||
let location = attributeRange.location
|
||
let placement = attachmentPlacement(at: location)
|
||
let blockKind = blockKind(at: location)
|
||
|
||
// 对标 WXRead：只有块级附件才应将整个块推到下一页。
|
||
// 行内脚注图标等行内附件不应导致整段移动。
|
||
// 只有真正的块级附件才需要整块挪页。
|
||
// 行内/基线对齐的附件（例如脚注 note.png）不能触发附件边界分页。
|
||
let isBlockLevelAttachment: Bool
|
||
switch placement {
|
||
case .centered:
|
||
isBlockLevelAttachment = true
|
||
case .inline, .baseline:
|
||
isBlockLevelAttachment = false
|
||
case nil:
|
||
isBlockLevelAttachment = blockKind == .attachment
|
||
}
|
||
guard isBlockLevelAttachment else { return }
|
||
|
||
let boundaryRange = blockRange(at: location) ?? paragraphRange(containing: location)
|
||
if boundaryRange.location > safeRange.location, boundaryRange.location >= minimumEnd {
|
||
boundary = boundaryRange.location
|
||
stop.pointee = true
|
||
}
|
||
}
|
||
return boundary
|
||
}
|
||
|
||
/// 查找 pageRelate 跨页关联边界：当下一页起始是一个 pageRelate 块且
|
||
/// 该块恰好是当前页最后一行时，将最后一行移到下一页。
|
||
private func preferredPageRelateBoundary(
|
||
after range: NSRange,
|
||
minimumEnd: Int,
|
||
lineRanges: [NSRange]
|
||
) -> Int? {
|
||
let pageStartOfNext = range.location + range.length
|
||
guard pageStartOfNext > range.location,
|
||
pageStartOfNext < attributedString.length,
|
||
lineRanges.count >= 2,
|
||
semanticHints(at: pageStartOfNext).contains(.pageRelate) else {
|
||
return nil
|
||
}
|
||
|
||
let boundaryBlockStart = blockRange(at: pageStartOfNext)?.location ?? paragraphRange(containing: pageStartOfNext).location
|
||
guard boundaryBlockStart == pageStartOfNext else { return nil }
|
||
|
||
let lastLineStart = lineRanges[lineRanges.count - 1].location
|
||
guard lastLineStart > range.location, lastLineStart >= minimumEnd else {
|
||
return nil
|
||
}
|
||
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)
|
||
if let encodedRange = attributes[.rdPageBlockRange] as? String {
|
||
return NSRangeFromString(encodedRange)
|
||
}
|
||
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)
|
||
guard let rawValue = attributes[.rdPageBlockKind] as? String else { return nil }
|
||
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)
|
||
guard let rawValue = attributes[.rdPageAttachmentPlacement] as? String else { return nil }
|
||
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) }
|
||
let safeLocation = min(max(location, 0), max(source.length - 1, 0))
|
||
return source.paragraphRange(for: NSRange(location: safeLocation, length: 0))
|
||
}
|
||
|
||
/// 获取指定范围内的所有附件字符范围
|
||
private func attachmentRanges(in range: NSRange) -> [NSRange] {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return []
|
||
}
|
||
var results: [NSRange] = []
|
||
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, attributeRange, _ in
|
||
guard value != nil else { return }
|
||
results.append(attributeRange)
|
||
}
|
||
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)
|
||
guard let rawValue = attributes[.rdPageSemanticHints] as? String else { return [] }
|
||
return rawValue
|
||
.split(separator: ",")
|
||
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
|
||
}
|
||
|
||
/// 获取指定范围内的附件类型列表（去重）
|
||
private func attachmentKinds(in range: NSRange) -> [RDEPUBTextAttachmentKind] {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return []
|
||
}
|
||
var kinds: [RDEPUBTextAttachmentKind] = []
|
||
attributedString.enumerateAttribute(.rdPageAttachmentKind, in: safeRange) { value, _, _ in
|
||
guard let rawValue = value as? String,
|
||
let kind = RDEPUBTextAttachmentKind(rawValue: rawValue),
|
||
!kinds.contains(kind) else {
|
||
return
|
||
}
|
||
kinds.append(kind)
|
||
}
|
||
return kinds
|
||
}
|
||
|
||
/// 获取指定范围内的块级元素类型列表（去重）
|
||
private func blockKinds(in range: NSRange) -> [RDEPUBTextBlockKind] {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return []
|
||
}
|
||
var kinds: [RDEPUBTextBlockKind] = []
|
||
attributedString.enumerateAttribute(.rdPageBlockKind, in: safeRange) { value, _, _ in
|
||
guard let rawValue = value as? String,
|
||
let kind = RDEPUBTextBlockKind(rawValue: rawValue),
|
||
!kinds.contains(kind) else {
|
||
return
|
||
}
|
||
kinds.append(kind)
|
||
}
|
||
return kinds
|
||
}
|
||
|
||
/// 获取指定范围内的语义提示列表（去重）
|
||
private func semanticHints(in range: NSRange) -> [RDEPUBTextSemanticHint] {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return []
|
||
}
|
||
var hints: [RDEPUBTextSemanticHint] = []
|
||
attributedString.enumerateAttribute(.rdPageSemanticHints, in: safeRange) { value, _, _ in
|
||
guard let rawValue = value as? String else { return }
|
||
for hint in rawValue.split(separator: ",").compactMap({ RDEPUBTextSemanticHint(rawValue: String($0)) }) where !hints.contains(hint) {
|
||
hints.append(hint)
|
||
}
|
||
}
|
||
return hints
|
||
}
|
||
|
||
/// 获取指定范围内的附件布局方式列表（去重）
|
||
private func attachmentPlacements(in range: NSRange) -> [RDEPUBTextAttachmentPlacement] {
|
||
guard let safeRange = clampedRange(range), safeRange.length > 0 else {
|
||
return []
|
||
}
|
||
var placements: [RDEPUBTextAttachmentPlacement] = []
|
||
attributedString.enumerateAttribute(.rdPageAttachmentPlacement, in: safeRange) { value, _, _ in
|
||
guard let rawValue = value as? String,
|
||
let placement = RDEPUBTextAttachmentPlacement(rawValue: rawValue),
|
||
!placements.contains(placement) else {
|
||
return
|
||
}
|
||
placements.append(placement)
|
||
}
|
||
return placements
|
||
}
|
||
|
||
/// 将范围裁剪到 attributedString 的合法边界内，避免属性枚举与子串提取越界。
|
||
private func clampedRange(_ range: NSRange) -> NSRange? {
|
||
guard range.location >= 0, range.length >= 0 else { return nil }
|
||
guard attributedString.length > 0 else {
|
||
return range.location == 0 ? NSRange(location: 0, length: 0) : nil
|
||
}
|
||
guard range.location < attributedString.length else { return nil }
|
||
|
||
let maxLength = attributedString.length - range.location
|
||
return NSRange(location: range.location, length: min(range.length, maxLength))
|
||
}
|
||
|
||
private func clampedProbeRange(for lineRange: NSRange) -> NSRange? {
|
||
clampedRange(NSRange(location: lineRange.location, length: max(lineRange.length, 1)))
|
||
}
|
||
|
||
/// 查找指定位置之前最近的 fragment ID（用于阅读位置恢复）
|
||
private func nearestTrailingFragmentID(
|
||
endingAt location: Int,
|
||
fragmentOffsets: [String: Int]
|
||
) -> String? {
|
||
fragmentOffsets
|
||
.filter { $0.value <= location }
|
||
.max { lhs, rhs in lhs.value < rhs.value }?
|
||
.key
|
||
}
|
||
|
||
// MARK: - 行级 avoidPageBreakInside（WXRead 方案）
|
||
|
||
/// 从 CTFrame 最后一行向前扫描，移除落在 avoidPageBreakInside 保护块内的尾部行。
|
||
/// 对标 WXRead 的 WRCoreTextLayoutFrame.avoidPageBreakInsideByRemovingLastLinesIfNeeded。
|
||
/// 最多移除 3 行（kMaxLinesToRemove），避免因保护块过大导致整页内容被清空。
|
||
private func trimmedRangeForAvoidPageBreakInside(
|
||
from frame: CTFrame,
|
||
proposed: NSRange
|
||
) -> NSRange {
|
||
guard config.avoidPageBreakInsideEnabled else { return proposed }
|
||
|
||
let lines = CTFrameGetLines(frame) as! [CTLine]
|
||
guard !lines.isEmpty else { return proposed }
|
||
|
||
var origins = [CGPoint](repeating: .zero, count: lines.count)
|
||
CTFrameGetLineOrigins(frame, CFRangeMake(0, 0), &origins)
|
||
|
||
// 从最后一行向前扫描，统计落在保护块内的连续尾部行数
|
||
// kMaxLinesToRemove = 3（与 WXRead 一致）
|
||
let kMaxLinesToRemove = 3
|
||
var linesToRemove = 0
|
||
|
||
for i in stride(from: lines.count - 1, through: 0, by: -1) {
|
||
let lineRange = CTLineGetStringRange(lines[i])
|
||
let lineNSRange = NSRange(location: lineRange.location, length: lineRange.length)
|
||
|
||
if lineIsInAvoidPageBreakInsideBlock(lineNSRange) {
|
||
linesToRemove += 1
|
||
if linesToRemove >= kMaxLinesToRemove {
|
||
// 不超过 kMaxLinesToRemove 行，停在这里
|
||
linesToRemove = kMaxLinesToRemove
|
||
break
|
||
}
|
||
} else {
|
||
break
|
||
}
|
||
}
|
||
|
||
guard linesToRemove > 0 else { return proposed }
|
||
|
||
let validLineCount = lines.count - linesToRemove
|
||
guard validLineCount > 0 else {
|
||
// 所有行都在保护块内，回退到原始范围
|
||
return proposed
|
||
}
|
||
|
||
let lastValidLine = lines[validLineCount - 1]
|
||
let lastLineRange = CTLineGetStringRange(lastValidLine)
|
||
let endLocation = lastLineRange.location + lastLineRange.length
|
||
let adjustedLength = endLocation - proposed.location
|
||
|
||
guard adjustedLength > 0 else { return proposed }
|
||
|
||
return NSRange(location: proposed.location, length: adjustedLength)
|
||
}
|
||
|
||
/// CoreText 路径的 keepWithNext 处理：从最后行向前扫描
|
||
private func trimmedRangeForKeepWithNext(
|
||
from frame: CTFrame,
|
||
proposed: NSRange
|
||
) -> NSRange {
|
||
let lines = CTFrameGetLines(frame) as! [CTLine]
|
||
let lineRanges = lines.map {
|
||
let range = CTLineGetStringRange($0)
|
||
return NSRange(location: range.location, length: range.length)
|
||
}
|
||
return trimmedRangeForKeepWithNext(proposed: proposed, lineRanges: lineRanges)
|
||
}
|
||
|
||
// MARK: - DTCoreText 行级处理
|
||
|
||
#if canImport(DTCoreText)
|
||
/// DTCoreText 路径的 avoidPageBreakInside 处理
|
||
private func trimmedRangeForAvoidPageBreakInside(
|
||
from layoutFrame: DTCoreTextLayoutFrame,
|
||
proposed: NSRange
|
||
) -> NSRange {
|
||
guard config.avoidPageBreakInsideEnabled else { return proposed }
|
||
|
||
guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine], !lines.isEmpty else {
|
||
return proposed
|
||
}
|
||
|
||
let kMaxLinesToRemove = 3
|
||
var linesToRemove = 0
|
||
|
||
for line in lines.reversed() {
|
||
let lineRange = line.stringRange()
|
||
if lineIsInAvoidPageBreakInsideBlock(lineRange) {
|
||
linesToRemove += 1
|
||
if linesToRemove >= kMaxLinesToRemove {
|
||
linesToRemove = kMaxLinesToRemove
|
||
break
|
||
}
|
||
} else {
|
||
break
|
||
}
|
||
}
|
||
|
||
guard linesToRemove > 0 else { return proposed }
|
||
|
||
let validLineCount = lines.count - linesToRemove
|
||
guard validLineCount > 0 else { return proposed }
|
||
|
||
let lastValidLine = lines[validLineCount - 1]
|
||
let lastLineRange = lastValidLine.stringRange()
|
||
let endLocation = lastLineRange.location + lastLineRange.length
|
||
let adjustedLength = endLocation - proposed.location
|
||
|
||
guard adjustedLength > 0 else { return proposed }
|
||
|
||
return NSRange(location: proposed.location, length: adjustedLength)
|
||
}
|
||
|
||
/// DTCoreText 路径的 keepWithNext 处理
|
||
private func trimmedRangeForKeepWithNext(
|
||
from layoutFrame: DTCoreTextLayoutFrame,
|
||
proposed: NSRange
|
||
) -> NSRange {
|
||
guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine], !lines.isEmpty else {
|
||
return proposed
|
||
}
|
||
let lineRanges = lines.map { $0.stringRange() }
|
||
return trimmedRangeForKeepWithNext(proposed: proposed, lineRanges: lineRanges)
|
||
}
|
||
#endif
|
||
|
||
/// 从最后行向前扫描，移除落在 keepWithNext 保护块内的尾部行。
|
||
/// 最多移除 3 行。
|
||
private func trimmedRangeForKeepWithNext(
|
||
proposed: NSRange,
|
||
lineRanges: [NSRange]
|
||
) -> NSRange {
|
||
guard !lineRanges.isEmpty else { return proposed }
|
||
|
||
let kMaxLinesToRemove = 3
|
||
var linesToRemove = 0
|
||
|
||
for lineRange in lineRanges.reversed() {
|
||
if lineIsInKeepWithNextBlock(lineRange) {
|
||
linesToRemove += 1
|
||
if linesToRemove >= kMaxLinesToRemove {
|
||
linesToRemove = kMaxLinesToRemove
|
||
break
|
||
}
|
||
} else {
|
||
break
|
||
}
|
||
}
|
||
|
||
guard linesToRemove > 0 else { return proposed }
|
||
|
||
let validLineCount = lineRanges.count - linesToRemove
|
||
guard validLineCount > 0 else { return proposed }
|
||
|
||
let lastValidLine = lineRanges[validLineCount - 1]
|
||
let endLocation = lastValidLine.location + lastValidLine.length
|
||
let adjustedLength = endLocation - proposed.location
|
||
guard adjustedLength > 0 else { return proposed }
|
||
return NSRange(location: proposed.location, length: adjustedLength)
|
||
}
|
||
|
||
/// 检查某行是否落在 avoidPageBreakInside 保护块内
|
||
private func lineIsInAvoidPageBreakInsideBlock(_ lineRange: NSRange) -> Bool {
|
||
guard let probeRange = clampedProbeRange(for: lineRange) else {
|
||
return false
|
||
}
|
||
var found = false
|
||
attributedString.enumerateAttributes(in: probeRange) { attributes, _, stop in
|
||
guard shouldTreatAvoidHintAsBlockProtection(attributes) else {
|
||
return
|
||
}
|
||
guard let rawValue = attributes[.rdPageSemanticHints] as? String else { return }
|
||
let hints = rawValue
|
||
.split(separator: ",")
|
||
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
|
||
if hints.contains(.avoidPageBreakInside) {
|
||
found = true
|
||
stop.pointee = true
|
||
}
|
||
}
|
||
return found
|
||
}
|
||
|
||
/// 只有真正的块级内容才应触发 avoidPageBreakInside。
|
||
/// 像脚注 note.png 这类行内图片会被标记为 `img`，但不该把整行推到下一页。
|
||
private func shouldTreatAvoidHintAsBlockProtection(_ attributes: [NSAttributedString.Key: Any]) -> Bool {
|
||
guard let rawValue = attributes[.rdPageSemanticHints] as? String else {
|
||
return false
|
||
}
|
||
let hints = rawValue
|
||
.split(separator: ",")
|
||
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
|
||
guard hints.contains(.avoidPageBreakInside) else {
|
||
return false
|
||
}
|
||
|
||
let placement = (attributes[.rdPageAttachmentPlacement] as? String)
|
||
.flatMap(RDEPUBTextAttachmentPlacement.init(rawValue:))
|
||
let blockKind = (attributes[.rdPageBlockKind] as? String)
|
||
.flatMap(RDEPUBTextBlockKind.init(rawValue:))
|
||
|
||
if blockKind == .attachment, placement != .centered {
|
||
return false
|
||
}
|
||
|
||
return true
|
||
}
|
||
|
||
/// 检查某行是否落在 keepWithNext 保护块内
|
||
private func lineIsInKeepWithNextBlock(_ lineRange: NSRange) -> Bool {
|
||
guard let probeRange = clampedProbeRange(for: lineRange) else {
|
||
return false
|
||
}
|
||
var found = false
|
||
attributedString.enumerateAttribute(.rdPageSemanticHints, in: probeRange) { value, _, stop in
|
||
guard let rawValue = value as? String else { return }
|
||
let hints = rawValue
|
||
.split(separator: ",")
|
||
.compactMap { RDEPUBTextSemanticHint(rawValue: String($0)) }
|
||
if hints.contains(.keepWithNext) {
|
||
found = true
|
||
stop.pointee = true
|
||
}
|
||
}
|
||
return found
|
||
}
|
||
|
||
/// 获取 CTFrame 中所有行的字符范围
|
||
private func lineRanges(from frame: CTFrame) -> [NSRange] {
|
||
let lines = CTFrameGetLines(frame) as! [CTLine]
|
||
return lines.map {
|
||
let lineRange = CTLineGetStringRange($0)
|
||
return NSRange(location: lineRange.location, length: lineRange.length)
|
||
}
|
||
}
|
||
|
||
/// 逐句对齐 WXRead `WRChapterPageCount.recalculatePageRangesForAttributedString` 的分页循环：
|
||
/// 1. 取出 CTFrame 当前页的所有行
|
||
/// 2. 读取每行 origin
|
||
/// 3. 用 `lineY - ascent > usableHeight` 判断是否越过可用高度
|
||
/// 4. 累计能容纳行的字符数得到本页范围
|
||
private func proposedRangeUsingWXReadPageCount(
|
||
from frame: CTFrame,
|
||
start location: Int,
|
||
usableHeight: CGFloat,
|
||
totalLength: Int
|
||
) -> NSRange {
|
||
let lines = CTFrameGetLines(frame) as! [CTLine]
|
||
guard !lines.isEmpty else {
|
||
return NSRange(location: location, length: 0)
|
||
}
|
||
|
||
var origins = [CGPoint](repeating: .zero, count: lines.count)
|
||
CTFrameGetLineOrigins(frame, CFRangeMake(0, 0), &origins)
|
||
|
||
var pageCharCount = 0
|
||
for (index, line) in lines.enumerated() {
|
||
let lineRange = CTLineGetStringRange(line)
|
||
let lineY = origins[index].y
|
||
var ascent: CGFloat = 0
|
||
var descent: CGFloat = 0
|
||
CTLineGetTypographicBounds(line, &ascent, &descent, nil)
|
||
|
||
if lineY - ascent > usableHeight {
|
||
break
|
||
}
|
||
|
||
pageCharCount += lineRange.length
|
||
}
|
||
|
||
if pageCharCount == 0 {
|
||
pageCharCount = 1
|
||
}
|
||
|
||
return NSRange(location: location, length: min(pageCharCount, totalLength - location))
|
||
}
|
||
|
||
#if canImport(DTCoreText)
|
||
/// 获取 DTCoreTextLayoutFrame 中所有行的字符范围
|
||
private func lineRanges(from layoutFrame: DTCoreTextLayoutFrame) -> [NSRange] {
|
||
guard let lines = layoutFrame.lines as? [DTCoreTextLayoutLine] else {
|
||
return []
|
||
}
|
||
return lines.map { $0.stringRange() }
|
||
}
|
||
#endif
|
||
|
||
// MARK: - 诊断日志
|
||
|
||
/// 生成分页诊断日志，记录分页原因、范围和语义信息
|
||
private func diagnostics(
|
||
reason: RDEPUBTextPageBreakReason,
|
||
range: NSRange,
|
||
attachmentRanges: [NSRange],
|
||
blockRange: NSRange?,
|
||
blockKinds: [RDEPUBTextBlockKind],
|
||
semanticHints: [RDEPUBTextSemanticHint],
|
||
attachmentPlacements: [RDEPUBTextAttachmentPlacement],
|
||
trigger: String? = nil
|
||
) -> [String] {
|
||
var items = ["page break: \(reason.rawValue)", "page range: \(NSStringFromRange(range))"]
|
||
if let blockRange {
|
||
items.append("block range: \(NSStringFromRange(blockRange))")
|
||
}
|
||
if !attachmentRanges.isEmpty {
|
||
items.append("attachment ranges: \(attachmentRanges.map(NSStringFromRange).joined(separator: ","))")
|
||
}
|
||
if !blockKinds.isEmpty {
|
||
items.append("block kinds: \(blockKinds.map(\.rawValue).joined(separator: ","))")
|
||
}
|
||
if !semanticHints.isEmpty {
|
||
items.append("semantic hints: \(semanticHints.map(\.rawValue).joined(separator: ","))")
|
||
}
|
||
if !attachmentPlacements.isEmpty {
|
||
items.append("attachment placements: \(attachmentPlacements.map(\.rawValue).joined(separator: ","))")
|
||
}
|
||
if let trigger, !trigger.isEmpty {
|
||
items.append("semantic trigger: \(trigger)")
|
||
}
|
||
return items
|
||
}
|
||
}
|