Files
ReadViewSDK/Doc/PDF_SDK_SINK_CANDIDATES_2026-08-14.md
2026-10-23 19:29:45 +09:00

9.5 KiB
Raw Permalink Blame History

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 助手入口且愿意接受这个新依赖,再评估是否值得下沉。