9.5 KiB
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 项。
结论与优先级
- P0(已实施):宿主导航栏 / 侧滑返回手势保存恢复(第 2 项)——和已修过的 EPUB bug 同一类风险,其他 PDF 宿主随时可能踩中。
- P1(已实施):
bookIdentifier→ 存储路径哈希派生(第 3 项)——对齐 EPUB 已有做法,减少宿主重复实现。 - P1(已实施):页面图片主题变色默认实现(第 1 项)。
- 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数值分支的写法,因此对任意宿主自定义主题集合都有合理默认,不只是对 SDKdefaultPresets生效。Configuration.pageImageTransform默认值改为该函数(原来是nil),宿主不设置也有效果,仍可整体覆盖或显式设为nil关闭。经验证该规则在 SDKdefaultPresets(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 助手入口且愿意接受这个新依赖,再评估是否值得下沉。