# h5storage

**Repository Path**: web/h5storage

## Basic Information

- **Project Name**: h5storage
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# H5Storage

多浏览器存储统一封装库，支持 **IndexedDB / localStorage / sessionStorage / Cookie**。
一套统一API，内部自动处理JSON序列化，可随时切换存储驱动，专为浏览器环境使用。

> ⚠️ **重要提醒**
> 1. IndexedDB 在 `file://` 本地文件协议会被浏览器安全策略禁用，会报错。**必须通过 HTTP 服务访问**（VSCode Live Server、Nginx等）。
> 2. file协议下除 indexedDB 外，localStorage / sessionStorage / cookie 均可正常工作。

## 项目文件结构
```
├─ h5storage.js      # UMD库源码，浏览器script直接引入，Node可require，无ESModule语法
├─ index.html        # 可视化演示页面
├─ test.html         # 精简测试文件
├─ minifun.html      # 单函数版本（精简，仅支持localStorage / sessionStorage / Cookie）
└─ README.md         # 使用文档
```

## 快速引入

### 方式1：浏览器 script 标签（普通网页）
```html
<script src="./h5storage.js"></script>
<script>
  //实例化
  const store = new H5Storage({
    driver: "local" // 默认驱动可选：indexedDB / local / session / cookie
  });
</script>
```

### 方式2：Node.js CommonJS
> 仅可导入类，Node环境没有浏览器存储API，不能实际读写数据
```javascript
const H5Storage = require('./h5storage.js');
```

### 方式3：Vite / Webpack 打包项目使用
本文件不含 `export`，打包环境使用全局方式引入：
```javascript
import './h5storage.js';
const store = new window.H5Storage({ driver: "local" });
```

## API文档

### 实例初始化
```javascript
const store = new H5Storage({
  driver: "indexedDB",       // 默认存储驱动
  cookieExpireDays: 7,      // cookie默认过期天数
  dbName: "H5StorageDB",    // indexedDB数据库名
  storeName: "store"        // indexedDB仓库名
});
```

### 基础方法

#### set(key, value, [overrideOpts]) 设置数据
- `overrideOpts`：临时覆盖实例配置，可以临时切换驱动
- indexedDB 返回 Promise；local / session / cookie 直接返回布尔值
```javascript
// 使用实例默认驱动
store.set("username","张三");

// 临时切换驱动为sessionStorage
store.set("tempData",[1,2,3],{driver:"session"});

// indexedDB异步，需要await或.then
store.set("bigData",{list:[1,2,3]},{driver:"indexedDB"})
.then(res=>console.log(res));
```

#### get(key, [overrideOpts]) 读取数据
```javascript
//同步驱动
const name = store.get("username");

// indexedDB异步
store.get("bigData",{driver:"indexedDB"}).then(val=>console.log(val));
```

#### remove(key, [overrideOpts]) 删除数据
```javascript
store.remove("username");
```

#### storage(key, value, [overrideOpts]) 底层主方法
- `storage(key)` → 读取
- `storage(key, value)` →写入
- `storage(key, null)` →删除
```javascript
store.storage("foo","bar");     //写入
store.storage("foo");           //读取
store.storage("foo",null);      //删除
```

## 四种驱动对比

|驱动|特性|返回值|大小限制|
|---|---|---|---|
|`indexedDB`|异步大容量存储|Promise|几MB~几十MB|
|`local`(localStorage)|同步持久化|boolean|约5MB|
|`session`(sessionStorage)|会话级，关闭标签丢失|boolean|约5MB|
|`cookie`|可传给后端，容量小|boolean|4KB以内|

## 演示页面说明
打开 `index.html`，强烈建议使用 Live Server 启动 http 服务。
功能：
1. 自定义key、value，选择驱动进行增删查操作
2. **全部驱动一轮读写测试**：依次循环测试4种存储
> 注意：file协议打开时 indexedDB 会失败，每个驱动有独立异常捕获，不会中断后续测试，错误信息打印在页面日志和控制台。

## 异步异常处理示例
indexedDB全部操作是异步，务必捕获Promise异常：
```javascript
async function demo(){
  try {
    await store.set("key1",{a:1},{driver:"indexedDB"});
    const data = await store.get("key1",{driver:"indexedDB"});
    console.log(data);
  }catch(err){
    console.error("存储出错",err);
  }
}
demo();
```

## 常见问题

### Q1：点击全部驱动测试，运行到indexedDB就卡住不动
旧版本未做单驱动异常捕获，一个驱动报错会中断整个循环。
> 当前版本每个驱动循环内部有独立 try‑catch，indexedDB失败后打印错误，继续执行 local / session / cookie。

### Q2：Uncaught SyntaxError: Unexpected token 'export'
本库已经移除 `export / import.meta`，直接普通 `<script src>` 引入，**不要加 type="module"**。

### Q3：indexedDB报错 open failed
大概率是直接使用 `file://` 打开页面，浏览器安全限制，改用 http 服务访问。

### Q4：Cookie存储对象需要手动JSON处理吗？
库内部自动做 JSON.stringify / JSON.parse，直接传入对象即可。

## 使用注意事项
1. Cookie有4KB容量限制，不适合存放大量数据。
2. sessionStorage 在浏览器标签关闭后数据自动清空。
3. indexedDB全部操作异步，必须使用 await / .then 获取返回结果。
4. 浏览器隐私模式下部分浏览器会禁用 IndexedDB。