ReactNative文档翻译-------Native Modules

有时App需要使用的系统API没有对应的ReactNative模型，或者你想重用已有的java代码而不想用js去重复实现，又或者你想写一些高性能的多线程处理代码，比如图片处理，数据库操作或其他的高级扩展，这时候就可以使用Native Modules。ReactNative使得编写本地代码并充分利用平台特性成为可能，编写本地模型（NativeModules）是React Native的高级特征，我们并不建议在通常的开发过程中使用这一特性，但是这一特征的必要性（开发者的客观需求）让我们加上了这一特征；如果React native不能提供你所需要的本地功能，你可以通过NativeModules自己添加。

Toast Module
这篇手册将使用Toast Module作为示例。我们将使用Js创建一条Toast消息展示。
一.创建模型
首先我们创建一个本地模型，本地模型是一个继承自ReactContextBaseJavaModule的java类，实现了Js需要的功能，在这个例子里，我们要用Js代码ToastAndroid.show('Awesome', ToastAndroid.SHORT); 在屏幕上展示一条Toast提示。

package com.facebook.react.modules.toast;import android.widget.Toast;import com.facebook.react.bridge.NativeModule;import com.facebook.react.bridge.ReactApplicationContext;import com.facebook.react.bridge.ReactContext;import com.facebook.react.bridge.ReactContextBaseJavaModule;import com.facebook.react.bridge.ReactMethod;import java.util.Map;public class ToastModule extends ReactContextBaseJavaModule {  private static final String DURATION_SHORT_KEY = "SHORT";  private static final String DURATION_LONG_KEY = "LONG";  public ToastModule(ReactApplicationContext reactContext) {    super(reactContext);  }}

继承ReactContextBaseJavaModule需要实现抽象方法getName，该方法返回本地模型的字符名称，在Js中代表了本地模型这个类，这里我们把本地模型命名为ToastAndroid，这样我们就可以在Js中用React.NativeModules.ToastAndroid使用这个模型

  @Override  public String getName() {    return "ToastAndroid";  }

getConstants是一个可选的实现方法，返回常量给js使用，这个方法不是必须的，但是在js实时调用java交互时，可以用这个方法给Java中预定义的值指定键值并在js中使用，是很有用的一个方法；

 @Override  public Map<String, Object> getConstants() {    final Map<String, Object> constants = new HashMap<>();    constants.put(DURATION_SHORT_KEY, Toast.LENGTH_SHORT);    constants.put(DURATION_LONG_KEY, Toast.LENGTH_LONG);    return constants;  }

把本地模型中的java方法暴露给js使用，必须给方法加上@ReactMethod注解，这种桥接方法的返回值总是void类型，ReactNative桥接是异步的（方法调用？异步还是同步），要想把Java方法执行结果传给Js只能使用CallBack或触发事件

  @ReactMethod  public void show(String message, int duration) {    Toast.makeText(getReactApplicationContext(), message, duration).show();  }

参数类型

Boolean -> BoolInteger -> NumberDouble -> NumberFloat -> NumberString -> StringCallback -> functionReadableMap -> ObjectReadableArray -> Array

二.注册模型
java代码处理的最后一步是注册模型，注册过程发生在模型package的createNativeModules 方法中，如果模型没注册是无法在Js中使用的。
1.定义ReactPackage

