Native 模块(Android)

有时候一个应用需要访问 React Native 平台目前没有对应模块的 API 。也许你需要复用一些已经存在的 Java 代码而不需要在 JavaScript 里面重新实现，或者写一些高性能，多线程的代码，比如图片处理，数据库，或者任何先进的扩展。

我们设计了 React Native 以致于你可以写一些真正的原生代码并且可以完全拥有系统的权限的能力。这是一个更加先进的特征，并且我们不希望这是传统开发过程中的一部分，然而它存在是非常重要的。如果 React Native 不支持你需要的原生特征，那么你应该可以自己创建它。

Toast 模块

这个引导将会使用这个 Toast 的例子。我们将会可以通过使用 JavaScript 创建一个 toast 消息。

我们从创建一个原生模块开始。一个原生模块是一个通常继承 ReactContextBaseJavaModule 类的 Java 类，并且实现了 JavaScript 需要实现的方法。我们这里的目标是允许通过使用 JavaScript 书写
ToastAndroid.show('Awesome', ToastAndroid.SHORT);就可以在屏幕上面显示一个短短的 toast 消息。

  1. package com.facebook.react.modules.toast;
  3. import android.widget.Toast;
  5. import com.facebook.react.bridge.NativeModule;
  6. import com.facebook.react.bridge.ReactApplicationContext;
  7. import com.facebook.react.bridge.ReactContext;
  8. import com.facebook.react.bridge.ReactContextBaseJavaModule;
  9. import com.facebook.react.bridge.ReactMethod;
  11. import java.util.Map;
  13. public class ToastModule extends ReactContextBaseJavaModule {
  15.   private static final String DURATION_SHORT_KEY = "SHORT";
  16.   private static final String DURATION_LONG_KEY = "LONG";
  18.   public ToastModule(ReactApplicationContext reactContext) {
  19.     super(reactContext);
  20.   }
  21. }

ReactContextBaseJavaModule 需要一个叫做 getName 的方法被实现。这个方法的目的就是返回在 JavaScript 里面表示这个类的叫做 NativeModule 的字符串的名字。在这里我们调用 ToastAndroid 因此我们可以在 JavaScript 里面使用 React.NativeModules.ToastAndroid 来得到它。

  1.   @Override
  2.   public String getName() {
  3.     return "ToastAndroid";
  4.   }

一个可选的叫做 getConstants 的方法会将传递给 JavaScript 的常量返回。这个方法的实现并不是必须的，但是却对在 JavaScript 和 Java 中同步的预定义的关键字的值非常重要。

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

给 JavaScript 暴露一个方法，一个 Java 方法需要使用 @ReactMethod 来注解。桥接的方法的返回值类型总是 void。React Native 的桥接是异步的，因此将一个结果传递给 JavaScript 的唯一方式就是使用回调函数或者调用事件（见下面）。

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

参数类型

下面的参数类型是被使用 @ReactMethod 注解的方法支持的，并且它们直接对应 JavaScript 中对应的值。

  1. Boolean -> Bool
  2. Integer -> Number
  3. Double -> Number
  4. Float -> Number
  5. String -> String
  6. Callback -> function
  7. ReadableMap -> Object
  8. ReadableArray -> Array

注册模块

