数据缓存

setStorageSync

setStorageSync(string key, any data)

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

参数

string key

本地缓存中指定的 key

any data

需要存储的内容。只支持原生类型、Date、及能够通过 JSON.stringify 序列化的对象。

示例代码

ft.setStorage({
  key: 'key',
  data: 'value'
})

try {
  ft.setStorageSync('key', 'value')
} catch (e) { }

setStorage

setStorage(Object object)

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

参数

Object object

属性	类型	默认值	必填	说明
key	string		是	本地缓存中指定的 key
data	any		是	需要存储的内容。只支持原生类型、Date、及能够通过 JSON.stringify 序列化的对象。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

ft.setStorage({
  key: 'key',
  data: 'value'
})

try {
  ft.setStorageSync('key', 'value')
} catch (e) { }

removeStorageSync

removeStorageSync(string key)

ft.removeStorage 的同步版本

参数

string key

本地缓存中指定的 key

示例代码

ft.removeStorage({
  key: 'key',
  success(res) {
    console.log(res)
  }
})

try {
  ft.removeStorageSync('key')
} catch (e) {
  // Do something when catch error
}

removeStorage

removeStorage(Object object)

从本地缓存中异步移除指定 key 对应的内容

参数

Object object

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

示例代码

ft.removeStorage({
  key: 'key',
  success(res) {
    console.log(res)
  }
})

try {
  ft.removeStorageSync('key')
} catch (e) {
  // Do something when catch error
}

getStorageSync

getStorageSync(string key)

ft.getStorage 的同步版本

参数

string key

本地缓存中指定的 key

返回值

any

key 对应的本地存储内容

示例代码

ft.getStorage({
  key: 'key',
  success(res) {
    console.log(res.data)
  }
})

try {
  const value = ft.getStorageSync('key')
  if (value) {
    // Do something with return value
  }
} catch (e) {
  // Do something when catch error
}

getStorageInfoSync

getStorageInfoSync(Object object)

ft.getStorageInfo 的同步版本

返回值

Object object

属性	类型	说明
keys	Array.<string>	当前 storage 中所有的 key
currentSize	number	当前占用的空间大小, 单位 KB
limitSize	number	限制的空间大小，单位 KB

示例代码

ft.getStorageInfoSync({
  success(res) {
    console.log(res.keys)
    console.log(res.currentSize)
    console.log(res.limitSize)
  }
})

try {
  const res = ft.getStorageInfoSync()
  console.log(res.keys)
  console.log(res.currentSize)
  console.log(res.limitSize)
} catch (e) {
  // Do something when catch error
}

getStorageInfo

getStorageInfo(Object object)

获取当前storage的相关信息。

参数

Object object

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

object.success 回调函数

参数

Object res

属性	类型	说明
keys	Array.<string>	当前 storage 中所有的 key
currentSize	number	当前占用的空间大小, 单位 KB
limitSize	number	限制的空间大小，单位 KB

示例代码

ft.getStorageInfo({
  success(res) {
    console.log(res.keys)
    console.log(res.currentSize)
    console.log(res.limitSize)
  }
})

try {
  const res = ft.getStorageInfoSync()
  console.log(res.keys)
  console.log(res.currentSize)
  console.log(res.limitSize)
} catch (e) {
  // Do something when catch error
}

getStorage

getStorage(Object object)

从本地缓存中获取指定key对应的内容。

参数

Object object

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

object.success 回调函数

参数

Object res

属性	类型	说明
data	any	key对应的内容

示例代码

ft.getStorage({
  key: 'key',
  success(res) {
    console.log(res.data)
  }
})

try {
  const value = ft.getStorageSync('key')
  if (value) {
    // Do something with return value
  }
} catch (e) {
  // Do something when catch error
}

clearStorageSync

clearStorageSync(Object object)

ft.clearStorage 的同步版本

示例代码

ft.clearStorage()

try {
  ft.clearStorageSync()
} catch (e) {
  // Do something when catch error
}

clearStorage

clearStorage(Object object)

清理本地数据缓存

参数

Object object

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

示例代码

ft.clearStorage()

try {
  ft.clearStorageSync()
} catch (e) {
  // Do something when catch error
}

batchSetStorageSync

基础库 3.0.49 起支持

batchSetStorageSync(Array kvList)

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

参数

Object object

属性	类型	默认值	必填	说明
kvList	Array		是	key value 数组: [{ key, value }]，本地缓存中指定的 keyList

示例代码

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

batchSetStorage

基础库 3.0.49 起支持

batchSetStorage(Object object)

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

参数

Object object

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

示例代码

