@react-native-ohos/react-native-mmkv
v4.0.0
Published
⚡️ The fastest key/value storage for React Native.
Readme
文档模板：v0.4.1
本项目基于 react-native-mmkv 开发。
该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-mmkv 版本所属关系如下：
| 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 |
| ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- |
| @react-native-ohos/react-native-mmkv | ~ 0.4.0 | Gitcode Releases |0.82.* | 是 | API12+ | 4.3.1 | Npm Address |
| @react-native-ohos/react-native-mmkv | 3.3.1 | Gitcode Releases |0.72.* /0.77.* | 否 | API12+ | 3.3.0 | Npm Address |
简介
MMKV 是由微信开发的高效、轻量级移动键值存储框架。更多信息请参见 Tencent/MMKV。 react-native-mmkv 是一个能让您在 React Native 应用中轻松使用 MMKV 的库，它通过快速直接的 JS 绑定与原生 C++ 库交互。
下载安装
进入到工程目录并输入以下命令：
npm
npm install @react-native-ohos/react-native-mmkvyarn
yarn add @react-native-ohos/react-native-mmkvLink
本库 HarmonyOS 侧实现依赖@react-native-ohos/react-native-nitro-modules 的原生端代码，如已在 HarmonyOS 工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。
如未引入请参照@react-native-ohos/react-native-nitro-modules 文档的 Link 章节进行引入。
并且本库需要添加以下代码，autolink及手动配置都需要加：
打开 entry/src/main/cpp/PackageProvider.cpp，添加：
#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
using namespace rnoh;
+ #include "NitroMmkvAutolinking.hpp"
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
+ margelo::nitro::mmkv::registerNitroMmkvHybridObjects();
return {
std::make_shared<SamplePackage>(ctx),
};
}| | 是否支持autolink | RN框架版本 | |--------------------------------------|-----------------|------------| | ~ 0.4.0 | Yes | 0.82 |
使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md
如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。
首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。
1. Overrides RN SDK
为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。
关于该字段的作用请阅读官方说明
{
"overrides": {
"@rnoh/react-native-openharmony": "^0.82.32" // ohpm 在线版本
// "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
// "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
}
}2. 引入原生端代码
目前有两种方法：
- 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
- 直接链接源码。
方法一：通过 har 包引入（推荐）
[!TIP] har 包位于三方库安装路径的
harmony文件夹下。
打开 entry/oh-package.json5，添加以下依赖
"dependencies": {
"@react-native-ohos/react-native-mmkv": "file:../../node_modules/@react-native-ohos/react-native-mmkv/harmony/reactNativeMMKV.har"
}点击右上角的 sync 按钮
或者在终端执行：
cd entry
ohpm install方法二：直接链接源码
[!TIP] 如需使用直接链接源码，请参考直接链接源码说明
3. 配置 CMakeLists
打开 entry/src/main/cpp/CMakeLists.txt，添加：
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
# RNOH_BEGIN: manual_package_linking_1
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-mmkv/src/main/cpp" ./reactNativeMMKV)
# RNOH_END: manual_package_linking_1
# RNOH_BEGIN: manual_package_linking_2
+ target_link_libraries(rnoh_app PUBLIC rnoh_native_mmkv)
# RNOH_END: manual_package_linking_2运行
点击右上角的 sync 按钮
或者在命令行终端执行：
cd entry
ohpm install然后编译、运行即可。
约束与限制
兼容性
本文档内容基于以下版本验证通过：
- RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.120 SP7;
使用示例
下面的代码展示了这个库的基本使用场景：
[!WARNING] 使用时 import 的库名不变。
import { StyleSheet, Text, View, Button } from 'react-native';
import React, { useState } from 'react';
import { createMMKV } from 'react-native-mmkv';
export function getStringTest() {
let storageString = createMMKV({ id: 'mmkv.default' })
const [getStringText, setgetStringText] =
useState<string>('');
function setProp() {
storageString.set('mmkv.string.test.sex', "男")
storageString.set('mmkv.string.test.name', "john")
setgetStringText("set mmkv.string.test.name:john \n mmkv.string.test.sex:男")
}
function getProp() {
const name = storageString.getString('mmkv.string.test.name')
const sex = storageString.getString('mmkv.string.test.sex')
setgetStringText(`mmkv.string.test.name:${name} \n mmkv.string.test.sex:${sex}` )
}
return (
<View>
<Text>result：{getStringText}</Text>
<View style={style.actionBtn}>
<Button title="mmkv setStringTest" onPress={setProp}></Button>
<Button title="mmkv getStringTest" onPress={getProp}></Button>
</View>
</View >
);
}
const style = StyleSheet.create({
actionBtn: {
flexDirection: 'row',
flexWrap: 'wrap',
justifyContent: 'space-evenly',
padding: 10,
gap: 5,
position: 'absolute',
top: 300,
},
text: {
fontSize: 20,
textAlign: 'center',
color: '#000',
},
});
接口说明
[!TIP] "Platform"列表示该属性在原三方库上支持的平台。
[!TIP] "OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持 该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
Configuration
| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
|---|---|---|---|---|---|---|
| id | string | 'mmkv.default' | Yes | iOS, Android | Yes | 必填 - MMKV 实例的 ID。如果需要使用多个实例，请确保使用不同的 ID。例如：createMMKV({ id: 'user-storage' }) |
| path | string | / | No | iOS, Android | Yes | MMKV 实例的根路径。默认情况下，MMKV 将文件存储在 /data/storage/el2/base/haps/entry/files/mmkv 目录下，可自定义 MMKV 的根目录 |
| encryptionKey | string | / | No | iOS, Android | Yes | MMKV 实例的加密/解密密钥。默认情况下，MMKV 以明文形式存储所有键值对。如需加密，可提供此密钥。AES-128 加密密钥最大长度为 16 字节，AES-256 加密密钥最大长度为 32 字节 |
| encryptionType | 'AES-128' \| 'AES-256' | 'AES-128' | No | iOS, Android | Yes | 提供加密密钥时使用的加密算法。'AES-128' 使用 AES-128 加密（默认），'AES-256' 使用 AES-256 加密以增强安全性 |
| mode | 'single-process' \| 'multi-process' | 'single-process' | No | iOS, Android | Yes | 配置 MMKV 的进程模式。'single-process' 表示 MMKV 实例仅在单个进程中使用；'multi-process' 表示 MMKV 实例可能在多个进程中使用 |
| readOnly | boolean | false | No | iOS, Android | Yes | 如果为 true，MMKV 实例只能从存储中读取数据，不能写入。如果不需要写入操作，启用此选项可提高效率 |
| compareBeforeSet | boolean | false | No | iOS, Android | Yes | 如果为 true，MMKV 在写入磁盘前会内部比较值是否相等，如果新值与已存储的值相同，则跳过文件写入|
MMKV
| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 |
|---|---|---|---|---|---|---|
| id | string | 'mmkv.default' | No | iOS, Android | Yes | 获取当前MMKV实例的唯一ID |
| length | number | / | No | iOS, Android | Yes | 获取当前存储的key/value对数量 |
| size | number | / | No | iOS, Android | Yes | 获取存储占用的字节大小（已废弃，推荐使用byteSize） |
| byteSize | number | / | No | iOS, Android | Yes | 获取存储占用的字节大小（推荐替代size） |
| isReadOnly | boolean | / | No | iOS, Android | Yes | 判断当前MMKV实例是否为只读模式 |
| isEncrypted | boolean | / | No | iOS, Android | Yes | 判断当前MMKV实例是否已加密 |
| set | (key: string, value: boolean | string | number | ArrayBuffer) => void | / | No | iOS, Android | Yes | 存储键值对数据 |
| getBoolean | (key: string) => boolean | undefined | / | No | iOS, Android | Yes | 获取boolean类型值，key不存在返回undefined |
| getString | (key: string) => string | undefined | / | No | iOS, Android | Yes | 获取string类型值，key不存在返回undefined |
| getNumber | (key: string) => number | undefined | / | No | iOS, Android | Yes | 获取number类型值，key不存在返回undefined |
| getBuffer | (key: string) => ArrayBuffer | undefined | / | No | iOS, Android | Yes | 获取二进制Buffer数据，key不存在返回undefined |
| contains | (key: string) => boolean | / | No | iOS, Android | Yes | 判断MMKV实例是否存在指定key |
| remove | (key: string) => boolean | / | No | iOS, Android | Yes | 删除指定key对应的存储数据，返回是否删除成功 |
| getAllKeys | () => string[] | / | No | iOS, Android | Yes | 获取当前实例下全部key数组 |
| clearAll | () => void | / | No | iOS, Android | Yes | 清空当前实例所有存储数据 |
| recrypt | (key: string | undefined) => void | / | No | iOS, Android | Yes | 重新设置/移除MMKV加密密钥（已废弃，推荐使用encrypt/decrypt） |
| encrypt | (key: string, encryptionType?: 'AES-128' | 'AES-256') => void | / | No | iOS, Android | Yes | 对已有数据加密，默认AES-128，支持切换AES-256 |
| decrypt | () => void | / | No | iOS, Android | Yes | 解除加密 |
| trim | () => void | / | No | iOS, Android | Yes | 清理MMKV内部空闲存储碎片，优化占用空间 |
| toString | () => string | / | No | iOS, Android | Yes | 输出MMKV实例概要信息字符串 |
| addOnValueChangedListener | (callback: (key: string) => void) => Listener | / | No | iOS, Android | Yes | 注册键值变更监听器，返回{remove:()=>void}用于取消订阅 |
| importAllFrom | (other: MMKV) => number | / | No | iOS, Android | Yes | 从另一个MMKV实例导入所有数据，返回导入的key数量 |
API
| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |--------|---------|-----|-------|-------|--------|-----|-----------------| | createMMKV | function | configuration?: Configuration | MMKV | Yes | iOS/Android | yes | 创建MMKV实例，不传配置时使用默认id'mmkv.default' | | existsMMKV | function | id: string | boolean | No | iOS/Android | yes | 判断指定id的MMKV实例是否存在 | | deleteMMKV | function | id: string | boolean | No | iOS/Android | yes | 删除指定id的MMKV实例，返回是否成功 | | useMMKV | Hook | configuration?: Configuration | MMKV | No | iOS/Android | yes | 通过React Hook方式创建/获取MMKV实例 | | useMMKVString | Hook | key: string, instance?: MMKV | [string | undefined, (value: string | undefined) => void] | No | iOS/Android | yes | Hook方式读写字符串类型存储 | | useMMKVNumber | Hook | key: string, instance?: MMKV | [number | undefined, setValue: (value: number | undefined | ((prev: number | undefined) => number | undefined)) => void] | No | iOS/Android | yes | Hook方式读写数字类型存储 | | useMMKVBoolean | Hook | key: string, instance?: MMKV | [boolean | undefined, setValue: (value: boolean | undefined | ((prev: boolean | undefined) => boolean | undefined)) => void] | No | iOS/Android | yes | Hook方式读写布尔类型存储 | | useMMKVBuffer | Hook | key: string, instance?: MMKV | [ArrayBuffer | undefined, setValue: (value: ArrayBuffer | undefined | ((prev: ArrayBuffer | undefined) => ArrayBuffer | undefined)) => void] | No | iOS/Android | yes | Hook方式读写二进制Buffer数据 | | useMMKVObject | Hook | key: string, instance?: MMKV | [T | undefined, setValue: (value: T | undefined | ((prev: T | undefined) => T | undefined)) => void] | No | iOS/Android | yes | Hook方式序列化读写JS对象 | | useMMKVListener | Hook | callback: (key: string) => void, instance?: MMKV | void | No | iOS/Android | yes | Hook方式监听存储变化，组件卸载时自动取消监听 | | useMMKVKeys | Hook | instance?: MMKV | string[] | No | iOS/Android | yes | Hook方式获取当前实例所有key列表，自动响应变化 |
遗留问题
无
其它
- 偶现报错“librnoh_native_mmkv.so(mmkv::CodeOutputData::writeRawData(mmkv::MMBuffer const &))...”
解决方案: 该报错来源于 librnoh_native_mmkv.so 中调用的上游库MMKV接口，建议前往原库提交Issue咨询。
toString方法，现在只会输出[HybridObject MMKV],跟其他平台表现一致，非harmony版本的问题。
useMMKVBuffer方法，现在使用会报错，源库4.3.1版本也无法正常使用，是上流代码的问题，其他平台表现一致，非harmony版本的问题。
目录结构
/rntpc_react-native-mmkv # 项目根目录
├── packages # 核心包
│ └─ react-native-mmkv # 主库包
│ └─ cpp/ # 跨平台 C++ 核心代码
│ └─ HybridMMKV.cpp
│ └─ HybridMMKV.hpp
│ └─ HybridMMKVFactory.cpp
│ └─ HybridMMKVFactory.hpp
│ └─ MMKVTypes.hpp
│ └─ MMKVValueChangedListenerRegistry.cpp
│ └─ MMKVValueChangedListenerRegistry.hpp
│ └─ ManagedMMBuffer.hpp
│ └─ harmony # 鸿蒙适配代码
│ └─ reactNativeMMKV.har # har包
│ └─ reactNativeMMKV # 鸿蒙适配核心代码
│ └─ index.ets # 鸿蒙适配代码入口
│ └─ ts.ts # TypeScript 配置
│ └─ src/main/cpp # C++ 原生代码
│ └─ CMakeLists.txt # CMake 构建配置
│ └─ cpp/ # MMKV 核心实现
│ └─ HybridMMKV.cpp
│ └─ HybridMMKV.hpp
│ └─ HybridMMKVFactory.cpp
│ └─ HybridMMKVFactory.hpp
│ └─ MMKVTypes.hpp
│ └─ MMKVValueChangedListenerRegistry.cpp
│ └─ MMKVValueChangedListenerRegistry.hpp
│ └─ ManagedMMBuffer.hpp
│ └─ spec/ # Nitro 生成的 Spec 文件
│ └─ HybridMMKVFactorySpec.cpp
│ └─ HybridMMKVFactorySpec.hpp
│ └─ HybridMMKVPlatformContextSpec.cpp
│ └─ HybridMMKVPlatformContextSpec.hpp
│ └─ HybridMMKVSpec.cpp
│ └─ HybridMMKVSpec.hpp
│ └─ Listener.hpp
│ └─ Mode.hpp
│ └─ HarmonyLogger.cpp # 鸿蒙日志实现
│ └─ HybridMMKVPlatformContext.cpp # 平台上下文实现
│ └─ HybridMMKVPlatformContext.hpp
│ └─ NitroMmkvAutolinking.cpp # 自动链接
│ └─ NitroMmkvAutolinking.hpp
│ └─ MMKVManagedBuffer.h
│ └─ MmkvLogger.h
│ └─ src/ # RN 代码
│ └─ index.ts # 入口文件
├── README.md # 中文安装使用方法
├── README_en.md # 英文安装使用方法 贡献代码
使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。
开源协议
本项目基于 MIT License (MIT) ，请自由地享受和参与开源。