在使用 Java 的最后一步就是注册这个模块，这将在你的应用包中的 createNativeModules 发生。如果一个模块没有被注册，那么它在 JavaScript 是不可用的。

  1. class AnExampleReactPackage implements ReactPackage {
  3.   ...
  5.   @Override
  6.   public List<NativeModule> createNativeModules(
  7.                               ReactApplicationContext reactContext) {
  8.     List<NativeModule> modules = new ArrayList<>();
  10.     modules.add(new ToastModule(reactContext));
  12.     return modules;
  13.   }

当包被创建的时候，它需要提供给 ReactInstanceManager 。可以看 UIExplorerActivity.java 这个例子。当你初始化一个新工程的时候默认的包是MainReactPackage.java。

  1. mReactInstanceManager = ReactInstanceManager.builder()
  2.   .setApplication(getApplication())
  3.   .setBundleAssetName("AnExampleApp.android.bundle")
  4.   .setJSMainModuleName("Examples/AnExampleApp/AnExampleApp.android")
  5.   .addPackage(new AnExampleReactPackage())
  6.   .setUseDeveloperSupport(true)
  7.   .setInitialLifecycleState(LifecycleState.RESUMED)
  8.   .build();

为了能让你更加方便的从 JavaScript 访问你的新功能的时候，通常会将原生模块包裹在一个 JavaScript 模块里面。这不是必须的，但是节省了你的类库的使用者每次都要 pull NativeModules 的不便。这个 JavaScript 文件也为你增加任何 JavaScript 端功能提供了方便。

  1. /**
  2.  * @providesModule ToastAndroid
  3.  */
  5. 'use strict';
  7. /**
  8.  * This exposes the native ToastAndroid module as a JS module. This has a function 'showText'
  9.  * which takes the following parameters:
  10.  *
  11.  * 1. String message: A string with the text to toast
  12.  * 2. int duration: The duration of the toast. May be ToastAndroid.SHORT or ToastAndroid.LONG
  13.  */
  14. var { NativeModules } = require('react-native');
  15. module.exports = NativeModules.ToastAndroid;

现在，在你的 JavaScript 文件里面你可以像下面这样调用方法：

  1. var ToastAndroid = require('ToastAndroid')
  2. ToastAndroid.show('Awesome', ToastAndroid.SHORT);
  4. // Note: We require ToastAndroid without any relative filepath because
  5. // of the @providesModule directive. Using @providesModule is optional.

远不止 Toasts

回调

原生模块也提供了一种特殊的参数－一个回调。在大多数情况下这是给 JavaScript 返回结果使用的。

  1. public class UIManagerModule extends ReactContextBaseJavaModule {
  3. ...
  5.   @ReactMethod
  6.   public void measureLayout(
  7.       int tag,
  8.       int ancestorTag,
  9.       Callback errorCallback,
  10.       Callback successCallback) {
  11.     try {
  12.       measureLayout(tag, ancestorTag, mMeasureBuffer);
  13.       float relativeX = PixelUtil.toDIPFromPixel(mMeasureBuffer[0]);
  14.       float relativeY = PixelUtil.toDIPFromPixel(mMeasureBuffer[1]);
  15.       float width = PixelUtil.toDIPFromPixel(mMeasureBuffer[2]);
  16.       float height = PixelUtil.toDIPFromPixel(mMeasureBuffer[3]);
  17.       successCallback.invoke(relativeX, relativeY, width, height);
  18.     } catch (IllegalViewOperationException e) {
  19.       errorCallback.invoke(e.getMessage());
  20.     }
  21.   }
  23. ...

使用以下方法可以来访问在 JavaScript 里面可以使用：

  1. UIManager.measureLayout(
  2.   100,
  3.   100,
  4.   (msg) => {
  5.     console.log(msg);
  6.   },
  7.   (x, y, width, height) => {
  8.     console.log(x + ':' + y + ':' + width + ':' + height);
  9.   }
  10. );

一个原生模块支持只调用一次它的回调。它可以保存这个回调，并且在以后调用。

有一点需要强调的就是在原生方法完成之后这个回调并不是立即被调用的－请记住桥接通信是异步的，因此这个也在运行时循环里面。

线程

原生模块不应该设想有它们将在哪些线程里面被调用，因为目前的任务在以后改变是主要的。如果一个块调用是必须的，那么耗时操作将会被分配到间歇性的工作线程中，并且任何回调将会从这里开始。

给 JavaScript 传递事件

原生模块可以不需要立即被调用就可以给 JavaScript 发送事件。最简单的方式就是使用从 ReactContext 获得的 RCTDeviceEventEmitter，就像下面的代码片段：

  1. ...
  2. private void sendEvent(ReactContext reactContext,
  3.                        String eventName,
  4.                        @Nullable WritableMap params) {
  5.   reactContext
  6.       .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
  7.       .emit(eventName, params);
  8. }
  9. ...
  10. WritableMap params = Arguments.createMap();
  11. ...
  12. sendEvent(reactContext, "keyboardWillShow", params);

JavaScript 模块在那时可以通过使用 Subscribable 的 addListenerOn 来注册并且接收事件。

  1. var RCTDeviceEventEmitter = require('RCTDeviceEventEmitter');
  2. ...
  4. var ScrollResponderMixin = {
  5.   mixins: [Subscribable.Mixin],
  8.   componentWillMount: function() {
  9.     ...
  10.     this.addListenerOn(RCTDeviceEventEmitter,
  11.                        'keyboardWillShow',
  12.                        this.scrollResponderKeyboardWillShow);
  13.     ...
  14.   },
  15.   scrollResponderKeyboardWillShow:function(e: Event) {
  16.     this.keyboardWillOpenTo = e;
  17.     this.props.onKeyboardWillShow && this.props.onKeyboardWillShow(e);
  18.   },