福昕开发者文档中心

自定义存储驱动 (StorageDriver) ​

概述 ​

存储驱动 (StorageDriver) 是一个专门用于存储和管理数据的接口,它主要负责:

  • 数据的存储和读取
  • 数据的删除操作
  • 数据的分区管理
  • 数据变更监控

关于存储的详细接口信息，请参阅开发者手册 storage 。

核心类型定义 ​

StorageContext 基础类 ​

typescript
class StorageContext {
    public id: string;
    public feature: string;
}

StorageContext 类用于标识存储的数据和特性。

PDFViewer 相关接口 ​

typescript
interface PDFViewer {
    getInstanceId(): string;
}

interface PDFViewerConstructor {
    new(options: {
        instanceId: string,
        customs: {
            storageDriver: StorageDriver;
        }
    }): PDFViewer;
}

实例 ID 说明

getInstanceId() 方法用于获取 PDFViewer 实例的唯一标识。当存在多个实例时,请确保每个实例的 ID 都是唯一的。

StorageDriver 接口 ​

typescript
interface StorageDriver {
    getAll(context: StorageContext): Promise<Record<string, any>>;

    get<T>(context: StorageContext, key: string): Promise<T | null>;

    set<T>(context: StorageContext, key: string, value: T): Promise<void>;

    removeAll(context: StorageContext): Promise<void>;

    remove(context: StorageContext, key: string): Promise<void>;

    onChange<T>(callback: (event: StorageDriverChangeEvent<T>) => void): Function;

    onRemove(callback: (event: StorageDriverRemoveEvent) => void): Function;
}

核心方法说明:

  • getAll: 获取指定上下文中的所有数据
  • get: 获取指定键的数据
  • set: 设置指定键的数据
  • removeAll: 移除所有数据
  • remove: 移除指定键的数据
  • onChange: 注册数据变化监听
  • onRemove: 注册数据删除监听

事件相关接口 ​

typescript
interface StorageDriverChangeEvent<T> {
    context: StorageContext;
    key: string;
    oldValue: T;
    newValue: T;
}

interface StorageDriverRemoveEvent {
    context: StorageContext;
    key: string;
}

实现自定义存储驱动 ​

下面是一个基于 sessionStorage 实现的示例:

typescript
class MyStorageDriver extends StorageDriver {
    private readonly eventEmitter = new EventEmitter();

    // 生成存储空间名称
    private getSpace(context: StorageContext): string {
        return [context.id, context.feature].join('.');
    }

    // ... existing code ...

    // 核心存储方法实现
    async set<T>(context: StorageContext, key: string, value: T): Promise<void> {
        const storageKey = this.generateUniqueKey(context, key);
        const oldValueJSON = sessionStorage.getItem(storageKey);
        const oldValue = oldValueJSON ? JSON.parse(oldValueJSON) : undefined;
        const newValue = JSON.stringify(value);

        if (oldValueJSON === newValue) return;

        sessionStorage.setItem(storageKey, newValue);
        this.emitChangeEvent({
            context,
            key,
            oldValue,
            newValue: value
        });
    }

    // ... existing code ...
}

完整实现

完整的示例代码请参考上文的 MyStorageDriver 类实现。该示例演示了如何:

  • 使用 EventEmitter 处理事件
  • 实现数据的分区存储
  • 处理数据变更通知

使用自定义存储驱动 ​

创建 PDFViewer 实例时,通过 customs 选项传入自定义的 StorageDriver:

typescript
const storageDriver = new MyStorageDriver();

const pdfViewer = new PDFViewer({
    instanceId: 'pdf-viewer-1',
    customs: {
        storageDriver: storageDriver
    }
});

最佳实践

  • 为每个 PDFViewer 实例指定唯一的 instanceId
  • 根据业务需求选择合适的存储方式(localStorage、IndexedDB 等)
  • 实现数据分区管理,避免不同实例间的数据混淆