browser-localstorge

v1.1.3

Published

5 months ago

浏览器本地存储工具库

0High
0Medium
0Low

aurora_

🌈browser-localstorge

📌localStorage 存储

初始化

new BrowserStoreKit(type, options)

| 属性名 | 含义 | 格式、默认值 | | :----:| :----: | :----: | | type | 存储模块类型 | `string`，目前支持三种模式：LOCAL_STORAGE, SESSION_STORAGE, INDEXED_DB（请从库中导入使用）。 | | options | 配置参数 | `object`，根据模式的不同设置项的属性也不同。添加localStorage下的属性，会在LOCAL_STORAGE模式下生效。 |

示例参考：

import BrowserStoreKit, { LOCAL_STORAGE, SESSION_STORAGE, INDEXED_DB } from 'browser-localstorage'

const localKit = new BrowserStoreKit(LOCAL_STORAGE, {
    // 使用localStorage的时候，这边配置项参数就给属性localStorage赋值即可（session同理）
    localStorage: {
        auto_cover: true,
        auto_parse: true,
        auto_stringify: true,
        debug: false,
    }
})

// 实例化之后，就可以执行localKit的方法了
localKit.setItem(...)
localKit.getItem(...)
...

下面介绍一下配置项参数的含义：

目前，localStorage 和 sessionStorage 的配置项参数是一致的。

控制台输出的调试信息格式大致如下：

[2025-04-22 10:16:42] 🔗localStorage 📎[getItem]: 数据项获取成功➡️(key: 2)➡️值为{"id":"2","name":"咪咪","age":"3.56"}

这其实没有什么实质性的大作用，但是console能够给到你一些足够的安全感~

1️⃣新增 / 修改数据 `setItem`

key：string类型，必填项，表示键。
value：any类型，必填项，表示存储的值。

注意：value的类型可以是任意类型，但是在存储的时候可能会自动将其序列化为字符串。

localKit.setItem(key, value)

2️⃣删除数据 `removeItem`

根据键删除数据

key：string类型，必填项，表示键。

localKit.removeItem(key)

3️⃣查找数据 `getItem`

根据键查找数据

key：string类型，必填项，表示键。

localKit.getItem(key)

4️⃣清空数据 `clear`

清空本地localStorage中的所有数据，无参数。不可撤销请谨慎使用。

localKit.clear()

5️⃣获取数据长度 `length`

获取localStorage中的所有数据的长度，无参数。

localKit.length()

📌sessionStorage 存储

sessionStorage不做过多的赘述，因为它和localStorage的使用是完全一致的。请仔细阅读上面的localStorage文档部分即可。

📌indexedDB 存储🔥🔥🔥

简单介绍一下indexedDB的使用方法。它与前面的localStorage和sessionStorage的使用方式是完全不同的。因此在使用之前，希望你仔细阅读下面的文档。

👉初始化

首先初始化 indexedDB

import BrowserStoreKit, { INDEXED_DB } from 'browser-localstorage'

const DBKit = new BrowserStoreKit(INDEXED_DB, {
    // 在使用indexedDB的时候，需要配置indexedDB的参数
    indexedDB: {
        databaseName: "testDB", // 此参数必填
        tableName: "testTable",
        primaryKey: "id",
        autoIncrement: true,
        auto_cover: false,
        debug: false
    }
})

// 这一步十分重要❗❗❗
// 请注意，因为indexedDB是异步操作，因此在实例化之后需要再执行init方法
// 这一步保证你的数据库和数据表已经处于打开状态，以此来进行后续的操作

await DBKit.init()

请注意 primaryKey（主键） 和 autoIncrement（是否自动递增） 两者之间的关系：

primaryKey为必需参数，并且要保证唯一性，主要作用如下：

在新增数据的时候，作为唯一主键
在修改、查找、删除数据的时候作为查找线索

当你申明了autoIncrement参数值为true的时候，这意味着：

BrowserStoreKit会在你每次插入数据（setItem）的时候，为你的数据增加一个主键（也就是参数primaryKey），这个过程是自动的，且遵循的逻辑是递增（i++）

例如，当你调用setItem新增数据的时候是这样的：

await DBKit.setItem({ name: '老王', age: 48 })

当你后续调用getItem的时候，会拿到{ id: 2, name: '老王', age: 48 }

👉数据表相关操作

数据表的相关操作是在版本V1.1.0新增的。考虑到一个数据库下存在多张表的应用场景下，建议使用同一个数据库多张数据表的模式去开发。

1.创建数据表 `createTable(tableName, options)`

tableName：string类型，必填项，表示数据表名称。
options：CreateTableOptions类型，非必填项，表示配置参数。同初始化时候的数据表相关的三个参数：primaryKey、autoIncrement、auto_cover。

2.删除数据表 `deleteTable(tableName)`

tableName：string类型，必填项，表示数据表名称。

3.查询数据表 `hasTable(tableName)`

tableName：string类型，必填项，表示数据表名称。

4.设置当前数据表 `setCurrentTable(tableName)`

在进行下面的数据项相关操作之前，需要先设置当前数据表。通过setCurrentTable方法设置当前数据表。

tableName：string类型，必填项，表示数据表名称。

👉数据项相关操作

请注意，indexedDB模式下，下面这些操作都是异步的，因此在使用的时候需要使用await关键字。

