LocalStorage 文档

LocalStorage 是一个增强版的本地存储类，提供了数据存储、加密、过期处理、备份与恢复以及事件监听等功能。以下是详细的实现和使用说明。

1. 功能概述

1.1 数据存储

• 支持基本的数据存储和检索。
• 支持命名空间，避免数据冲突。
• 支持数据类型恢复（如字符串、数字、布尔值、日期、对象等）。

1.2 加密功能

• 支持数据加密和解密，确保数据安全。
• 使用 CryptoService 进行加密和解密操作。

1.3 过期机制

• 支持设置数据的过期时间。
• 自动清理过期数据。
• 使用 ExpirationService 管理过期数据。

1.4 备份与恢复

• 支持将存储的数据导出为 JSON 字符串。
• 支持从 JSON 字符串导入数据。
• 使用 BackupService 管理备份和恢复。

1.5 事件监听

• 支持事件监听和触发。
• 提供 CHANGE、REMOVE 和 CLEAR 事件。

2. 使用方法

2.1 初始化

import LocalStorage from './LocalStorage';

const config = {
  namespace: 'app1', // 命名空间
  key: 'my-encryption-key' // 加密密钥
};
const storage = new LocalStorage(config);

2.2 存储数据

storage.set('name', 'Kimi', { encrypt: true }); // 加密存储
storage.set('age', 25); // 普通存储
storage.set('date', new Date(), { expires: 30000 }); // 设置过期时间

2.3 获取数据

const name = storage.get('name'); // 获取加密数据
const age = storage.get('age'); // 获取普通数据
const date = storage.get('date'); // 获取过期数据

2.4 删除数据

storage.remove('name'); // 删除单个键
storage.clear(); // 清空所有数据

2.5 备份与恢复

const backupData = storage.exportData(); // 导出数据
storage.importData(backupData); // 导入数据

2.6 事件监听

storage.on(EventTypes.CHANGE, (key, value) => {
  console.log(`Data changed: ${key} = ${value}`);
});

storage.on(EventTypes.REMOVE, (key) => {
  console.log(`Data removed: ${key}`);
});

storage.on(EventTypes.CLEAR, () => {
  console.log('All data cleared');
});

3. 类定义

3.1 LocalStorageConfig

export interface LocalStorageConfig {
  namespace?: string; // 命名空间
  key?: string; // 加密密钥
}

3.2 StorageSetOptions

export interface StorageSetOptions {
  expires?: number; // 过期时间（毫秒）
  encrypt?: boolean; // 是否加密
}

3.3 StorageData

export interface StorageData {
  value: string; // 序列化后的值
  type: string; // 数据类型
  expires?: number; // 过期时间戳
  encrypt?: boolean; // 是否加密
}

3.4 EventTypes

export enum EventTypes {
  CHANGE = 'change',
  REMOVE = 'remove',
  CLEAR = 'clear'
}

4. 方法说明

4.1 set 方法

set(key: string, value: any, options?: StorageSetOptions): void;

• 参数：
  • key：存储的键名。
  • value：存储的值。
  • options：可选参数，包含 expires 和 encrypt。
• 功能：
  • 序列化数据并存储到 localStorage。
  • 如果设置了 encrypt，则对数据进行加密。
  • 如果设置了 expires，则设置过期时间。
  • 触发 CHANGE 事件。

4.2 get 方法

get(key: string): any;

• 参数：
  • key：存储的键名。
• 功能：
  • 从 localStorage 中获取数据。
  • 如果数据加密，则解密。
  • 根据存储的类型恢复数据。
  • 如果数据已过期，则清理并返回 null。

4.3 remove 方法

remove(key: string): void;

• 参数：
  • key：存储的键名。
• 功能：
  • 从 localStorage 中删除指定的键。
  • 触发 REMOVE 事件。

4.4 clear 方法

clear(): void;

• 功能：
  • 清空 localStorage 中的所有数据。
  • 触发 CLEAR 事件。

4.5 exportData 方法

exportData(): string;

• 功能：
  • 导出所有存储的数据为 JSON 字符串。

4.6 importData 方法

importData(data: string): void;

• 参数：
  • data：JSON 字符串。
• 功能：
  • 从 JSON 字符串导入数据到 localStorage。

4.7 on 方法

on(event: string, listener: Listener): void;

• 参数：
  • event：事件类型。
  • listener：事件监听器。
• 功能：
  • 添加事件监听器。

4.8 off 方法

off(event: string, listener: Listener): void;

• 参数：
  • event：事件类型。
  • listener：事件监听器。
• 功能：
  • 移除事件监听器。

5. 示例代码

5.1 存储和获取数据

const storage = new LocalStorage({ namespace: 'app1', key: 'my-key' });

// 存储数据
storage.set('name', 'Kimi', { encrypt: true });
storage.set('age', 25);

// 获取数据
console.log(storage.get('name')); // 输出：Kimi
console.log(storage.get('age')); // 输出：25

5.2 备份与恢复

// 导出数据
const backupData = storage.exportData();

// 清空存储
storage.clear();

// 导入数据
storage.importData(backupData);

5.3 事件监听

storage.on(EventTypes.CHANGE, (key, value) => {
  console.log(`Data changed: ${key} = ${value}`);
});

storage.set('name', 'Kimi'); // 触发 CHANGE 事件

6. 注意事项

1. 加密密钥：确保加密密钥的安全性，避免泄露。
2. 过期时间：过期时间以毫秒为单位，例如 30000 表示 30 秒后过期。
3. 命名空间：使用命名空间可以避免数据冲突，但需要确保命名空间的唯一性。

7. 依赖模块

• CryptoService：用于加密和解密。
• ExpirationService：用于管理过期数据。
• BackupService：用于备份和恢复数据。
• EventEmitter：用于事件监听和触发。

8. 兼容性

• 本库兼容现代浏览器，包括 Chrome、Firefox、Safari、Edge 等。
• 不支持 IE 浏览器。

9. 贡献

欢迎提交 issue 和 pull request，共同改进 LocalStorage 库。

10. 许可证

本项目采用 MIT 许可证。