模板版本：v0.4.0

本项目基于 原库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

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

[!WARNING] 使用时 import 的库名不变。

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)

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

| 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)

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

| 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)

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

| 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) ，请自由地享受和参与开源。