Native 模块(iOS)

有时一个应用程序需要访问平台 API，React Native 并没有相应的封装器。也许你想重用现有的一些 Objective——C 或 C++ 代码，无需在 JavaScript 上重新实现。或者写一些高性能，多线程的代码，如图像处理、网络堆栈，数据库或渲染。

我们设计 React Native，这样可以为你写真正的本地代码，并且能够访问整个平台。这是一个更高级的特性，且我们并不期望它成为通常开发过程的一部分，但是它的存在是至关重要的。如果 React Native 不支持你需要的本地特性，那么你应该能够自己构建它。

这是一个更高级的指南，展示了如何构建一个本地模块。它假设读者知道 Objective-C(Swift 还没有支持)和核心库(Foundation,UIKit)。

iOS 日历模块的例子

本指南将使用 iOS 日历 API 的例子。假设我们希望能够从 JavaScript 访问 iOS 日历。

Native 模块只是一个 Objectve-C 类，实现了 RCTBridgeModule 协议。如果你想知道，RCT 是 ReaCT 的一个简称。

  1.     // CalendarManager.h
  2.     #import "RCTBridgeModule.h"
  3.     #import "RCTLog.h"
  4.     @interface CalendarManager : NSObject <RCTBridgeModule>
  5.     @end

React Native 不会向 JavaScript 公开任何 CalendarManager 方法，除非有明确的要求。幸运的是有了 RCT_EXPORT，这会非常简单：

  1.     // CalendarManager.m
  2.     @implementation CalendarManager
  3.     - (void)addEventWithName:(NSString *)name location:(NSString *)location
  4.     {
  5.           RCT_EXPORT();
  6.           RCTLogInfo(@"Pretending to create an event %@ at %@", name, location);
  7.     }
  8.     @end

现在从你的 JavaScript 文件中，你可以像这样调用方法：

  1.     var CalendarManager = require('NativeModules').CalendarManager;
  2.     CalendarManager.addEventWithName('Birthday Party', '4 Privet Drive, Surrey');

注意，导出的方法名称是从 Objective-C 选择器的第一部分中生成的。有时它会产生一个非惯用的 JavaScript 名称(就像在我们的例子中的那个)。你可以通过为 RCT_EXPORT 提供一个可选参数更改名字，如 RCT_EXPORT(addEvent)。

方法返回的类型应该是 void。React Native 桥是异步的,所以向 JavaScript 传递结果的唯一方法是使用回调或 emitting 事件(见下文)。

参数类型

React Native 支持多种参数类型，可以从 JavaScript 代码传递到 native 模块：

  • 字符串型(NSString)
  • 数字型(NSInteger，float,double ,CGFloat,NSNumber)
  • 布尔型(BOOL,NSNumber)
  • 这个列表中任何类型的数组(NSArray)
  • 这个列表中任何类型的字符串键和值的映射(NSDictionary)
  • 函数(RCTResponseSenderBlock)

在我们的 CalendarManager 示例中,如果我们想把事件日期传递到 native，我们必须将它转换成一个字符串或一个数字：

  1.     - (void)addEventWithName:(NSString *)name location:(NSString *)location date:(NSInteger)secondsSinceUnixEpoch
  2.     {
  3.           RCT_EXPORT(addEvent);
  4.           NSDate *date = [NSDate dateWithTimeIntervalSince1970:secondsSinceUnixEpoch];
  5.     }

随着 CalendarManager.addEvent 方法变得越来越复杂，参数的数量将会增加。其中一些可能是可选的。在这种情况下对改变 API 一点来接受事件属性的字典是值得考虑的，如：

  1.     #import "RCTConvert.h"
  2.     - (void)addEventWithName:(NSString *)name details:(NSDictionary *)details
  3.     {
  4.           RCT_EXPORT(addEvent);
  5.           NSString *location = [RCTConvert NSString:details[@"location"]]; // ensure location is a string
  6.           ...
  7.     }

并且从 JavaScript 调用它：

  1.     CalendarManager.addEvent('Birthday Party', {
  2.           location: '4 Privet Drive, Surrey',
  3.           time: date.toTime(),
  4.           description: '...'
  5.     })