wx.batchSetStorage({
  kvList: [{
    key: 'key',
    value: 'value',
  }],
})

batchGetStorageSync

基础库 3.0.49 起支持

batchGetStorageSync(Array keyList)

ft.batchGetStorage 的同步版本

参数

Object object

属性	类型	默认值	必填	说明
keyList	Array		是	key value 数组: [{ key, value }]

示例代码

try {
  var valueList = ft.batchGetStorageSync(['key'])
} catch (e) {
}

batchGetStorage

基础库 3.0.49 起支持

batchGetStorage(Object object)

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

参数

Object object

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

示例代码

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

数据预拉取和周期性更新

注意

该功能开启需要在管理后台配置，入口为【我的小程序】-【详情】-【其他】，开启数据周期性更新或数据预拉取。

更多可参考数据预拉取和周期性更新使用指南

setBackgroundFetchToken

基础库 3.2.1 起支持，SDK 2.43.1 起支持

setBackgroundFetchToken(Object object)

设置自定义登录 token，token 会在周期性拉取数据时带上，用于开发者的第三方服务器验证请求的合法性。

参数

Object object

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

示例代码

ft.setBackgroundFetchToken({
  token: 'some token'
})

getBackgroundFetchToken

基础库 3.2.1 起支持，SDK 2.43.1 起支持

getBackgroundFetchToken(Object object)

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

参数

Object object

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

参数

Object object

属性	类型	说明
token	string	自定义的请求 token
errMsg	string	接口调用结果

示例代码

ft.getBackgroundFetchToken({
  success(res) {
    console.log(res.token)
  }
})

getBackgroundFetchData

基础库 3.2.1 起支持，SDK 2.43.1 起支持

getBackgroundFetchData(Object object)

拉取客户端缓存的周期性更新和数据预拉取数据。

当调用接口时，若当次请求未结束，会先返回本地的旧数据（之前打开小程序时请求的）。

如果本地没有旧数据，两端不会等待请求完成。安卓上会返回 fail；iOS上会返回 success 但 fetchedData 为空。

参数

Object object

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

object.success 回调函数

参数

Object object

属性	类型	说明
fetchedData	string	缓存数据
timeStamp	number	客户端拿到缓存数据的时间戳，单位 ms
path	string	小程序页面路径
query	string	传给页面的 query 参数
scene	number	进入小程序的场景值

示例代码

ft.getBackgroundFetchToken({
  success(res) {
    console.log(res.token)
  }
})

onBackgroundFetchData

基础库 3.2.1 起支持，SDK 2.43.1 起支持

onBackgroundFetchData(function callback)

监听收到周期性更新和数据预拉取的事件，如果监听时请求已经完成，则事件不会触发，建议和 ft.getBackgroundFetchData 配合使用。

参数

function callback

收到周期性更新和数据预拉取数据事件的监听函数

参数

Object res

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

示例代码

ft.onBackgroundFetchData(function (res) {
  console.log(res.fetchType)
  console.log(res.fetchedData)
  console.log(res.timeStamp)
  console.log(res.path)
  console.log(res.query)
  console.log(res.scene)
})

缓存管理器

ft.createCacheManager

创建缓存管理器

参数

Object object

属性	类型	默认值	必填	说明
origin	string		否	全局 origin
mode	string	weakNetwork	否	缓存模式 可选值：weakNetwork,always,none
maxAge	number		否	全局缓存有效时间，单位为毫秒，默认为 7 天，最长不超过 30 天
extra	object		否	额外的缓存处理

extra

结构属性	类型	默认值	必填	说明
apiList	Array		否	需要缓存的 wx api 接口，不传则表示支持缓存的接口全都做缓存处理。返回的如果是缓存数据，开发者可通过 fromCache 标记区分. 可选值：wx.login,wx.checkSession ,wx.getSetting

返回值

CacheManager

缓存管理器

示例代码

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

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

CacheManager

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

在网络通畅时，符合一定规则的用户网络请求（目前只包括普通 wx.request 请求）会被缓存。 在网络通畅时，某些 wx api 调用会被缓存。 进入弱网/离线状态时，会提供事件给用户，用户可以决定是否使用缓存返回。 提供进入和退出弱网/离线状态的事件。

CacheManager.addRule

添加规则。

参数 Object rule

规则

返回值

string

规则 id

规则说明

支持的规则写法有字符串、正则和对象三种：

字符串写法

