Native UI 组件(iOS)

有许多 native UI 小部件可以应用到最新的应用程序中——其中一些是平台的一部分，另外的可以用作第三方库，并且更多的是它们可以用于你自己的选集中。React Native 有几个最关键的平台组件已经包装好了，如 ScrollView 和 TextInput，但不是所有的组件都被包装好了，当然了，你为先前的应用程序写的组件肯定没有包装好。幸运的是，为了与 React Native 应用程序无缝集成，将现存组件包装起来是非常容易实现的。

正如 native 模块指南，这也是一种更高级的指南，假定你对 iOS 编程有一定的了解。本指南将向你展示如何构建一个本地的 UI 组件，带你实现在核心 React Native 库中可用的现存的 MapView 组件的子集。

iOS MapView 示例

如果说我们想在我们的应用程序中添加一个交互式的 Map——不妨用 MKMapView，我们只需要让它在 JavaScript 中可用。

Native 视图是通过 RCTViewManager 的子类创建和操做的。这些子类的功能与视图控制器很相似，但本质上它们是单件模式——桥只为每一个子类创建一个实例。它们将 native 视图提供给 RCTUIManager，它会传回到 native 视图来设置和更新的必要的视图属性。RCTViewManager 通常也是视图的代表，通过桥将事件发送回 JavaScript。

发送视图是很简单的：

• 创建基本的子类。

• 添加标记宏 RCT_EXPORT_MODULE()。

• 实现 -(UIView *)view 方法。

// RCTMapManager.m
#import <MapKit/MapKit.h>
#import "RCTViewManager.h"
@interface RCTMapManager : RCTViewManager
@end
@implementation RCTMapManager
RCT_EXPORT_MODULE()
- (UIView *)view
{
  return [[MKMapView alloc] init];
}
@end

然后你需要一些 JavaScript 使之成为有用的 React 组件：

// MapView.js
var { requireNativeComponent } = require('react-native');
module.exports = requireNativeComponent('RCTMap', null);

现在这是 JavaScript 中一个功能完整的 native map 视图组件了，包括 pinch-zoom 和其他 native 手势支持。但是我们还不能用 JavaScript 来真正的控制它。

属性

为了使该组件更可用，我们可以做的第一件事是连接一些 native 属性。比如说我们希望能够禁用音高控制并指定可见区域。禁用音高是一个简单的布尔值，所以我们只添加这一行:

// RCTMapManager.m
RCT_EXPORT_VIEW_PROPERTY(pitchEnabled, BOOL)

注意我们显式的指定类型为 BOOL——当谈到连接桥时，React Native 使用 hood 下的 RCTConvert 来转换所有不同的数据类型，且错误的值会显示明显的 “RedBox” 错误使你知道这里有 ASAP 问题。当一切进展顺利时，这个宏就会为你处理整个实现。

现在要真正的实现禁用音高，我们只需要在 JS 中设置如下所示属性：

// MyApp.js
<MapView pitchEnabled={false} />

但是这不是很好记录——为了知道哪些属性可用以及它们接收了什么值，你的新组件的客户端需要挖掘 objective-C 代码。为了更好的实现这一点，让我们做一个包装器组件并用 React PropTypes 记录接口：

// MapView.js
var React = require('react-native');
var { requireNativeComponent } = React;
class MapView extends React.Component {
  render() {
    return <RCTMap {...this.props} />;
  }
}
var RCTMap = requireNativeComponent('RCTMap', MapView);
MapView.propTypes = {
  /**
   * When this property is set to `true` and a valid camera is associated
   * with the map, the camera’s pitch angle is used to tilt the plane
   * of the map. When this property is set to `false`, the camera’s pitch
   * angle is ignored and the map is always displayed as if the user
   * is looking straight down onto it.
   */
  pitchEnabled: React.PropTypes.bool,
};
module.exports = MapView;

现在我们有一个很不错的已记录的包装器组件，它使用非常容易。注意我们为新的 MapView 包装器组件将第二个参数从 null 改为 requireNativeComponent。这使得基础设施验证了 propTypes 匹配native 工具来减少 ObjC 和 JS 代码之间的不匹配的可能。

