From 4388831abb375d797375dbaf5c81b0cae2e94026 Mon Sep 17 00:00:00 2001 From: shenlei Date: Fri, 23 Oct 2026 19:29:45 +0900 Subject: [PATCH] =?UTF-8?q?=E9=98=85=E8=AF=BB=E5=99=A8=E4=BF=AE=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md | 60 ++++++++++ .../ReadViewDemo.xcodeproj/project.pbxproj | 8 +- .../PDFDemoReaderViewController.swift | 86 +++++++------- .../ReadViewDemo/ViewController.swift | 8 +- .../Helpers/XCUIApplication+Launch.swift | 6 +- .../LocationPersistenceTests.swift | 67 +++++++++++ .../PDFPageTurnBlankPageTests.swift | 109 ++++++++++++++++- .../Sources/RDPDFInteractionHotspotView.swift | 3 + .../Sources/RDPDFKitPageProvider.swift | 21 ++-- .../Sources/RDPDFReaderContainerView.swift | 7 ++ .../RDPDFReaderPageImageTransform.swift | 48 ++++++++ .../Sources/RDPDFReaderPageView.swift | 19 ++- .../Sources/RDPDFReaderPersistenceStore.swift | 65 +++++++++-- .../Sources/RDPDFReaderViewController.swift | 110 ++++++++++++++++-- 14 files changed, 536 insertions(+), 81 deletions(-) create mode 100644 Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md create mode 100644 Sources/RDPDFReaderView/Sources/RDPDFReaderPageImageTransform.swift diff --git a/Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md b/Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md new file mode 100644 index 0000000..1384bfb --- /dev/null +++ b/Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md @@ -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 助手入口且愿意接受这个新依赖,再评估是否值得下沉。 diff --git a/ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj b/ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj index cda965e..90711d8 100644 --- a/ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj +++ b/ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj @@ -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; diff --git a/ReadViewDemo/ReadViewDemo/PDFDemoReaderViewController.swift b/ReadViewDemo/ReadViewDemo/PDFDemoReaderViewController.swift index 055cd38..21db5f4 100644 --- a/ReadViewDemo/ReadViewDemo/PDFDemoReaderViewController.swift +++ b/ReadViewDemo/ReadViewDemo/PDFDemoReaderViewController.swift @@ -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() 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 } diff --git a/ReadViewDemo/ReadViewDemo/ViewController.swift b/ReadViewDemo/ReadViewDemo/ViewController.swift index 56bcab1..5c95aad 100644 --- a/ReadViewDemo/ReadViewDemo/ViewController.swift +++ b/ReadViewDemo/ReadViewDemo/ViewController.swift @@ -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) diff --git a/ReadViewDemo/ReadViewDemoUITests/Helpers/XCUIApplication+Launch.swift b/ReadViewDemo/ReadViewDemoUITests/Helpers/XCUIApplication+Launch.swift index 1de028c..ed35b2e 100644 --- a/ReadViewDemo/ReadViewDemoUITests/Helpers/XCUIApplication+Launch.swift +++ b/ReadViewDemo/ReadViewDemoUITests/Helpers/XCUIApplication+Launch.swift @@ -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() } diff --git a/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/LocationPersistenceTests.swift b/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/LocationPersistenceTests.swift index 5b411fa..da87108 100644 --- a/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/LocationPersistenceTests.swift +++ b/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/LocationPersistenceTests.swift @@ -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 页") + } } diff --git a/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/PDFPageTurnBlankPageTests.swift b/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/PDFPageTurnBlankPageTests.swift index 71798f3..984a7cd 100644 --- a/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/PDFPageTurnBlankPageTests.swift +++ b/ReadViewDemo/ReadViewDemoUITests/ReaderUITests/PDFPageTurnBlankPageTests.swift @@ -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)) + } } diff --git a/Sources/RDPDFReaderView/Sources/RDPDFInteractionHotspotView.swift b/Sources/RDPDFReaderView/Sources/RDPDFInteractionHotspotView.swift index 5c056ba..6eafe1a 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFInteractionHotspotView.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFInteractionHotspotView.swift @@ -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 { diff --git a/Sources/RDPDFReaderView/Sources/RDPDFKitPageProvider.swift b/Sources/RDPDFReaderView/Sources/RDPDFKitPageProvider.swift index 040b53a..1c1cf2a 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFKitPageProvider.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFKitPageProvider.swift @@ -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)" diff --git a/Sources/RDPDFReaderView/Sources/RDPDFReaderContainerView.swift b/Sources/RDPDFReaderView/Sources/RDPDFReaderContainerView.swift index c11e319..35b89e9 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFReaderContainerView.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFReaderContainerView.swift @@ -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 diff --git a/Sources/RDPDFReaderView/Sources/RDPDFReaderPageImageTransform.swift b/Sources/RDPDFReaderView/Sources/RDPDFReaderPageImageTransform.swift new file mode 100644 index 0000000..d864de3 --- /dev/null +++ b/Sources/RDPDFReaderView/Sources/RDPDFReaderPageImageTransform.swift @@ -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 + } +} diff --git a/Sources/RDPDFReaderView/Sources/RDPDFReaderPageView.swift b/Sources/RDPDFReaderView/Sources/RDPDFReaderPageView.swift index 80c409b..1bc36b7 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFReaderPageView.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFReaderPageView.swift @@ -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,不是用户第一次看到这一页, diff --git a/Sources/RDPDFReaderView/Sources/RDPDFReaderPersistenceStore.swift b/Sources/RDPDFReaderView/Sources/RDPDFReaderPersistenceStore.swift index 952de57..7d65e0d 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFReaderPersistenceStore.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFReaderPersistenceStore.swift @@ -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] { diff --git a/Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift b/Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift index 480295f..74a1595 100644 --- a/Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift +++ b/Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift @@ -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()