更新记录

1.0.0（2026-07-18） 下载此版本

更新

平台兼容性

uni-app(3.8.10)

Cache 模块说明

主要功能

• set(params, async=true)

  • 设置缓存数据。
  • 参数：
    • key：缓存键，必填。
    • data：缓存值，必填。
    • unit：缓存时间单位，可选值 day、hours、minutes，默认 day。
    • time：过期时间，默认 0 表示永久缓存。
    • async：是否使用异步缓存，默认 true。
  • 行为：
    • time === 0 时直接存储数据；
    • 否则计算过期时间后，将数据序列化为 JSON 并追加 |过期时间 保存到 Storage。

• get(key, cb)

  • 获取缓存数据。
  • 支持同步返回值和异步回调两种方式：
    • 传入 cb 时，使用 uni.getStorage 异步读取并通过回调返回。
    • 不传回调时，使用 uni.getStorageSync 同步读取并返回。
  • 会自动判断是否过期，如果过期则删除缓存并返回空字符串。

• fileCache(cacheKey, httpFilePath, callback)

  • 执行文件缓存逻辑。
  • 流程：
    1. 读取已保存文件列表；
    2. 尝试从 cacheKey 对应的缓存路径中查找已缓存文件；
    3. 若存在则直接返回本地文件路径；
    4. 否则下载文件并保存，再把本地路径写入 Storage。
  • 参数：
    • cacheKey：缓存键。
    • httpFilePath：远程文件地址。
    • callback：回调函数，成功后返回本地文件路径。

内部辅助函数

• getData(key, val)
  • 解析缓存值并判断过期。
  • 如果缓存值是字符串，会以 | 分隔原始数据与过期时间：
    • 过期时间存在且已过期时，删除缓存并返回 ''。
    • 过期时间存在且未过期时，返回 JSON 解析后的数据。
    • 过期时间不存在时，返回原始值。
  • 如果缓存值不是字符串，直接返回原始值。

代码导出

• export default new CacheManage()
  • 导出 CacheManage 的单例实例，方便在项目中直接引入使用。

使用示例

import Cache from "@/uni_modules/zh-cache/js_sdk/cache.js";

// 设置缓存
Cache.set({ key: "userInfo", data: { name: "Alice" }, unit: "hours", time: 2 });

// 获取缓存（同步）
const userInfo = Cache.get("userInfo");

// 获取缓存（异步）
Cache.get("userInfo", (value) => {
    console.log(value);
});

// 缓存文件
Cache.fileCache("avatarFile", "https://example.com/avatar.jpg", (localPath) => {
    console.log("本地文件路径:", localPath);
});