阅读器修改
This commit is contained in:
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user