分类： 微信小程序开发

CacheManager

基础库 2.24.0 开始支持，低版本需做兼容处理。

相关文档: 弱网体验优化

缓存管理器。全局只有唯一实例，一旦被创建出来即表示接入缓存管理器。其有以下几个能力：

  1. 在网络通畅时，符合一定规则的用户网络请求（目前只包括普通 wx.request 请求）会被缓存。
  2. 在网络通畅时，某些 wx api 调用会被缓存。
  3. 进入弱网/离线状态时，会提供事件给用户，用户可以决定是否使用缓存返回。
  4. 提供进入和退出弱网/离线状态的事件。
  1. 缓存管理器中涉及的网络请求如无特指，均指普通的 wx.request 异步请求，参数和返回值中均不考虑涉及 ArrayBuffer 或 TypedArray 的情形。
  2. 缓存管理器中的缓存不会占用 storage 空间，但是有大小限制，请勿在非必要的请求上使用缓存。

属性

string mode

当前缓存模式

mode 的合法值

值 说明 最低版本
weakNetwork 默认值，弱网/离线使用缓存返回
always 总是使用缓存返回
none 不开启，后续可手动开启/停止使用缓存返回

string origin

全局 origin

number maxAge

全局缓存有效时间

number state

当前缓存管理器状态

state 的合法值

值 说明 最低版本
0 不使用缓存返回
1 使用缓存返回
2 未知

方法

Array. CacheManager.addRules(Array.<(string|RegExp|Record.)> rules)

批量添加规则，规则写法可参考 CacheManager.addRule。

string CacheManager.addRule(string|RegExp|Record. rule)

添加规则。

CacheManager.deleteRules(Array. ids)

批量删除规则，同时会删除对应规则下所有缓存。

CacheManager.deleteRule(string id)

删除规则，同时会删除对应规则下所有缓存。

CacheManager.clearRules()

清空所有规则，同时会删除对应规则下所有缓存。

CacheManager.on(string eventName, function handler)

监听事件。

CacheManager.off(string eventName, function handler)

取消事件监听。

CacheManager.start()

开启缓存，仅在 mode 为 none 时生效，调用后缓存管理器的 state 会置为 1。

CacheManager.stop()

关闭缓存，仅在 mode 为 none 时生效，调用后缓存管理器的 state 会置为 0。

Object CacheManager.match(Object evt)

匹配命中的缓存规则，一般需要和 request 事件搭配使用。

CacheManager.deleteCaches(Array. ids)

批量删除缓存。

CacheManager.deleteCache(string id)

删除缓存。

CacheManager.clearCaches()

清空所有缓存。

wx.createCacheManager(Object object)

基础库 2.24.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

相关文档: 弱网体验优化

功能描述

创建缓存管理器

参数

Object object

属性 类型 默认值 必填 说明
origin string 否 全局 origin
mode string weakNetwork 否 缓存模式
合法值 说明
weakNetwork 弱网/离线使用缓存返回
always 总是使用缓存返回
none 不开启，后续可手动开启/停止使用缓存返回
maxAge number 否 全局缓存有效时间，单位为毫秒，默认为 7 天，最长不超过 30 天
extra object 否 额外的缓存处理
结构属性 类型 默认值 必填 说明
apiList Array.<string> 否 需要缓存的 wx api 接口，不传则表示支持缓存的接口全都做缓存处理。返回的如果是缓存数据，开发者可通过 fromCache 标记区分
合法值 说明
wx.login
wx.checkSession
wx.getSetting

返回值

CacheManager

缓存管理器

示例代码

查看完整示例代码

const cacheManager = createCacheManager()
cacheManager.addRule(/https:\/\/(?:.*)/ig) // 表示所有 https 请求都匹配

cacheManager.on('request', evt => {
 // 在弱网时接收到 wx.request 请求
 return new Promise((resolve, reject) => {
   const matchRes = cm.match(evt)
   if (matchRes && matchRes.data) {
     // 有缓存，返回
     resolve(matchRes.data)
   } else {
     // 没缓存，抛错
     reject({ errMsg: 'no cache' })
   }
 })
})

wx.getBackgroundFetchData(object object)

基础库 2.8.0 开始支持，低版本需做兼容处理。

以 Promise 风格 调用：支持

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 周期性更新、数据预拉取

功能描述