• addRule('/abc')：纯 uri 串。
• `addRule('GET /abc')：带方法的 uri 串，除了匹配 uri 外，还会匹配请求方法。如例子中必须是 GET 方法请求才会被匹配。
• addRule('/abc/:id')：带可变部分的 uri 串，id 可以是任意符合标准的字符串，表示这一段可以动态变化。比如/abc/123和/abc/321都会被匹配，而/abc/123/xxx` 因为多了一段，就不会被匹配。
• addRule('/abc?aa')：带 query 参数的 uri 串，包含 aa 参数，值可以为任意值。比如/abc?aa=haha会被匹配，但是/abc就不会被匹配，因为缺少规则中声明的 aa 参数；不过如果请求是/abc?aa=haha&bb=123`，虽然多带了 bb 参数，但是因为包含了 aa 参数，所以也可以被匹配。
• addRule('/abc?dd=haha')：带 query 参数的 uri 串，包含 dd 参数且值为 haha。比如/abc?dd=haha和/abc?dd=haha&bb=123会被匹配，而/abc?dd=123` 就不会被匹配，因为规则要求了 dd 参数的值。

以上写法中的 uri 串如果只有 path 部分，则会取全局 origin 进行补全。比如全局 origin 是 https://weixin.qq.com，而规则是 /abc，则会补全为 https://weixin.qq.com/abc。因此在前面例子中 addRule('/abc') 和 addRule('https://weixin.qq.com/abc') 的写法效果一致。所以一般情况下如果需要匹配的请求 origin 和全局 origin 一致，则规则中可忽略不写 orign。

正则写法

