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 -> Bool
Integer -> Number
Double -> Number
Float -> Number
String -> String
Callback -> function
ReadableMap -> Object
ReadableArray -> 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方法

@Override
public 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);

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

@Override
public void onHostResume() {
    // Activity `onResume`
}

@Override
public void onHostPause() {
    // Activity `onPause`
}

@Override
public void onHostDestroy() {
    // Activity `onDestroy`
}

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