key-value本地数据存储

app、小程序、web，均提供了方便的key-value模式的本地数据存储，通过键值对的方式存取数据。

uni-app的Storage在不同端的实现不同：

• H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理
• App端为原生storage，无大小限制，不是缓存，是持久化的
• 各个小程序端为其自带的storage api，数据存储生命周期跟小程序本身一致，即除用户主动删除或超过一定时间被自动清理，否则数据都一直可用。
  • 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。
  • 支付宝小程序单条数据转换成字符串后，字符串长度最大200*1024。同一个支付宝用户，同一个小程序缓存总上限为10MB。
  • 百度小程序策略详见
  • 抖音小程序策略详见

注意

• uni-、uni_、dcloud-、dcloud_为前缀的key，为系统保留关键前缀。如uni_deviceId、uni_id_token，请开发者为key命名时避开这些前缀。
• 非App平台清空Storage会导致uni.getSystemInfo获取到的deviceId改变

uni.setStorage(options)

uni.setStorage函数定义 将数据存储在本地storage存储中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口。

Parameters

name	type	required	default	description
options	SetStorageOptions	YES	-	uni.setStorage参数定义

SetStorageOptions Values

name	type	optinal	default	description
key	string	YES	-	本地存储中的指定的 key
data	any	YES	-	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象
success	(res: SetStorageSuccess) => void	NO	-	接口调用成功的回调函数
fail	(res: UniError) => void	NO	-	接口调用失败的回调函数
complete	(res: any) => void	NO	-	接口调用结束的回调函数（调用成功、失败都会执行）

setStorage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

setStorage

Related Bug

uni.setStorageSync(key, data)

uni.setStorageSync函数定义 将 data 存储在本地storage存储中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

Parameters

name	type	required	default	description
key	string	YES	-	本地storage存储中的指定的 key
data	any	YES	-	需要存储的内容，只支持原生类型、及能够通过 JSON.stringify 序列化的对象

setStorageSync Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

setStorageSync

Related Bug

uni.getStorage(options)

uni.getStorage函数定义 从本地存储中异步获取指定 key 对应的内容。

Parameters

name	type	required	default	description
options	GetStorageOptions	YES	-	uni.getStorage参数定义

GetStorageOptions Values

name	type	optinal	default	description
key	string	YES	-	本地存储中的指定的 key
success	(res: GetStorageSuccess) => void	NO	-	接口调用成功的回调函数
fail	(res: UniError) => void	NO	-	接口调用失败的回调函数
complete	(res: any) => void	NO	-	接口调用结束的回调函数（调用成功、失败都会执行）

GetStorageSuccess Values

name	type	optinal	default	description
data	any	NO	-	key 对应的内容

getStorage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

getStorage

Related Bug

uni.getStorageSync(key)

uni.getStorageSync函数定义 从本地存储中同步获取指定 key 对应的内容。

Parameters

name	type	required	default	description
key	string	YES	-	本地存储中的指定的 key

Return value

Type	optinal
any	NO

getStorageSync Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

getStorageSync

Related Bug

uni.getStorageInfo(options)

uni.getStorageInfo函数定义 异步获取当前 storage 的相关信息。

Parameters

name	type	required	default	description
options	GetStorageInfoOptions	YES	-	uni.getStorageInfo参数定义

GetStorageInfoOptions Values

name	type	optinal	default	description
success	(res: GetStorageInfoSuccess) => void	NO	-	接口调用成功的回调函数
fail	(res: UniError) => void	NO	-	接口调用失败的回调函数
complete	(res: any) => void	NO	-	接口调用结束的回调函数（调用成功、失败都会执行）

GetStorageInfoSuccess Values

name	type	optinal	default	description
keys	Array<string>	YES	-	当前 storage 中所有的 key
currentSize	number	YES	-	当前占用的空间大小, 单位：kb
limitSize	number	YES	-	限制的空间大小, 单位：kb

getStorageInfo Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

getStorageInfo

Related Bug

uni.getStorageInfoSync()

uni.getStorageInfoSync函数定义 同步获取当前 storage 的相关信息。

Return value

Type
GetStorageInfoSuccess

GetStorageInfoSuccess Values

name	type	optinal	default	description
keys	Array<string>	YES	-	当前 storage 中所有的 key
currentSize	number	YES	-	当前占用的空间大小, 单位：kb
limitSize	number	YES	-	限制的空间大小, 单位：kb

getStorageInfoSync Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

getStorageInfoSync

Related Bug

uni.removeStorage(options)

uni.removeStorage函数定义 从本地存储中异步移除指定 key。

Parameters

name	type	required	default	description
options	RemoveStorageOptions	YES	-	uni.removeStorage参数定义

RemoveStorageOptions Values