拉取 backgroundFetch 客户端缓存数据。 当调用接口时，若当次请求未结束，会先返回本地的旧数据（之前打开微信小程序时请求的），如果本地没有旧数据，安卓上会返回fail，不会等待请求完成，iOS上会返回success但fetchedData为空，也不会等待请求完成。建议和 wx.onBackgroundFetchData 配合使用。

参数

object object

属性 类型 默认值 必填 说明
fetchType String 是 缓存数据类别，取值为 periodic 或 pre
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数
Object res
属性 类型 说明
fetchedData String 缓存数据
timeStamp Number 客户端拿到缓存数据的时间戳 ms。(iOS 时间戳存在异常，8.0.27 修复)
path String 微信小程序页面路径
query String 传给页面的 query 参数
scene Number 进入微信小程序的场景值

wx.getBackgroundFetchToken(Object object)

基础库 2.8.0 开始支持，低版本需做兼容处理。

以 Promise 风格 调用：支持

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 周期性更新、数据预拉取

功能描述

获取设置过的自定义登录态。若无，则返回 fail。

参数

Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数
Object res
属性 类型 说明
token String 自定义的登录态
errMsg String 接口调用结果

wx.onBackgroundFetchData(function listener)

基础库 2.8.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

相关文档: 周期性更新、数据预拉取

功能描述

监听收到 backgroundFetch 数据事件。如果监听时请求已经完成，则事件不会触发。建议和 wx.getBackgroundFetchData 配合使用

参数

function listener

收到 backgroundFetch 数据事件的监听函数

参数

Object res
属性 类型 说明
fetchType string 缓存数据类别，取值为 periodic 或 pre
fetchedData string 缓存数据
timeStamp number 客户端拿到缓存数据的时间戳
path String 微信小程序页面路径
query String 传给页面的 query 参数
scene Number 进入微信小程序的场景值

wx.setBackgroundFetchToken(object object)

基础库 2.8.0 开始支持，低版本需做兼容处理。

以 Promise 风格 调用：支持

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 周期性更新、数据预拉取

功能描述

设置自定义登录态，在周期性拉取数据时带上，便于第三方服务器验证请求合法性

参数

object object

属性 类型 默认值 必填 说明
token String 是 自定义的登录态。上限 1024 字符。
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

wx.batchGetStorage(Object object)

基础库 2.25.0 开始支持，低版本需做兼容处理。

以 Promise 风格 调用：支持

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 存储策略

功能描述

从本地缓存中异步批量获取指定 key 的内容。

参数

Object object

属性 类型 默认值 必填 说明
keyList Array.<string> 是 本地缓存中指定的 keyList
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.batchGetStorage({
  keyList: ['key'],
  success (res) {
    console.log(res)
  }
})

wx.batchGetStorageSync(Array. keyList)

基础库 2.25.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 存储策略

功能描述

从本地缓存中同步批量获取指定 key 的内容。

参数

Array. keyList

本地缓存中指定的 key 数组

返回值

Array.

key对应的内容

示例代码

try {
  var valueList = wx.batchGetStorageSync(['key'])
  if (valueList) {
    // Do something with return value
  }
} catch (e) {
  // Do something when catch error
}

对于多个key的读取, 批量读取在性能上优于多次getStorageSync读取

wx.batchSetStorage(Object object)

基础库 2.25.0 开始支持，低版本需做兼容处理。

以 Promise 风格 调用：支持

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 存储策略

功能描述

将数据批量存储在本地缓存中指定的 key 中。会覆盖掉原来该 key 对应的内容。除非用户主动删除或因存储空间原因被系统清理，否则数据都一直可用。单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

参数

Object object

属性 类型 默认值 必填 说明
kvList Array 是 [{ key, value }]
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.setStorage({
  key:"key",
  data:"value"
})

// 开启加密存储
wx.batchSetStorage({
  kvList: [{
    key: 'key',
    value: 'value',
  }],
})

wx.batchSetStorageSync(Array. kvList)

基础库 2.25.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信 鸿蒙 OS 版：支持

相关文档: 存储策略

功能描述

将数据批量存储在本地缓存中指定的 key 中。会覆盖掉原来该 key 对应的内容。除非用户主动删除或因存储空间原因被系统清理，否则数据都一直可用。单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

参数

Array. kvList
属性 类型 默认值 必填 说明
key string 是 key 本地缓存中指定的 key
value any 是 data 需要存储的内容。只支持原生类型、Date、及能够通过JSON.stringify序列化的对象。

示例代码

try {
  wx.batchSetStorageSync([{key: 'key', value: 'value'}])
} catch (e) { }