YuStorage

统一浏览器存储接口，支持 localStorage、sessionStorage、Cookie 和 IndexedDB 的封装库。

特性

• 🚀 统一的 API 接口，支持多种存储方式
• 📦 模块化设计，按需引入
• 🔧 支持 TypeScript
• 🌐 支持多种模块格式（ESM、CommonJS、UMD）
• 🛡️ 完善的错误处理和降级机制
• 📱 浏览器兼容性良好

安装

npm install yu-storage

快速开始

ES6 模块

import yuStorage from 'yu-storage';

// 使用默认存储（localStorage）
yuStorage.set('name', '张三');
const name = yuStorage.get('name');
console.log(name); // 张三

// 指定存储类型
yuStorage.set('theme', 'dark', { type: 'session' });
yuStorage.set('token', 'abc123', { type: 'cookie', expires: 7 });
yuStorage.set('settings', { lang: 'zh' }, { type: 'indexeddb' });

CommonJS

const yuStorage = require('yu-storage');

yuStorage.set('data', 'value');
const data = yuStorage.get('data');

浏览器直接引入

<script src="dist/yu-storage.umd.js"></script>
<script>
  const yuStorage = YuStorage.default;
  yuStorage.set('key', 'value');
  const value = yuStorage.get('key');
</script>

重要提示： 由于浏览器的安全限制，Cookie 功能需要在 HTTP 服务器环境下测试，不能直接打开 HTML 文件（file:// 协议）。建议使用以下方式之一：

• Live Server (VS Code 扩展)
• Python: python -m http.server 8080
• Node.js: npx http-server -p 8080
• 其他本地服务器

API 文档

基础方法

set(key, value, options)

设置数据到指定存储。

参数：

• key (string): 键名
• value (any): 值
• options (object): 选项
  • type (string): 存储类型，可选值：'local', 'session', 'cookie', 'indexeddb'
  • 其他选项根据存储类型而定

返回值： boolean | Promise<boolean>

示例：

// localStorage
yuStorage.set('user', { name: '张三', age: 25 });

// sessionStorage
yuStorage.set('temp', '临时数据', { type: 'session' });

// Cookie
yuStorage.set('theme', 'dark', { 
  type: 'cookie', 
  expires: 30,  // 30天过期
  path: '/',
  secure: true
});

// IndexedDB
yuStorage.set('settings', { lang: 'zh' }, { type: 'indexeddb' });

get(key, options)

从指定存储获取数据。

参数：

• key (string): 键名
• options (object): 选项
  • type (string): 存储类型

返回值： any | Promise<any>

示例：

const user = yuStorage.get('user');
const temp = yuStorage.get('temp', { type: 'session' });
const theme = yuStorage.get('theme', { type: 'cookie' });
const settings = await yuStorage.get('settings', { type: 'indexeddb' });

remove(key, options)

从指定存储删除数据。

参数：

• key (string): 键名
• options (object): 选项
  • type (string): 存储类型

返回值： boolean | Promise<boolean>

clear(options)

清空指定存储的所有数据。

参数：

• options (object): 选项
  • type (string): 存储类型

返回值： boolean | Promise<boolean>

keys(options)

获取指定存储的所有键名。

参数：

• options (object): 选项
  • type (string): 存储类型

返回值： string[] | Promise<string[]>

工具方法

isAvailable(type)

检查指定存储类型是否可用。

参数：

• type (string): 存储类型

返回值： boolean

getAvailableTypes()

获取所有可用的存储类型。

返回值： string[]

setDefaultType(type)

设置默认存储类型。

参数：

• type (string): 存储类型

getStorageInfo(type)

获取指定存储的详细信息。

参数：

• type (string): 存储类型

返回值： object | Promise<object>

返回内容：

{
  type: string,        // 存储类型名称
  available: boolean,  // 是否可用
  keys: string[]       // 所有键名数组
}

示例：

// 同步存储
const localInfo = yuStorage.getStorageInfo('local');
console.log(localInfo.keys); // ['user', 'theme']

// 异步存储
const dbInfo = await yuStorage.getStorageInfo('indexeddb');
console.log(dbInfo.keys); // ['settings', 'data']

存储类型说明

localStorage

• 持久化存储，除非手动清除
• 存储大小限制：通常 5-10MB
• 同步操作

sessionStorage

• 会话级存储，关闭标签页后清除
• 存储大小限制：通常 5-10MB
• 同步操作

Cookie

• 持久化存储，可设置过期时间
• 存储大小限制：4KB
• 同步操作
• 支持额外选项：expires, path, domain, secure, sameSite

IndexedDB

• 持久化存储，大容量存储
• 存储大小限制：通常几百MB到几GB
• 异步操作，返回 Promise

测试和示例

项目包含两个测试页面：

• test.html: 功能测试页面，测试所有存储类型
• example.html: 使用示例页面，展示各种存储操作

运行测试：

# 启动本地服务器
python -m http.server 8080
# 或
npx http-server -p 8080

# 访问测试页面
# http://localhost:8080/test.html
# http://localhost:8080/example.html

构建

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听文件变化）
npm run dev

浏览器支持

• Chrome 4+
• Firefox 3.5+
• Safari 4+
• Edge 12+
• IE 8+（部分功能）

许可证

MIT