指南
API
指南
API
简体中文

API 参考

⚠️ 重要版本说明

v0.0.3 破坏性变更

v0.0.3 版本引入了重大变更，包括：

  1. 框架专用入口点：现在需要从特定的框架入口点导入
  2. 统一的API：所有框架都使用 useStorage 函数名
  3. 零外部依赖：框架依赖作为外部依赖处理

迁移指南

旧版本 (v0.0.1-beta.8 及之前)：

1import { useStorage } from 'ew-responsive-store';
2import { useReactStorage } from 'ew-responsive-store';

新版本 (v0.0.3+)：

1// Vue
2import { useStorage } from 'ew-responsive-store/vue';
3
4// React
5import { useStorage } from 'ew-responsive-store/react';
6
7// 其他框架...

v0.0.3+ 多框架支持

useStorage (Vue) - v0.0.3+

useStorage 函数是 ew-responsive-store 库的核心 API。它允许你创建与浏览器存储（localStorage 或 sessionStorage）同步的响应式状态。

类型定义

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: StoreOptions = {
5    storage: StoreType.LOCAL,
6    immediate: true,
7    deep: true,
8  }
9): Ref<T>;

参数

参数 类型 描述
key string 用于在存储中存储值的键
initialValue T 如果在存储中找不到值，则使用的初始值
options StoreOptions 配置选项（可选）

选项

options 参数接受以下属性：

属性 类型 默认值 描述
storage StoreType StoreType.LOCAL 要使用的存储类型（localStorage 或 sessionStorage）
deep boolean true 是否深度监视状态变化

此外，所有 Vue 的 watch 选项都受支持，因为 StoreOptions 扩展了 Vue 的 WatchOptions。

返回值

一个与指定存储同步的响应式 Ref<T>。

示例

1import { useStorage } from "ew-responsive-store/vue";
2import { StoreType } from "ew-responsive-store";
3
4// 基本用法，使用 localStorage
5const count = useStorage("count", 0);
6
7// 使用 sessionStorage
8const user = useStorage(
9  "user",
10  { name: "张三" },
11  { storage: StoreType.SESSION }
12);
13
14// 禁用深度监视
15const list = useStorage("list", [1, 2, 3], { deep: false });
16
17// 禁用立即效果
18const settings = useStorage(
19  "settings",
20  { theme: "dark" },
21  { immediate: false }
22);

useStorage (React) - v0.0.3+

React 版本的 useStorage 函数，提供 React 原生的使用体验。

类型定义

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: ReactStoreOptions = {
5    storage: StoreType.LOCAL,
6  }
7): readonly [T, (newValue: T) => void];

参数

参数 类型 描述
key string 用于在存储中存储值的键
initialValue T 如果在存储中找不到值，则使用的初始值
options ReactStoreOptions 配置选项（可选）

选项

options 参数接受以下属性：

属性 类型 默认值 描述
storage StoreType StoreType.LOCAL 要使用的存储类型（localStorage 或 sessionStorage）

返回值

一个包含以下内容的元组：

  • [0]: 当前值，类型为 T
  • [1]: 用于更新值的设置函数

示例

1import React from 'react';
2import { useStorage, StoreType } from "ew-responsive-store/react";
3
4function Counter() {
5  // 基本用法，使用 localStorage
6  const [count, setCount] = useStorage("count", 0);
7  
8  // 使用 sessionStorage
9  const [user, setUser] = useStorage(
10    "user",
11    { name: "张三", age: 25 },
12    { storage: StoreType.SESSION }
13  );
14
15  const increment = () => setCount(count + 1);
16
17  return (
18    <div>
19      <p>计数: {count}</p>
20      <button onClick={increment}>增加</button>
21      
22      <p>用户: {user.name} ({user.age}岁)</p>
23      <button onClick={() => setUser({ ...user, age: user.age + 1 })}>
24        增加年龄
25      </button>
26    </div>
27  );
28}

useStorage (Preact) - v0.0.3+

Preact 版本的 useStorage 函数，与 React API 相同但针对 Preact 优化。