接下来，让我们添加更复杂的 region 工具。从添加 native 代码入手：

// RCTMapManager.m
RCT_CUSTOM_VIEW_PROPERTY(region, MKCoordinateRegion, RCTMap)
{
  [view setRegion:json ? [RCTConvert MKCoordinateRegion:json] : defaultView.region animated:YES];
}

好的，这显然比之前简单的 BOOL 情况更加复杂。现在我们有一个 MKCoordinateRegion 类型，该类型需要一个转换函数，并且我们有自定义的代码，这样当我们从 JS 设置区域时，视图可以产生动画效果。还有一个 defaultView，如果 JS 发送给我们一个 null 标记，我们使用它将属性重置回默认值。

当然你可以为你的视图编写任何你想要的转换函数——下面是通过 RCTConvert 的两类来实现 MKCoordinateRegion 的例子：

@implementation RCTConvert(CoreLocation)
RCT_CONVERTER(CLLocationDegrees, CLLocationDegrees, doubleValue);
RCT_CONVERTER(CLLocationDistance, CLLocationDistance, doubleValue);
+ (CLLocationCoordinate2D)CLLocationCoordinate2D:(id)json
{
  json = [self NSDictionary:json];
  return (CLLocationCoordinate2D){
    [self CLLocationDegrees:json[@"latitude"]],
    [self CLLocationDegrees:json[@"longitude"]]
  };
}
@end
@implementation RCTConvert(MapKit)
+ (MKCoordinateSpan)MKCoordinateSpan:(id)json
{
  json = [self NSDictionary:json];
  return (MKCoordinateSpan){
    [self CLLocationDegrees:json[@"latitudeDelta"]],
    [self CLLocationDegrees:json[@"longitudeDelta"]]
  };
}
+ (MKCoordinateRegion)MKCoordinateRegion:(id)json
{
  return (MKCoordinateRegion){
    [self CLLocationCoordinate2D:json],
    [self MKCoordinateSpan:json]
  };
}

这些转换函数是为了安全地处理任何 JSON 而设计的，当出现丢失的键或开发人员错误操作时，JS 可能向它们抛出 “RedBox” 错误并返回标准的初始化值。

为完成对 region 工具的支持，我们需要把它记录到 propTypes中(否则我们将得到一个错误，即 native 工具没有被记录)，然后我们就可以按照设置其他工具的方式来设置它：

// MapView.js
MapView.propTypes = {
  /**
   * When this property is set to `true` and a valid camera is associated
   * with the map, the camera’s pitch angle is used to tilt the plane
   * of the map. When this property is set to `false`, the camera’s pitch
   * angle is ignored and the map is always displayed as if the user
   * is looking straight down onto it.
   */
  pitchEnabled: React.PropTypes.bool,
  /**
   * The region to be displayed by the map.
   *
   * The region is defined by the center coordinates and the span of
   * coordinates to display.
   */
  region: React.PropTypes.shape({
    /**
     * Coordinates for the center of the map.
     */
    latitude: React.PropTypes.number.isRequired,
    longitude: React.PropTypes.number.isRequired,
    /**
     * Distance between the minimum and the maximum latitude/longitude
     * to be displayed.
     */
    latitudeDelta: React.PropTypes.number.isRequired,
    longitudeDelta: React.PropTypes.number.isRequired,
  }),
};
// MyApp.js
  render() {
    var region = {
      latitude: 37.48,
      longitude: -122.16,
      latitudeDelta: 0.1,
      longitudeDelta: 0.1,
    };
    return <MapView region={region} />;
  }

在这里你可以看到该区域的形状在 JS 文档中是显式的——理想情况下我们可以生成一些这方面的东西，但是这没有实现。

事件

所以现在我们有一个 native map 组件，可以从 JS 很容易的控制，但是我们如何处理来自用户的事件，如 pinch-zooms 或平移来改变可见区域？关键是要使 RCTMapManager 成为它发送的所有视图的代表，并把事件通过事件调度器发送给 JS。这看起来如下所示(从整个实现中简化出来的部分)：