1.新增 / 修改数据 `setItem`

DBKit.setItem(key, value)

key：string | number类型，必填项，表示键。
value：Object类型，必填项，表示存储的值。

在自增模式下，key可以传入null，因为此时会自动生成主键。

DBKit.setItem(id, { name, age }).then(r => {
    console.log("-----setItem返回结果-----")
    console.log(r)
})

2.删除数据 `removeItem`

key：string | number类型，必填项，表示键。

DBKit.removeItem(key).then(r => {
    console.log("-----removeItem返回结果-----")
    console.log(r)
})

3.查找数据 `getItem`

key：string | number类型，必填项，表示键。

DBKit.getItem(key).then(r => {
    console.log("-----getItem返回结果-----")
    console.log(r)
})

4.清空数据 `clear`

无参数，谨慎使用。

DBKit.clear().then(r => {
    console.log("-----clear返回结果-----")
    console.log(r)
})

5.获取数据长度 `length`

无参数。

DBKit.length().then(r => {
    console.log("-----length返回结果-----")
    console.log(r)
})

6.删除数据表 `deleteTable`

无参数，这里要删除的数据表即为初始化时指定的数据表。

DBKit.deleteTable().then(r => {
    console.log("-----deleteTable返回结果-----")
    console.log(r)
})

👉批量操作 `BatchProcess`

考虑到indexedDB存储的特性，在批量处理、数据量比较大的场景下会有比较高的应用频率。因此在原来的基础上，设计了批量操作的API，可以对数据进行批量新增、删除以及查找。请注意，批量操作目前仅支持indexedDB模式。

批量操作统一使用batchProcess方法，该方法接受三个参数

mode：<string>类型：批量操作的模式，目前支持三种模式，分别是新增（add）、查找（get）以及删除（delete）。
itemList：Array<string | number | Object>类型：批量操作的数据集合。
options：Object类型：批量操作的配置项。

options目前仅支持两个属性:

filter：(item) => {}回调函数类型，其中item就是每一个数据项的属性值。可以传入filter属性，自定义过滤元素。
vaildTime：number类型，非必填项，表示数据有效期，单位：秒（仅在执行批量新增的时候会生效）。

当执行批量新增的时候，如果传入了vaildTime参数，那么在执行批量获取的时候，就会校验数据有效性。如果发现数据过期，那么会自动全部清空数据。

1.批量新增操作 `ADD`

let startIndex = 1
const dataList = new Array(5).fill(0).map((item, index) => {
    return { id: startIndex + index, name: `我是第${startIndex+index}个name`, age: startIndex + index }
})

// 当我们执行批量新增的时候，数组的Item项为Object类型
// 并且，如果是自增模式下，Item不需要指定主键属性（id），因为会自动生成主键
// 此示例演示的是，非自增模式下，Item需要指定主键属性（id）
DBKit.batchProcess("add", dataList).then(r => {
    console.log("-----batchSetItem返回结果-----")
    console.log(r)
})

2.批量删除操作 `DELETE`

根据主键删除数据

// 当我们执行批量新增的时候，数组的Item项为number或string类型
DBKit.batchProcess("delete", [1, 2, 3, 4, 5]).then(r => {
    console.log("-----batchRemoveItem返回结果-----")
    console.log(r)
})

3.批量查询操作 `GET`

根据主键查询数据

// 当我们执行批量新增的时候，数组的Item项为number或string类型
DBKit.batchProcess("get", [1, 2, 3, 4, 5]).then(r => {
    console.log("-----batchGetItem返回结果-----")
    console.log(r)
})

当我们给第二个参数itemList传入一个空数组[]的时候，此时会获取数据表中的所有数据。配合options的filter属性，我们可以实现一些复杂的自定义的查询操作。

写在最后💻

如果觉得这个库对你有帮助，欢迎给我一个star⭐️⭐️⭐️ 如果有什么问题，欢迎交流。

源码地址：https://gitee.com/AuroraO23/browser-local-storage

版本更新记录📋

1.0.0 (2025-5)

📌1.0.0 首次发布

1.0.1 (2025-5)

🔧 批量操作模式代码优化，性能提升
🔧 批量操作模式下，返回增加timeDiff属性，用于记录执行时间

1.0.2 (2025-8)

🔧 新增deleteTable方法

1.1.1 (2025-8-27)

🔧 新增数据表的相关操作，详见文档
🔧 在批量新增的模式下，新增validTime参数，用于设置数据有效期；在批量获取模式下可以根据过期时间自动清除本地缓存数据
🐞 修复已知问题

1.1.3 (2025-8-28)

🐞 在ES模块下（也就是npm引入）环境中，修复options参数赋值错乱的问题
🔧 完善了一些打包命令

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🌈browser-localstorge

📌localStorage 存储

初始化

1️⃣新增 / 修改数据 setItem

2️⃣删除数据 removeItem

3️⃣查找数据 getItem

4️⃣清空数据 clear

5️⃣获取数据长度 length

📌sessionStorage 存储

📌indexedDB 存储🔥🔥🔥

👉初始化

👉数据表相关操作

1.创建数据表 createTable(tableName, options)

2.删除数据表 deleteTable(tableName)

3.查询数据表 hasTable(tableName)

4.设置当前数据表 setCurrentTable(tableName)