接入 PDF 预览功能，代码照文档抄的，loadDocument 返回成功，页面上干干净净一片白。你以为是渲染没触发，反复调 loadDocument、反复刷新，甚至怀疑 PDF 文件坏了。实际上 loadDocument 的成功只代表“文件被读取了”，如果传入的路径不是应用沙箱里的本地文件，或者文件根本没有被完整拷贝进沙箱，渲染阶段拿到的就是空页面。HarmonyOS 的 PDF Kit 对文件来源有明确的边界，在线 URL、外部存储的原始路径、rawfile 里的资源，都需要先落到应用沙箱再加载。

loadDocument 只认沙箱本地路径，rawfile 和网络流都要先落地

官方 FAQ 写得很清楚：使用 PdfView 预览时，建议通过沙箱目录加载和保存 PDF 文档，以避免文件目录的权限问题。rawfile 里的 PDF 资源没有直接的沙箱路径，必须先 fileIo.copyFile 到 context.filesDir 下，再用拷贝后的完整路径调 loadDocument。网络下载的 PDF 同理，下载完成、写入沙箱、关闭文件流之后，才能把路径交给 PdfView。

typescript

import { pdfService } from '@kit.PDFKit';
import { fileIo } from '@kit.CoreFileKit';

async function loadPdfFromRawfile(
  context: common.UIAbilityContext,
  rawName: string,
  controller: pdfService.PdfController
): Promise<void> {
  const destPath = `${context.filesDir}/${rawName}`;
  const rawData = await context.resourceManager.getRawFileContent(rawName);
  const file = fileIo.openSync(destPath, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
  fileIo.writeSync(file.fd, rawData.buffer);
  fileIo.closeSync(file);

  // 必须用沙箱路径，rawfile 路径直接传会白屏
  await controller.loadDocument(destPath);
}

fileIo.closeSync 不能省。写了一半就去加载，PdfView 读到的是截断的文件，渲染可能直接失败。路径拼接用 context.filesDir，不要自己拼 /data/storage/el2/base/... 这种硬编码前缀。

手写笔滑不动不是手势冲突，是 PdfView 还没适配

平板用户反馈“手指能翻页，手写笔滑不动”。官方论坛的回复很直接：PdfView 组件暂时没有做手写笔的滑动适配，签字笔的事件被识别为书写行为，不是滚动操作。如果你的场景必须支持手写笔翻页，短期内可行的替代方案是用 Web 组件加载 PDF，并在外层用 PanGesture 统一处理滑动；或者等 PdfView 后续版本补齐手写笔支持。排查时先用手指和手写笔分别测试，如果只有手写笔失效，不要往手势冲突的方向查，那是组件能力边界的问题。

大文档的崩溃发生在缩放，不是首次加载

几百页的工程图纸第一次打开可能正常，但用户连续放大到十几倍再松手，应用直接闪退。PDF Kit 底层用的是分页内存置换和分块渲染策略，放大到极高倍数时如果在一个手势结束回调里同步请求全量重光栅化，内存峰值会瞬间冲顶。控制缩放倍数上限、在缩放过程中用低精度占位、松手后再分块渲染高质量切片，比一次性把整页按 10 倍分辨率光栅化要安全得多。白屏先查路径，手写笔先查组件能力，闪退先查缩放时的内存峰值——三条线分开排查，比混在一起猜要快。