name	type	optinal	default	description
key	string	YES	-	本地存储中的指定的 key
success	(res: RemoveStorageSuccess) => void	NO	-	接口调用的回调函数
fail	(res: UniError) => void	NO	-	接口调用失败的回调函数
complete	(res: any) => void	NO	-	接口调用结束的回调函数（调用成功、失败都会执行）

removeStorage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

removeStorage

Related Bug

uni.removeStorageSync(key)

uni.removeStorageSync函数定义 从本地存储中同步移除指定 key。

Parameters

name	type	required	default	description
key	string	YES	-	本地存储中的指定的 key

removeStorageSync Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

removeStorageSync

Related Bug

uni.clearStorage(option?)

uni.clearStorage函数定义 清除本地数据存储。

Parameters

name	type	required	default	description
option	ClearStorageOptions	NO	-	-

ClearStorageOptions Values

name	type	optinal	default	description
success	(res: ClearStorageSuccess) => void	NO	-	接口调用的回调函数
fail	(res: UniError) => void	NO	-	接口调用失败的回调函数
complete	(res: any) => void	NO	-	接口调用结束的回调函数（调用成功、失败都会执行）

clearStorage Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

clearStorage

Related Bug

uni.clearStorageSync()

uni.clearStorageSync函数定义 清除本地数据存储。

clearStorageSync Compatibility

Android version	Android uni-app	Android uni-app-x	iOS version	iOS uni-app	iOS uni-app-x
4.4.4	2.0.3	3.9.0	9.0	2.0.3	3.9.0

See also

clearStorageSync

Related Bug

Example

hello uni-app x

<template>
 <!-- #ifdef APP -->
 <scroll-view style="flex: 1">
   <!-- #endif -->
   <view>
     <page-head :title="title"></page-head>
     <view class="uni-common-mt">
       <view class="uni-list">
         <view class="uni-list-cell uni-list-cell-line">
           <view class="uni-list-cell-left">
             <view class="uni-label">key</view>
           </view>
           <view class="uni-list-cell-db">
             <input
               class="uni-input"
               type="text"
               placeholder="请输入key"
               name="key"
               :value="key"
               @input="keyChange"
             />
           </view>
         </view>
         <view class="uni-list-cell">
           <view class="uni-list-cell-left">
             <view class="uni-label">value</view>
           </view>
           <view class="uni-list-cell-db">
             <input
               class="uni-input"
               type="text"
               placeholder="请输入value"
               name="data"
               :value="data"
               @input="dataChange"
             />
           </view>
         </view>
       </view>
       <view class="uni-padding-wrap">
         <view class="uni-btn-v">
           <button class="uni-btn btn-getStorageInfoASync" type="primary" @tap="getStorageInfo">
             获取存储概述-异步
           </button>
           <button class="uni-btn btn-getStorageInfoSync" @tap="getStorageInfoSync">
             获取存储概述-同步
           </button>
         </view>
         <text>{{ storageInfo }}</text>
         <view class="uni-flex uni-row">
           <button
             type="default"
             style="width:325rpx"
             @tap="strMock"
           >
             填充字符串
           </button>
           <button
             type="default"
             style="width:325rpx"
             @tap="complexMock"
           >
             填充复杂对象
           </button>
         </view>
         <view class="uni-flex uni-row">
           <button
             type="default"
             style="width:325rpx"
             @tap="numberMock"
           >
             填充整型
           </button>
           <button
             type="default"
             style="width:325rpx"
             @tap="floatMock"
           >
             填充浮点型
           </button>
         </view>
       </view>
       <view class="uni-padding-wrap">
         <view class="uni-btn-v">
           <button
             type="primary"
             class="uni-btn btn-setstorageAsync"
             @tap="setStorage"
           >
             存储数据-异步
           </button>
           <button class="uni-btn btn-getstorageAsync" @tap="getStorage">读取数据-异步</button>
           <button class="uni-btn btn-removeStorageInfoASync" @tap="removeStorage">移除数据-异步</button>
           <button class="uni-btn btn-clearStorageInfoASync" @tap="clearStorage">清理数据-异步</button>
         </view>

         <view class="uni-btn-v">
           <button
             type="primary"
             class="uni-btn btn-setstorageSync"
             @tap="setStorageSync"
           >
             存储数据-同步
           </button>
           <button class="uni-btn btn-getstorageSync" @tap="getStorageSync">读取数据-同步</button>
           <button class="uni-btn btn-removeStorageInfoSync" @tap="removeStorageSync">
             移除数据-同步
           </button>
           <button class="uni-btn btn-clearStorageInfoSync" @tap="clearStorageSync">
             清理数据-同步
           </button>
         </view>
       </view>
     </view>
   </view>
   <!-- #ifdef APP -->
 </scroll-view>
 <!-- #endif -->
