阅读器修改

This commit is contained in:
shenlei
2026-10-23 19:29:45 +09:00
parent e59bad9abf
commit 4388831abb
14 changed files with 536 additions and 81 deletions
+60
View File
@@ -0,0 +1,60 @@
# PDF 阅读器可下沉到 SDK 的功能排查(2026-08-14)
起因:Demo 侧切换主题时发现 PDF 页面图片不跟随主题变色(`configuration.pageImageTransform` 只在自定义 Provider 分支设置,内置 PDFKit Provider 默认分支漏接),修复后追问"其它宿主接入这个 SDK 要怎么处理""能不能直接下沉到 SDK"。本次以 `PDFDemoReaderViewController.swift` 为对象,对照 EPUB 侧 `RDEPUBReaderController` 已经内置的能力,排查还有哪些当前由宿主(Demo)自己实现、但更适合下沉进 `RDPDFReaderView` SDK 的逻辑。
---
## 1. 页面图片主题变色(已修复,作为对照案例)
- **现象**:切换主题面板后,工具栏、页面背景色都跟着变了,页面图片本身颜色不变。
- **根因**:`PDFDemoReaderViewController.init` 只在 `textSource != .vision`(自定义 `PDFDemoPageProvider`)分支设置了 `configuration.pageImageTransform`;默认使用内置 PDFKit Provider 的 `.vision` 分支从未设置这个闭包,SDK 渲染页面图片时没有变色规则可用。
- **已做的修复**:把 `PDFDemoPageProvider.transformed(_:for:)` 改成 `static`,在两个分支之前统一设置 `configuration.pageImageTransform`(`PDFDemoReaderViewController.swift:185-193`)。
- **是否应下沉**:`configuration.pageImageTransform` 目前默认是 `nil`,需要宿主主动实现"怎么变色"(反相 / multiply 混合 / 其它算法),这是 SDK 有意留的口子——不同宿主对 PDF 位图配色的诉求不同。但这次 Demo 自己就漏接了默认分支,说明"每个宿主接入都要记得实现并设置这个闭包"不可靠。**建议**:把 Demo 里这套默认规则(夜间反相、其它主题 multiply 背景色)下沉成 SDK 内置默认实现,`pageImageTransform` 保留但给一个非 `nil` 的默认值,宿主不传就有合理效果,要自定义配色时仍可覆盖。
---
## 2. 宿主导航栏 / 侧滑返回手势的保存与恢复(优先级最高)
- **现状**:`PDFDemoReaderViewController.viewWillAppear/viewWillDisappear`(`PDFDemoReaderViewController.swift:251-260`)只保存/恢复了 `navigationController?.isNavigationBarHidden`,完全没有处理 `interactivePopGestureRecognizer`。
- **对照**:EPUB 侧 `RDEPUBReaderController.viewWillAppear/viewWillDisappear`(`Sources/RDEpubReaderView/EPUBUI/RDEPUBReaderController.swift:289-314`)在 **SDK 内部**同时保存/恢复了导航栏隐藏状态 **和** `interactivePopGestureRecognizer.isEnabled` / `.delegate`。这正是历史上"退出 EPUB 阅读器后宿主侧滑返回手势被改成阅读器配置"那个 bug 的修复点(`git log`: `修复退出 EPUB 阅读器后宿主侧滑返回手势被改成阅读器的配置`)。
- **风险**:PDF 侧目前完全没有这层保护。`RDPDFReaderView+Paging.swift` 里横向翻页 / 仿真翻页会启用 `curlPanGestureRecognizer` / `panGestureRecognizer` 等手势,理论上和宿主的边缘侧滑返回手势存在同一类冲突风险,只是 Demo 用 `addChild` 直接嵌入、且未触发。任何把 `RDPDFReaderViewController` 塞进 `UINavigationController` 的宿主都可能复现 EPUB 已经修过的同一个 bug。
- **建议**:把这段保存/恢复逻辑下沉进 `RDPDFReaderViewController` 自己的 `viewWillAppear/viewWillDisappear`,不要指望每个宿主照抄 EPUB 那份实现。
---
## 3. 书籍标识符 → 本地存储路径的哈希派生
- **现状**:`RDPDFReaderPersistenceStore.init(rootURL:)` 要求宿主自己把 `bookIdentifier` 转换成文件系统安全的目录。Demo 为此手写了一段 SHA256 哈希 + 旧路径迁移逻辑(`PDFDemoReaderViewController.swift:359-378`:`annotationStorageURL` / `annotationStorageRoot` / `migrateLegacyAnnotationsIfNeeded`)。
- **对照**:EPUB 侧同样的需求由 SDK 内部完成——`RDEPUBReaderPersistence.swift:85-99` 直接对 `storageKey` 做 SHA256 定长摘要(注释:"编码会翻倍,长书名很容易撞上 255 字节的文件名上限"),宿主只需要传原始 `bookIdentifier`。
- **风险**:PDF 侧把这一步甩给宿主,等于要求每个接入方重新实现一遍"长标识符定长摘要、避免撞文件名长度上限"的逻辑,且各家哈希方式可能不一致(不影响正确性,但不利于统一约定/迁移工具复用)。
- **建议**:给 `RDPDFReaderPersistenceStore` 增加一个按 `bookIdentifier` 派生路径的初始化方式(内部做哈希),对齐 EPUB 的 `RDEPUBReaderPersistence` 用法。
- **不建议下沉的部分**:`migrateLegacyAnnotationsIfNeeded` 里"旧 base64 路径迁移到新哈希路径"是 Demo 自己的历史遗留迁移代码(Demo 早期用 base64 编码绝对路径作为目录名),不是通用需求。
---
## 4.(次要)AI 助手 Provider 按 iOS 版本选择
- **现状**:`presentAIAssistant()` 里用 `#available(iOS 26.0, *)` 分支选择 `RDAIAppleFoundationModelsProvider()`,否则走默认 Provider(`PDFDemoReaderViewController.swift:268-274`)。
- **评估**:目前只有这一处用到,且功能已被 `Self.showsAIAssistant = false` 关闭,影响面很小。可以考虑让 `makeAIReaderAssistant()` 自己按运行时可用性选默认 Provider,减少宿主分支代码,但优先级明显低于第 2、3 项。
---
## 结论与优先级
1. **P0(已实施)**:宿主导航栏 / 侧滑返回手势保存恢复(第 2 项)——和已修过的 EPUB bug 同一类风险,其他 PDF 宿主随时可能踩中。
2. **P1(已实施)**:`bookIdentifier` → 存储路径哈希派生(第 3 项)——对齐 EPUB 已有做法,减少宿主重复实现。
3. **P1(已实施)**:页面图片主题变色默认实现(第 1 项)。
4. **P2(待决定,见下)**:AI 助手 Provider 按 iOS 版本自动选择(第 4 项)。
---
## 实施记录(2026-08-14)
- **第 2 项**:`RDPDFReaderViewController` 新增 `navigationBarHiddenBeforeReader` / `interactivePopWasEnabledBeforeReader` / `interactivePopDelegateBeforeReader`,在 `viewWillAppear`/`viewWillDisappear` 中保存与恢复导航栏隐藏状态及侧滑返回手势,实现与 `RDEPUBReaderController` 对齐(`Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift`)。Demo 侧 `PDFDemoReaderViewController` 用 `addChild` 把 `RDPDFReaderViewController` 嵌为子控制器,其 `viewWillAppear/viewWillDisappear` 会由 UIKit 自动转发给子控制器(子控制器在父控制器 `viewDidLoad` 阶段就已 `addChild`,符合标准 containment 转发条件),因此已删除 Demo 自己重复的保存/恢复代码。`testPDFBackButtonReturnsToBookList` 验证了返回后导航栏状态正确恢复。
- **第 3 项**:`RDPDFReaderPersistenceStore` 新增 `init(bookIdentifier:baseDirectory:directoryName:)` 便利构造器与 `static func storageDirectoryURL(bookIdentifier:baseDirectory:directoryName:)`,内部对 `bookIdentifier` 做 SHA256 定长摘要(算法与 Demo 原实现字节级一致)。Demo 侧 `annotationStorageURL(for:legacyBookURL:)` 改为调用该静态方法,且显式传入原有的 `directoryName: "RDPDFImageReaderAnnotations"`,存量用户的标注/书签/阅读进度路径不变,不触发数据迁移。`migrateLegacyAnnotationsIfNeeded` 保持不变(Demo 自身的历史迁移逻辑,未下沉)。
- **第 1 项**:新增 `RDPDFReaderPageImageTransform.apply(_:theme:)`(`Sources/RDPDFReaderView/Sources/RDPDFReaderPageImageTransform.swift`),规则改为按主题 `contentBackgroundColor` 的感知亮度判定(纯白不处理、亮度 <0.5 反相、其余正片叠底),不再依赖 Demo 那种按 `identifier` 数值分支的写法,因此对任意宿主自定义主题集合都有合理默认,不只是对 SDK `defaultPresets` 生效。`Configuration.pageImageTransform` 默认值改为该函数(原来是 `nil`),宿主不设置也有效果,仍可整体覆盖或显式设为 `nil` 关闭。经验证该规则在 SDK `defaultPresets`(6 个主题,含 identifier 5 夜间)下与 Demo 原 `PDFDemoPageProvider.transformed` 逐主题行为一致,因此已删除 Demo 侧的重复实现和 `configuration.pageImageTransform` 赋值。
- **验证**:`xcodebuild ... build` 通过;`ReaderOpenCloseTests/testPDFBackButtonReturnsToBookList` 通过。`PDFAnnotationTests/testPDFAnnotationPersistsAfterClosingAndReopeningBook` 在改动前后(用 `git worktree` 检出未改动的 `HEAD` 单独验证)均在同一步骤失败(长按拖选文字未弹出选区菜单),确认是与本次改动无关的既有模拟器手势时序问题,不在本次范围内修复。
## 第 4 项:暂不实施
排查后发现比文档原判断更明确的成本:`makeAIReaderAssistant()` 无参版本目前定义在 `Sources/RDPDFReaderView/AI/RDPDFAIContentProvider.swift`,随 podspec 的 `AI` subspec 一起分发,该 subspec 只依赖 `RDAIReaderView/NaturalLanguage` 与 `RDAIReaderView/UI`,并不依赖 `RDAIReaderView/FoundationModels`。要让 SDK 自己按 `#available(iOS 26.0, *)` 选择 `RDAIAppleFoundationModelsProvider()`,`AI` subspec 必须新增对 `RDAIReaderView/FoundationModels`(弱链接 `FoundationModels.framework`)的依赖——这会让**所有**接入 PDF `AI` subspec 的宿主都多引入一个新依赖边界,即便他们不需要苹果端上模型。而当前该功能在 Demo 里通过 `showsAIAssistant = false` 整体关闭,收益很小。建议维持宿主自选(现状),除非有宿主明确要接入 AI 助手入口且愿意接受这个新依赖,再评估是否值得下沉。
@@ -374,10 +374,14 @@
inputFileListPaths = (
"${PODS_ROOT}/Target Support Files/Pods-ReadViewDemo/Pods-ReadViewDemo-frameworks-${CONFIGURATION}-input-files.xcfilelist",
);
inputPaths = (
);
name = "[CP] Embed Pods Frameworks";
outputFileListPaths = (
"${PODS_ROOT}/Target Support Files/Pods-ReadViewDemo/Pods-ReadViewDemo-frameworks-${CONFIGURATION}-output-files.xcfilelist",
);
outputPaths = (
);
runOnlyForDeploymentPostprocessing = 0;
shellPath = /bin/sh;
shellScript = "\"${PODS_ROOT}/Target Support Files/Pods-ReadViewDemo/Pods-ReadViewDemo-frameworks.sh\"\n";
@@ -539,7 +543,7 @@
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";
"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Distribution";
CODE_SIGN_STYLE = Manual;
CURRENT_PROJECT_VERSION = 1;
DEVELOPMENT_TEAM = "";
@@ -560,7 +564,7 @@
PRODUCT_BUNDLE_IDENTIFIER = cn.shen.ReadViewDemo;
PRODUCT_NAME = "$(TARGET_NAME)";
PROVISIONING_PROFILE_SPECIFIER = "";
"PROVISIONING_PROFILE_SPECIFIER[sdk=iphoneos*]" = TouchLinked_dev;
"PROVISIONING_PROFILE_SPECIFIER[sdk=iphoneos*]" = TouchLinked_adHoc;
STRING_CATALOG_GENERATE_SYMBOLS = YES;
SWIFT_APPROACHABLE_CONCURRENCY = YES;
SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor;
@@ -1,6 +1,5 @@
import UIKit
import PDFKit
import CryptoKit
import RDPDFReaderView
import RDAIReaderView
import RDSpeechReaderView
@@ -21,12 +20,17 @@ private final class PDFDemoPageProvider: RDPDFReaderPageProvider, RDPDFReaderOut
private let renderQueue = DispatchQueue(label: "com.readviewsdk.demo-pdf-render", qos: .userInitiated)
private let images = NSCache<NSNumber, UIImage>()
private var outlineItemsCache: [RDPDFReaderOutlineItem]?
/// 测试钩子:首次被请求该页时返回 `image == nil`(模拟宿主页面图尚未就绪),
/// 之后返回真实图。用于验证朗读/AI 预取不会把无图结果写进显示缓存。
private let nilImageOnceForPage: Int?
private var servedNilForProbePage = false
init(document: PDFDocument, identifier: String, title: String, textSource: PDFDemoImageTextSource) {
init(document: PDFDocument, identifier: String, title: String, textSource: PDFDemoImageTextSource, nilImageOnceForPage: Int? = nil) {
self.document = document
self.identifier = identifier
self.title = title
self.textSource = textSource
self.nilImageOnceForPage = nilImageOnceForPage
images.countLimit = 6
images.totalCostLimit = 96 * 1024 * 1024
}
@@ -43,6 +47,11 @@ private final class PDFDemoPageProvider: RDPDFReaderPageProvider, RDPDFReaderOut
}
renderQueue.async { [weak self] in
guard let self else { return }
if let probePage = self.nilImageOnceForPage, index == probePage, !self.servedNilForProbePage {
self.servedNilForProbePage = true
DispatchQueue.main.async { completion(.init(index: index, image: nil, textRuns: textRuns)) }
return
}
let image = self.image(at: index)
DispatchQueue.main.async { completion(.init(index: index, image: image, textRuns: textRuns)) }
}
@@ -98,23 +107,6 @@ private final class PDFDemoPageProvider: RDPDFReaderPageProvider, RDPDFReaderOut
return resolved
}
func transformed(_ image: UIImage, for theme: RDPDFReaderThemeOption) -> UIImage {
// 图片缓存属于 PDFKit 适配层;SDK 只声明当前主题,不拥有原图或缓存策略。
guard theme.identifier != 0 else { return image }
if theme.identifier == 5, let ciImage = CIImage(image: image), let filter = CIFilter(name: "CIColorInvert") {
filter.setValue(ciImage, forKey: kCIInputImageKey)
if let output = filter.outputImage, let cgImage = CIContext().createCGImage(output, from: output.extent) {
return UIImage(cgImage: cgImage, scale: image.scale, orientation: image.imageOrientation)
}
}
let renderer = UIGraphicsImageRenderer(size: image.size)
return renderer.image { _ in
theme.contentBackgroundColor.setFill()
UIBezierPath(rect: CGRect(origin: .zero, size: image.size)).fill()
image.draw(in: CGRect(origin: .zero, size: image.size), blendMode: .multiply, alpha: 1)
}
}
private func image(at index: Int) -> UIImage? {
if let image = images.object(forKey: NSNumber(value: index)) { return image }
guard let page = document.page(at: index) else { return nil }
@@ -156,6 +148,10 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
private static let showsAIAssistant = false
private static let showsSpeechControls = false
private let reader: RDPDFReaderViewController
/// 测试钩子:非空时,阅读器加载后用 `speechTextRuns` 预取到该页 + 1,
/// 覆盖“朗读预取遇到暂时无图的页”这条路径。
private let speechWhitePageProbe: Int?
private var speechProbeDidComplete = false
private lazy var speechSession: RDPDFSpeechSession = {
let session = reader.makeSpeechSession()
session.onStateChange = { [weak self] state in
@@ -165,7 +161,6 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
return session
}()
private let speechControls = RDSpeechReaderControlView()
private var navigationBarHiddenBeforeReader: Bool?
private var display = "pagecurl"
private var lastPageIndex = 0
private var lastCopiedText: String?
@@ -177,13 +172,15 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
return label
}()
init(url: URL, bookIdentifier: String? = nil, textSource: PDFDemoImageTextSource = .vision) {
init(url: URL, bookIdentifier: String? = nil, textSource: PDFDemoImageTextSource = .vision, speechWhitePageProbe: Int? = nil) {
let identifier = bookIdentifier ?? url.lastPathComponent
let store = RDPDFReaderPersistenceStore(rootURL: Self.annotationStorageURL(for: identifier, legacyBookURL: url))
var configuration = RDPDFReaderViewController.Configuration()
configuration.enablesOCR = textSource == .vision
configuration.missingTextSource = .region
configuration.recognitionLanguages = ["zh-Hans", "en-US"]
// 页面图片配色使用 SDK 内置默认规则(深色主题反相、浅色有色主题正片叠底),
// 两个分支(内置 PDFKit Provider / 自定义 Provider)都自动生效,无需自行设置。
if textSource != .vision {
guard let document = PDFDocument(url: url) else { fatalError("无法打开 PDF") }
@@ -191,13 +188,12 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
document: document,
identifier: identifier,
title: url.deletingPathExtension().lastPathComponent,
textSource: textSource
textSource: textSource,
nilImageOnceForPage: speechWhitePageProbe
)
configuration.pageImageTransform = { [weak provider] image, theme in
provider?.transformed(image, for: theme) ?? image
}
reader = RDPDFReaderViewController(
pageProvider: provider,
persistence: store,
annotationPersistence: store,
configuration: configuration
)
@@ -206,6 +202,7 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
reader = try RDPDFReaderViewController(
pdfURL: url,
bookIdentifier: identifier,
persistence: store,
annotationPersistence: store,
configuration: configuration
)
@@ -213,6 +210,7 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
fatalError("无法打开 PDF:\(error.localizedDescription)")
}
}
self.speechWhitePageProbe = speechWhitePageProbe
super.init(nibName: nil, bundle: nil)
reader.delegate = self
title = url.deletingPathExtension().lastPathComponent
@@ -241,24 +239,26 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
stateLabel.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(stateLabel)
NSLayoutConstraint.activate([stateLabel.widthAnchor.constraint(equalToConstant: 1), stateLabel.heightAnchor.constraint(equalToConstant: 1), stateLabel.topAnchor.constraint(equalTo: view.topAnchor), stateLabel.leadingAnchor.constraint(equalTo: view.leadingAnchor)])
updateState(page: 0)
}
// reader.view 上屏时 RDPDFReaderViewController 可能已恢复到上次阅读页,
// 别用 0 覆盖它自己 didChangePage 报出来的页码。
updateState(page: reader.currentPageIndex)
override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated)
if navigationBarHiddenBeforeReader == nil { navigationBarHiddenBeforeReader = navigationController?.isNavigationBarHidden }
navigationController?.setNavigationBarHidden(true, animated: animated)
}
override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
if let hidden = navigationBarHiddenBeforeReader { navigationController?.setNavigationBarHidden(hidden, animated: animated) }
if let probe = speechWhitePageProbe {
Task { [weak self] in
guard let self else { return }
for page in 0...(probe + 1) {
_ = await self.reader.speechTextRuns(at: page)
}
self.speechProbeDidComplete = true
self.updateState(page: self.lastPageIndex)
}
}
}
func applyDemoDisplayType(_ type: RDPDFReaderView.DisplayType) {
reader.switchDisplayType(type)
display = type == .pageCurl ? "pagecurl" : (type == .verticalScroll ? "verticalscroll" : "horizontalscroll")
updateState(page: 0)
updateState(page: reader.currentPageIndex)
}
@objc private func presentAIAssistant() {
@@ -293,6 +293,9 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
private func updateState(page: Int) {
lastPageIndex = page
var state = "reader=opened mode=pdf page=\(page + 1) display=\(display)"
if speechProbeDidComplete {
state += " speechProbe=done"
}
if let lastCopiedText {
// 状态字段以空格分隔,文本需百分号编码;UI 测试端会解码还原。
let encoded = lastCopiedText.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? ""
@@ -353,9 +356,12 @@ final class PDFDemoReaderViewController: UIViewController, RDPDFReaderViewContro
}
private static func annotationStorageURL(for bookIdentifier: String, legacyBookURL: URL) -> URL {
let root = annotationStorageRoot()
let hash = SHA256.hash(data: bookIdentifier.data(using: .utf8) ?? Data()).map { String(format: "%02x", $0) }.joined()
let destination = root.appendingPathComponent(hash, isDirectory: true)
// 目录哈希派生已下沉到 SDK;directoryName 保持与旧版一致,避免存量用户的
// 标注/书签/阅读进度在升级后“凭空丢失”。
let destination = RDPDFReaderPersistenceStore.storageDirectoryURL(
bookIdentifier: bookIdentifier,
directoryName: annotationStorageFolderName
)
migrateLegacyAnnotationsIfNeeded(from: legacyBookURL, to: destination)
return destination
}
@@ -24,6 +24,7 @@ final class ViewController: UIViewController {
let enablesVerboseWebLogs: Bool
let searchKeyword: String?
let pdfTextSource: String?
let pdfSpeechWhitePageProbe: Int?
nonisolated private static func parseDisplayType(_ rawValue: String) -> RDEpubReaderView.DisplayType? {
switch rawValue.lowercased() {
@@ -67,6 +68,7 @@ final class ViewController: UIViewController {
let enablesVerboseWebLogs = arguments.contains("--demo-enable-verbose-weblogs")
let searchKeyword = value(after: "--demo-search-keyword")
let pdfTextSource = value(after: "--demo-pdf-text-source")
let pdfSpeechWhitePageProbe = value(after: "--demo-pdf-speech-whitepage-probe").flatMap(Int.init)
return LaunchAutomationPlan(
bookTitleQuery: bookTitleQuery,
@@ -82,7 +84,8 @@ final class ViewController: UIViewController {
allowsInspectableWebViews: allowsInspectableWebViews,
enablesVerboseWebLogs: enablesVerboseWebLogs,
searchKeyword: searchKeyword,
pdfTextSource: pdfTextSource
pdfTextSource: pdfTextSource,
pdfSpeechWhitePageProbe: pdfSpeechWhitePageProbe
)
}
}
@@ -268,7 +271,8 @@ final class ViewController: UIViewController {
let controller = PDFDemoReaderViewController(
url: book.fileURL,
bookIdentifier: "demo.pdf.\(book.fileURL.lastPathComponent)",
textSource: textSource
textSource: textSource,
speechWhitePageProbe: automationPlan?.pdfSpeechWhitePageProbe
)
if let navigationController {
navigationController.pushViewController(controller, animated: true)
@@ -26,7 +26,8 @@ extension XCUIApplication {
allowsInspectableWebViews: Bool = false,
enablesVerboseWebLogs: Bool = false,
searchKeyword: String? = nil,
pdfTextSource: String? = nil
pdfTextSource: String? = nil,
pdfSpeechWhitePageProbe: Int? = nil
) {
var args = ["--demo-book-title", bookTitleQuery]
if resetsReaderState {
@@ -62,6 +63,9 @@ extension XCUIApplication {
if let pdfTextSource {
args += ["--demo-pdf-text-source", pdfTextSource]
}
if let pdfSpeechWhitePageProbe {
args += ["--demo-pdf-speech-whitepage-probe", "\(pdfSpeechWhitePageProbe)"]
}
launchArguments = args
launch()
}
@@ -205,4 +205,71 @@ final class LocationPersistenceTests: XCTestCase {
}
XCTAssertEqual(restoredState.page, 3, "字体变化后,通过高亮面板跳转仍应回到原始高亮页")
}
// MARK: - PDF 阅读进度恢复
//
// 回归点:`RDPDFReaderViewController.viewDidLoad` 里 `reloadData()` 会同步触发
// `pageNum(0)` → `saveReadingPage(0)`,把待恢复的页覆盖成 0,导致 `restoreReadingPage`
// 永远读到第 1 页。修复:`reloadData()` 前先读恢复页,恢复窗口内跳过写盘。
// 前置:Demo 侧 `PDFDemoReaderViewController` 现已把 `RDPDFReaderPersistenceStore`
// 同时作为 `persistence:` 传入(此前只传了 `annotationPersistence:`)。
func testPDFReadingPositionRestoredOnReopen() throws {
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
pageNumber: 4,
resetsReaderState: true,
pdfTextSource: "none"
)
app.waitForReader(timeout: 30)
let moved = app.waitForDemoReaderState(timeout: 20, description: "PDF 跳到第 4 页") { $0.page == 4 }
XCTAssertEqual(moved.page, 4)
// 翻页写盘有 1s 防抖,再留出后台 IO 队列写文件的时间。
RunLoop.current.run(until: Date().addingTimeInterval(2.5))
app.showReaderChromeIfNeeded()
let back = app.buttons[IDs.readerBack]
XCTAssertTrue(back.waitForExistence(timeout: 5), "返回按钮应出现")
back.tap()
XCTAssertTrue(app.tables[IDs.demoBooksTable].waitForExistence(timeout: 8), "应返回书库列表")
RunLoop.current.run(until: Date().addingTimeInterval(1.5))
// 重开必须保留状态,displayType 不传:避免 Demo 的 applyDemoDisplayType 把
// 状态标签重置成 page=1 干扰断言。
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
resetsReaderState: false,
pdfTextSource: "none"
)
app.waitForReader(timeout: 30)
let restored = app.waitForDemoReaderState(timeout: 15, description: "PDF 恢复到第 4 页") { $0.page == 4 }
XCTAssertEqual(restored.page, 4, "重开 PDF 应恢复上次阅读页,而不是被开局 reloadData 覆盖成第 1 页")
}
func testPDFResetStateClearsPersistedReadingPage() throws {
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
pageNumber: 5,
resetsReaderState: true,
pdfTextSource: "none"
)
app.waitForReader(timeout: 30)
app.waitForDemoReaderState(timeout: 20, description: "PDF 跳到第 5 页") { $0.page == 5 }
RunLoop.current.run(until: Date().addingTimeInterval(2.5))
app.showReaderChromeIfNeeded()
let back = app.buttons[IDs.readerBack]
if back.waitForExistence(timeout: 5) { back.tap() }
RunLoop.current.run(until: Date().addingTimeInterval(1.0))
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
resetsReaderState: true,
pdfTextSource: "none"
)
app.waitForReader(timeout: 30)
let state = app.waitForDemoReaderState(timeout: 15, description: "reset 后回到第 1 页") { $0.page != nil }
XCTAssertEqual(state.page, 1, "--demo-reset-state 应清掉 reader-state.json,重开回到第 1 页")
}
}
@@ -35,11 +35,12 @@ final class PDFPageTurnBlankPageTests: XCTestCase {
// MARK: - 步骤
private func openDictionaryPDF(displayType: String) {
private func openDictionaryPDF(displayType: String, textSource: String? = nil) {
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
displayType: displayType,
resetsReaderState: true
resetsReaderState: true,
pdfTextSource: textSource
)
app.waitForReader(timeout: 30)
app.waitForReaderPage(1, timeout: 30)
@@ -144,4 +145,108 @@ final class PDFPageTurnBlankPageTests: XCTestCase {
}
return Double(darkCount) / Double(side * side)
}
// MARK: - 主题切换:变换缓存失效正确性
//
// 回归点:`pageImageTransform` 结果现按 (页码, 主题 id) 缓存。若失效点漏接,
// 切主题 / 翻页 / 内存回收后会显示上一个主题算出的陈旧帧。此用例churn 页面并
// 在夜间/浅色间往返,确认没有陈旧帧、也没有因缓存导致的白页。
// 注:XCUITest 无法可靠地测毫秒级耗时;这里以“缓存正确性”作为性能修复的回归护栏。
func testDarkThemeSurvivesPageChurnWithoutStaleOrBlankFrames() {
openDictionaryPDF(displayType: "horizontalscroll", textSource: "none")
let lightRatio = currentInkRatio()
XCTAssertGreaterThan(lightRatio, blankInkRatioThreshold, "首页不应是白页")
XCTAssertLessThan(lightRatio, 0.35, "浅色主题下正文页不应接近全黑(ink=\(lightRatio))")
switchTheme(toIdentifier: 5) // 夜间:contentBackgroundColor 亮度 < 0.5 → 整页反相
let darkRatio = currentInkRatio()
XCTAssertGreaterThan(darkRatio, 0.5, "切到夜间主题后正文页应被反相为深色(ink=\(darkRatio))")
app.hideReaderChromeIfNeeded()
// 前翻 3 页:每页首次 configure 命中/回填变换缓存;翻页同时触发
// trimPageDescriptorCache 的 renderedImageCache 失效路径。
for page in 2...4 {
turnPageAndWait(toPage: page, forward: true)
let r = currentInkRatio()
XCTAssertGreaterThan(r, blankInkRatioThreshold, "夜间主题前翻后出现白页(page \(page),ink=\(r))")
XCTAssertGreaterThan(r, 0.4, "夜间主题前翻后出现未反相的浅色帧(page \(page),ink=\(r))")
}
for page in stride(from: 3, through: 1, by: -1) {
turnPageAndWait(toPage: page, forward: false)
let r = currentInkRatio()
XCTAssertGreaterThan(r, 0.4, "夜间主题回翻后出现未反相的浅色帧(page \(page),ink=\(r))")
}
switchTheme(toIdentifier: 0) // 浅色
let restoredLight = currentInkRatio()
XCTAssertLessThan(
restoredLight, 0.35,
"切回浅色主题后应立即用浅色帧;陈旧的深色变换缓存未随 apply(theme) 清除(ink=\(restoredLight))"
)
}
// MARK: - 朗读预取遇到暂时无图的页,不应把该页永久变白
//
// 回归点:`speechTextRuns(at:)` 之前会无条件把 provider 返回的 descriptor 写进
// `pageDescriptors`,即使 `image == nil`。之后翻到该页时 `configure` 的
// `guard descriptor == nil else { … return }` 短路,页面永久白屏、也不重试。
// 修复:仅在 `descriptor.image != nil` 时写缓存。
func testSpeechPrefetchDoesNotBlankPageWhenImageArrivesLate() {
// probe=3:宿主 Provider 首次被请求 index 3(第 4 页)时返回 image=nil,
// 之后返回真实图;阅读器加载后用 speechTextRuns 预取到 index 4。
app.launchAndOpenSampleBook(
bookTitleQuery: "英汉大词典",
displayType: "horizontalscroll",
resetsReaderState: true,
pdfTextSource: "none",
pdfSpeechWhitePageProbe: 3
)
app.waitForReader(timeout: 30)
app.waitForReaderPage(1, timeout: 30)
_ = app.waitForDemoReaderState(timeout: 30, description: "朗读预取完成") { $0["speechProbe"] == "done" }
app.hideReaderChromeIfNeeded()
// 翻到第 4 页(index 3)——被预取“污染”的那一页。
for page in 2...4 {
turnPageAndWait(toPage: page, forward: true)
}
let ratio = currentInkRatio()
XCTAssertGreaterThan(
ratio, blankInkRatioThreshold,
"朗读预取到暂时无图的页后,翻到该页仍是白页(ink=\(ratio))——speechTextRuns 不应缓存无图 descriptor"
)
}
// MARK: - 辅助
private func currentInkRatio() -> Double {
RunLoop.current.run(until: Date().addingTimeInterval(0.4))
return inkRatio(of: XCUIScreen.main.screenshot().image)
}
private func turnPageAndWait(toPage page: Int, forward: Bool) {
turnPage(forward: forward)
app.waitForDemoReaderState(timeout: 15, description: "page=\(page)") { $0.page == page }
// 翻页动画 + 异步页面图装配完成后再取样。
RunLoop.current.run(until: Date().addingTimeInterval(1.2))
}
private func switchTheme(toIdentifier identifier: Int) {
app.showReaderChromeIfNeeded()
let settings = app.buttons[IDs.readerSettings]
XCTAssertTrue(settings.waitForExistence(timeout: 5), "设置按钮应存在")
settings.tap()
let themeButton = app.buttons[IDs.settingsTheme(identifier)]
XCTAssertTrue(themeButton.waitForExistence(timeout: 5), "主题按钮 \(identifier) 应存在")
themeButton.tap()
let done = app.buttons[IDs.settingsDone]
if done.waitForExistence(timeout: 3) { done.tap() }
// 面板关闭动画 + 当前页按新主题重绘。
RunLoop.current.run(until: Date().addingTimeInterval(1.0))
}
}
@@ -93,6 +93,7 @@ final class RDPDFInteractionHotspotView: UIView {
deinit {
flickerTimer?.invalidate()
flickerTimer = nil
if let embedPlayerViewController {
embedPlayerViewController.player?.pause()
embedPlayerViewController.willMove(toParent: nil)
@@ -231,8 +232,10 @@ final class RDPDFInteractionHotspotView: UIView {
func setActive(_ active: Bool) {
guard isActive != active else { return }
isActive = active
// 彻底清理任何正在进行的闪烁
flickerTimer?.invalidate()
flickerTimer = nil
remainingFlickerToggles = 0
styleView.layer.removeAllAnimations()
applyBorderAndFillColors()
if active {
@@ -230,22 +230,21 @@ public final class RDPDFKitPageProvider: RDPDFReaderPageProvider, RDPDFReaderOut
return runs
}
/// 使用完整文件内容生成稳定身份。按块读取避免大 PDF 一次性进入内存;绝对路径、
/// 修改时间不参与签名,因此应用容器迁移或重新下载不会丢失阅读状态。
/// 用文件名 + 大小 + 头部 64KB 内容生成稳定身份。绝对路径、修改时间不参与签名,
/// 因此应用容器迁移或重新下载不会丢失阅读状态;只读头部而非整文件,避免大 PDF
/// 在 `init`(通常主线程)里对几十~上百 MB 做同步哈希阻塞打开。
private static func defaultBookIdentifier(for url: URL) -> String {
let fileURL = url.standardizedFileURL
let fileSize = (try? fileURL.resourceValues(forKeys: [.fileSizeKey]))?.fileSize
guard let handle = try? FileHandle(forReadingFrom: fileURL) else {
let fallback = "\(fileURL.lastPathComponent)|\(fileSize.map(String.init) ?? "")"
return "pdf.\(RDPDFReaderTextRunDiskCache.stableIdentifier(for: fallback))"
}
defer { handle.closeFile() }
var hasher = SHA256()
while true {
let chunk = handle.readData(ofLength: 1024 * 1024)
guard chunk.isEmpty == false else { break }
hasher.update(data: chunk)
hasher.update(data: Data(fileURL.lastPathComponent.utf8))
if let fileSize {
withUnsafeBytes(of: UInt64(fileSize).littleEndian) { hasher.update(data: Data($0)) }
}
if let handle = try? FileHandle(forReadingFrom: fileURL) {
defer { handle.closeFile() }
hasher.update(data: handle.readData(ofLength: 64 * 1024))
}
let digest = hasher.finalize().map { String(format: "%02x", $0) }.joined()
return "pdf.sha256.\(digest)"
@@ -372,6 +372,13 @@ public final class RDPDFReaderView: UIView, UIGestureRecognizerDelegate {
public func setDrawingToolActive(_ active: Bool) { zoomOverlayView.isDrawingToolActive = active }
public func hideToolViewIfNeeded() { if isToolViewVisible { toggleToolbars() } }
public func refreshCurrentPageIfNeeded() { pageContentView(pageNum: currentPage)?.setNeedsLayout() }
/// 页面图异步到达后,让仿真翻页容器按真实纸张尺寸重新收缩;首屏页面图迟到时
/// `updateNativeCurlBookFrame` 会因取不到 fitted frame 提前返回,之后没有其它
/// 路径重试,导致仿真书页比例/留白错误直到下一次翻页。
public func refreshPageCurlLayoutIfNeeded() {
guard currentDisplayType == .pageCurl else { return }
updateNativeCurlBookFrame()
}
public func register(contentView: UIView.Type, contentViewWithReuseIdentifier identifier: String) {
reusableTypes[identifier] = contentView
@@ -0,0 +1,48 @@
import CoreImage
import UIKit
/// `Configuration.pageImageTransform` 的内置默认实现:深色主题按反相处理,浅色系
/// 有色主题按正片叠底混合背景色,纯白/未设主题不做处理。宿主不传该闭包也能获得
/// 合理的页面图片配色,需要自定义规则时仍可整体覆盖 `pageImageTransform`。
public enum RDPDFReaderPageImageTransform {
/// 复用同一个 `CIContext`:反相分支每次新建 `CIContext` 的开销很高,且该变换会
/// 在朗读逐句高亮、OCR 回填等路径被频繁触发。
private static let sharedCIContext = CIContext(options: [.useSoftwareRenderer: false])
public static func apply(_ image: UIImage, theme: RDPDFReaderThemeOption) -> UIImage {
let background = theme.contentBackgroundColor
guard background != .white else { return image }
if background.rdPDFPerceivedBrightness < 0.5 {
return invertedImage(image) ?? image
}
return multiplyBlended(image, backgroundColor: background)
}
private static func invertedImage(_ image: UIImage) -> UIImage? {
guard let ciImage = CIImage(image: image), let filter = CIFilter(name: "CIColorInvert") else { return nil }
filter.setValue(ciImage, forKey: kCIInputImageKey)
guard let output = filter.outputImage, let cgImage = sharedCIContext.createCGImage(output, from: output.extent) else { return nil }
return UIImage(cgImage: cgImage, scale: image.scale, orientation: image.imageOrientation)
}
private static func multiplyBlended(_ image: UIImage, backgroundColor: UIColor) -> UIImage {
UIGraphicsImageRenderer(size: image.size).image { _ in
backgroundColor.setFill()
UIBezierPath(rect: CGRect(origin: .zero, size: image.size)).fill()
image.draw(in: CGRect(origin: .zero, size: image.size), blendMode: .multiply, alpha: 1)
}
}
}
private extension UIColor {
/// ITU-R BT.601 感知亮度权重,用于粗略区分“深色主题”与“浅色有色主题”。
var rdPDFPerceivedBrightness: CGFloat {
var r: CGFloat = 0, g: CGFloat = 0, b: CGFloat = 0, a: CGFloat = 0
if getRed(&r, green: &g, blue: &b, alpha: &a) {
return 0.299 * r + 0.587 * g + 0.114 * b
}
var w: CGFloat = 0
getWhite(&w, alpha: &a)
return w
}
}
@@ -36,6 +36,17 @@ public extension RDPDFReaderPageViewDelegate {
func pageView(_ pageView: RDPDFReaderPageView, didTap interaction: RDPDFReaderPageInteraction) {}
}
/// 点读热区的容器层。裸 `UIView` 在没有子视图接住触摸时,默认 `hitTest` 会返回
/// 自身,导致整页(哪怕零热区)都会截住触摸,使叠在它下面的 `textLayer` 收不到
/// 长按选区手势。这里让容器像它的热区子视图(`RDPDFInteractionHotspotView.hitTest`)
/// 一样只在真正命中某个热区时才截获触摸,否则放行给下层视图。
private final class RDPDFReaderPageInteractionOverlayView: UIView {
override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
let hit = super.hitTest(point, with: event)
return hit === self ? nil : hit
}
}
/// PDF 页面视图:组合缩放画布、文字选择层和选区放大镜,
/// 并提供与 EPUB 一致的两套系统编辑菜单:
/// - 选区菜单:复制、划线、注释;
@@ -68,7 +79,7 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
private let zoomView = RDPDFZoomablePageView()
private let textLayer = RDPDFReaderImageTextLayerView()
private let drawingCanvas = RDPDFReaderDrawingCanvasView()
private let interactionOverlay = UIView()
private let interactionOverlay = RDPDFReaderPageInteractionOverlayView()
private var pageInteractions: [RDPDFReaderPageInteraction] = []
private var activeInteractionIdentifier: String?
/// 已经在本 page view 实例上播放过入场闪烁的热区标识。`configureInteractions`
@@ -179,7 +190,11 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
flickerTrackedPageIndex = pageIndex
flickeredInteractionIdentifiers.removeAll()
}
interactionOverlay.subviews.forEach { $0.removeFromSuperview() }
// 先停止所有旧热区的闪烁,确保没有遗留的 timer
interactionOverlay.subviews.forEach { subview in
(subview as? RDPDFInteractionHotspotView)?.setActive(false)
subview.removeFromSuperview()
}
for interaction in interactions {
// 同一个热区标识如果之前已经在这一页播放过入场闪烁,这次重建只是因为
// 资源异步就绪触发的 configureInteractions,不是用户第一次看到这一页,
@@ -1,3 +1,4 @@
import CryptoKit
import Foundation
/// 标注文件无法安全读写时返回的错误。调用方应提示用户重试或导出原文件,SDK 不会
@@ -49,6 +50,9 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting,
/// 同一进程内的多个阅读器可能指向同一本书;将本地状态文件的读写串行化,
/// 避免原子替换过程中出现竞争或读取半完成文件。
private static let annotationPersistenceLock = NSLock()
/// 阅读位置 / 书签写盘走后台串行队列:这类高频更新(每次翻页)不该在主线程
/// 做整文件读 + 编码 + 原子写,原子性仍由 `annotationPersistenceLock` 保证。
private static let readerStateIOQueue = DispatchQueue(label: "com.readoor.pdf-reader.reader-state-io", qos: .utility)
private let rootURL: URL
private let drawingsURL: URL
private let highlightsURL: URL
@@ -63,6 +67,39 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting,
readerStateURL = rootURL.appendingPathComponent("reader-state.json")
}
/// 按 `bookIdentifier` 派生存储目录,宿主无需自己把标识符转换成文件系统安全的
/// 目录名。对齐 EPUB 侧 `RDEPUBProtectedContentStore` 的做法:`bookIdentifier`
/// 可能含 `/`、空格等非法字符,且长度不可控,用 SHA256 定长摘要避免撞文件名
/// 长度上限,也避免每个宿主各自实现一套不一致的哈希方案。
public convenience init(
bookIdentifier: String,
baseDirectory: URL? = nil,
directoryName: String = "ssreaderview-pdf"
) {
self.init(rootURL: Self.storageDirectoryURL(
bookIdentifier: bookIdentifier,
baseDirectory: baseDirectory,
directoryName: directoryName
))
}
/// `init(bookIdentifier:baseDirectory:directoryName:)` 使用的目录派生规则,单独
/// 暴露出来供宿主在构造 store 前需要读写同一目录时复用(例如迁移旧数据)。
public static func storageDirectoryURL(
bookIdentifier: String,
baseDirectory: URL? = nil,
directoryName: String = "ssreaderview-pdf"
) -> URL {
let base = baseDirectory
?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first
?? FileManager.default.temporaryDirectory
let digest = SHA256.hash(data: Data(bookIdentifier.utf8))
let name = digest.map { String(format: "%02x", $0) }.joined()
return base
.appendingPathComponent(directoryName, isDirectory: true)
.appendingPathComponent(name, isDirectory: true)
}
// MARK: - RDPDFReaderPersistence
public func restoreReadingPage(for bookIdentifier: String) -> Int? {
@@ -73,11 +110,13 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting,
public func saveReadingPage(_ pageIndex: Int, for bookIdentifier: String) {
guard pageIndex >= 0 else { return }
Self.annotationPersistenceLock.lock()
defer { Self.annotationPersistenceLock.unlock() }
var state = loadReaderStateLocked()
state.readingPages[bookIdentifier] = pageIndex
saveReaderStateLocked(state)
Self.readerStateIOQueue.async { [self] in
Self.annotationPersistenceLock.lock()
defer { Self.annotationPersistenceLock.unlock() }
var state = loadReaderStateLocked()
state.readingPages[bookIdentifier] = pageIndex
saveReaderStateLocked(state)
}
}
public func loadBookmarks(for bookIdentifier: String) -> [RDPDFReaderBookmark] {
@@ -90,13 +129,15 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting,
public func setBookmark(_ isBookmarked: Bool, pageIndex: Int, for bookIdentifier: String) {
guard pageIndex >= 0 else { return }
Self.annotationPersistenceLock.lock()
defer { Self.annotationPersistenceLock.unlock() }
var state = loadReaderStateLocked()
var pages = Set(state.bookmarks[bookIdentifier] ?? [])
if isBookmarked { pages.insert(pageIndex) } else { pages.remove(pageIndex) }
state.bookmarks[bookIdentifier] = pages.sorted()
saveReaderStateLocked(state)
Self.readerStateIOQueue.async { [self] in
Self.annotationPersistenceLock.lock()
defer { Self.annotationPersistenceLock.unlock() }
var state = loadReaderStateLocked()
var pages = Set(state.bookmarks[bookIdentifier] ?? [])
if isBookmarked { pages.insert(pageIndex) } else { pages.remove(pageIndex) }
state.bookmarks[bookIdentifier] = pages.sorted()
saveReaderStateLocked(state)
}
}
public func drawingPaths(pageNo: Int) -> [RDPDFReaderDrawingPath] {
@@ -4,7 +4,7 @@ import SnapKit
/// 成品 PDF 阅读控制器。自定义加密文件由宿主提供页面;普通 PDF 可由 SDK 使用
/// PDFKit 直接解析。两种来源共用阅读交互、OCR、标注及面板。
public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataSource, RDPDFReaderDelegate, RDPDFReaderPageViewDelegate {
public struct Configuration {
public var displayType: RDPDFReaderView.DisplayType = .pageCurl
/// 默认与 EPUB 成品控制器一致:横屏仿真/横滑使用双页,竖滑保持单页。
@@ -28,8 +28,10 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
public var pageDescriptorCacheRadius = 2
/// 内存中保留当前页前后的 OCR 结果数量;默认沿用页面描述缓存半径。
public var ocrMemoryCacheRadius: Int?
/// 宿主或内置 Provider 提供页面后,可在此进行反色或其它主题渲染。
public var pageImageTransform: ((UIImage, RDPDFReaderThemeOption) -> UIImage)?
/// 宿主或内置 Provider 提供页面后,可在此进行反色或其它主题渲染。默认使用
/// SDK 内置规则(深色主题反相、浅色有色主题正片叠底),宿主不设置也有合理
/// 效果;显式赋值可整体覆盖,赋值为 nil 可关闭页面图片配色。
public var pageImageTransform: ((UIImage, RDPDFReaderThemeOption) -> UIImage)? = RDPDFReaderPageImageTransform.apply
/// 试读策略。非 nil 且宿主经 delegate 提供了墙视图时启用试读墙。
public var trialPolicy: RDPDFReaderTrialPolicy?
@@ -94,6 +96,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
guard pageIndex >= 0, pageIndex < book.totalPages else { return }
clearPageDescriptorRequest(for: pageIndex)
pageDescriptors.removeValue(forKey: pageIndex)
renderedImageCache.removeValue(forKey: pageIndex)
pageLoadFailedPages.remove(pageIndex)
pageDescriptorRequestAttempts[pageIndex] = 0
refreshPageViews(at: pageIndex)
@@ -142,6 +145,21 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
private var preferredDisplayType: RDPDFReaderView.DisplayType
/// 旋转动画期间不能依赖尚未更新的 view.bounds,提前锁定目标方向以避免先建出双页。
private var phoneLandscapeTransitionOverride: Bool?
/// 宿主可能把控制器塞进 UINavigationController;进入/离开阅读器时临时接管导航栏
/// 与侧滑返回手势,离开后原样恢复,避免污染宿主配置(对齐 EPUB 侧已修过的同类问题)。
private var navigationBarHiddenBeforeReader: Bool?
private var interactivePopWasEnabledBeforeReader: Bool?
private weak var interactivePopDelegateBeforeReader: UIGestureRecognizerDelegate?
/// 初次进入恢复上次阅读页的窗口期。期间 `reloadData()` 触发的 `pageNum(0)`
/// 不能把待恢复的进度覆盖成 0。
private var isRestoringInitialReadingState = false
/// 翻页进度写盘防抖:快速翻页时合并为一次落盘。
private var readingPagePersistWork: DispatchWorkItem?
private var pendingReadingPagePersist: Int?
/// 按 (页码, 主题 identifier) 缓存变换后的页面图。`configure` 会被 OCR 回填、
/// 朗读逐句高亮、标注增删等路径高频触发,若每次都重跑整页 CIFilter/正片叠底
/// 会在主线程掉帧。
private var renderedImageCache: [Int: (theme: Int, image: UIImage)] = [:]
public init(
pageProvider: RDPDFReaderPageProvider,
@@ -220,20 +238,56 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
return availableWidth * imageSize.height / imageSize.width
}
view.addSubview(readerView)
// reloadData() 会把 currentPage 从 -1 置 0 并同步回调 pageNum(0)。必须在此之前
// 读出待恢复页,并在恢复窗口内抑制写盘,否则续读进度每次打开都被覆盖成 0。
isRestoringInitialReadingState = true
let restoredReadingPage = persistence?.restoreReadingPage(for: book.identifier)
readerView.reloadData()
applyDisplayTypeForCurrentInterface()
if let page = persistence?.restoreReadingPage(for: book.identifier), page >= 0, page < readableContentPageCount {
if let page = restoredReadingPage, page >= 0, page < readableContentPageCount {
readerView.transitionToPage(pageNum: page, animated: false)
}
isRestoringInitialReadingState = false
bookmarks = Set(persistence?.loadBookmarks(for: book.identifier).map(\.pageIndex) ?? [])
NotificationCenter.default.addObserver(
self,
selector: #selector(handleAppDidEnterBackground),
name: UIApplication.didEnterBackgroundNotification,
object: nil
)
}
public override func viewWillAppear(_ animated: Bool) {
super.viewWillAppear(animated)
if navigationBarHiddenBeforeReader == nil {
navigationBarHiddenBeforeReader = navigationController?.isNavigationBarHidden
}
if interactivePopWasEnabledBeforeReader == nil {
interactivePopWasEnabledBeforeReader = navigationController?.interactivePopGestureRecognizer?.isEnabled
interactivePopDelegateBeforeReader = navigationController?.interactivePopGestureRecognizer?.delegate
}
navigationController?.setNavigationBarHidden(true, animated: animated)
navigationController?.interactivePopGestureRecognizer?.isEnabled = false
// 宿主或另一阅读器实例可能已修改同一本书的标注;重新出现时刷新快照。
reloadAnnotations()
}
public override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
if let navigationBarHiddenBeforeReader {
navigationController?.setNavigationBarHidden(navigationBarHiddenBeforeReader, animated: animated)
}
if let interactivePopWasEnabledBeforeReader {
navigationController?.interactivePopGestureRecognizer?.delegate = interactivePopDelegateBeforeReader
navigationController?.interactivePopGestureRecognizer?.isEnabled = interactivePopWasEnabledBeforeReader
}
flushReadingPagePersist()
}
@objc private func handleAppDidEnterBackground() {
flushReadingPagePersist()
}
public override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
cancelOutstandingOCRRequests()
@@ -243,6 +297,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
pageDescriptors = pageDescriptors.filter { visibleIndexes.contains($0.key) }
ocrRuns = ocrRuns.filter { visibleIndexes.contains($0.key) }
drawingDocuments = drawingDocuments.filter { visibleIndexes.contains($0.key) }
renderedImageCache = renderedImageCache.filter { visibleIndexes.contains($0.key) }
(pageProvider as? RDPDFKitPageProvider)?.removeCachedImages()
visiblePageViews().forEach { $0.releaseDrawingRenderingCache() }
visibleIndexes.sorted().forEach { startOCRIfNeeded($0) }
@@ -295,7 +350,12 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
descriptor = await withCheckedContinuation { continuation in
pageProvider.readerPage(at: pageIndex) { continuation.resume(returning: $0) }
}
pageDescriptors[pageIndex] = descriptor
// 只有带页面图的结果才能进显示缓存:无图 descriptor 会让 configure 的
// `guard descriptor == nil else { … return }` 短路成永久白页(configure
// 自己的请求路径对无图结果是按无效处理、给重试入口的)。
if descriptor.image != nil {
pageDescriptors[pageIndex] = descriptor
}
}
if let nativeRuns = descriptor.textRuns, !nativeRuns.isEmpty { return nativeRuns }
guard configuration.enablesOCR, let image = descriptor.image else { return [] }
@@ -431,7 +491,9 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
title = "PDF · \(pageNum + 1) / \(readableContentPageCount)"
topToolbar?.setTitle(title ?? book.title)
topToolbar?.setBookmarkSelected(bookmarks.contains(pageNum))
persistence?.saveReadingPage(pageNum, for: book.identifier)
if !isRestoringInitialReadingState {
scheduleReadingPagePersist(pageNum)
}
delegate?.pdfReaderViewController(self, didChangePage: pageNum)
}
@@ -440,6 +502,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
let visiblePages = Set(visiblePageViews().map(\.tag))
let isStale: (Int) -> Bool = { abs($0 - pageIndex) > safeRadius && !visiblePages.contains($0) }
pageDescriptors.keys.filter(isStale).forEach { pageDescriptors.removeValue(forKey: $0) }
renderedImageCache.keys.filter(isStale).forEach { renderedImageCache.removeValue(forKey: $0) }
// Provider 本身无法取消时,以 token 失效保证迟到回调不能把远页重新塞回缓存。
pageDescriptorRequestTokens.keys.filter(isStale).forEach { clearPageDescriptorRequest(for: $0) }
@@ -479,11 +542,15 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
private func acceptPageDescriptor(_ descriptor: RDPDFReaderPageDescriptor, at index: Int) {
removePageDescriptorRequestState(for: index)
pageDescriptors[index] = descriptor
// 新页面图到达,丢弃基于旧图(或空图占位)算出的主题变换缓存。
renderedImageCache.removeValue(forKey: index)
// 宽度适配竖滑下,占位的一屏高 cell 要按真实纸张比例重新排版。
readerView.invalidateWidthFitLayoutIfNeeded(updatedPage: index)
// 初始请求的 cell 可能已经因旋转或复用离开屏幕,也可能是仿真翻页提前构建、
// 尚未上屏的页;两者都要装配,否则翻到它时是白页。
refreshPageViews(at: index)
// 仿真翻页首屏的页面图迟到时,book frame 需在拿到真实尺寸后重新收缩一次。
readerView.refreshPageCurlLayoutIfNeeded()
}
private func handleInvalidPageDescriptor(at index: Int, token: UUID, attempt: Int) {
@@ -503,7 +570,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
private func configure(_ page: RDPDFReaderPageView, at index: Int) {
let descriptor = pageDescriptors[index]
page.image = descriptor.flatMap { renderedImage($0.image) }
page.image = descriptor.flatMap { renderedImage($0.image, at: index) }
page.applyTheme(contentBackgroundColor: currentTheme.contentBackgroundColor, surroundingBackgroundColor: pageSurroundingColor)
page.setPhoneLandscapeWidthFitting(isPhoneLandscape, safeAreaInsets: view.safeAreaInsets)
let runs = descriptor?.textRuns ?? ocrRuns[index] ?? []
@@ -601,9 +668,15 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
pageDescriptorRequestTimeouts.removeValue(forKey: index)?.cancel()
}
private func renderedImage(_ image: UIImage?) -> UIImage? {
private func renderedImage(_ image: UIImage?, at index: Int) -> UIImage? {
guard let image else { return nil }
return configuration.pageImageTransform?(image, currentTheme) ?? image
guard let transform = configuration.pageImageTransform else { return image }
if let hit = renderedImageCache[index], hit.theme == currentTheme.identifier {
return hit.image
}
let result = transform(image, currentTheme)
renderedImageCache[index] = (currentTheme.identifier, result)
return result
}
private func startOCRIfNeeded(_ index: Int) {
@@ -705,6 +778,23 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
topToolbar?.setBookmarkSelected(marked)
}
/// 翻页进度写盘防抖:1s 内的连续翻页只落最后一页;离开阅读器或进入后台时立即落盘。
private func scheduleReadingPagePersist(_ page: Int) {
pendingReadingPagePersist = page
readingPagePersistWork?.cancel()
let work = DispatchWorkItem { [weak self] in self?.flushReadingPagePersist() }
readingPagePersistWork = work
DispatchQueue.main.asyncAfter(deadline: .now() + 1.0, execute: work)
}
private func flushReadingPagePersist() {
readingPagePersistWork?.cancel()
readingPagePersistWork = nil
guard let page = pendingReadingPagePersist else { return }
pendingReadingPagePersist = nil
persistence?.saveReadingPage(page, for: book.identifier)
}
private func showNavigation() {
if let asyncOutlineProvider = pageProvider as? RDPDFReaderAsyncOutlineProviding {
guard navigationLoadingIndicator == nil else { return }
@@ -921,6 +1011,8 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
private func apply(_ theme: RDPDFReaderThemeOption) {
currentTheme = theme
// 主题变了,所有按旧主题算出的页面图变换缓存作废。
renderedImageCache.removeAll()
view.backgroundColor = theme.contentBackgroundColor
readerView.backgroundColor = pageSurroundingColor
applyChromeTheme()