API 参考
⚠️ 重要版本说明
v0.0.5(当前版本)
补丁版本,修复子入口缺失 useStorage、getSnapshot 渲染期写存储等问题,并新增管理器回收 API。详见更新日志。
v0.0.4 破坏性变更
- Vue
immediate 默认值改为 false:创建时直接使用存储中的值,不再额外写一次存储。需要把默认值立即持久化时显式传入 immediate: true。
ParseStrType.EVAL 标记为废弃:内部使用 new Function,在严格 CSP(如 Tauri、Electron 加固)环境会直接抛错,请改用 JSON 或 AUTO。
- UMD 产物扩展名改为
.cjs:通过包名或子路径导入不受影响。
迁移指南
旧版本(v0.0.1-beta.8 及之前):
1import { useStorage, useReactStorage } from 'ew-responsive-store';
v0.0.3+:按框架从子路径导入。
1import { useStorage } from 'ew-responsive-store'; // 原生 JavaScript
2import { useStorage } from 'ew-responsive-store/vue'; // Vue
3import { useStorage } from 'ew-responsive-store/react'; // React
4import { useStorage } from 'ew-responsive-store/preact'; // Preact
5import { useStorage } from 'ew-responsive-store/solid'; // Solid
6import { useStorage } from 'ew-responsive-store/svelte'; // Svelte
7import { useStorage } from 'ew-responsive-store/angular'; // Angular
8import { useStorage } from 'ew-responsive-store/vanilla'; // 原生 JavaScript(显式子路径)
useReactStorage 等旧名字仍作为别名导出,但不再推荐使用。
通用配置项
所有框架共享 BaseStoreOptions<T>:
| 属性 |
类型 |
默认值 |
描述 |
storage |
StoreType |
StoreType.LOCAL |
存储区域:LOCAL 或 SESSION |
parse |
'json' | 'auto' |
'json' |
反序列化模式 |
serializer |
(value: T) => string | null | undefined |
- |
自定义序列化;返回 null / undefined 时拒绝写入 |
deserializer |
(raw: string) => T |
- |
自定义反序列化 |
version |
number |
- |
数据版本号,配合 migrate 使用 |
migrate |
(oldValue: unknown, oldVersion: number) => T |
- |
读取旧版本数据时迁移并回写 |
equals |
(a: T, b: T) => boolean |
引用 / JSON 字符串比较 |
相等时跳过写入与通知 |
memoryFallback |
boolean |
true |
存储不可用或写入失败时降级到内存 |
onError |
(ctx: StorageErrorContext) => void |
- |
错误回调,ctx 含 key、storage、operation、error |
同一个 key + 存储区域共享一个管理器,options 与 initialValue 只在首次创建时生效。
解析模式
json(默认):严格 JSON。解析失败回落到初始值。
auto:兼容历史裸字符串。读取时只有以 {、[、" 开头的字符串才尝试 JSON 解析,其余原样返回;写入时字符串原样存储,其他类型仍走 JSON.stringify。
auto 下数字与布尔会以 JSON 写入,读取时可能回落为字符串;需要严格类型请使用 json。
状态操作(StorageActions)
React、Preact、Solid 的第三个返回值,以及 Svelte、Vanilla 的返回对象,都提供:
| 成员 |
描述 |
key |
当前存储键 |
remove() |
删除当前 key,值回落初始值 |
clear() |
只清理本库管理的 key,不会调用原生 storage.clear() |
manager |
底层管理器实例 |
底层管理器 API
1import {
2 getStorageManager,
3 retainStorageManager,
4 releaseStorageManager,
5 getRegisteredManagers,
6 clearManagedStorage,
7 clearStorageManagerRegistry,
8} from 'ew-responsive-store';
| API |
描述 |
getStorageManager(key, initialValue, options?) |
获取或创建同 key 的共享管理器 |
retainStorageManager(key, storage?) |
持有引用,与 releaseStorageManager 成对使用 |
releaseStorageManager(key, storage?) |
释放引用;计数归零且无订阅者时在微任务中回收 |
getRegisteredManagers(storage?) |
获取已注册的管理器 |
clearManagedStorage(storage?) |
删除本库管理的所有 key |
clearStorageManagerRegistry() |
销毁并移除全部管理器(测试 / 热更新用) |
框架适配器会在组件卸载时自动 retain / release;手动创建或非组件场景需自行调用。Vue 在 setup 外使用时,请放入 effectScope() 并通过 scope.stop() 释放。
框架适配器
useStorage (Vue)
类型定义
1function useStorage<T>(
2 key: string,
3 initialValue: T | (() => T),
4 options?: VueStoreOptions<T>,
5): Ref<T>;
选项
在通用配置项之外,Vue 额外支持:
| 属性 |
类型 |
默认值 |
描述 |
immediate |
boolean |
false |
是否在创建时立即把当前值写回存储 |
deep |
boolean |
true |
是否深度监听值变化 |
其余 Vue watch 选项同样支持。
返回值
Ref<T>,与指定存储区域同步。
示例
1import { useStorage } from 'ew-responsive-store/vue';
2import { StoreType } from 'ew-responsive-store';
3
4const count = useStorage('count', 0);
5count.value += 1;
6
7const user = useStorage('user', { name: '张三' }, {
8 storage: StoreType.SESSION,
9});
10
11// 默认不会在创建时写回;需要持久化初始值时显式开启
12const settings = useStorage('settings', { theme: 'dark' }, {
13 immediate: true,
14});
useStorage (React)
类型定义
1function useStorage<T>(
2 key: string,
3 initialValue: T | (() => T),
4 options?: ReactStoreOptions<T>,
5): readonly [T, (value: StorageUpdater<T>) => void, StorageActions<T>];
基于 useSyncExternalStore,支持 React 18+ 的并发渲染与 SSR(服务端使用 getInitialSnapshot() 返回初始值)。
返回值
[0]:当前值 T
[1]:更新函数,支持 setValue(next) 与 setValue(prev => next)
[2]:{ key, remove, clear, manager }
示例
1import { useStorage } from 'ew-responsive-store/react';
2
3function Todos() {
4 const [todos, setTodos, actions] = useStorage<string[]>('todos', []);
5
6 const add = (title: string) =>
7 setTodos((prev) => [...prev, title]);
8
9 return (
10 <div>
11 <button onClick={() => add('新待办')}>添加</button>
12 <button onClick={actions.remove}>清空当前 key</button>
13 </div>
14 );
15}
useStorage (Preact)
与 React 相同的三元组返回值:
1import { useStorage } from 'ew-responsive-store/preact';
2
3const [count, setCount, actions] = useStorage('count', 0);
useStorage (Solid)
返回 [Accessor<T>, setter, StorageActions<T>]:
1import { useStorage } from 'ew-responsive-store/solid';
2
3function Counter() {
4 const [count, setCount] = useStorage('count', 0);
5 return <button onClick={() => setCount(count() + 1)}>{count()}</button>;
6}
useStorage (Svelte)
返回 Svelte store,并附加 set / update / remove / clear / destroy:
1<script>
2 import { useStorage } from 'ew-responsive-store/svelte';
3
4 const store = useStorage('count', 0);
5 $: count = $store;
6
7 function reset() {
8 store.remove();
9 }
10</script>
11
12<button on:click={reset}>Count: {count}</button>
useStorage (Angular)
需在组件 / 服务的注入上下文中调用。返回值:
1interface AngularStorageReturn<T> {
2 value: () => T; // computed signal
3 setValue: (value: StorageUpdater<T>) => void;
4 updateValue: (updater: (current: T) => T) => void;
5 reset: () => void;
6 remove: () => void;
7 clear: () => void;
8}
1import { Component } from '@angular/core';
2import { useStorage } from 'ew-responsive-store/angular';
3
4@Component({
5 template: `
6 <div>Count: {{ storage.value() }}</div>
7 <button (click)="storage.setValue(storage.value() + 1)">+1</button>
8 `,
9})
10export class CounterComponent {
11 storage = useStorage('count', 0);
12}
组件的 DestroyRef 触发时会自动释放管理器。
useStorage (Vanilla JS)
根入口与 /vanilla 都指向原生适配器:
1import { useStorage } from 'ew-responsive-store';
2
3const storage = useStorage('count', 0);
4
5storage.value; // 当前值
6storage.setValue(1); // 直接赋值
7storage.updateValue((n) => n + 1);
8storage.remove(); // 删除 key,回落初始值
9storage.clear(); // 清理本库管理的 key
10const unsubscribe = storage.subscribe((value) => console.log(value));
11storage.destroy(); // 退订并释放管理器
实用函数
parseStr
1function parseStr<T>(str: string, type?: ParseStrType): T | null;
| 参数 |
类型 |
默认值 |
描述 |
str |
string |
- |
要解析的字符串 |
type |
ParseStrType |
ParseStrType.JSON |
解析模式:JSON、AUTO 或已废弃的 EVAL |
1import { parseStr, ParseStrType } from 'ew-responsive-store';
2
3parseStr<{ name: string }>('{"name":"张三"}');
4parseStr('dark', ParseStrType.AUTO); // 'dark'
ParseStrType.EVAL 已废弃,严格 CSP 环境下会抛错,不要在新代码中使用。
isValidJSON
1function isValidJSON(value: string): boolean;
isStorageEnabled
1function isStorageEnabled(storage?: Storage): boolean;
检测存储是否可用(Safari 隐私模式、配额受限等场景),结果会被缓存。
枚举
StoreType
1enum StoreType {
2 LOCAL = 'localStorage',
3 SESSION = 'sessionStorage',
4}
ParseStrType
1enum ParseStrType {
2 JSON = 'json',
3 AUTO = 'auto',
4 /** @deprecated 使用 new Function,严格 CSP 下会抛错 */
5 EVAL = 'eval',
6}
历史版本 API
v0.0.1-beta.8 及之前的 useStorage 默认 immediate: true,React 使用独立的 useReactStorage。这些接口仅出于兼容保留,行为与当前版本不同:
- 旧 Vue
useStorage 的 immediate 默认值已改为 false。
useReactStorage 现在是 useStorage 的别名,返回值已扩展为三元组。
- 旧文档中的
parseStr 仅支持 JSON / EVAL,当前新增 AUTO 并废弃 EVAL。
新项目请直接使用上文的统一 API。