1import { useStorage } from "ew-responsive-store/preact";
2
3function Counter() {
4  const [count, setCount] = useStorage("count", 0);
5  return <div>Count: {count}</div>;
6}

useStorage (Solid) - v0.0.3+

Solid 版本的 useStorage 函数，返回 Solid 的 signal。

1import { useStorage } from "ew-responsive-store/solid";
2
3function Counter() {
4  const [count, setCount] = useStorage("count", 0);
5  return <div>Count: {count()}</div>;
6}

useStorage (Svelte) - v0.0.3+

Svelte 版本的 useStorage 函数，返回 Svelte store。

1<script>
2  import { useStorage } from "ew-responsive-store/svelte";
3  
4  const store = useStorage("count", 0);
5  let count = $store;
6</script>
7
8<div>Count: {count}</div>

useStorage (Angular) - v0.0.3+

Angular 版本的 useStorage 函数，返回 Angular signal。

1import { Component } from '@angular/core';
2import { useStorage } from "ew-responsive-store/angular";
3
4@Component({
5  template: `<div>Count: {{ count() }}</div>`
6})
7export class CounterComponent {
8  private storage = useStorage("count", 0);
9  count = this.storage.value;
10}

useStorage (Vanilla JS) - v0.0.3+

原生 JavaScript 版本的 useStorage 函数，返回存储管理器对象。

1import { useStorage } from "ew-responsive-store/vanilla";
2
3const storage = useStorage("count", 0);
4
5// 获取当前值
6console.log(storage.value); // 0
7
8// 更新值
9storage.setValue(1);
10console.log(storage.value); // 1
11
12// 订阅变化
13storage.subscribe((newValue) => {
14  console.log("Value changed:", newValue);
15});

历史版本 API (v0.0.1-beta.8 及之前)

useStorage (Vue) - v0.0.1-beta.8

useStorage 函数是 ew-responsive-store 库的核心 API。它允许你创建与浏览器存储（localStorage 或 sessionStorage）同步的响应式状态。

类型定义

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: StoreOptions = {
5    storage: StoreType.LOCAL,
6    immediate: true,
7    deep: true,
8  }
9): Ref<T>;

参数

参数 类型 描述
key string 用于在存储中存储值的键
initialValue T 如果在存储中找不到值，则使用的初始值
options StoreOptions 配置选项（可选）

选项

options 参数接受以下属性：

属性 类型 默认值 描述
storage StoreType StoreType.LOCAL 要使用的存储类型（localStorage 或 sessionStorage）
deep boolean true 是否深度监视状态变化

此外，所有 Vue 的 watch 选项都受支持，因为 StoreOptions 扩展了 Vue 的 WatchOptions。

返回值

一个与指定存储同步的响应式 Ref<T>。

示例

1import { useStorage } from "ew-responsive-store";
2import { StoreType } from "ew-responsive-store/typings/core/enum";
3
4// 基本用法，使用 localStorage
5const count = useStorage("count", 0);
6
7// 使用 sessionStorage
8const user = useStorage(
9  "user",
10  { name: "张三" },
11  { storage: StoreType.SESSION }
12);
13
14// 禁用深度监视
15const list = useStorage("list", [1, 2, 3], { deep: false });
16
17// 禁用立即效果
18const settings = useStorage(
19  "settings",
20  { theme: "dark" },
21  { immediate: false }
22);

useReactStorage (React) - v0.0.1-beta.7

useReactStorage 函数专为 React 应用程序设计。它提供了一种 React 原生的方式来管理与浏览器存储同步的状态。

类型定义

1function useReactStorage<T>(
2  key: string,
3  initialValue: T,
4  options: ReactStoreOptions = {
5    storage: StoreType.LOCAL,
6  }
7): readonly [T, (newValue: T) => void];

参数

参数 类型 描述
key string 用于在存储中存储值的键
initialValue T 如果在存储中找不到值，则使用的初始值
options ReactStoreOptions 配置选项（可选）

选项

options 参数接受以下属性：

