Facebook/react-native
1
0
Fork 0
mirror of https://github.com/facebook/react-native.git synced 2025-11-01 09:14:26 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e2e489b17ba4e5cb83a1a7068a6b98f8fd5f3e08
react-native/docs/nativecomponentsios.html
T
Travis CI cca4409e70 update website
2015-05-07 23:07:58 +00:00

238 lines
46 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"><title>React Native | A framework for building native apps using React</title><meta name="viewport" content="width=device-width"><meta property="og:title" content="React Native | A framework for building native apps using React"><meta property="og:type" content="website"><meta property="og:url" content="http://facebook.github.io/react-native/index.html"><meta property="og:image" content="http://facebook.github.io/react-native/img/opengraph.png?2"><meta property="og:description" content="A framework for building native apps using React"><link rel="shortcut icon" href="/react-native/img/favicon.png?2"><link rel="stylesheet" href="/react-native/css/react-native.css"><script type="text/javascript" src="//use.typekit.net/vqa1hcx.js"></script><script type="text/javascript">try{Typekit.load();}catch(e){}</script></head><body><div class="container"><div class="nav-main"><div class="wrap"><a class="nav-home" href="/react-native/"><img src="/react-native/img/header_logo.png">React Native</a><div class="nav-site-wrapper"><ul class="nav-site nav-site-internal"><li><a href="/react-native/docs/getting-started.html" class="active">Docs</a></li><li><a href="/react-native/support.html" class="">Support</a></li></ul><ul class="nav-site nav-site-external"><li><a href="https://github.com/facebook/react-native" class="">GitHub</a></li><li><a href="http://facebook.github.io/react" class="">React</a></li></ul></div></div></div><section class="content wrap documentationContent"><div class="nav-docs"><div class="nav-docs-section"><h3>Quick Start</h3><ul><li><a style="margin-left:0;" class="" href="/react-native/docs/getting-started.html#content">Getting Started</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/tutorial.html#content">Tutorial</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/videos.html#content">Videos</a></li></ul></div><div class="nav-docs-section"><h3>Guides</h3><ul><li><a style="margin-left:0;" class="" href="/react-native/docs/style.html#content">Style</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/gesture-responder-system.html#content">Gesture Responder System</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/nativemodulesios.html#content">Native Modules (iOS)</a></li><li><a style="margin-left:0;" class="active" href="/react-native/docs/nativecomponentsios.html#content">Native UI Components (iOS)</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/linking-libraries.html#content">Linking Libraries</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/debugging.html#content">Debugging</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/testing.html#content">Testing</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/runningondevice.html#content">Running On Device</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/embedded-app.html#content">Integration with Existing App</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/javascript-environment.html#content">JavaScript Environment</a></li></ul></div><div class="nav-docs-section"><h3>components</h3><ul><li><a style="margin-left:0;" class="" href="/react-native/docs/activityindicatorios.html#content">ActivityIndicatorIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/datepickerios.html#content">DatePickerIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/image.html#content">Image</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/listview.html#content">ListView</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/mapview.html#content">MapView</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/navigator.html#content">Navigator</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/navigatorios.html#content">NavigatorIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/pickerios.html#content">PickerIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/scrollview.html#content">ScrollView</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/sliderios.html#content">SliderIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/switchios.html#content">SwitchIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/tabbarios.html#content">TabBarIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/tabbarios-item.html#content">TabBarIOS.Item</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/text.html#content">Text</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/textinput.html#content">TextInput</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/touchablehighlight.html#content">TouchableHighlight</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/touchableopacity.html#content">TouchableOpacity</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/touchablewithoutfeedback.html#content">TouchableWithoutFeedback</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/view.html#content">View</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/webview.html#content">WebView</a></li></ul></div><div class="nav-docs-section"><h3>apis</h3><ul><li><a style="margin-left:0;" class="" href="/react-native/docs/alertios.html#content">AlertIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/appregistry.html#content">AppRegistry</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/appstateios.html#content">AppStateIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/asyncstorage.html#content">AsyncStorage</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/cameraroll.html#content">CameraRoll</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/interactionmanager.html#content">InteractionManager</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/layoutanimation.html#content">LayoutAnimation</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/linkingios.html#content">LinkingIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/netinfo.html#content">NetInfo</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/panresponder.html#content">PanResponder</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/pixelratio.html#content">PixelRatio</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/pushnotificationios.html#content">PushNotificationIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/statusbarios.html#content">StatusBarIOS</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/stylesheet.html#content">StyleSheet</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/vibrationios.html#content">VibrationIOS</a></li></ul></div><div class="nav-docs-section"><h3>Polyfills</h3><ul><li><a style="margin-left:0;" class="" href="/react-native/docs/flexbox.html#content">Flexbox</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/geolocation.html#content">Geolocation</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/network.html#content">Network</a></li><li><a style="margin-left:0;" class="" href="/react-native/docs/timers.html#content">Timers</a></li></ul></div></div><div class="inner-content"><a id="content"></a><h1>Native UI Components (iOS)</h1><div><p>There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like <code>ScrollView</code> and <code>TextInput</code>, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, it&#x27;s quite easy to wrap up these existing components for seamless integration with your React Native application.</p><p>Like the native module guide, this too is a more advanced guide that assumes you are somewhat familiar with iOS programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing <code>MapView</code> component available in the core React Native library.</p><h2><a class="anchor" name="ios-mapview-example"></a>iOS MapView example <a class="hash-link" href="#ios-mapview-example">#</a></h2><p>Let&#x27;s say we want to add an interactive Map to our app - might as well use <a href="https://developer.apple.com/library/prerelease/mac/documentation/MapKit/Reference/MKMapView_Class/index.html" target="_blank"><code>MKMapView</code></a>, we just need to make it usable from JavaScript.</p><p>Native views are created and manipulated by subclasses of <code>RCTViewManager</code>. These subclasses are similar in function to view controllers, but are essentially singletons - only one instance of each is created by the bridge. They vend native views to the <code>RCTUIManager</code>, which delegates back to them to set and update the properties of the views as necessary. The <code>RCTViewManager</code>s are also typically the delegates for the views, sending events back to JavaScript via the bridge.</p><p>Vending a view is simple:</p><ul><li>Create the basic subclass.</li><li>Add the <code>RCT_EXPORT_MODULE()</code> marker macro.</li><li>Implement the <code>-(UIView *)view</code> method</li></ul><div class="prism language-javascript"><span class="token comment" spellcheck="true">// RCTMapManager.m
</span>#import &lt;MapKit<span class="token operator">/</span>MapKit<span class="token punctuation">.</span>h<span class="token operator">&gt;</span>
#import <span class="token string">&quot;RCTViewManager.h&quot;</span>
@interface <span class="token class-name">RCTMapManager</span> <span class="token punctuation">:</span> RCTViewManager
@end
@implementation RCTMapManager
<span class="token function">RCT_EXPORT_MODULE<span class="token punctuation">(</span></span><span class="token punctuation">)</span>
<span class="token operator">-</span> <span class="token punctuation">(</span>UIView <span class="token operator">*</span><span class="token punctuation">)</span>view
<span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token punctuation">[</span><span class="token punctuation">[</span>MKMapView alloc<span class="token punctuation">]</span> init<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
@end</div><p>Then you just need a little bit of JavaScript to make this a usable React component:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// MapView.js
</span>
<span class="token keyword">var</span> <span class="token punctuation">{</span> requireNativeComponent <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">require<span class="token punctuation">(</span></span><span class="token string">&#x27;react-native&#x27;</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
module<span class="token punctuation">.</span>exports <span class="token operator">=</span> <span class="token function">requireNativeComponent<span class="token punctuation">(</span></span><span class="token string">&#x27;RCTMap&#x27;</span><span class="token punctuation">,</span> <span class="token keyword">null</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div><p>This is now a fully-functioning native map view component in JavaScript, complete with pinch-zoom and other native gesture support. We can&#x27;t really control it from JavaScript yet, though :(</p><h2><a class="anchor" name="properties"></a>Properties <a class="hash-link" href="#properties">#</a></h2><p>The first thing we can do to make this component more usable is to bridge over some native properties. Let&#x27;s say we want to be able to disable pitch control and specify the visible region. Disabling pitch is a simple boolean, so we just add this one line:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// RCTMapManager.m
</span><span class="token function">RCT_EXPORT_VIEW_PROPERTY<span class="token punctuation">(</span></span>pitchEnabled<span class="token punctuation">,</span> BOOL<span class="token punctuation">)</span></div><p>Note that we explicitly specify the type as <code>BOOL</code> - React Native uses <code>RCTConvert</code> under the hood to convert all sorts of different data types when talking over the bridge, and bad values will show convenient &quot;RedBox&quot; errors to let you know there is an issue ASAP. When things are straightforward like this, the whole implementation is taken care of for you by this macro.</p><p>Now to actually disable pitch, we just set the property in JS:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// MyApp.js
</span>&lt;MapView pitchEnabled<span class="token operator">=</span><span class="token punctuation">{</span><span class="token boolean">false</span><span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">&gt;</span></div><p>This isn&#x27;t very well documented though - in order to know what properties are available and what values they accept, the client of your new component needs to dig through the Objective-C code. To make this better, let&#x27;s make a wrapper component and document the interface with React <code>PropTypes</code>:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// MapView.js
</span><span class="token keyword">var</span> React <span class="token operator">=</span> <span class="token function">require<span class="token punctuation">(</span></span><span class="token string">&#x27;react-native&#x27;</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">var</span> <span class="token punctuation">{</span> requireNativeComponent <span class="token punctuation">}</span> <span class="token operator">=</span> React<span class="token punctuation">;</span>
class <span class="token class-name">MapView</span> extends <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
<span class="token function">render<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> &lt;RCTMap <span class="token punctuation">{</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">&gt;</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
<span class="token keyword">var</span> RCTMap <span class="token operator">=</span> <span class="token function">requireNativeComponent<span class="token punctuation">(</span></span><span class="token string">&#x27;RCTMap&#x27;</span><span class="token punctuation">,</span> MapView<span class="token punctuation">)</span><span class="token punctuation">;</span>
MapView<span class="token punctuation">.</span>propTypes <span class="token operator">=</span> <span class="token punctuation">{</span>
<span class="token comment" spellcheck="true">/**
* 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.
*/</span>
pitchEnabled<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>bool<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
module<span class="token punctuation">.</span>exports <span class="token operator">=</span> MapView<span class="token punctuation">;</span></div><p>Now we have a nicely documented wrapper component that is easy to work with. Note that we changed the second argument to <code>requireNativeComponent</code> from <code>null</code> to the new <code>MapView</code> wrapper component. This allows the infrastructure to verify that the propTypes match the native props to reduce the chances of mismatches between the ObjC and JS code.</p><p>Next, let&#x27;s add the more complex <code>region</code> prop. We start by adding the native code:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// RCTMapManager.m
</span><span class="token function">RCT_CUSTOM_VIEW_PROPERTY<span class="token punctuation">(</span></span>region<span class="token punctuation">,</span> MKCoordinateRegion<span class="token punctuation">,</span> RCTMap<span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token punctuation">[</span>view setRegion<span class="token punctuation">:</span>json <span class="token operator">?</span> <span class="token punctuation">[</span>RCTConvert MKCoordinateRegion<span class="token punctuation">:</span>json<span class="token punctuation">]</span> <span class="token punctuation">:</span> defaultView<span class="token punctuation">.</span>region animated<span class="token punctuation">:</span>YES<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>Ok, this is clearly more complicated than the simple <code>BOOL</code> case we had before. Now we have a <code>MKCoordinateRegion</code> type that needs a conversion function, and we have custom code so that the view will animate when we set the region from JS. There is also a <code>defaultView</code> that we use to reset the property back to the default value if JS sends us a null sentinel.</p><p>You could of course write any conversion function you want for your view - here is the implementation for <code>MKCoordinateRegion</code> via two categories on <code>RCTConvert</code>:</p><div class="prism language-javascript">@implementation <span class="token function">RCTConvert<span class="token punctuation">(</span></span>CoreLocation<span class="token punctuation">)</span>
<span class="token function">RCT_CONVERTER<span class="token punctuation">(</span></span>CLLocationDegrees<span class="token punctuation">,</span> CLLocationDegrees<span class="token punctuation">,</span> doubleValue<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token function">RCT_CONVERTER<span class="token punctuation">(</span></span>CLLocationDistance<span class="token punctuation">,</span> CLLocationDistance<span class="token punctuation">,</span> doubleValue<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token operator">+</span> <span class="token punctuation">(</span>CLLocationCoordinate2D<span class="token punctuation">)</span>CLLocationCoordinate2D<span class="token punctuation">:</span><span class="token punctuation">(</span>id<span class="token punctuation">)</span>json
<span class="token punctuation">{</span>
json <span class="token operator">=</span> <span class="token punctuation">[</span>self NSDictionary<span class="token punctuation">:</span>json<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span>CLLocationCoordinate2D<span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span>self CLLocationDegrees<span class="token punctuation">:</span>json<span class="token punctuation">[</span>@<span class="token string">&quot;latitude&quot;</span><span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">[</span>self CLLocationDegrees<span class="token punctuation">:</span>json<span class="token punctuation">[</span>@<span class="token string">&quot;longitude&quot;</span><span class="token punctuation">]</span><span class="token punctuation">]</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
@end
@implementation <span class="token function">RCTConvert<span class="token punctuation">(</span></span>MapKit<span class="token punctuation">)</span>
<span class="token operator">+</span> <span class="token punctuation">(</span>MKCoordinateSpan<span class="token punctuation">)</span>MKCoordinateSpan<span class="token punctuation">:</span><span class="token punctuation">(</span>id<span class="token punctuation">)</span>json
<span class="token punctuation">{</span>
json <span class="token operator">=</span> <span class="token punctuation">[</span>self NSDictionary<span class="token punctuation">:</span>json<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span>MKCoordinateSpan<span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span>self CLLocationDegrees<span class="token punctuation">:</span>json<span class="token punctuation">[</span>@<span class="token string">&quot;latitudeDelta&quot;</span><span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">[</span>self CLLocationDegrees<span class="token punctuation">:</span>json<span class="token punctuation">[</span>@<span class="token string">&quot;longitudeDelta&quot;</span><span class="token punctuation">]</span><span class="token punctuation">]</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token operator">+</span> <span class="token punctuation">(</span>MKCoordinateRegion<span class="token punctuation">)</span>MKCoordinateRegion<span class="token punctuation">:</span><span class="token punctuation">(</span>id<span class="token punctuation">)</span>json
<span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span>MKCoordinateRegion<span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span>self CLLocationCoordinate2D<span class="token punctuation">:</span>json<span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">[</span>self MKCoordinateSpan<span class="token punctuation">:</span>json<span class="token punctuation">]</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>These conversion functions are designed to safely process any JSON that the JS might throw at them by displaying &quot;RedBox&quot; errors and returning standard initialization values when missing keys or other developer errors are encountered.</p><p>To finish up support for the <code>region</code> prop, we need to document it in <code>propTypes</code> (or we&#x27;ll get an error that the native prop is undocumented), then we can set it just like any other prop:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// MapView.js
</span>
MapView<span class="token punctuation">.</span>propTypes <span class="token operator">=</span> <span class="token punctuation">{</span>
<span class="token comment" spellcheck="true">/**
* 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.
*/</span>
pitchEnabled<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>bool<span class="token punctuation">,</span>
<span class="token comment" spellcheck="true">/**
* The region to be displayed by the map.
*
* The region is defined by the center coordinates and the span of
* coordinates to display.
*/</span>
region<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span><span class="token function">shape<span class="token punctuation">(</span></span><span class="token punctuation">{</span>
<span class="token comment" spellcheck="true">/**
* Coordinates for the center of the map.
*/</span>
latitude<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>number<span class="token punctuation">.</span>isRequired<span class="token punctuation">,</span>
longitude<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>number<span class="token punctuation">.</span>isRequired<span class="token punctuation">,</span>
<span class="token comment" spellcheck="true">/**
* Distance between the minimum and the maximum latitude/longitude
* to be displayed.
*/</span>
latitudeDelta<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>number<span class="token punctuation">.</span>isRequired<span class="token punctuation">,</span>
longitudeDelta<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>number<span class="token punctuation">.</span>isRequired<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token comment" spellcheck="true">
// MyApp.js
</span>
<span class="token function">render<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">var</span> region <span class="token operator">=</span> <span class="token punctuation">{</span>
latitude<span class="token punctuation">:</span> <span class="token number">37.48</span><span class="token punctuation">,</span>
longitude<span class="token punctuation">:</span> <span class="token operator">-</span><span class="token number">122.16</span><span class="token punctuation">,</span>
latitudeDelta<span class="token punctuation">:</span> <span class="token number">0.1</span><span class="token punctuation">,</span>
longitudeDelta<span class="token punctuation">:</span> <span class="token number">0.1</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token keyword">return</span> &lt;MapView region<span class="token operator">=</span><span class="token punctuation">{</span>region<span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">&gt;</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>Here you can see that the shape of the region is explicit in the JS documentation - ideally we could codegen some of this stuff, but that&#x27;s not happening yet.</p><h2><a class="anchor" name="events"></a>Events <a class="hash-link" href="#events">#</a></h2><p>So now we have a native map component that we can control easily from JS, but how do we deal with events from the user, like pinch-zooms or panning to change the visible region? The key is to make the <code>RCTMapManager</code> a delegate for all the views it vends, and forward the events to JS via the event dispatcher. This looks like so (simplified from the full implementation):</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// RCTMapManager.m
</span>
#import <span class="token string">&quot;RCTMapManager.h&quot;</span>
#import &lt;MapKit<span class="token operator">/</span>MapKit<span class="token punctuation">.</span>h<span class="token operator">&gt;</span>
#import <span class="token string">&quot;RCTBridge.h&quot;</span>
#import <span class="token string">&quot;RCTEventDispatcher.h&quot;</span>
#import <span class="token string">&quot;UIView+React.h&quot;</span>
@interface <span class="token class-name">RCTMapManager</span><span class="token punctuation">(</span><span class="token punctuation">)</span> &lt;MKMapViewDelegate<span class="token operator">&gt;</span>
@end
@implementation RCTMapManager
<span class="token function">RCT_EXPORT_MODULE<span class="token punctuation">(</span></span><span class="token punctuation">)</span>
<span class="token operator">-</span> <span class="token punctuation">(</span>UIView <span class="token operator">*</span><span class="token punctuation">)</span>view
<span class="token punctuation">{</span>
MKMapView <span class="token operator">*</span>map <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">[</span>MKMapView alloc<span class="token punctuation">]</span> init<span class="token punctuation">]</span><span class="token punctuation">;</span>
map<span class="token punctuation">.</span>delegate <span class="token operator">=</span> self<span class="token punctuation">;</span>
<span class="token keyword">return</span> map<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
#pragma mark MKMapViewDelegate
<span class="token operator">-</span> <span class="token punctuation">(</span>void<span class="token punctuation">)</span>mapView<span class="token punctuation">:</span><span class="token punctuation">(</span>RCTMap <span class="token operator">*</span><span class="token punctuation">)</span>mapView regionDidChangeAnimated<span class="token punctuation">:</span><span class="token punctuation">(</span>BOOL<span class="token punctuation">)</span>animated
<span class="token punctuation">{</span>
MKCoordinateRegion region <span class="token operator">=</span> mapView<span class="token punctuation">.</span>region<span class="token punctuation">;</span>
NSDictionary <span class="token operator">*</span>event <span class="token operator">=</span> @<span class="token punctuation">{</span>
@<span class="token string">&quot;target&quot;</span><span class="token punctuation">:</span> mapView<span class="token punctuation">.</span>reactTag<span class="token punctuation">,</span>
@<span class="token string">&quot;region&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">{</span>
@<span class="token string">&quot;latitude&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>region<span class="token punctuation">.</span>center<span class="token punctuation">.</span>latitude<span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;longitude&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>region<span class="token punctuation">.</span>center<span class="token punctuation">.</span>longitude<span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;latitudeDelta&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>region<span class="token punctuation">.</span>span<span class="token punctuation">.</span>latitudeDelta<span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;longitudeDelta&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>region<span class="token punctuation">.</span>span<span class="token punctuation">.</span>longitudeDelta<span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">[</span>self<span class="token punctuation">.</span>bridge<span class="token punctuation">.</span>eventDispatcher sendInputEventWithName<span class="token punctuation">:</span>@<span class="token string">&quot;topChange&quot;</span> body<span class="token punctuation">:</span>event<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>You can see we&#x27;re setting the manager as the delegate for every view that it vends, then in the delegate method <code>-mapView:regionDidChangeAnimated:</code> the region is combined with the <code>reactTag</code> target to make an event that is dispatched to the corresponding React component instance in your application via <code>sendInputEventWithName:body:</code>. The event name <code>@&quot;topChange&quot;</code> maps to the <code>onChange</code> callback prop in JavaScript (mappings are <a href="https://github.com/facebook/react-native/blob/master/React/Modules/RCTUIManager.m#L1146" target="_blank">here</a>). This callback is invoked with the raw event, which we typically process in the wrapper component to make a simpler API:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// MapView.js
</span>
class <span class="token class-name">MapView</span> extends <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
<span class="token function">constructor<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>_onChange <span class="token operator">=</span> <span class="token keyword">this</span><span class="token punctuation">.</span>_onChange<span class="token punctuation">.</span><span class="token function">bind<span class="token punctuation">(</span></span><span class="token keyword">this</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token function">_onChange<span class="token punctuation">(</span></span>event<span class="token punctuation">:</span> Event<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token operator">!</span><span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">.</span>onRegionChange<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">.</span><span class="token function">onRegionChange<span class="token punctuation">(</span></span>event<span class="token punctuation">.</span>nativeEvent<span class="token punctuation">.</span>region<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token function">render<span class="token punctuation">(</span></span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> &lt;RCTMap <span class="token punctuation">{</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">}</span> onChange<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>_onChange<span class="token punctuation">}</span> <span class="token operator">/</span><span class="token operator">&gt;</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
MapView<span class="token punctuation">.</span>propTypes <span class="token operator">=</span> <span class="token punctuation">{</span>
<span class="token comment" spellcheck="true">/**
* Callback that is called continuously when the user is dragging the map.
*/</span>
onRegionChange<span class="token punctuation">:</span> React<span class="token punctuation">.</span>PropTypes<span class="token punctuation">.</span>func<span class="token punctuation">,</span>
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span></div><h2><a class="anchor" name="styles"></a>Styles <a class="hash-link" href="#styles">#</a></h2><p>Since all our native react views are subclasses of <code>UIView</code>, most style attributes will work like you would expect out of the box. Some components will want a default style, however, for example <code>UIDatePicker</code> which is a fixed size. This default style is important for the layout algorithm to work as expected, but we also want to be able to override the default style when using the component. <code>DatePickerIOS</code> does this by wrapping the native component in an extra view, which has flexible styling, and using a fixed style (which is generated with constants passed in from native) on the inner native component:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// DatePickerIOS.ios.js
</span>
<span class="token keyword">var</span> RCTDatePickerIOSConsts <span class="token operator">=</span> <span class="token function">require<span class="token punctuation">(</span></span><span class="token string">&#x27;NativeModules&#x27;</span><span class="token punctuation">)</span><span class="token punctuation">.</span>UIManager<span class="token punctuation">.</span>RCTDatePicker<span class="token punctuation">.</span>Constants<span class="token punctuation">;</span>
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
render<span class="token punctuation">:</span> <span class="token keyword">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span>
&lt;View style<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>props<span class="token punctuation">.</span>style<span class="token punctuation">}</span><span class="token operator">&gt;</span>
&lt;RCTDatePickerIOS
ref<span class="token operator">=</span><span class="token punctuation">{</span>DATEPICKER<span class="token punctuation">}</span>
style<span class="token operator">=</span><span class="token punctuation">{</span>styles<span class="token punctuation">.</span>rkDatePickerIOS<span class="token punctuation">}</span>
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
<span class="token operator">/</span><span class="token operator">&gt;</span>
&lt;<span class="token operator">/</span>View<span class="token operator">&gt;</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">var</span> styles <span class="token operator">=</span> StyleSheet<span class="token punctuation">.</span><span class="token function">create<span class="token punctuation">(</span></span><span class="token punctuation">{</span>
rkDatePickerIOS<span class="token punctuation">:</span> <span class="token punctuation">{</span>
height<span class="token punctuation">:</span> RCTDatePickerIOSConsts<span class="token punctuation">.</span>ComponentHeight<span class="token punctuation">,</span>
width<span class="token punctuation">:</span> RCTDatePickerIOSConsts<span class="token punctuation">.</span>ComponentWidth<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div><p>The <code>RCTDatePickerIOSConsts</code> constants are exported from native by grabbing the actual frame of the native component like so:</p><div class="prism language-javascript"><span class="token comment" spellcheck="true">// RCTDatePickerManager.m
</span>
<span class="token operator">-</span> <span class="token punctuation">(</span>NSDictionary <span class="token operator">*</span><span class="token punctuation">)</span>constantsToExport
<span class="token punctuation">{</span>
UIDatePicker <span class="token operator">*</span>dp <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">[</span>UIDatePicker alloc<span class="token punctuation">]</span> init<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token punctuation">[</span>dp layoutIfNeeded<span class="token punctuation">]</span><span class="token punctuation">;</span>
<span class="token keyword">return</span> @<span class="token punctuation">{</span>
@<span class="token string">&quot;ComponentHeight&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span><span class="token function">CGRectGetHeight<span class="token punctuation">(</span></span>dp<span class="token punctuation">.</span>frame<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;ComponentWidth&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span><span class="token function">CGRectGetWidth<span class="token punctuation">(</span></span>dp<span class="token punctuation">.</span>frame<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;DatePickerModes&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">{</span>
@<span class="token string">&quot;time&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>UIDatePickerModeTime<span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;date&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>UIDatePickerModeDate<span class="token punctuation">)</span><span class="token punctuation">,</span>
@<span class="token string">&quot;datetime&quot;</span><span class="token punctuation">:</span> @<span class="token punctuation">(</span>UIDatePickerModeDateAndTime<span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span></div><p>This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the actual <code>RCTMapManager</code> and other components in the <a href="https://github.com/facebook/react-native/blob/master/React/Views" target="_blank">source code</a>.</p></div><div class="docs-prevnext"><a class="docs-next" href="linking-libraries.html#content">Next →</a></div></div></section><footer class="wrap"><div class="right">© 2015 Facebook Inc.</div></footer></div><div id="fb-root"></div><script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-41298772-2', 'facebook.github.io');
ga('send', 'pageview');
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)
){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
</script></body></html>
Reference in New Issue View Git Blame Copy Permalink