模板版本：v0.4.0

react-native-safe-modules

本项目基于 原库react-native-safe-modules 开发。

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

三方库名称	三方库版本	发布信息	支持RN版本	编译API版本	社区基线版本	npm地址
@react-native-ohos/react-native-safe-modules	~1.1.0	Gitcode Releases	0.77.* / 0.82.*	API12+	1.0.3	Npm Address
@react-native-oh-tpl/react-native-safe-modules	~1.0.3-0.0.1	Github Releases	0.72.*	API12+	1.0.3	Npm Address

1. 安装与使用

进入到工程目录并输入以下命令：

npm

# 0.72
npm install @react-native-oh-tpl/react-native-safe-modules

# 0.77/0.82
npm install @react-native-ohos/react-native-safe-modules

yarn

# 0.72
yarn add @react-native-oh-tpl/react-native-safe-modules

# 0.77/0.82
yarn add @react-native-ohos/react-native-safe-modules

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

import React from 'react';
import { View, Button } from 'react-native';
import SafeModule from 'react-native-safe-modules';

const App = () => {
  const myModule = SafeModule.create({
    moduleName: 'MyNativemodule',
    mock: {
      someAPI: () => 'doSomething'
    }
  })
  myModule.someAPI()
  
  const NativeLottieView = SafeModule.component({
    viewName: 'LottieAnimationView',
    mockComponent: View,
  });
  
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <NativeLottieView
        style={{ backgroundColor: 'red', width: 100, height: 100 }}
      />
    </View>
  );
};

export default App;

2. 约束与限制

2.1. 兼容性

在以下版本验证通过：

1. RNOH:0.72.28; SDK:HarmonyOS NEXT DB2; IDE:DevEco Studio 5.0.3.500; ROM:3.0.0.28;
2. RNOH: 0.77.1;SDK:HarmonyOS 5.1.1.208 (API Version 19 Release) ;IDE:DevEco Studio:5.1.1.830; ROM: HarmonyOS 6.0.0.112 SP12;.
3. RNOH: 0.82.7; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1.260; ROM: 6.0.0.130 SP15;

3. 属性

3.1. SafeModule.create(options)

Name	Description	Type	Required	Platform	HarmonyOS Support
options.moduleName	在 NativeModules 命名空间中查找模块的名称或名称数组。	string/string[]	yes	iOS,Android	yes
options.mock	原生模块的模拟实现。	object	yes	iOS,Android	yes
options.getVersion	返回原生模块版本的函数。仅在指定覆盖且未在原生模块上导出 VERSION 属性时才需要。默认值为 x => x.VERSION。	Function	no	iOS,Android	yes
options.versionOverrides	版本号到相应属性/方法的覆盖实现的映射。如果被覆盖的属性或方法是一个函数，在 SafeModule.create(...) 期间将使用两个参数调用它：原始模块上该属性的原始值和原始模块本身。该函数的返回值将放在 SafeModule.create(...) 的返回值上。	object	no	iOS,Android	yes
options.isEventEmitter	指示原生模块是否应为 EventEmitter 的标志。将 EventEmitter 实例放在结果模块的 emitter 属性上。默认为 false。	boolean	no	iOS,Android	yes

3.2. SafeModule.module(options)

Name	Description	Type	Required	Platform	HarmonyOS Support
options.moduleName	在 NativeModules 命名空间中查找模块的名称或名称数组。	string/string[]	yes	iOS,Android	yes
options.mock	原生模块的模拟实现。	object	yes	iOS,Android	yes
options.getVersion	返回原生模块版本的函数。仅在指定覆盖且未在原生模块上导出 VERSION 属性时才需要。默认值为 x => x.VERSION。	Function	no	iOS,Android	yes
options.versionOverrides	版本号到相应属性/方法的覆盖实现的映射。如果被覆盖的属性或方法是一个函数，在 SafeModule.create(...) 期间将使用两个参数调用它：原始模块上该属性的原始值和原始模块本身。该函数的返回值将放在 SafeModule.create(...) 的返回值上。	object	no	iOS,Android	yes
options.isEventEmitter	指示原生模块是否应为 EventEmitter 的标志。将 EventEmitter 实例放在结果模块的 emitter 属性上。默认为 false。	boolean	no	iOS,Android	yes

3.3. SafeModule.component(options)

Name	Description	Type	Required	Platform	HarmonyOS Support
options.viewName	传入的组件名称	string/string[]	yes	iOS,Android	yes
options.mockComponent	传入一个模拟的组件，当viewName查找不到的时候，component会返回这个模拟的组件	React.ComponentType<T>	yes	iOS,Android	yes
options.componentOverrides	根据版本获取其中定义的组件，如果和viewName相同，覆盖原生组件的React组件，需要确保返回的React组件是有效的	object	no	no	no
options.propOverrides	根据版本获取其中定义的组件属性，如果是相同组件的相同属性，根据版本覆盖原生组件的属性，需要确保覆盖的属性在原生组件中存在	object	no	no	no
options.mock	原生模块的模拟实现，原生模块中存在什么成员，可使用该属性自己模拟编写	object	no	no	no
options.getVersion	返回本机模块版本的函数。仅在指定替代且不导出本机模块上的版本属性时才需要。默认值为x => x.VERSION。	Function	no	no	no

4. 遗留问题

5. 其他

• component接口问题： 该接口在iOS和Android上均无法正常使用，不管输入的viewName是什么，都只会返回用户传递的mockComponent，无法获得封装后的组件，HarmonyOS与其表现一致:issue#19。

6. 开源协议

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