Angular-Async-Local-Storage核心API详解：从基础操作到高级Map接口

Angular-Async-Local-Storage核心API详解：从基础操作到高级Map接口

【免费下载链接】angular-async-local-storageEfficient client-side storage for Angular: simple API + performance + Observables + validation项目地址: https://gitcode.com/gh_mirrors/an/angular-async-local-storage

Angular-Async-Local-Storage是一个专为Angular应用设计的高效客户端存储解决方案，它提供了简单的API、出色的性能、基于Observables的异步操作以及强大的数据验证功能。本文将详细介绍其核心API，从基础的存储操作到高级的Map接口应用，帮助开发者充分利用这个强大的工具。

一、快速入门：核心存储类StorageMap

1.1 注入与初始化

StorageMap是Angular-Async-Local-Storage的核心服务类，提供了所有主要的存储操作方法。在组件中使用时，只需通过依赖注入即可：

import { StorageMap } from "@ngx-pwa/local-storage"; @Component({ ... }) export class MyComponent { private readonly storageMap = inject(StorageMap); }

1.2 存储引擎自动适配

StorageMap会根据浏览器环境自动选择最佳的存储引擎，并在需要时进行降级处理：

// 查看当前使用的存储引擎 console.log(this.storageMap.backingEngine); // 'indexedDB' | 'localStorage' | 'memory' | 'unknown'

• IndexedDB：默认优先使用，支持大容量数据存储
• localStorage：当IndexedDB不可用时自动降级
• 内存存储：当所有客户端存储都被禁用时的最后选择

二、基础存储操作：增删改查

2.1 存储数据（set）

使用set方法存储数据，支持自动序列化和可选的 schema 验证：

// 基本用法 this.storageMap.set('user', { name: 'John', age: 30 }).subscribe(() => { console.log('数据存储成功'); }); // 带验证的存储 const userSchema = { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' } }, required: ['name'] } satisfies JSONSchema; this.storageMap.set('user', { name: 'John', age: 30 }, userSchema).subscribe({ next: () => console.log('数据存储成功'), error: (err) => console.error('数据验证失败', err) });

注意：存储undefined或null会自动删除对应键，以保持跨存储引擎的一致性。

2.2 获取数据（get）

使用get方法获取数据，支持类型安全和 schema 验证：

// 基本用法 this.storageMap.get('user').subscribe((user) => { console.log('获取到用户数据', user); }); // 带类型和验证的获取 interface User { name: string; age?: number; } this.storageMap.get<User>('user', userSchema).subscribe((user) => { if (user) { console.log('用户名:', user.name); } });

2.3 删除数据（delete）

使用delete方法删除指定键的数据：

this.storageMap.delete('user').subscribe(() => { console.log('用户数据已删除'); });

2.4 清空存储（clear）

使用clear方法删除所有存储的数据：

this.storageMap.clear().subscribe(() => { console.log('所有数据已清空'); });

三、高级操作：键管理与监听

3.1 键操作方法

StorageMap提供了完整的键管理功能：

// 检查键是否存在 this.storageMap.has('user').subscribe((exists) => { console.log('用户数据是否存在:', exists); }); // 获取所有键 this.storageMap.keys().subscribe({ next: (key) => console.log('存储的键:', key), complete: () => console.log('所有键枚举完成') }); // 获取存储的项目数量 this.storageMap.size.subscribe((count) => { console.log('存储项目数量:', count); });

3.2 数据变化监听（watch）

使用watch方法可以监听特定键的数据变化，这对于实时更新UI非常有用：