• addRule(//(abc|cba)$/ig)：直接正则匹配请求的 uri，同时会比对请求 origin 和全局 origin 是否一致。
• addRule(/^https://weixin.qq.com/(abc|cba)$/ig)：带有 orign 部分的正则表达式，则只匹配 uri，不再比对 origin。

对象写法

使用规则对象，可以更为详细的描述规则内容。（一般使用规则对象，是为了匹配请求参数）

规则对象：

属性名	类型	默认值	备注
id	string		规则 id，如果不填则会由基础库生成
method	string		请求方法，可选值 GET/POST/PATCH/PUT/DELETE，如果为空则表示前面提到的所有方法都能被匹配到
url	any	必填	uri 匹配规则，可参考规则字符串写法和正则写法
maxAge	number	7 * 24 * 60 * 60 * 1000	缓存有效时间，单位为 ms，不填则默认取缓存管理器全局的缓存有效时间
dataSchema	Array<DataRule>		匹配请求参数

其中，dataSchema 用来匹配对象类型的请求参数（比如 wx.request 的 data），默认可以不填，即不做参数匹配。

dataSchema 的类型是一个 DataRule 对象数组，一个 DataRule 对象描述一个参数，比如一个 wx.request 请求的 data 是 {a: 123, b: 'haha', c: true}，你想要用一条规则来匹配其中的 a 和 b 参数，如果 a 是数字且 b 是字符串就能命中该规则，那么就需要在 dataSchema 中补充两个 DataRule 对象，即 [{name: 'a', schema: {type: 'number'}}, {name: 'b', schema: {type: 'string'}}]。

DataRule 对象：

属性名	类型	默认值	备注
name	string		需要匹配的参数名
schema	DataSchema/Array<DataSchema>		需要匹配的参数模式，支持数组，表示该参数值有多种模式

name 表示要匹配的参数名，schema 为 DataSchema 对象，用来描述该参数的类型和值。

一个 DataRule 对象也可以匹配可能拥有多种类型的参数，所以 schema 也支持为 DataSchema 对象数组。比如上述例子中，希望匹配的 a 参数必须是数值或者字符串，那么可以这么写：{name: 'a', schema: [{type: 'number'}, {type: 'string'}]}。

DataSchema 对象：

属性名	类型	默认值	备注
type	string		需要匹配的 data 对象的参数类型，支持 string、number、boolean、null、object、any（表示任意类型），同时支持数组模式（数组模式则在类型后面加 []，如 string[] 表示字符串数组）
value	string/regexp/function/Array<DataRule>		需要匹配的 data 对象的参数值，当 type 为基本类型时，可以用 string/regexp 来匹配固定的值，也可以通过 function 来确定值是否匹配，如果传入的 type 是 object，那么表示需要嵌套匹配值是否正确，可以传入 Array

补充说明 用户可以添加多条规则，每条规则都会去解析网络请求，然后判断是否命中规则。假设有多条规则命中，则取第一条命中的规则。

type 参数表示要匹配的参数类型，value 表示要匹配的参数值。其中 value 支持多种写法，不同写法有如下匹配方式：

• 字符串写法：直接判值的字符串形式是否和给定字符串一样，比如 value 值为 123，就要求参数值必须为 123 才能与之匹配。
• 正则写法：直接判值的字符串形式是否能被正则匹配，比如 value 值为 /\d+/ig，就要求参数值必须为数字，如果参数值为 abc 则不会被匹配。
• 函数写法：在匹配时会调用用户传入的函数，交由用户判断是否匹配。
• DataRule 数组写法：当参数类型为对象时，那么字符串写法和正则写法就无法使用，需要传入 DataRule 数组来进行匹配，即通过嵌套 DataRule 数组的方式来匹配嵌套的对象。

示例代码

const ruleId = cacheManager.addRule({
  id: 'haha-rule',
  method: 'GET',
  url: '/haha',
  maxAge: 123455,
  dataSchema: [
    // data 字段的匹配，默认为空，表示不匹配
    // 类型可以是：string、number、boolean、null、object、any（表示任意类型均可），以及这些类型的数组表示方式
    {name: 'aaa', schema: {type: 'string'}}, // 类型为 string
    {name: 'bbb', schema: [{type: 'number'}, {type: 'string'}]}, // 类型为 number, string
    {name: 'ccc', schema: {type: 'string', value: 'abc'}}, // 值为 abc
    {name: 'ddd', schema: {type: 'string', value: /(abc|cba)/ig}}, // 值符合该正则匹配，如果该值不是字符串类型，则会被尝试转成字符串后再进行比较
    {name: 'ddd', schema: {type: 'string', value: val => val === '123'}}, // 传入函数来校验值
    {name: 'eee', schema: {type: 'object', value: [{ // 类型为对象，则通过嵌套的方式来逐层校验
      name: 'aaa', schema: {type: 'string'},
      // ...
      // 嵌套 dataSchema，同上面的方式一样来匹配嵌套的对象
    }]}},
    {name: 'fff', schema: {type: 'string[]'}}, // 类型为 string 数组
    {name: 'ggg', schema: {type: 'any'}}, // 类型为任意类型
    {name: 'hhh', schema: {type: 'any[]'}}, // 类型为任意类型的数组
  }],
})

CacheManager.addRules

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

参数 Object rules

规则列表

返回值 Array

规则 id 列表

CacheManager.clearCaches

清空所有缓存。

CacheManager.clearRules

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

CacheManager.deleteCache

删除缓存。

参数 string id

缓存 id

CacheManager.deleteCaches

批量删除缓存。

参数 Array

缓存 id 列表

CacheManager.deleteRule

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

参数 string id

规则 id

CacheManager.deleteRules

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

参数 Array ids

规则 id 列表

CacheManager.match

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

参数 Object evt

request 事件对象

返回值 Object

匹配到的缓存

属性	类型	说明
ruleId	string	命中的规则 id
cacheId	string	缓存 id
data	any	缓存内容，会带有 fromCache 标记，方便开发者区分内容是否来自缓存
createTime	number	缓存创建时间
maxAge	number	缓存有效时间

示例代码

function handler(evt) {
  const cache = cacheManager.match(evt)
  // 若有重复监听，则取第一个 handler 返回的 promise
  return new Promise((resolve, reject) => {
    if (cache.data) {
      resolve(cache.data)
    } else {
      reject('no cache')
    }
  })
}
cacheManager.on('request', handler)

CacheManager.off

取消事件监听。

参数 string eventName

事件名

function handler

事件句柄

CacheManager.on

监听事件。

参数 string eventName

事件名

eventName 的合法值

值	说明	最低版本
request	发生 wx.request 请求，只在缓存管理器开启阶段会触发
enterWeakNetwork	进入弱网/离线状态
exitWeakNetwork	离开弱网/离线状态

function handler

事件句柄

这里 request 事件会提供 request 事件对象，用于做后续的处理；在 request 事件中需要返回一个 promise，用来生成 wx.request 请求的返回内容。

示例代码

async function handler(evt) {
  // evt.url - 请求 url
  // evt.data - 请求参数
  // evt.method - 请求方法
  // evt.request - 原始 request 方法，返回一个 promise

  // if (evt.url === '/xxx') {
  //   // 如果有些请求仍然希望走到网络，则可以如下处理
  //   const res = await evt.request()
  //   // res 即为网络请求返回
  // }

  return new Promsie((resolve, reject) => {
    // do sth
    if (data) {
      // 这里 resolve 的 data 就会作为 wx.request 的 success 回调结果返回
      resolve(data)
    } else {
      // 这里 reject 的错误信息就会作为 wx.request 的 fail 回调结果返回
      reject('no data')
    }
  })
}
cacheManager.on('request', handler)

CacheManager.start

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

CacheManager.stop

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