注意：关于数组和映射

React Ntive 没有为这些结构中值的类型提供任何担保。你的 native 模块可能期望一个字符串数组，但如果 JavaScript 调用你的包含数字和字符串数组的方法，你会得到带有 NSNumber 和 NSString 的 NSArray。检查数组/映射值类型是开发人员的责任 (助手方法见 RCTConvert)。

回调

警告

本节比其他更具有实验性，围绕回调我们没有得到一组最佳实践。

Native 模块还支持一种特殊的参数——回调。在大多数情况下它是用来向 JavaScript 提供函数调用结果的。

  1.     - (void)findEvents:(RCTResponseSenderBlock)callback
  2.     {
  3.           RCT_EXPORT();
  4.           NSArray *events = ...
  5.           callback(@[[NSNull null], events]);
  6.     }

RCTResponseSenderBlock 只接受一个参数——参数的数组传递给 JavaScript 的回调。在本例中，我们使用节点的惯例来为 error 和其他的——函数的结果设置第一个参数。

  1. CalendarManager.findEvents((error, events) => {
  2.   if (error) {
  3.     console.error(error);
  4.   } else {
  5.     this.setState({events: events});
  6.   }
  7. })

Native 模块应该只调用它的回调一次。然而，它可以将回调作为 ivar 存储并稍后调用回调。这种模式通常用于包装需要委托的 iOS 的 APIs。请看 RCTAlertManager。

如果你想向 JavaScript 传递 error ——如对象，使用 RCTUtils.h 的 RCTMakeError。

实现 native 模块

Native 模块应该没有任何关于什么线程正在被调用的假设。React Native 在一个单独的串行 GCD 队列中调用 native 模块方法，但这是一个实现细节，可能会改变。如果 native 模块需要调用 main-thread-only iOS API，它应该在主队列安排操作：

  1. - (void)addEventWithName:(NSString *)name callback:(RCTResponseSenderBlock)callback
  2. {
  3.   RCT_EXPORT(addEvent);
  4.   dispatch_async(dispatch_get_main_queue(), ^{
  5.     // Call iOS API on main thread
  6.     ...
  7.     // You can invoke callback from any thread/queue
  8.     callback(@[...]);
  9.   });
  10. }

同样的方法，如果操作要很长时间才能完成，native 模块不应该阻塞。使用 dispatch_async 在后台队列中安排耗费大的工作是一个好主意。

导出常量

Native 模块可以在运行时向 JavaScript 导出立即可用的常量。导出一些初始数据是有用的，否则这些初始数据需要往返的桥梁。

  1. - (NSDictionary *)constantsToExport
  2. {
  3.   return @{ @"firstDayOfTheWeek": @"Monday" };
  4. }

JavaScript 能够立即使用这些值：

  1. console.log(CalendarManager.firstDayOfTheWeek);

注意，只有在初始化时常量才能被导出，所以如果你在运行时改变了 constantsToExport 的值，它不会影响 JavaScript 环境。

发送事件到 JavaScript

Native 模块可以在不被直接调用的情况下向 JavaScript 发送事件信号。最简单的方法是使用 eventDispatcher：

  1.     #import "RCTBridge.h"
  2.     #import "RCTEventDispatcher.h"
  3.     @implementation CalendarManager
  4.     @synthesize bridge = _bridge;
  5.     - (void)calendarEventReminderReceived:(NSNotification *)notification
  6.     {
  7.           NSString *eventName = notification.userInfo[@"name"];
  8.           [self.bridge.eventDispatcher sendAppEventWithName:@"EventReminder"
  9.                                                body:@{@"name": eventName}];
  10.     }
  11.     @end

JavaScript 代码可以订阅这些事件：

  1. var subscription = DeviceEventEmitter.addListener(
  2.   'EventReminder',
  3.   (reminder) => console.log(reminder.name)
  4. );
  5. ...
  6. // Don't forget to unsubscribe
  7. subscription.remove();

更多的向 JavaScript 发送事件的例子，请看 RCTLocationObserver。