web-localstorage-plus
Version:
Enhanced localStorage
240 lines (194 loc) • 5.07 kB
Markdown
# web-localstorage-plus
基于 localStorage 做了一层封装，使其更易用、更简洁、更强大
## 特点功能
- 命名空间
- 加解密
- 批量操作
- 过期时间
- onChange
- onExpire
- eventBus
- pinia 持久化
- 离线消息（限定vite+vue3）
## 安装
```js
yarn add web-localstorage-plus
```
## 初始化
```ts
import createStorage from "web-localstorage-plus";
/**
* @rootName {string} 根命名空间，默认值：web-localstorage-plus
* @noUseLocalStorage {boolean} 是否禁用localStorage，默认值：true
*/
createStorage({
rootName: "spp-storage",
});
```
## 参数说明
| 属性名 | 说明 | 类型 |
| ---------- | ------------------------------------ | -------------------------------- |
| key | 保存的键名 | string |
| value | 保存的键值 | any（内部调用的 JSON.stringify） |
| namespace | 命名空间 | string |
| expireTime | 过期时间 | number |
| encrypt | 是否加密 | boolean |
| isFlatten | 是否将返回值拍平（仅批量操作时有效） | boolean |
## 基本使用
- useStorage
在 vue 或者 react 项目中，通过 useStorage 统一获取方式
```js
import { useStorage } from "web-localstorage-plus";
const storage = useStorage();
```
- setItem
```js
storage.setItem("a", 1);
storage.setItem("b", 2, true);
storage.setItem("c", 3, "space1");
storage.setItem("d", 4, 1000); // 设置1秒后过期
storage.setItem("e", 5, "space2", 5000, true);
storage.setItem([
{ key: "f", value: 4, namespace: "space3" },
{ key: "g", value: 5, namespace: "space4" },
]);
storage.setItem(
[
{ key: "h", value: 6 },
{ key: "i", value: 7, encrypt: true },
],
"space5"
);
/**
"web-storage":{
"a": 1,
"b": "*",
"space1": {
"c": 3
},
"d": 4, // 1秒后自动删除
"space2": {
"e": "*"
},
"space3": {
"f": 4
},
"space4": {
"g": 5
},
"space5": {
"h": 6,
"i": "*"
}
}
*/
```
- getItem
```js
storage.getItem("a"); // 1
storage.getItem("c", "space1"); // 3
storage.getItem(["a", "b", "d"], true); // [1, 2, 4]
storage.getItem(["e"], "space2"); // [{value:5,namespace:"space2"}]
storage.getItem([
"a",
{
key: "f",
namespace: "space3",
},
{
key: "c",
namespace: "space1",
},
]); // [1,4,3]
storage.getItem(
[
"a",
{
key: "c",
namespace: "space1",
},
],
true
); // [1,3]
```
- removeItem
```js
storage.removeItem("a");
storage.removeItem("f", "space3");
storage.removeItem([
"a",
{
key: "f",
namespace: "space3",
},
]);
```
- clear
```js
storage.clear();
storage.clear(["space2"]); // 将space2下的值清空
storage.clear(["space2"], true); // 将除了space2的其他命名空间下的值清空
```
## onChange、onExpire、postMessage、onMessage
- onMessage 与 postMessage
```js
storage.onMessage("login", (payload) => {
console.log(payload);
});
storage.onMessage(
"login",
(payload) => {
console.log(payload, "2");
},
false /* 指定参数2则不会被覆盖 */
);
setTimeout(() => {
storage.postMessage("login", {
user: "spp",
});
}, 3000);
```
- onChange
```js
storage.onChange("age", (payload) => {
const { newValue, oldValue, namespace } = payload;
// 当age改变时触发
});
setTimeout(() => {
storage.setItem / removeItem / clear();
}, 3000);
```
- onExpire
```js
storage.onExpire("d", () => {
console.log("1s后被调用");
});
storage.onExpire("d", () => {
console.log("5s后被调用");
});
```
## use
通过该接口能够参与到 web-storage 的内部运行逻辑，其接受一个函数类型，将在 "getItem" | "setItem" | "removeItem" | "clear"执行时被调用
当前加解密只是使用同等数量的"\*"对存储值做了替换，如果你想要使用 md5 或其他算法实现,可通过 use 进行重写
- 示例
```js
function userPlugin(payload) {
const { key, wark, value, namespace, ctx } = params;
if (wark === "setItem") {
// do somting
}
return value;
}
storage.use(userPlugin);
```
## pinia持久化
由于涉及到hmr，因此将该能力提取到了[@web-localstorage-plus/pinia](https://github.com/supanpanCn/web-localstorage-plus-pinia)
## 离线消息
由于是针对vite+vue3的，故将其提取到了[@web-localstorage-plus/offline](https://github.com/supanpanCn/web-localstorage-plus-offline)