react-native-mmkv
react-native-mmkv
开放Beta测试文档 作为预发布开放Beta测试的一项内容,亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代,所描述的这些功能可能会发生变化。有关最新功能的信息,请参阅发行说明。
MMKV是由微信开发的高效、小型移动键值存储框架。@amazon-devices/react-native-mmkv是一个库,它让您可以快速直接地将JS绑定到原生C++库,在React Native应用中轻松使用MMKV。有关更多信息,请参见Tencent/MMKV(仅提供英文版)。
安装
- 在
package.json文件中添加依赖项:"dependencies": { ... "@amazon-devices/react-native-mmkv": "~1.0.0", ... } - 使用
npm install命令重新安装依赖项。
示例
为随机键值对创建简单存储的示例。
import React, { useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import { MMKV, useMMKVString, useMMKVNumber, useMMKVBoolean } from '@amazon-devices/react-native-mmkv';
const storage = new MMKV();
export const App = () => {
const [hookUsername, setHookUsername] = useMMKVString('hookUsername');
const [hookAge, setHookAge] = useMMKVNumber('hookAge');
const [hookIsLoggedIn, setHookIsLoggedIn] = useMMKVBoolean('hookIsLoggedIn');
const [status, setStatus] = useState<string>("");
const handleSetData = () => {
storage.set('username', 'JohnDoe');
storage.set('isLoggedIn', true);
storage.set('age', 30);
setStatus('已存储username、isLoggedIn和age');
};
const handleGetStringData = () => {
const username = storage.getString('username');
setStatus(`从数据中检索到的用户名:${username || '无'}`);
};
const handleGetNumberData = () => {
const age = storage.getNumber('age');
setStatus(`从数据中检索到的年龄:${age}`);
};
const handleGetBooleanData = () => {
const isLoggedIn = storage.getBoolean('isLoggedIn');
setStatus(`从数据中检索到的登录状态:${isLoggedIn}`);
};
const handleCheckKey = () => {
const hasUsernameKey = storage.contains('username');
setStatus(`已存在用户名键:${hasUsernameKey}`);
};
const handleListKeys = () => {
const allKeys = storage.getAllKeys();
setStatus(`键:${allKeys.join(', ')}`);
};
const handleDeleteKey = () => {
storage.delete('username');
setStatus('已删除"username"键。');
};
const handleClearAll = () => {
storage.clearAll();
setStatus('所有数据已从存储中清除。');
};
const handleRecryptStorage = () => {
storage.recrypt('newEncryptionKey');
setStatus('存储的值已使用新键重新加密。');
};
const handleDisplaySize = () => {
setStatus(`存储大小:${storage.size} 字节`);
};
const handleHookSetData = () => {
setHookUsername('JaneDoe');
setHookIsLoggedIn(false);
setHookAge(25);
setStatus('已存储username、isLoggedIn和age');
};
const handleUseMMKVStringData = () => {
setStatus(`使用挂钩获取的用户名:${hookUsername || '无'}`);
};
const handleUseMMKVNumberData = () => {
setStatus(`使用挂钩获取的年龄:${hookAge}`);
};
const handleUseMMKVBooleanData = () => {
setStatus(`使用挂钩获取的登录状态:${hookIsLoggedIn}`);
};
return (
<View style={styles.container} testID="mmkv-app-container">
<Text style={styles.title}>React Native MMKV示例</Text>
<Text style={styles.title} testID="mmkv-status">状态: {status}</Text>
<Button title="设置数据" onPress={handleSetData} testID="mmkv-app-set-button" />
<Button title="获取字符串" onPress={handleGetStringData} testID="mmkv-app-get-string-button" />
<Button title="获取数值" onPress={handleGetNumberData} testID="mmkv-app-get-number-button" />
<Button title="获取布尔值" onPress={handleGetBooleanData} testID="mmkv-app-get-boolean-button"/>
<Button title="检查键是否存在" onPress={handleCheckKey} testID="mmkv-app-contains-button"/>
<Button title="列出所有键" onPress={handleListKeys} testID="mmkv-app-get-all-keys-button"/>
<Button title="删除'Username'键" onPress={handleDeleteKey} testID="mmkv-app-delete-key-button"/>
<Button title="清除所有数据" onPress={handleClearAll} testID="mmkv-app-clear-all-button"/>
<Button title="重新加密存储" onPress={handleRecryptStorage} testID="mmkv-app-recrypt-button"/>
<Button title="显示存储空间大小" onPress={handleDisplaySize} testID="mmkv-app-size-button"/>
<Button title="使用挂钩设置数据" onPress={handleHookSetData} testID="mmkv-app-hook-set-button"/>
<Button title="使用挂钩获取字符串数据" onPress={handleUseMMKVStringData} testID="mmkv-app-hook-get-string-button"/>
<Button title="使用挂钩获取数字数据" onPress={handleUseMMKVNumberData} testID="mmkv-app-hook-get-number-button"/>
<Button title="使用挂钩获取布尔数据" onPress={handleUseMMKVBooleanData} testID="mmkv-app-hook-get-boolean-button"/>
</View>
);
};
const styles = StyleSheet.create({
container: {
flexGrow: 1,
justifyContent: 'center',
alignItems: 'center',
padding: 20,
backgroundColor: '#fff',
},
title: {
fontSize: 20,
marginBottom: 20,
textAlign: 'center',
},
button: {
marginVertical: 10,
},
});
API参考
Vega上的MMKV库提供了Turbo模块,增加了对下面列出的方法的支持。
请查看以下专门文档页面(仅提供英文版),了解有关此库、API参考等更多信息:
原生MMKV
| 方法 | 描述 |
|---|---|
MMKV |
一个MMKV基本存储类 |
size |
获取当前存储空间的总大小,以字节为单位。 |
set |
为给定key设置一个值 |
getBoolean |
获取给定key的布尔值,如果不存在,则返回undefined。 |
getString |
获取给定key的字符串值,如果不存在,则返回undefined。 |
getNumber |
获取给定key的数字值,如果不存在,则返回undefined。 |
getBuffer |
获取无符号8位 (0-255) 数据的原始缓冲区。 |
contains |
检查给定key是否存储在此MMKV实例中。 |
delete |
删除给定的key。 |
getAllKeys |
获取所有键。 |
clearAll |
删除所有键。 |
recrypt |
设置(或更新)加密密钥以加密此MMKV实例中的所有数据。 |
trim |
缩减存储空间并清除内存缓存。 |
toString |
获取MMKV的字符串表示形式 |
toJSON |
获取MMKV的JSON表示形式 |
addOnValueChangedListener |
添加一个值已更改的侦听器。当此存储实例中的任何值发生变化(设置或删除)时,都会调用该侦听器。 |
挂钩
| 方法 | 描述 |
|---|---|
useMMKV |
使用默认的共享MMKV实例。 |
useMMKVString |
使用给定MMKV存储实例中给定key的字符串值。 |
useMMKVNumber |
使用给定MMKV存储实例中给定key的数字值。 |
useMMKVBoolean |
使用给定MMKV存储实例中给定key的布尔值。 |
useMMKVObject |
使用给定MMKV存储实例中给定key的对象值。 |
useMMKVListener |
侦听给定MMKV存储实例中的变化。 |
配置
| 方法 | 描述 |
|---|---|
id |
MMKV实例的ID。如果您想使用多个实例,请确保每个实例使用不同的ID。 |
path |
MMKV实例的根路径。 |
encryptionKey |
MMKV实例的加密/解密密钥。 |
mode |
配置MMKV的处理模式。 |
模式
| 方法 | 描述 |
|---|---|
SINGLE_PROCESS |
MMKV实例只能由单进程(此应用)使用。 |
MULTI_PROCESS |
MMKV实例可由多个进程使用,如应用片段、共享扩展或后台服务。 |
已知问题
- Vega虚拟设备不支持
recrypt方法 - 不支持
useMMKVBuffer挂钩
支持的react-native-kepler版本
| 程序包版本 | @amazon-devices/react-native-kepler版本 |
|---|---|
| 1.0.x+3.0.2 | 2.0.x+rn0.72.0 |
其他资源
有关其他库的信息,请参阅支持的第三方库和服务。
Last updated: 2025年9月30日