@Component({ ... }) export class MyComponent implements OnInit, OnDestroy { private storageSubscription?: Subscription; ngOnInit(): void { this.storageSubscription = this.storageMap.watch('user', userSchema).subscribe((user) => { console.log('用户数据变化:', user); // 更新UI }); } ngOnDestroy(): void { this.storageSubscription?.unsubscribe(); } }

注意：watch返回的是一个无限 Observable，需要在组件销毁时手动取消订阅。

四、数据验证：确保数据安全

4.1 JSON Schema验证

Angular-Async-Local-Storage内置了基于JSON Schema的强大数据验证功能，定义在lib/src/lib/validation/json-schema.ts中。通过在get和set方法中提供schema，可以确保存储的数据符合预期格式：

const productSchema = { type: 'object', properties: { id: { type: 'string', format: 'uuid' }, name: { type: 'string', minLength: 1 }, price: { type: 'number', minimum: 0 }, tags: { type: 'array', items: { type: 'string' } } }, required: ['id', 'name', 'price'] } satisfies JSONSchema; // 存储时验证 this.storageMap.set('product', productData, productSchema).subscribe({ error: (err) => console.error('产品数据验证失败', err) }); // 获取时验证 this.storageMap.get('product', productSchema).subscribe((product) => { // 这里的product已经过验证，类型安全 });

4.2 支持的验证类型

库支持多种JSON Schema验证类型，包括：

• 基本类型：字符串、数字、整数、布尔值
• 复杂类型：数组、元组、对象
• 高级验证：枚举、常量、格式验证等

详细的验证规则可以参考官方文档docs/VALIDATION.md。

五、存储引擎详情与互操作性

5.1 存储引擎信息

对于需要了解底层存储细节的场景，StorageMap提供了详细的存储引擎信息：

// IndexedDB存储详情 if (this.storageMap.backingEngine === 'indexedDB') { const { database, store, version } = this.storageMap.backingStore; console.log(`IndexedDB: 数据库=${database}, 存储区=${store}, 版本=${version}`); } // localStorage存储详情 if (this.storageMap.backingEngine === 'localStorage') { const { prefix } = this.storageMap.fallbackBackingStore; console.log(`localStorage: 前缀=${prefix}`); }

5.2 互操作性指南

当需要与其他库或原生API交互时，可以参考官方的互操作性文档docs/INTEROPERABILITY.md，了解如何安全地在不同存储引擎之间切换和共享数据。

六、最佳实践与常见问题

6.1 错误处理

始终处理存储操作中可能出现的错误，特别是验证错误和存储配额限制：

this.storageMap.set('large-data', veryBigData).subscribe({ next: () => console.log('存储成功'), error: (err) => { if (err instanceof ValidationError) { console.error('数据验证失败', err); } else { console.error('存储操作失败', err); } } });

6.2 性能优化

• 对于频繁访问的数据，考虑使用watch方法减少重复获取
• 对于大量数据，利用IndexedDB的高效性能，避免存储过大的单条记录
• 合理使用验证功能，确保数据质量的同时避免过度验证影响性能

6.3 浏览器兼容性

Angular-Async-Local-Storage在各种现代浏览器中都能良好工作，但仍需注意：

• 某些浏览器在私有模式下可能限制存储功能
• 跨域iframe中可能存在存储访问限制
• 旧版浏览器可能自动降级到localStorage或内存存储

详细的浏览器支持情况可以参考docs/BROWSERS_SUPPORT.md。

七、总结

Angular-Async-Local-Storage的StorageMap提供了一套完整、高效且类型安全的客户端存储解决方案。通过本文介绍的API，开发者可以轻松实现从简单的键值存储到复杂的数据管理。无论是构建小型应用还是大型企业级项目，这个库都能满足各种客户端存储需求，同时确保代码的可维护性和性能。

要开始使用Angular-Async-Local-Storage，只需克隆仓库并按照文档集成到你的Angular项目中：

git clone https://gitcode.com/gh_mirrors/an/angular-async-local-storage

更多详细信息和高级用法，请参考项目的官方文档和示例代码。

【免费下载链接】angular-async-local-storageEfficient client-side storage for Angular: simple API + performance + Observables + validation项目地址: https://gitcode.com/gh_mirrors/an/angular-async-local-storage