React NativeAccessibility
iOS #
Accessibility on iOS encompasses many topics, but for many, accessibility is synonymous with VoiceOver, a technology available since iOS 3.0. It acts as a screen reader, allowing people with visual impairments to use their iOS devices. Click here to learn more.
Android #
Accessibility on Android involves many diverse topics, one of which is enabling people with vision loss to use your application. For this community, Google provides a built-in screen reader service with Android called TalkBack. With TalkBack, you can use touch exploration and gestures to navigate a mobile device and application. TalkBack will read back the content on screen using text-to-speech and alert users to important notifications within your application. Click here to learn more about Android accessibility features and here to learn more about making your native applications accessible.
Making Accessible Apps #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
Accessibility
iOS #
Accessibility on iOS encompasses many topics, but for many, accessibility is synonymous with VoiceOver, a technology available since iOS 3.0. It acts as a screen reader, allowing people with visual impairments to use their iOS devices. Click here to learn more.
Android #
Accessibility on Android involves many diverse topics, one of which is enabling people with vision loss to use your application. For this community, Google provides a built-in screen reader service with Android called TalkBack. With TalkBack, you can use touch exploration and gestures to navigate a mobile device and application. TalkBack will read back the content on screen using text-to-speech and alert users to important notifications within your application. Click here to learn more about Android accessibility features and here to learn more about making your native applications accessible.
Making Accessible Apps #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
In the above example, we can't get accessibility focus separately on 'text one' and 'text two'. Instead we get focus on a parent view with 'accessible' property.
accessibilityLabel (iOS, Android) #
When a view is marked as accessible, it is a good practice to set an accessibilityLabel on the view, so that people who use VoiceOver know what element they have selected. VoiceOver will read this string when a user selects the associated element.
To use, set the accessibilityLabel property to a custom string on your View:
In the above example we've created a custom radio button that now behaves like a native one. More specifically, TalkBack now correctly announces changes to the radio button selection.
Testing VoiceOver Support (iOS) #
To enable VoiceOver, go to the Settings app on your iOS device. Tap General, then Accessibility. There you will find many tools that people use to use to make their devices more usable, such as bolder text, increased contrast, and VoiceOver.
To enable VoiceOver, tap on VoiceOver under "Vision" and toggle the switch that appears at the top.
At the very bottom of the Accessibility settings, there is an "Accessibility Shortcut". You can use this to toggle VoiceOver by triple clicking the Home button.
ActionSheetIOS
Methods #
Edit on GitHubExamples #
ActionSheetIOS
Methods #
Edit on GitHubExamples #
ActivityIndicatorIOS
Edit on GitHubProps #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Edit on GitHubExamples #
ActivityIndicatorIOS
Edit on GitHubProps #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Edit on GitHubExamples #
AlertIOS
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the +
AlertIOS
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the respective onPress callback and dismiss the alert. By default, the only button will be an 'OK' button
The last button in the list will be considered the 'Primary' button and it will appear bold.
Android Setup
This guide describes basic steps of the android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
These instructions only cover installation "from scratch". If you happen to have some old, outdated version of Android SDK make sure to update required packages to the version mentioned below and install all the missing ones.
Install and configure SDK #
- Install the latest JDK.
- Install the Android SDK with
brew install android-sdk. - Add this to your
~/.bashrc,~/.zshrcor whatever your shell uses:export ANDROID_HOME=/usr/local/opt/android-sdk - Start a new shell and run
android; in the window that appears make sure you check:- Android SDK Build-tools version 23.0.1
- Android 6.0 (API 23)
- Android Support Repository
- Click "Install Packages".
Install and run Android stock emulator #
- Start a new shell and run
android; in the window that appears make sure you check:- Intel x86 Atom System Image (for Android 5.1.1 - API 22)
- Intel x86 Emulator Accelerator (HAXM installer)
+
Android Setup – React Native | A framework for building native apps using React Android Setup
This guide describes basic steps of the android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
These instructions only cover installation "from scratch". If you happen to have some old, outdated version of Android SDK make sure to update required packages to the version mentioned below and install all the missing ones.
Install and configure SDK #
- Install the latest JDK.
- Install the Android SDK with
brew install android-sdk. - Add this to your
~/.bashrc,~/.zshrcor whatever your shell uses:export ANDROID_HOME=/usr/local/opt/android-sdk - Start a new shell and run
android; in the window that appears make sure you check:- Android SDK Build-tools version 23.0.1
- Android 6.0 (API 23)
- Android Support Repository
- Click "Install Packages".
Install and run Android stock emulator #
- Start a new shell and run
android; in the window that appears make sure you check:- Intel x86 Atom System Image (for Android 5.1.1 - API 22)
- Intel x86 Emulator Accelerator (HAXM installer)
- Click "Install Packages".
- Configure HAXM.
- Create an Android Virtual Device (AVD) to use with the Android emulator:
- Run
android avdand click on Create...
- With the new AVD selected, click
Start...
- Run
Animated
Animations are an important part of modern UX, and the
Animated+Animated – React Native | A framework for building native apps using React Animated
Animations are an important part of modern UX, and the
Animatedlibrary is designed to make them fluid, powerful, and easy to build and maintain.The simplest workflow is to create an
Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates either diff --git a/docs/animations.html b/docs/animations.html index bdba5733dd1..14ee78dbbfd 100644 --- a/docs/animations.html +++ b/docs/animations.html @@ -1,4 +1,4 @@ -Animations – React Native | A framework for building native apps using React Animations
Fluid, meaningful animations are essential to the mobile user experience. Like +
Animations – React Native | A framework for building native apps using React Animations
Fluid, meaningful animations are essential to the mobile user experience. Like everything in React Native, Animation APIs for React Native are currently under development, but have started to coalesce around two complementary systems:
LayoutAnimationfor animated global layout transactions, andAnimatedfor diff --git a/docs/appregistry.html b/docs/appregistry.html index 77b99adff65..a0d38470f19 100644 --- a/docs/appregistry.html +++ b/docs/appregistry.html @@ -1,4 +1,4 @@ -AppRegistry – React Native | A framework for building native apps using React AppRegistry
AppRegistryis the JS entry point to running all React Native apps. App +AppRegistry – React Native | A framework for building native apps using React AppRegistry
AppRegistryis the JS entry point to running all React Native apps. App root components should register themselves withAppRegistry.registerComponent, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking diff --git a/docs/appstateios.html b/docs/appstateios.html index 23c065134be..7f6bd4f9734 100644 --- a/docs/appstateios.html +++ b/docs/appstateios.html @@ -1,4 +1,4 @@ -AppStateIOS – React Native | A framework for building native apps using React AppStateIOS
AppStateIOScan tell you if the app is in the foreground or background, +AppStateIOS – React Native | A framework for building native apps using React AppStateIOS
AppStateIOScan tell you if the app is in the foreground or background, and notify you when the state changes.AppStateIOS is frequently used to determine the intent and proper behavior when handling push notifications.
iOS App States #
active- The app is running in the foregroundbackground- The app is running in the background. The user is either in another app or on the home screeninactive- This is a transition state that currently never happens for diff --git a/docs/asyncstorage.html b/docs/asyncstorage.html index d5b3a56e342..56ca8a6af94 100644 --- a/docs/asyncstorage.html +++ b/docs/asyncstorage.html @@ -1,4 +1,4 @@ -AsyncStorage – React Native | A framework for building native apps using React AsyncStorage
AsyncStorage is a simple, asynchronous, persistent, key-value storage +
AsyncStorage – React Native | A framework for building native apps using React AsyncStorage
AsyncStorage is a simple, asynchronous, persistent, key-value storage system that is global to the app. It should be used instead of LocalStorage.
It is recommended that you use an abstraction on top of AsyncStorage instead of AsyncStorage directly for anything more than light usage since it operates globally.
This JS code is a simple facade over the native iOS implementation to provide diff --git a/docs/backandroid.html b/docs/backandroid.html index c7908dbf2bd..e78d9318e02 100644 --- a/docs/backandroid.html +++ b/docs/backandroid.html @@ -1,4 +1,4 @@ -
BackAndroid – React Native | A framework for building native apps using React BackAndroid
Detect hardware back button presses, and programatically invoke the default back button +
BackAndroid – React Native | A framework for building native apps using React BackAndroid
Detect hardware back button presses, and programatically invoke the default back button functionality to exit the app if there are no listeners or if none of the listeners return true.
Example:
BackAndroid.addEventListener('hardwareBackPress', function() { if (!this.onMainScreen()) { this.goBack(); diff --git a/docs/cameraroll.html b/docs/cameraroll.html index eefbfbb1fc8..1b4303f7f69 100644 --- a/docs/cameraroll.html +++ b/docs/cameraroll.html @@ -1,4 +1,4 @@ -CameraRoll – React Native | A framework for building native apps using React CameraRoll
CameraRollprovides access to the local camera roll / gallery.Methods #
static saveImageWithTag(tag, successCallback, errorCallback) #
Saves the image to the camera roll / gallery.
@param {string} tag On Android, this is a local URI, such +
CameraRoll – React Native | A framework for building native apps using React CameraRoll
CameraRollprovides access to the local camera roll / gallery.Methods #
static saveImageWithTag(tag, successCallback, errorCallback) #
Saves the image to the camera roll / gallery.
@param {string} tag On Android, this is a local URI, such as
"file:///sdcard/img.png".On iOS, the tag can be one of the following:
- local URI
- assets-library tag
- a tag not maching any of the above, which means the image data will be stored in memory (and consume memory as long as the process is alive)
@param successCallback Invoked with the value of
tagon success. @param errorCallback Invoked with error message on error.static getPhotos(params, callback, errorCallback) #
Invokes
callbackwith photo identifier objects from the local camera diff --git a/docs/datepickerios.html b/docs/datepickerios.html index a20c5d770c8..9b6c3b492d3 100644 --- a/docs/datepickerios.html +++ b/docs/datepickerios.html @@ -1,4 +1,4 @@ -DatePickerIOS – React Native | A framework for building native apps using React DatePickerIOS
Use
DatePickerIOSto render a date/time picker (selector) on iOS. This is +DatePickerIOS – React Native | A framework for building native apps using React DatePickerIOS
Use
DatePickerIOSto render a date/time picker (selector) on iOS. This is a controlled component, so you must hook in to theonDateChangecallback and update thedateprop in order for the component to update, otherwise the user's change will be reverted immediately to reflectprops.dateas the diff --git a/docs/debugging.html b/docs/debugging.html index 68bbccdca6f..1ba0ca6d32e 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -1,4 +1,4 @@ -Debugging – React Native | A framework for building native apps using React Debugging
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click)
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease. - For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting
Reload(or pressing⌘ + rin the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image toImages.xcassetson iOS or tores/drawablefolder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.Chrome Developer Tools #
To debug the JavaScript code in Chrome, select
Debug in Chromefrom the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.In Chrome, press
⌘ + option + ior selectView→Developer→Developer Toolsto toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse 8081 8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the
Reactin the developer tools (see facebook/react-devtools for more information).Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On
0.5.0-rcand higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.Debugging
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click)
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease. - For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting
Reload(or pressing⌘ + rin the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image toImages.xcassetson iOS or tores/drawablefolder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.Chrome Developer Tools #
To debug the JavaScript code in Chrome, select
Debug in Chromefrom the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.In Chrome, press
⌘ + option + ior selectView→Developer→Developer Toolsto toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse 8081 8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the
Reactin the developer tools (see facebook/react-devtools for more information).Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On
0.5.0-rcand higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.Direct Manipulation
It is sometimes necessary to make changes directly to a component +
Direct Manipulation – React Native | A framework for building native apps using React Direct Manipulation
It is sometimes necessary to make changes directly to a component without using state/props to trigger a re-render of the entire subtree. When using React in the browser for example, you sometimes need to directly modify a DOM node, and the same is true for views in mobile @@ -152,7 +152,7 @@ the jerky animation each 250ms when
setStatetriggers a re-render.<shouldComponentUpdateyou can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to -usesetStateinstead ofsetNativeProps.DrawerLayoutAndroid
React component that wraps the platform
DrawerLayout(Android only). The +DrawerLayoutAndroid – React Native | A framework for building native apps using React DrawerLayoutAndroid
React component that wraps the platform
DrawerLayout(Android only). The Drawer (typically used for navigation) is rendered withrenderNavigationViewand direct children are the main view (where your content goes). The navigation view is initially not visible on the screen, but can be pulled in from the diff --git a/docs/embedded-app-ios.html b/docs/embedded-app-ios.html index 8059ed216e0..696a357619f 100644 --- a/docs/embedded-app-ios.html +++ b/docs/embedded-app-ios.html @@ -1,4 +1,4 @@ -Integrating with Existing Apps (iOS) – React Native | A framework for building native apps using React Integrating with Existing Apps (iOS)
Since React makes no assumptions about the rest of your technology stack – it’s commonly noted as simply the
VinMVC– it’s easily embeddable within an existing non-React Native app. In fact, it integrates with other best practice community tools like CocoaPods.Requirements #
- CocoaPods –
gem install cocoapods - Node.js
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them.
- Install nvm with its setup instructions here. Then run
Install React Native Using CocoaPods #
CocoaPods is a package management tool for iOS/Mac development. We need to use it to download React Native. If you haven't installed CocoaPods yet, check out this tutorial.
When you are ready to work with CocoaPods, add the following line to
Podfile. If you don't have one, then create it under the root directory of your project.pod 'React' +Integrating with Existing Apps – React Native | A framework for building native apps using React Integrating with Existing Apps
Since React makes no assumptions about the rest of your technology stack – it’s commonly noted as simply the
VinMVC– it’s easily embeddable within an existing non-React Native app. In fact, it integrates with other best practice community tools like CocoaPods.Requirements #
- CocoaPods –
gem install cocoapods - Node.js
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them.
- Install nvm with its setup instructions here. Then run
Install React Native Using CocoaPods #
CocoaPods is a package management tool for iOS/Mac development. We need to use it to download React Native. If you haven't installed CocoaPods yet, check out this tutorial.
When you are ready to work with CocoaPods, add the following line to
Podfile. If you don't have one, then create it under the root directory of your project.pod 'React' pod 'React/RCTText' # Add any subspecs you want to use in your projectRemember to install all subspecs you need. The
<Text>element cannot be used withoutpod 'React/RCTText'.Then install your pods:
$ pod installCreate Your React Native App #
There are two pieces you’ll need to set up:
- The root JavaScript file that will contain your actual React Native app and other components
- Wrapper Objective-C code that will load up your script and create a
RCTRootViewto display and manage your React Native components
First, create a directory for your app’s React code and create a simple
index.ios.jsfile:$ mkdir ReactComponent $ touch ReactComponent/index.ios.jsCopy & paste following starter code for
index.ios.js– it’s a barebones React Native app:'use strict'; @@ -45,7 +45,7 @@ React.AppRegistry*rootView = [[RCTRootView alloc] initWithBundleURL:jsCodeLocation moduleName: @"SimpleApp" launchOptions:nil];Then add it as a subview of the
ReactView.[self addSubview:rootView]; -rootView.frame = self.bounds;Start Development Server #
In root directory, we need to start React Native development server.
(JS_DIR=`pwd`/ReactComponent; cd Pods/React; npm run start -- --root $JS_DIR)This command will start up a React Native development server within our CocoaPods dependency to build our bundled script. The
--rootoption indicates the root of your React Native apps – this will be ourReactComponentsdirectory containing the singleindex.ios.jsfile. This running server will package up theindex.ios.bundlefile accessible viahttp://localhost:8081/index.ios.bundle.Compile And Run #
Now compile and run your app. You shall now see your React Native app running inside of the
ReactView.
Live reload works from the simulator, too! You’ve got a simple React component totally encapsulated behind an Objective-C
UIViewsubclass.Conclusion #
So under the hood, when
RCTRootViewis initialized, it will try to download, parse and run the bundle file from React Native development server. This means all you need to do is to implement your own container view or view controller for theRCTRootView– theRCTRootViewingests your bundled JS and renders your React components. Bravo!You can checkout full source code of a sample application here.
Flexbox
Edit on GitHubProps #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Flexbox
Edit on GitHubProps #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Geolocation
You need to include the
NSLocationWhenInUseUsageDescriptionkey +Geolocation – React Native | A framework for building native apps using React Geolocation
You need to include the
NSLocationWhenInUseUsageDescriptionkey in Info.plist to enable geolocation. Geolocation is enabled by default when you create a project withreact-native init.Geolocation follows the MDN specification: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation
Methods #
static getCurrentPosition(geo_success: Function, geo_error?: Function, geo_options?: GeoOptions) #
Invokes the success callback once with the latest location info. Supported diff --git a/docs/gesture-responder-system.html b/docs/gesture-responder-system.html index 82c35799348..dcddeaedcc3 100644 --- a/docs/gesture-responder-system.html +++ b/docs/gesture-responder-system.html @@ -1,4 +1,4 @@ -
Gesture Responder System – React Native | A framework for building native apps using React Gesture Responder System
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in
ResponderEventPlugin.js, which contains further details and documentation.Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract
Touchableimplementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. UseTouchableHighlightanywhere where you would use a button or link on web.Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evtis a synthetic touch event with the following form:nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the screenpageY- The Y position of the touch, relative to the screentarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponderandonMoveShouldSetResponderare called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for*ShouldSetResponderhandlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing
on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have aonStartShouldSetResponderCapturehandler which returns true.View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Gesture Responder System
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in
ResponderEventPlugin.js, which contains further details and documentation.Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract
Touchableimplementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. UseTouchableHighlightanywhere where you would use a button or link on web.Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evtis a synthetic touch event with the following form:nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the screenpageY- The Y position of the touch, relative to the screentarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponderandonMoveShouldSetResponderare called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for*ShouldSetResponderhandlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing
on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have aonStartShouldSetResponderCapturehandler which returns true.View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Getting Started
Requirements #
- OS X - Only OS X is currently supported
- Homebrew is the recommended way to install nvm, watchman, and flow.
- Install Node.js 4.0 or newer.
- Install nvm with Homebrew or its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with Homebrew or its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running
brew update && brew upgradeto keep your programs up-to-date.iOS Setup #
Xcode 6.3 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
Quick start #
$ npm install -g react-native-cli +Getting Started – React Native | A framework for building native apps using React Getting Started
Requirements #
- OS X - Only OS X is currently supported
- Homebrew is the recommended way to install nvm, watchman, and flow.
- Install Node.js 4.0 or newer.
- Install nvm with Homebrew or its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with Homebrew or its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running
brew update && brew upgradeto keep your programs up-to-date.iOS Setup #
Xcode 6.3 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
Quick start #
$ npm install -g react-native-cli $ react-native init AwesomeProject $ cd AwesomeProject/To run the iOS app:
- Open
ios/AwesomeProject.xcodeprojand hit run in Xcode. - Open
index.ios.jsin your text editor of choice and edit some lines. - Hit ⌘-R in your iOS simulator to reload the app and see your change!
To run the Android app:
$ react-native run-android- Open
index.android.jsin your text editor of choice and edit some lines. - Press the menu button (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
- Run
adb logcat *:S ReactNative:V ReactNativeJS:Vin a terminal to see your app's logs
Note: If you are using a device, see the Running on Device page.
Congratulations! You've successfully run and modified your first React Native app.
If you run into any issues getting started, see the troubleshooting page.
Adding Android to an existing React Native project #
If you already have a (iOS-only) React Native project and want to add Android support, you need to execute the following commands in your existing project directory:
- Update the
react-nativedependency in yourpackage.jsonfile to the latest version $ npm install$ react-native android
Image
A React component for displaying different types of images, +
Image – React Native | A framework for building native apps using React Image
A React component for displaying different types of images, including network images, static resources, temporary local images, and images from local disk, such as the camera roll.
Example usage:
renderImages: function() { return ( diff --git a/docs/interactionmanager.html b/docs/interactionmanager.html index b94df2f56b8..042697f9ec1 100644 --- a/docs/interactionmanager.html +++ b/docs/interactionmanager.html @@ -1,4 +1,4 @@ -InteractionManager – React Native | A framework for building native apps using React InteractionManager
InteractionManager allows long-running work to be scheduled after any +
InteractionManager – React Native | A framework for building native apps using React InteractionManager
InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.
Applications can schedule tasks to run after interactions with the following:
InteractionManager.runAfterInteractions(() => { // ...long-running synchronous task... diff --git a/docs/javascript-environment.html b/docs/javascript-environment.html index eb419a85525..444e1a7611c 100644 --- a/docs/javascript-environment.html +++ b/docs/javascript-environment.html @@ -1,4 +1,4 @@ -JavaScript Environment – React Native | A framework for building native apps using React JavaScript Environment
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Destructuring:
var {isActive, style} = this.props; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { }
JavaScript Environment
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Destructuring:
var {isActive, style} = this.props; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { }
Known Issues
Missing Modules and Native Views #
This is an initial release of React Native Android and therefore not all of the views present on iOS are released on Android. We are very much interested in the communities' feedback on the next set of modules and views for Open Source. Not all native views between iOS and Android have a 100% equivalent representation, here it will be necessary to use a counterpart eg using ProgressBar on Android in place of ActivityIndicator on iOS.
Our provisional plan for common views and modules includes:
Views #
View Pager +Known Issues – React Native | A framework for building native apps using React Known Issues
Missing Modules and Native Views #
This is an initial release of React Native Android and therefore not all of the views present on iOS are released on Android. We are very much interested in the communities' feedback on the next set of modules and views for Open Source. Not all native views between iOS and Android have a 100% equivalent representation, here it will be necessary to use a counterpart eg using ProgressBar on Android in place of ActivityIndicator on iOS.
Our provisional plan for common views and modules includes:
Views #
View Pager Swipe Refresh Spinner ART @@ -25,7 +25,7 @@ Alert: 0}} /> </View>
The behavior on Android is what you would expect from the web as well. If you want to be able to click through an overlaying transparent view, you can set
pointerEvents='none'on it.The
overflowstyle property defaults tohiddenand cannot be changed on Android #This is a result of how Android rendering works. This feature is not being worked on as it would be a significant undertaking and there are many more important tasks.
No support for shadows on Android #
We don't support shadows on Android currently. These are notoriously hard to implement as they require drawing outside of a view's bounds and Android's invalidation logic has a hard time with that. A possible solution is to use elevation, but more experimentation will be required.
Layout-only nodes on Android #
An optimization feature of the Android version of React Native is for views which only contribute to the layout to not have a native view, only their layout properties are propagated to their children views. This optimization is to provide stability in deep view hierarchies for React Native and gis therefore enabled by default. Should you depend on a view being present or internal tests incorrectly detect a view is layout only it will be necessary to turn off this behavior. To do this, set
collapsableto false as in this example:<View collapsable={false}> ... -</View>Memory issues with PNG images #
React Native Android depends on Fresco for loading and displaying images. Currently we have disabled downsampling because it is experimental, so you may run into memory issues when loading large PNG images.
LayoutAnimation
Automatically animates views to their new positions when the +
LayoutAnimation – React Native | A framework for building native apps using React LayoutAnimation
Automatically animates views to their new positions when the next layout happens.
A common way to use this API is to call
LayoutAnimation.configureNextbefore callingsetState.Methods #
static configureNext(config: Config, onAnimationDidEnd?: Function) #
Schedules an animation to happen on the next layout.
@param config Specifies animation properties:
durationin millisecondscreate, config for animating in new views (seeAnimtype)update, config for animating views that have been updated (seeAnimtype)
@param onAnimationDidEnd Called when the animation finished. diff --git a/docs/linking-libraries-ios.html b/docs/linking-libraries-ios.html index bfcd0bd7854..6da417b760b 100644 --- a/docs/linking-libraries-ios.html +++ b/docs/linking-libraries-ios.html @@ -1,4 +1,4 @@ -
Linking Libraries (iOS) – React Native | A framework for building native apps using React Linking Libraries (iOS)
Not every app uses all the native capabilities, and including the code to support +
Linking Libraries – React Native | A framework for building native apps using React Linking Libraries
Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to make it easy to add these features whenever you need them.
With that in mind we exposed many of these features as independent static libraries.
For most of the libs it will be as simple as dragging two files, sometimes a third step will be necessary, but no more than that.
All the libraries we ship with React Native live on the
Librariesfolder in @@ -18,7 +18,7 @@ received.For that we need to know the library's headers. To achieve to your project's file, select
Build Settingsand search forHeader Search Paths. There you should include the path to your library (if it has relevant files on subdirectories remember to make itrecursive, likeReacton the -example).
LinkingIOS
LinkingIOSgives you a general interface to interact with both, incoming +LinkingIOS – React Native | A framework for building native apps using React LinkingIOS
LinkingIOSgives you a general interface to interact with both, incoming and outgoing app links.Basic Usage #
Handling deep links #
If your app was launched from an external url registered to your app you can access and handle it from any component you want with
componentDidMount() { var url = LinkingIOS.popInitialURL(); diff --git a/docs/listview.html b/docs/listview.html index a7a74f024d6..858529cbfd5 100644 --- a/docs/listview.html +++ b/docs/listview.html @@ -1,4 +1,4 @@ -ListView – React Native | A framework for building native apps using React ListView
ListView - A core component designed for efficient display of vertically +
ListView – React Native | A framework for building native apps using React ListView
ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a
ListView.DataSource, populate it with a simple array of data blobs, and instantiate aListViewcomponent with that data source and arenderRowdiff --git a/docs/mapview.html b/docs/mapview.html index 37d0911e9d3..24a0c8fb0fc 100644 --- a/docs/mapview.html +++ b/docs/mapview.html @@ -1,4 +1,4 @@ -MapView – React Native | A framework for building native apps using React MapView
Edit on GitHubProps #
annotations [{latitude: number, longitude: number, animateDrop: bool, title: string, subtitle: string, hasLeftCallout: bool, hasRightCallout: bool, onLeftCalloutPress: function, onRightCalloutPress: function, id: string}] #
Map annotations with title/subtitle.
legalLabelInsets {top: number, left: number, bottom: number, right: number} #
Insets for the map's legal label, originally at bottom left of the map. +
MapView – React Native | A framework for building native apps using React MapView
Edit on GitHubProps #
annotations [{latitude: number, longitude: number, animateDrop: bool, title: string, subtitle: string, hasLeftCallout: bool, hasRightCallout: bool, onLeftCalloutPress: function, onRightCalloutPress: function, id: string}] #
Map annotations with title/subtitle.
legalLabelInsets {top: number, left: number, bottom: number, right: number} #
Insets for the map's legal label, originally at bottom left of the map. See
EdgeInsetsPropType.jsfor more information.mapType enum('standard', 'satellite', 'hybrid') #
The map type to be displayed.
- standard: standard road map (default)
- satellite: satellite view
- hybrid: satellite view with roads and points of interest overlayed
maxDelta number #
Maximum size of area that can be displayed.
minDelta number #
Minimum size of area that can be displayed.
onAnnotationPress function #
Callback that is called once, when the user is clicked on a annotation.
onRegionChange function #
Callback that is called continuously when the user is dragging the map.
onRegionChangeComplete function #
Callback that is called once, when the user is done moving the map.
pitchEnabled bool #
When this property is set to
trueand 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 tofalse, the camera’s pitch diff --git a/docs/modal.html b/docs/modal.html index 2fe5534f91e..138c333674d 100644 --- a/docs/modal.html +++ b/docs/modal.html @@ -1,4 +1,4 @@ -Modal – React Native | A framework for building native apps using React