</template>
<script lang="uts">
export default {
 data() {
   return {
     title: 'get/set/clearStorage',
     key: '',
     data: '' as any,
     apiGetData:'' as any|null,
     storageInfo: '',
   }
 },
 methods: {
   getStorageInfo() {
     uni.getStorageInfo({
       success: (res) => {
         this.apiGetData = res
         this.storageInfo = JSON.stringify(res)
       },
     })
   },
   getStorageInfoSync() {
     try {
       const res = uni.getStorageInfoSync()
       this.apiGetData = res
       this.storageInfo = JSON.stringify(res)
     } catch (e) {
       // error
       console.log(e)
     }
   },
   strMock() {
     this.key = 'key_' + Math.random()
     this.data = '测试字符串数据，长度为16个字符'
   },
   complexMock() {
     this.key = 'key_' + Math.random()
     let jsonObj = {
       name: '张三',
       age: 12,
       classMate: [
         {
           id: 1001,
           name: '李四',
         },
         {
           id: 1002,
           name: 'jack ma',
         },
       ],
     }
     this.data = jsonObj
   },
   numberMock() {
     this.key = 'key_' + Math.random()
     this.data = 10011
   },
   floatMock() {
     this.key = 'key_' + Math.random()
     this.data = 3.1415926535893384626
   },

   keyChange: function (e: InputEvent) {
     this.key = e.detail.value
   },
   dataChange: function (e: InputEvent) {
     this.data = e.detail.value
   },
   getStorage: function () {
     var key = this.key
     if (key.length == 0) {
       uni.showModal({
         title: '读取数据失败',
         content: 'key 不能为空',
         showCancel: false,
       })
     } else {
       let that = this
       uni.getStorage({
         key: key,
         success: (res) => {
           that.apiGetData = res.data

           let desc:string = typeof this.apiGetData
           if("object" == desc){
             desc = desc  + ": " + JSON.stringify(this.apiGetData)
           }else{
             desc = desc  + ": " + this.apiGetData
           }

           uni.showModal({
             title: '读取数据成功',
             content: desc,
             showCancel: false,
           })
         },
         fail: () => {
           uni.showModal({
             title: '读取数据失败',
             content: '找不到 key 对应的数据',
             showCancel: false,
           })
         },
       })
     }
   },
   getStorageSync: function () {
     var key = this.key
     if (key.length == 0) {
       uni.showModal({
         title: '读取数据失败',
         content: 'key 不能为空',
         showCancel: false,
       })
     } else {
       this.apiGetData = uni.getStorageSync(key)

       let desc:string = typeof this.apiGetData
       if("object" == desc){
         desc = desc  + ": " + JSON.stringify(this.apiGetData)
       }else{
         desc = desc  + ": " + this.apiGetData
       }

       uni.showModal({
         title: '读取数据成功',
         content:  desc,
         showCancel: false,
       })
     }
   },
   setStorage: function () {
     var key = this.key
     var data = this.data
     if (key.length == 0) {
       uni.showModal({
         title: '保存数据失败',
         content: 'key 不能为空',
         showCancel: false,
       })
     } else {
       uni.setStorage({
         key: key,
         data: data,
         success: () => {
           uni.showModal({
             title: '存储数据成功',
             showCancel: false,
           })
         },
         fail: () => {
           uni.showModal({
             title: '储存数据失败!',
             showCancel: false,
           })
         },
       })
     }
   },
   setStorageSync: function () {
     var key = this.key
     var data = this.data
     if (key.length == 0) {
       uni.showModal({
         title: '保存数据失败',
         content: 'key 不能为空',
         showCancel: false,
       })
     } else {
       uni.setStorageSync(key, data)
       uni.showModal({
         title: '存储数据成功',
         showCancel: false,
       })
     }
   },
   removeStorage: function () {
     uni.removeStorage({
       key: this.key,
       success: () => {
         uni.showModal({
           title: '移除数据成功',
           showCancel: false,
         })
       },
       fail: () => {
         uni.showModal({
           title: '移除数据失败',
           showCancel: false,
         })
       },
     })
   },
   removeStorageSync: function () {
     uni.removeStorageSync(this.key)
     uni.showModal({
       title: '移除数据成功',
       showCancel: false,
     })
   },
   clearStorage: function () {
     this.key = ''
     this.data = ''
     uni.clearStorage({
       success: function (_) {
         uni.showModal({
           title: '清除数据成功',
           showCancel: false,
         })
       },
       fail: function (_) {
         uni.showModal({
           title: '清除数据失败',
           showCancel: false,
         })
       },
     })
   },
   clearStorageSync: function () {
     this.key = ''
     this.data = ''
     uni.clearStorageSync()
     uni.showModal({
       title: '清除数据成功',
       content: ' ',
       showCancel: false,
     })
   },
 },
}
</script>

<style>
.btn-setstorage {
 background-color: #007aff;
 color: #ffffff;
}

.button-sp-area {
 flex-direction: row;
 margin: 0 auto;
}
</style>

General type

GeneralCallbackResult

name	type	optinal	default	description
errMsg	string	YES	-	错误信息