文档模板：v0.4.1

react-native-mmkv

本项目基于 react-native-mmkv 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-mmkv 版本所属关系如下：

三方库名称	三方库版本	发布信息	支持RN版本	Autolink	编译API版本	社区基线版本	npm地址
@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-mmkv

yarn

yarn add @react-native-ohos/react-native-mmkv

Link

	是否支持autolink	RN框架版本
~ 3.3.0	No	0.72/0.77

使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.72.38" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

2. 引入原生端代码

目前有两种方法：

1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
2. 直接链接源码。

方法一：通过 har 包引入（推荐）

打开 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

方法二：直接链接源码

3.配置 CMakeLists 和引入 NativeMMKVPackage

打开 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

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
+ #include "NativeMMKVPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
      std::make_shared<RNOHGeneratedPackage>(ctx),
+      std::make_shared<NativeMMKVPackage>(ctx)
    };
}

4.在 ArkTs 侧引入 reactNativeMMKVPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

  ... 
+ import { MmkvCxxPackage, MmkvPlatformContextPackage } from '@react-native-ohos/react-native-mmkv/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+   new MmkvPlatformContextPackage(ctx),
+   new MmkvCxxPackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

1. RNOH:0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;
2. RNOH:0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.868; ROM: 6.0.0.112;

使用示例

下面的代码展示了这个库的基本使用场景：

import { StyleSheet, Text, View, Button } from 'react-native';
import React, { useState } from 'react';
import { MMKV } from 'react-native-mmkv';

export default function getStringTest() {
  let storageString = new MMKV()
  const [getStringText, setgetStringText] =
    useState<string>('');

  function setProp() {
    storageString.set('mmkv.string.test.sex', "男")
    storageString.set('mmkv.string.test.name', "john")
    setgetStringText("set string success")
  }

  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',
  }
});

接口说明

Configuration

名称	参数类型	默认值	必填	平台	HarmonyOS平台支持	描述
id	string	'mmkv.default'	Yes	iOS, Android	Yes	必填 - MMKV 实例的 ID。如果需要使用多个实例，请确保使用不同的 ID。例如：createMMKV({ id: 'user-storage' })
path	string	undefined	No	iOS, Android	Yes	MMKV 实例的根路径。默认情况下，MMKV 将文件存储在 /data/storage/el2/base/haps/entry/files/mmkv 目录下，可自定义 MMKV 的根目录
encryptionKey	string	undefined	No	iOS, Android	Yes	MMKV 实例的加密/解密密钥。默认情况下，MMKV 以明文形式存储所有键值对。如需加密，可提供此密钥。AES-128 加密密钥最大长度为 16 字节
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 实例只能从存储中读取数据，不能写入。如果不需要写入操作，启用此选项可提高效率

---

MMKV

名称	参数类型	默认值	必填	平台	HarmonyOS平台支持	描述
size	number	-	No	iOS, Android	Yes	获取MMKV持久化文件占用字节大小
isReadOnly	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) => ArrayBufferLike | undefined	-	No	iOS, Android	Yes	获取二进制Buffer数据，key不存在返回undefined
contains	(key: string) => boolean	-	No	iOS, Android	Yes	判断MMKV实例是否存在指定key
delete	(key: string) => void	-	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加密密钥，实现数据重加密
trim	() => void	-	No	iOS, Android	Yes	清理MMKV内部空闲存储碎片，优化占用空间
toString	() => string	-	No	iOS, Android	Yes	输出MMKV实例概要信息字符串
toJSON	() => object	-	No	iOS, Android	Yes	输出MMKV实例的JSON表示
addOnValueChangedListener	(callback: (key: string) => void) => Listener	-	No	iOS, Android	Yes	注册键值变更监听器，返回{remove:()=>void}用于取消订阅

---

API

名称	类型	参数类型	返回值	必填	平台	OpenHarmony平台支持	描述
new MMKV	构造函数	configuration?: Configuration	MMKV	Yes	iOS/Android	yes	创建MMKV实例，不传配置时使用默认id'mmkv.default'
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	[ArrayBufferLike | undefined, setValue: (value: ArrayBufferLike | undefined | ((prev: ArrayBufferLike | undefined) => ArrayBufferLike | 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方式监听存储变化，组件卸载时自动取消监听

遗留问题

无

其它

1. 偶现报错“librnoh_native_mmkv.so(mmkv::CodeOutputData::writeRawData(mmkv::MMBuffer const &))...”

解决方案: 该报错来源于 librnoh_native_mmkv.so 中调用的上游库MMKV接口，建议前往原库提交Issue咨询。

目录结构

/rntpc_react-native-mmkv  # 项目根目录
├── package/                  # 主包
│    ├── cpp/                 # C++ 原生代码
│    │    ├── MmkvHostObject.cpp
│    │    ├── MmkvHostObject.h
│    │    ├── MmkvLogger.h
│    │    ├── MMKVManagedBuffer.h
│    │    ├── NativeMmkvModule.cpp
│    │    └── NativeMmkvModule.h
│    ├── harmony/             # 鸿蒙适配
│    │    ├── reactNativeMMKV.har          # har包
│    │    └── reactNativeMMKV/             # 鸿蒙适配核心代码
│    │         ├── index.ets               # 鸿蒙适配代码入口
│    │         ├── ts.ts                   # TypeScript 配置
│    │         ├── BuildProfile.ets
│    │         ├── build-profile.json5
│    │         ├── hvigorfile.ts
│    │         ├── oh-package.json5
│    │         ├── LICENSE
│    │         ├── NOTICE
│    │         ├── README.OpenSource
│    │         └── src/
│    │              ├── main/
│    │              │    ├── cpp/          # C++ 原生代码
│    │              │    ├── ets/
│    │              │    ├── resources/
│    │              │    └── module.json5
│    ├── src/                 # TypeScript/JS 源码
│    │    ├── __tests__/
│    │    │    └── hooks.test.tsx
│    │    ├── createMMKV.mock.ts
│    │    ├── createMMKV.ts
│    │    ├── createMMKV.web.ts
│    │    ├── createTextEncoder.ts
│    │    ├── hooks.ts
│    │    ├── index.ts
│    │    ├── MemoryWarningListener.ts
│    │    ├── MemoryWarningListener.web.ts
│    │    ├── MMKV.ts
│    │    ├── ModuleNotFoundError.ts
│    │    ├── NativeMmkv.ts
│    │    ├── NativeMmkvPlatformContext.ts
│    │    ├── PlatformChecker.ts
│    │    └── Types.ts
│    ├── MMKV/               # MMKV 原生模块
├── README.md            # # 中文安装使用方法   
├── README_en.md         # # 英文安装使用方法  

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

本项目基于 MIT License (MIT) ，请自由地享受和参与开源。