key-value本地数据存储

展示全部

# key-value本地数据存储

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

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

H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理
App端为原生storage，无大小限制，不是缓存，是持久化的
各个小程序端为其自带的storage api，数据存储生命周期跟小程序本身一致，即除用户主动删除或超过一定时间被自动清理，否则数据都一直可用。
- 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。
- 支付宝小程序单条数据转换成字符串后，字符串长度最大200*1024。同一个支付宝用户，同一个小程序缓存总上限为10MB。
- 百度小程序策略详见
- 抖音小程序策略详见
- Android 端采用应用内SQLIte数据库储存，每个基座对应一个数据库文件，储存位置为：/data/data/io.dcloud.uniappx(基座包名)/databases/DCStorage,同基座内的不同应用，以表名区分。

注意

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

# uni.setStorage(options)

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

# setStorage 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

options

SetStorageOptions

是

名称	类型	必备	默认值	兼容性	描述
key	string	是	-	-	本地存储中的指定的 key
data	any	是	-	-	需要存储的内容，只支持能通过 JSON.stringify 序列化的对象
success	(res: SetStorageSuccess) => void	否	-	-	uni.setStorage成功回调函数定义
fail	(res: UniError) => void	否	-	-	uni.setStorage失败回调函数定义
complete	(res: any) => void	否	-	-	uni.setStorage完成回调函数定义

# 参见

# uni.setStorageSync(key, data)

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

# setStorageSync 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称	类型	必填	默认值	兼容性	描述
key	string	是	-	-	本地storage存储中的指定的 key
data	any	是	-	-	需要存储的内容，只支持能通过 JSON.stringify 序列化的对象

WARNING

参数 data 为对象字面量时，需要通过 as UTSJSONObject 明确类型，例如：

uni.setStorageSync('obj', {"a": 1} as UTSJSONObject)

# 参见

# uni.getStorage(options)

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

# getStorage 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

options

GetStorageOptions

是

名称	类型	必备	默认值	兼容性	描述
key	string	是	-	-	本地存储中的指定的 key
success	(res: GetStorageSuccess) => void	否	-	-	uni.getStorage成功回调函数定义
fail	(res: UniError) => void	否	-	-	uni.getStorage失败回调函数定义
complete	(res: any) => void	否	-	-	uni.getStorage完成回调函数定义

# GetStorageSuccess 的属性值

名称	类型	必备	默认值	兼容性	描述
data	any	否	-	-	key 对应的内容

# 参见

注意：获取一个不存在的 key 会触发 fail 回调，返回错误信息为 "getStorage:fail data not found" 的错误。

# uni.getStorageSync(key)

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

# getStorageSync 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称	类型	必填	默认值	兼容性	描述
key	string	是	-	-	本地存储中的指定的 key

# 返回值

类型	必备
any	否

# 参见

注意：同步方法获取一个不存在的 key 会返回空字符串，而不是 null

# uni.getStorageInfo(options)

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

# getStorageInfo 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

options

GetStorageInfoOptions

是

名称

类型

必备

默认值

兼容性

描述

success

(res: GetStorageInfoSuccess) => void

否

uni.getStorageInfo成功回调函数定义

fail

(res: UniError) => void

否

uni.getStorageInfo失败回调函数定义

complete

(res: any) => void

否

uni.getStorageInfo完成回调函数定义

# GetStorageInfoSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

keys

Array<string>

是

当前 storage 中所有的 key

currentSize

number

是

当前占用的空间大小, 单位：kb

limitSize

number

是

限制的空间大小, 单位：kb

# 参见

# uni.getStorageInfoSync()

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

# getStorageInfoSync 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 返回值

类型

描述

GetStorageInfoSuccess

uni.getStorageInfo成功回调参数

名称

类型

必备

默认值

兼容性

描述

keys

Array<string>

是

当前 storage 中所有的 key

currentSize

number

是

当前占用的空间大小, 单位：kb

limitSize

number

是

限制的空间大小, 单位：kb

# 参见

# uni.removeStorage(options)

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

# removeStorage 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

options

RemoveStorageOptions

是

名称

类型

必备

默认值

兼容性

描述

key

string

是

本地存储中的指定的 key

success

(res: RemoveStorageSuccess) => void

否

uni.removeStorage成功回调函数定义

fail

(res: UniError) => void

否

uni.removeStorage失败回调函数定义

complete

(res: any) => void

否

uni.removeStorage完成回调函数定义

# 参见

# uni.removeStorageSync(key)

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

# removeStorageSync 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称	类型	必填	默认值	兼容性	描述
key	string	是	-	-	本地存储中的指定的 key

# 参见

# uni.clearStorage(option?)

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

# clearStorage 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

option

ClearStorageOptions

否

uni.removeStorage参数定义

名称

类型

必备

默认值

兼容性

描述

success

(res: ClearStorageSuccess) => void

否

uni.clearStorage 成功回调函数定义

fail

(res: UniError) => void

否

uni.clearStorage 失败回调函数定义

complete

(res: any) => void

否

uni.clearStorage 完成回调函数定义

# 参见

# uni.clearStorageSync()

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

# clearStorageSync 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9.0	4.11

# 参见

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #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" maxlength="-1"
                @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="typeof data === 'string' ? data : JSON.stringify(data)" maxlength="-1" @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:50%" @tap="strMock">
              填充字符串
            </button>
            <button type="default" style="width:50%" @tap="complexMock">
              填充复杂对象
            </button>
          </view>
          <view class="uni-flex uni-row">
            <button type="default" style="width:50%" @tap="numberMock">
              填充整型
            </button>
            <button type="default" style="width:50%" @tap="floatMock">
              填充浮点型
            </button>
          </view>
          <view class="uni-flex uni-row">
            <button type="default" style="width:50%" @tap="jsonLikeMock">
              填充json字符串
            </button>
            <button type="default" style="width:50%" @tap="longLikeMock">
              填充整数字符串
            </button>
          </view>
          <view class="uni-flex uni-row">
            <button type="default" style="width:50%" @tap="floatLikeMock">
              填充浮点字符串
            </button>
            <button type="default" style="width:50%" @tap="negativeLikeMock">
              填充负数字符串
            </button>
          </view>
          <view class="uni-flex uni-row">
            <button type="default" class="uni-btn btn-complexStaticTest" style="width:100%" @tap="complexStaticTest">
              字面量读写测试
            </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>



<style>
</style>

# 通用类型

# GeneralCallbackResult

名称

类型

必备

默认值

兼容性

描述

errMsg

string

是

错误信息

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001