class AnExampleReactPackage implements ReactPackage {  @Override  public List<Class<? extends JavaScriptModule>> createJSModules() {    return Collections.emptyList();  }  @Override  public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {    return Collections.emptyList();  }  @Override  public List<NativeModule> createNativeModules(                              ReactApplicationContext reactContext) {    List<NativeModule> modules = new ArrayList<>();    modules.add(new ToastModule(reactContext));    return modules;  }

2.注册ReactPackage
在MainApplication.java文件中的getPackage方法中添加定义的ReactPackage，MainApplication.java文件在项目android文件夹下，路径是android/app/src/main/java/com/your-app-name/MainApplication.java

protected List<ReactPackage> getPackages() {    return Arrays.<ReactPackage>asList(            new MainReactPackage(),            new AnExampleReactPackage()); // <-- Add this line with your package name.}

三。在Js中使用
要想在Js中方便的使用本地模型，通常会定义一个Js模型映射本地模型，这部操作不是必须的，但是可以免于每次从NativeModules中提取需要的模块，对应的 Js文件也是定义Js侧（方法）功能的好地方

'use strict';/** * This exposes the native ToastAndroid module as a JS module. This has a * function 'show' which takes the following parameters: * * 1. String message: A string with the text to toast * 2. int duration: The duration of the toast. May be ToastAndroid.SHORT or *    ToastAndroid.LONG */import { NativeModules } from 'react-native';module.exports = NativeModules.ToastAndroid;

定义好Js模型以后，就可以在其他Js文件中使用了

import ToastAndroid from './ToastAndroid';ToastAndroid.show('Awesome', ToastAndroid.SHORT);

Java回调js方法
1.CallBack
本地模型支持CallBack类型参数，通常用于把函数执行结果返回给Js

public class UIManagerModule extends ReactContextBaseJavaModule {...  @ReactMethod  public void measureLayout(      int tag,      int ancestorTag,      Callback errorCallback,      Callback successCallback) {    try {      measureLayout(tag, ancestorTag, mMeasureBuffer);      float relativeX = PixelUtil.toDIPFromPixel(mMeasureBuffer[0]);      float relativeY = PixelUtil.toDIPFromPixel(mMeasureBuffer[1]);      float width = PixelUtil.toDIPFromPixel(mMeasureBuffer[2]);      float height = PixelUtil.toDIPFromPixel(mMeasureBuffer[3]);      successCallback.invoke(relativeX, relativeY, width, height);    } catch (IllegalViewOperationException e) {      errorCallback.invoke(e.getMessage());    }  }...

在Js中可以如下调用

UIManager.measureLayout(  100,  100,  (msg) => {    console.log(msg);  },  (x, y, width, height) => {    console.log(x + ':' + y + ':' + width + ':' + height);  });

本地模型只能触发一次CallBack，但是CallBack对象可以缓存起来在其他方法中触发
2.Promise
在本地模型中也可以使用Promise来简化代码，特别是在使用ES2016’s async/await语法时，当本地模型的桥接方法的最后一个参数是Promise类型时，对应的Js方法将返回一个js的Promise对象，上面的代码也可以使用Promise实现

public class UIManagerModule extends ReactContextBaseJavaModule {...  @ReactMethod  public void measureLayout(      int tag,      int ancestorTag,      Promise promise) {    try {      measureLayout(tag, ancestorTag, mMeasureBuffer);      WritableMap map = Arguments.createMap();      map.putDouble("relativeX", PixelUtil.toDIPFromPixel(mMeasureBuffer[0]));      map.putDouble("relativeY", PixelUtil.toDIPFromPixel(mMeasureBuffer[1]));      map.putDouble("width", PixelUtil.toDIPFromPixel(mMeasureBuffer[2]));      map.putDouble("height", PixelUtil.toDIPFromPixel(mMeasureBuffer[3]));      promise.resolve(map);    } catch (IllegalViewOperationException e) {      promise.reject(e);    }  }...

对应的Js方法返回Promise，这意味着在异步方法中可以使用await关键字调用方法并等待结果返回

async function measureLayout() {  try {    var {      relativeX,      relativeY,      width,      height,    } = await UIManager.measureLayout(100, 100);    console.log(relativeX + ':' + relativeY + ':' + width + ':' + height);  } catch (e) {    console.error(e);  }}measureLayout();

3.Sending Events to JavaScript
本地模型可以向Js发送事件而不是立即触发Js代码执行（？），最简单的方法是使用RCTDeviceEventEmitter，RCTDeviceEventEmitter对象可以通过ReactContext获得，如下代码所示

...private void sendEvent(ReactContext reactContext,                       String eventName,                       @Nullable WritableMap params) {  reactContext      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)      .emit(eventName, params);}...WritableMap params = Arguments.createMap();...sendEvent(reactContext, "keyboardWillShow", params);

Js 代码可以使用Subscribable mixin，用addListenerOn注册处理接收事件

import { DeviceEventEmitter } from 'react-native';...var ScrollResponderMixin = {  mixins: [Subscribable.Mixin],  componentWillMount: function() {    ...    this.addListenerOn(DeviceEventEmitter,                       'keyboardWillShow',                       this.scrollResponderKeyboardWillShow);    ...  },  scrollResponderKeyboardWillShow:function(e: Event) {    this.keyboardWillOpenTo = e;    this.props.onKeyboardWillShow && this.props.onKeyboardWillShow(e);  },

也可以直接使用DeviceEventEmitter监听事件

...componentWillMount: function() {  DeviceEventEmitter.addListener('keyboardWillShow', function(e: Event) {    // handle event.  });}...

四。在本地模型中使用startActivityForResult及生命周期监听
这里主要涉及到两个接口ActivityEventListener 和LifecycleEventListener。
1.ActivityEventListener
如果使用startActivityForResult跳转到本地Activity需要实现ActivityEventListener接口，如果要从本地Activity返回结果，需要实现ActivityEventListener的OnActivityResult方法，此外还要在模型构造方法中添加一个Listener

reactContext.addActivityEventListener(this);

实现ActivityEventListener的OnActivityResult方法就可以监听React Activity的OnActivityResult方法

@Overridepublic void onActivityResult(final int requestCode, final int resultCode, final Intent intent) {  // Your logic here}

使用示例，图片选择器：

public class ImagePickerModule extends ReactContextBaseJavaModule implements ActivityEventListener {  private static final int IMAGE_PICKER_REQUEST = 467081;  private static final String E_ACTIVITY_DOES_NOT_EXIST = "E_ACTIVITY_DOES_NOT_EXIST";  private static final String E_PICKER_CANCELLED = "E_PICKER_CANCELLED";  private static final String E_FAILED_TO_SHOW_PICKER = "E_FAILED_TO_SHOW_PICKER";  private static final String E_NO_IMAGE_DATA_FOUND = "E_NO_IMAGE_DATA_FOUND";  private Promise mPickerPromise;  public ImagePickerModule(ReactApplicationContext reactContext) {    super(reactContext);    // Add the listener for `onActivityResult`    reactContext.addActivityEventListener(this);  }  @Override  public String getName() {    return "ImagePickerModule";  }  @ReactMethod  public void pickImage(final Promise promise) {    Activity currentActivity = getCurrentActivity();    if (currentActivity == null) {      promise.reject(E_ACTIVITY_DOES_NOT_EXIST, "Activity doesn't exist");      return;    }    // Store the promise to resolve/reject when picker returns data    mPickerPromise = promise;    try {      final Intent galleryIntent = new Intent(Intent.ACTION_PICK);      galleryIntent.setType("image/*");      final Intent chooserIntent = Intent.createChooser(galleryIntent, "Pick an image");      currentActivity.startActivityForResult(chooserIntent, IMAGE_PICKER_REQUEST);    } catch (Exception e) {      mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);      mPickerPromise = null;    }  }  // You can get the result here  @Override  public void onActivityResult(final int requestCode, final int resultCode, final Intent intent) {    if (requestCode == IMAGE_PICKER_REQUEST) {      if (mPickerPromise != null) {        if (resultCode == Activity.RESULT_CANCELED) {          mPickerPromise.reject(E_PICKER_CANCELLED, "Image picker was cancelled");        } else if (resultCode == Activity.RESULT_OK) {          Uri uri = intent.getData();          if (uri == null) {            mPickerPromise.reject(E_NO_IMAGE_DATA_FOUND, "No image data found");          } else {            mPickerPromise.resolve(uri.toString());          }        }        mPickerPromise = null;      }    }  }}

2.LifecycleEventListener
类似于ActivityEventListener，实现ReactActivity生命周期的监听可以通过实现LifecycleEventListener接口来完成。在本地模型构造方法中添加监听器

reactContext.addLifecycleEventListener(this);

通过实现以下方法可实现生命周期监听

@Overridepublic void onHostResume() {    // Activity `onResume`}@Overridepublic void onHostPause() {    // Activity `onPause`}@Overridepublic void onHostDestroy() {    // Activity `onDestroy`}

需要注意的是 在生命周期回调和@ReactMethod方法中是关联到上下文环境的，也就是说通过getCurrentActivity方法是可以获取到Activity 对象的，但是在ActivityEventListener实现方法中getCurrentActivity方法返回值是Null，对应在方法中执行CallBack等回调Js时可能出现无上下文的问题