PDF Web SDK 缓存数据持久化存储

一、功能说明

在使用 PDF Web SDK（PDFViewCtrl）开发时，若需记录业务数据（如用户配置、处理进度、自定义样式等），并希望下次打开浏览器时仍能获取这些数据，可通过 SDK 内置的 IndexedDBStorageDriver 实现持久化存储。该存储基于浏览器 IndexedDB 技术，数据存储容量大、支持异步操作，且在浏览器重启后不丢失（区别于临时存储 sessionStorage）。

二、核心 API 说明

API 方法	作用	参数说明
storageDriver.get(context, key)	根据上下文和键名读取缓存数据	`context`：存储上下文（用于分类数据）；`key`：数据唯一标识
storageDriver.set(context, key, value)	根据上下文和键名存储数据	`context`：存储上下文；`key`：数据唯一标识；`value`：待存储的内容（支持字符串、数字、对象等可序列化类型）

三、基础用法（存储 / 读取简单数据）

// 需在 async 函数中执行（如 SDK 初始化完成后的回调函数）
async function handlePersistentStorage() {
  try {
    // 1. 获取 IndexedDB 存储驱动实例
    const { IndexedDBStorageDriver } = PDFViewCtrl.storage;
    const storageDriver = pdfui.pdfViewer.getIoC().getInstanceByClass(IndexedDBStorageDriver);

    // 2. 定义存储上下文（context）和键名（key）
    // context：用于分类数据，建议包含业务标识（如功能模块、用户ID），避免不同业务数据冲突
    const context = { 
      id: 'PDF_User_Config', // 上下文唯一标识（可自定义，如用户ID、功能ID）
      feature: 'Annotation_Style' // 功能模块（如“批注样式”“表单数据”）
    };
    // key：数据唯一键名（同一 context 下 key 不可重复）
    const storageKey = 'Default_Annotation_Color';

    // 3. 读取已存储的数据（若存在）
    const storedValue = await storageDriver.get(context, storageKey);
    if (storedValue) {
      console.log('读取缓存成功：', storedValue);
      // 业务逻辑：使用缓存数据（如设置默认批注颜色）
      // setAnnotationDefaultColor(storedValue);
    } else {
      console.log('无对应缓存数据，将存储新数据');
    }

    // 4. 存储新数据（支持字符串、数字、对象等可序列化类型）
    const newData = '#FF5733'; // 待存储的内容（示例：批注默认颜色）
    await storageDriver.set(context, storageKey, newData);
    console.log('数据存储成功：', newData);

  } catch (error) {
    console.error('缓存操作失败：', error);
    // 异常处理：如提示用户存储失败、使用默认值替代
    // showErrorToast('数据缓存失败，请刷新页面重试');
  }
}

// 调用函数（需确保 pdfui 已初始化）
// 示例：在 SDK 加载完成后的回调中执行
pdfui.on('ready', handlePersistentStorage);

四、关键注意事项

上下文（context）设计规范：
- context 用于数据分类，建议包含 id（全局唯一标识）和 feature（功能模块），避免不同业务模块的 key 冲突；
- 示例：用户 A 的批注样式上下文 {id: 'User_1001', feature: 'Annotation'}，用户 B 的上下文 {id: 'User_1002', feature: 'Annotation'}，即使 key 相同也不会冲突。
键名（key）命名规范：
- key 需在同一 context 下唯一，建议使用 “业务含义 + 时间戳 / 唯一标识” 命名（如 Default_Style_20251114）；
- 避免使用特殊字符（如 @、#、$），建议用字母、数字、下划线组合。
数据类型限制：
- 支持存储字符串、数字、布尔值、对象、数组等可 JSON 序列化的数据；
- 不支持存储函数、DOM 元素、Blob 等不可序列化类型（若需存储 Blob，需先转换为 Base64 字符串）。
异步操作必须处理：
- get 和 set 方法均返回 Promise，必须使用 await 或 .then() 处理，否则会导致数据操作失败；
- 建议添加 try/catch 捕获异常（如浏览器禁用 IndexedDB、存储容量不足等情况）。

五、数据清理说明

若需删除缓存数据，可调用 storageDriver.remove(context, key) 方法（示例如下）；浏览器 IndexedDB 数据不会自动过期，需手动清理无用数据，避免占用过多存储空间。

async function deleteStorageData() {
  const { IndexedDBStorageDriver } = PDFViewCtrl.storage;
  const storageDriver = pdfui.pdfViewer.getIoC().getInstanceByClass(IndexedDBStorageDriver);

  const context = { id: 'PDF_User_Config', feature: 'Annotation_Style' };
  const storageKey = 'Default_Annotation_Color';

  // 删除指定 context 和 key 对应的缓存
  await storageDriver.remove(context, storageKey);
  console.log('数据删除成功');
}

六、调试与查看缓存数据

打开浏览器开发者工具（F12），切换到「Application」（应用）面板；
在左侧导航栏找到「IndexedDB」，展开后可看到 SDK 存储的数据库（名称通常包含 PDFViewCtrl）；
依次展开数据库 → 存储上下文对应的存储区 → 可查看 / 编辑 / 删除存储的 key 和 value，方便调试。

七、参考文档

官方开发者手册：PDF Web SDK 自定义存储驱动
IndexedDB 浏览器兼容性：MDN IndexedDB 兼容性

如何设置用户仅可删除自身注释的权限？

如何在PDF页面上添加文本内容时实现自动换行功能？

Conversion SDK Linux C++版本如何执行样例代码？

GSDK的OCR能力如何支持多进程?

如何导入导出表单数据

如何截取PDF中的表格导出为Excel？

如何将注释中的富文本格式设置为默认格式

PDF文档如何设置数字签名？

WebSDK 实现注释组合与取消组合

如何获取签名的日期、签名人等信息？

如何设置用户仅可删除自身注释的权限？

PDF Web SDK 缓存数据持久化存储

如何在PDF页面上添加文本内容时实现自动换行功能？

Conversion SDK Linux C++版本如何执行样例代码？

GSDK的OCR能力如何支持多进程?

如何导入导出表单数据

如何截取PDF中的表格导出为Excel？

如何将注释中的富文本格式设置为默认格式

PDF文档如何设置数字签名？

WebSDK 实现注释组合与取消组合