属性 类型 默认值 描述
storage StoreType StoreType.LOCAL 要使用的存储类型（localStorage 或 sessionStorage）

返回值

一个包含以下内容的元组：

  • [0]: 当前值，类型为 T
  • [1]: 用于更新值的设置函数

示例

1import React from 'react';
2import { useReactStorage, StoreType } from "ew-responsive-store";
3
4function Counter() {
5  // 基本用法，使用 localStorage
6  const [count, setCount] = useReactStorage("count", 0);
7  
8  // 使用 sessionStorage
9  const [user, setUser] = useReactStorage(
10    "user",
11    { name: "张三", age: 25 },
12    { storage: StoreType.SESSION }
13  );
14
15  // 复杂数据类型
16  const [todos, setTodos] = useReactStorage("todos", [
17    { id: 1, text: "学习 React", completed: false },
18    { id: 2, text: "学习 TypeScript", completed: true }
19  ]);
20
21  const increment = () => setCount(count + 1);
22  const addTodo = (text: string) => {
23    setTodos([...todos, { 
24      id: Date.now(), 
25      text, 
26      completed: false 
27    }]);
28  };
29
30  return (
31    <div>
32      <p>计数: {count}</p>
33      <button onClick={increment}>增加</button>
34      
35      <p>用户: {user.name} ({user.age}岁)</p>
36      <button onClick={() => setUser({ ...user, age: user.age + 1 })}>
37        增加年龄
38      </button>
39      
40      <div>
41        <h3>待办事项:</h3>
42        {todos.map(todo => (
43          <div key={todo.id}>
44            <span style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}>
45              {todo.text}
46            </span>
47          </div>
48        ))}
49      </div>
50    </div>
51  );
52}

跨标签页同步

useReactStorage 使用 storage 事件自动同步不同浏览器标签页之间的数据：

1import { useReactStorage } from "ew-responsive-store";
2
3function App() {
4  const [theme, setTheme] = useReactStorage("theme", "light");
5  
6  // 当改变时，这会在其他标签页中自动更新
7  const toggleTheme = () => {
8    setTheme(theme === "light" ? "dark" : "light");
9  };
10
11  return (
12    <div className={`app ${theme}`}>
13      <button onClick={toggleTheme}>
14        切换到 {theme === "light" ? "深色" : "浅色"} 主题
15      </button>
16    </div>
17  );
18}

错误处理

如果存储不可用，该钩子会抛出错误：

1import { useReactStorage } from "ew-responsive-store";
2
3function SafeStorage() {
4  try {
5    const [data, setData] = useReactStorage("data", {});
6    return <div>存储可用</div>;
7  } catch (error) {
8    return <div>存储不可用: {error.message}</div>;
9  }
10}

parseStr

parseStr 函数是一个用于解析字符串值的实用工具。它提供了两种解析模式：EVAL 和 JSON。

类型定义

1function parseStr<T>(
2  str: string,
3  type: parseStrType = parseStrType.JSON
4): T | null;

参数

参数 类型 描述
str string 要解析的字符串
type parseStrType 要使用的解析方法（JSON 或 EVAL）

返回值

类型为 T 的解析值，如果解析失败则为 null。

示例

1import { parseStr, ParseStrType } from "ew-responsive-store";
2
3// 解析 JSON
4const data = parseStr<{ name: string }>('{ "name": "张三" }');
5// 结果: { name: '张三' }
6
7// 执行 JavaScript 代码
8const result = parseStr<number>("1 + 2", ParseStrType.EVAL);
9// 结果: 3

实用函数

isValidJSON

检查字符串是否为有效的 JSON。

1function isValidJSON(val: string): boolean;

isStorageEnabled

检查当前环境中是否启用了存储类型。

1function isStorageEnabled(storage: Storage): boolean;

枚举

StoreType

定义可用的存储类型。

1enum StoreType {
2  LOCAL = "localStorage",
3  SESSION = "sessionStorage",
4}

parseStrType

定义 parseStr 的可用解析方法。

1enum parseStrType {
2  EVAL = "eval",
3  JSON = "json",
4}
ON THIS PAGE