// RCTMapManager.m
#import "RCTMapManager.h"
#import <MapKit/MapKit.h>
#import "RCTBridge.h"
#import "RCTEventDispatcher.h"
#import "UIView+React.h"
@interface RCTMapManager() <MKMapViewDelegate>
@end
@implementation RCTMapManager
RCT_EXPORT_MODULE()
- (UIView *)view
{
  MKMapView *map = [[MKMapView alloc] init];
  map.delegate = self;
  return map;
}
#pragma mark MKMapViewDelegate
- (void)mapView:(RCTMap *)mapView regionDidChangeAnimated:(BOOL)animated
{
  MKCoordinateRegion region = mapView.region;
  NSDictionary *event = @{
    @"target": mapView.reactTag,
    @"region": @{
      @"latitude": @(region.center.latitude),
      @"longitude": @(region.center.longitude),
      @"latitudeDelta": @(region.span.latitudeDelta),
      @"longitudeDelta": @(region.span.longitudeDelta),
    }
  };
  [self.bridge.eventDispatcher sendInputEventWithName:@"topChange" body:event];
}

你可以看到我们设置管理器为它发送的每个视图的代表，然后在代表方法 -mapView:regionDidChangeAnimated: 中，区域与 reactTag 目标相结合来产生事件，通过 sendInputEventWithName:body 分派到你应用程序中相应的 React 组件实例中。事件名称 @"topChange" 映射到从 JavaScript 中回调的 onChange（这里查看 mappings ）。原始事件调用这个回调，我们通常在包装器组件中处理这个过程来实现一个简单的 API：

// MapView.js
class MapView extends React.Component {
  constructor() {
    this._onChange = this._onChange.bind(this);
  }
  _onChange(event: Event) {
    if (!this.props.onRegionChange) {
      return;
    }
    this.props.onRegionChange(event.nativeEvent.region);
  }
  render() {
    return <RCTMap {...this.props} onChange={this._onChange} />;
  }
}
MapView.propTypes = {
  /**
   * Callback that is called continuously when the user is dragging the map.
   */
  onRegionChange: React.PropTypes.func,
  ...
}; 

样式

由于我们所有的 native react 视图是 UIView 的子类，大多数样式属性会像你预想的一样内存不足。然而，一些组件需要默认的样式，例如 UIDatePicker，大小固定。为了达到预期的效果，默认样式对布局算法来说是非常重要的，但是我们也希望在使用组件时能够覆盖默认的样式。DatePickerIOS 通过包装一个额外的视图中的 native 组件实现这一功能，该额外的视图具有灵活的样式设计，并在内部 native 组件中使用一个固定的样式(用从 native 传递的常量生成)：

// DatePickerIOS.ios.js
var RCTDatePickerIOSConsts = require('NativeModules').UIManager.RCTDatePicker.Constants;
...
  render: function() {
    return (
      <View style={this.props.style}>
        <RCTDatePickerIOS
          ref={DATEPICKER}
          style={styles.rkDatePickerIOS}
          ...
        />
      </View>
    );
  }
});
var styles = StyleSheet.create({
  rkDatePickerIOS: {
    height: RCTDatePickerIOSConsts.ComponentHeight,
    width: RCTDatePickerIOSConsts.ComponentWidth,
  },
});

RCTDatePickerIOSConsts 常量是通过抓取 native 组件的实际框架从 native 中导出的，如下所示：

// RCTDatePickerManager.m
- (NSDictionary *)constantsToExport
{
  UIDatePicker *dp = [[UIDatePicker alloc] init];
  [dp layoutIfNeeded];
  return @{
    @"ComponentHeight": @(CGRectGetHeight(dp.frame)),
    @"ComponentWidth": @(CGRectGetWidth(dp.frame)),
    @"DatePickerModes": @{
      @"time": @(UIDatePickerModeTime),
      @"date": @(UIDatePickerModeDate),
      @"datetime": @(UIDatePickerModeDateAndTime),
    }
  };
}

本指南涵盖了衔接自定义 native 组件的许多方面，但有你可能有更多需要考虑的地方，如自定义 hooks 来插入和布局子视图。如果你想了解更多，请在源代码中查看实际的 RCTMapManager 和其他组件。