React NativeAccessibility #
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
Making Apps Accessible #
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 #
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
Making Apps Accessible #
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.
You can edit the content above on GitHub and send us a pull request!
ActionSheetIOS #
Methods #
static showActionSheetWithOptions(options, callback) #
Display an iOS action sheet. The options object must contain one or more
+
ActionSheetIOS #
Methods #
static showActionSheetWithOptions(options, callback) #
Display an iOS action sheet. The options object must contain one or more
of:
options(array of strings) - a list of button titles (required)cancelButtonIndex(int) - index of cancel button inoptionsdestructiveButtonIndex(int) - index of destructive button inoptionstitle(string) - a title to show above the action sheetmessage(string) - a message to show below the title
static showShareActionSheetWithOptions(options, failureCallback, successCallback) #
Display the iOS share sheet. The options object should contain
one or both of message and url and can additionally have
a subject or excludedActivityTypes:
url(string) - a URL to sharemessage(string) - a message to sharesubject(string) - a subject for the messageexcludedActivityTypes(array) - the activities to exclude from the ActionSheet
NOTE: if url points to a local file, or is a base64-encoded
@@ -204,7 +204,7 @@ exports.examples return <ShareScreenshotExample />;
}
}
-];
ActivityIndicator #
Displays a circular loading indicator.
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
size enum('small', 'large'), number #
Size of the indicator (default is 'small'). -Passing a number to the size prop is only supported on Android.
ioshidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
ActivityIndicator #
Displays a circular loading indicator.
Props #
animating?: bool #
Whether to show the indicator (true, the default) or hide it (false).
size?: enum('small', 'large'), number #
Size of the indicator (default is 'small'). +Passing a number to the size prop is only supported on Android.
ioshidesWhenStopped?: bool #
Whether the indicator should hide when not animating (true by default).
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
AdSupportIOS #
Methods #
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
AdSupportIOS #
Methods #
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
Alert #
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the +
Alert #
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.
This is an API that works both on iOS and Android and can show static alerts. To show an alert that prompts the user to enter some information, @@ -151,7 +151,7 @@ class AlertExample extends .exports = { AlertExample, SimpleAlertExampleBlock, -};
AlertIOS #
AlertIOS provides functionality to create an iOS alert dialog with a
+
AlertIOS #
AlertIOS provides functionality to create an iOS alert dialog with a
message or create a prompt for user input.
Creating an iOS alert:
Creating an iOS alert:
We recommend using the Alert.alert method for
-cross-platform support if you don't need to create iOS-only prompts.
Methods #
static alert(title, message?, callbackOrButtons?, type?) #
Create and display a popup alert.
| Name and Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| title string | The dialog's title. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| [message] string | An optional message that appears below +cross-platform support if you don't need to create iOS-only prompts. Methods #static alert(title: string, message?: string, callbackOrButtons?: ?(() => void), ButtonsArray, type?: AlertType) #Create and display a popup alert. Parameters:
'use strict';
+when using the minDate and maxDate options.static dateSetAction() #A date has been selected. static dismissedAction() #The dialog has been dismissed. You can edit the content above on GitHub and send us a pull request!
'use strict';
var React = require('react');
var ReactNative = require('react-native');
@@ -144,7 +144,7 @@ class DatePickerAndroidExample extends DatePickerIOS #Use DatePickerIOS #Use Props #date Date #The currently selected date. maximumDate Date #Maximum date. Restricts the range of possible date/time values. minimumDate Date #Minimum date. Restricts the range of possible date/time values. minuteInterval enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30) #The interval at which minutes can be selected. mode enum('date', 'time', 'datetime') #The date picker mode. onDateChange function #Date change handler. This is called when the user changes the date or time in the UI. +source of truth. Props #date: Date #The currently selected date. maximumDate?: Date #Maximum date. Restricts the range of possible date/time values. minimumDate?: Date #Minimum date. Restricts the range of possible date/time values. minuteInterval?: enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30) #The interval at which minutes can be selected. mode?: enum('date', 'time', 'datetime') #The date picker mode. onDateChange: function #Date change handler. This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new -date and time. timeZoneOffsetInMinutes number #Timezone offset in minutes. By default, the date picker will use the device's timezone. With this +date and time. timeZoneOffsetInMinutes?: number #Timezone offset in minutes. By default, the date picker will use the device's timezone. With this parameter, it is possible to force a certain timezone offset. For instance, to show times in Pacific Standard Time, pass -7 * 60. You can edit the content above on GitHub and send us a pull request!
'use strict';
@@ -155,7 +155,7 @@ exports.examples : '500',
fontSize: 14,
},
-}); Debugging #Accessing the In-App Developer Menu #You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the
Reloading JavaScript #Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press
Automatic reloading #You can speed up your development times by having your app reload automatically any time your code changes. Automatic reloading can be enabled by selecting "Enable Live Reload" from the Developer Menu. You may even go a step further and keep your app running as new versions of your files are injected into the JavaScript bundle automatically by enabling Hot Reloading from the Developer Menu. This will allow you to persist the app's state through reloads.
You will need to rebuild your app for changes to take effect in certain situations:
In-app Errors and Warnings #Errors and warnings are displayed inside your app in development builds. Errors #In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use Warnings #Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them. As with a RedBox, you can use YellowBoxes can be disabled during development by using In CI/Xcode, YellowBoxes can also be disabled by setting the
Accessing console logs #You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running: $ react-native log-ios
+ Debugging #Accessing the In-App Developer Menu #You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the
Reloading JavaScript #Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press
Automatic reloading #You can speed up your development times by having your app reload automatically any time your code changes. Automatic reloading can be enabled by selecting "Enable Live Reload" from the Developer Menu. You may even go a step further and keep your app running as new versions of your files are injected into the JavaScript bundle automatically by enabling Hot Reloading from the Developer Menu. This will allow you to persist the app's state through reloads.
You will need to rebuild your app for changes to take effect in certain situations:
In-app Errors and Warnings #Errors and warnings are displayed inside your app in development builds. Errors #In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use Warnings #Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them. As with a RedBox, you can use YellowBoxes can be disabled during development by using In CI/Xcode, YellowBoxes can also be disabled by setting the
Accessing console logs #You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running: $ react-native log-ios
$ react-native log-android You may also access these through Chrome Developer Tools #To debug the JavaScript code in Chrome, select "Debug JS Remotely" from the Developer Menu. This will open a new tab at http://localhost:8081/debugger-ui. Select
Debugging on a device with Chrome Developer Tools #On iOS devices, open the file On Android 5.0+ devices connected via USB, you can use the
Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.
Debugging using a custom JavaScript debugger #To use a custom JavaScript debugger in place of Chrome Developer Tools, set the The debugger will receive a list of all project roots, separated by a space. For example, if you set
Debugging with Stetho on Android #
Debugging native code #When working with native code (e.g. when writing native modules) you can launch the app from Android Studio or Xcode and take advantage of the debugging features (setup breakpoints, etc.) as you would in case of building a standard native app. Performance Monitor #You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu. You can edit the content above on GitHub and send us a pull request! Dimensions #Methods #static set(dims) #This should only be called from native code by sending the + Dimensions #Methods #static set(dims) #This should only be called from native code by sending the didUpdateDimensions event. @param {object} dims Simple string-keyed object of dimensions to set static get(dim) #Initial dimensions are set before Note: Although dimensions are available immediately, they may change (e.g
due to device rotation) so any rendering logic or styles that depend on
these constants should try to call this function on every render, rather
than caching the value (for example, using inline styles rather than
setting a value in a Example: @param {string} dim Name of dimension as defined when calling You can edit the content above on GitHub and send us a pull request! Direct Manipulation #It is sometimes necessary to make changes directly to a component + 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
@@ -136,7 +136,7 @@ the jerky animation each 250ms when You can edit the content above on GitHub and send us a pull request! DrawerLayoutAndroid #React component that wraps the platform DrawerLayoutAndroid #React component that wraps the platform Example: /View>
</DrawerLayoutAndroid>
);
-}, Props #drawerBackgroundColor color #Specifies the background color of the drawer. The default value is white. +}, Props #drawerBackgroundColor?: color #Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example: return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)">
</DrawerLayoutAndroid>
-); drawerLockMode enum('unlocked', 'locked-closed', 'locked-open') #Specifies the lock mode of the drawer. The drawer can be locked in 3 states: +); drawerLockMode?: enum('unlocked', 'locked-closed', 'locked-open') #Specifies the lock mode of the drawer. The drawer can be locked in 3 states:
- unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
- locked-closed, meaning that the drawer will stay closed and not respond to gestures.
- locked-open, meaning that the drawer will stay opened and not respond to gestures.
-The drawer may still be opened and closed programmatically ( drawerPosition enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right) #Specifies the side of the screen from which the drawer will slide in. drawerWidth number #Specifies the width of the drawer, more precisely the width of the view that be pulled in -from the edge of the window. keyboardDismissMode enum('none', 'on-drag') #Determines whether the keyboard gets dismissed in response to a drag.
+The drawer may still be opened and closed programmatically ( drawerPosition?: enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right) #Specifies the side of the screen from which the drawer will slide in. drawerWidth?: number #Specifies the width of the drawer, more precisely the width of the view that be pulled in +from the edge of the window. keyboardDismissMode?: enum('none', 'on-drag') #Determines whether the keyboard gets dismissed in response to a drag. - 'none' (the default), drags do not dismiss the keyboard. - - 'on-drag', the keyboard is dismissed when a drag begins. onDrawerClose function #Function called whenever the navigation view has been closed. onDrawerOpen function #Function called whenever the navigation view has been opened. onDrawerSlide function #Function called whenever there is an interaction with the navigation view. onDrawerStateChanged function #Function called when the drawer state has changed. The drawer can be in 3 states: + - 'on-drag', the keyboard is dismissed when a drag begins. onDrawerClose?: function #Function called whenever the navigation view has been closed. onDrawerOpen?: function #Function called whenever the navigation view has been opened. onDrawerSlide?: function #Function called whenever there is an interaction with the navigation view. onDrawerStateChanged?: function #Function called when the drawer state has changed. The drawer can be in 3 states: - idle, meaning there is no interaction with the navigation view happening at the time - dragging, meaning there is currently an interaction with the navigation view - settling, meaning that there was an interaction with the navigation view, and the -navigation view is now finishing its closing or opening animation renderNavigationView function #The navigation view that will be rendered to the side of the screen and can be pulled in. statusBarBackgroundColor color #Make the drawer take the entire screen and draw the background of the +navigation view is now finishing its closing or opening animation renderNavigationView: function #The navigation view that will be rendered to the side of the screen and can be pulled in. Methods #You can edit the content above on GitHub and send us a pull request! Easing #This class implements common easing functions. The math is pretty obscure, + Easing #This class implements common easing functions. The math is pretty obscure, but this cool website has nice visual illustrations of what they represent: http://xaedes.de/dev/transitions/ Methods #static step0(n) #static step1(n) #static linear(t) #static ease(t) #static quad(t) #static cubic(t) #static poly(n) #static sin(t) #static circle(t) #static exp(t) #static elastic(bounciness) #A simple elastic interaction, similar to a spring. Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times. Wolfram Plots: http://tiny.cc/elastic_b_1 (default bounciness = 1) - http://tiny.cc/elastic_b_3 (bounciness = 3) static back(s) #static bounce(t) #static bezier(x1, y1, x2, y2) #static in(easing) #static out(easing) #Runs an easing function backwards. static inOut(easing) #Makes any easing function symmetrical. You can edit the content above on GitHub and send us a pull request! Layout with Flexbox #A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes. You will normally use a combination of
Flex Direction #Adding import React, { Component } from 'react';
+ Layout with Flexbox #A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes. You will normally use a combination of
Flex Direction #Adding import React, { Component } from 'react';
import { AppRegistry, View } from 'react-native';
class FlexDirectionBasics extends Component {
@@ -58,7 +58,7 @@ class AlignItemsBasics extends }
};
-AppRegistry.registerComponent('AwesomeProject', () => AlignItemsBasics); Going Deeper #We've covered the basics, but there are many other styles you may need for layouts. The full list of props that control layout is documented here. We're getting close to being able to build a real application. One thing we are still missing is a way to take user input, so let's move on to learn how to handle text input with the TextInput component. You can edit the content above on GitHub and send us a pull request! Geolocation #The Geolocation API extends the web spec: + Geolocation #The Geolocation API extends the web spec: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation As a browser polyfill, this API is available through the iOS #You need to include the
|
Examples # | Edit on GitHub |
static clearWatch(watchID) #
static stopObserving() #
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
Gesture Responder System #
The gesture responder system manages the lifecycle of gestures in your app. 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 #
To make your app feel great, 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 Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere 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)
evt is 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 root elementpageY- The Y position of the touch, relative to the root elementtarget- 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 #
onStartShouldSetResponder and onMoveShouldSetResponder are 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 *ShouldSetResponder handlers. 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 a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
You can edit the content above on GitHub and send us a pull request!
Gesture Responder System #
The gesture responder system manages the lifecycle of gestures in your app. 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 #
To make your app feel great, 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 Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere 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)
evt is 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 root elementpageY- The Y position of the touch, relative to the root elementtarget- 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 #
onStartShouldSetResponder and onMoveShouldSetResponder are 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 *ShouldSetResponder handlers. 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 a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
You can edit the content above on GitHub and send us a pull request!
Getting Started #
Welcome to React Native! This page will help you install React Native on +
Getting Started #
Welcome to React Native! This page will help you install React Native on your system, so that you can build apps with it right away. If you already have React Native installed, you can skip ahead to the Tutorial.
The instructions are a bit different depending on your development operating system, and whether you want to start developing for iOS or Android. If you @@ -214,7 +214,7 @@ if (!foundHash) { display('platform', isMac ? 'ios' : 'android'); } -
You can edit the content above on GitHub and send us a pull request!
Handling Text Input #
TextInput is a basic component that allows the user to enter text. It has an onChangeText prop that takes
+
Handling Text Input #
TextInput is a basic component that allows the user to enter text. It has an onChangeText prop that takes
a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.
For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".
In this example, we store text in the state, because it changes over time.
There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.
Text input is probably the simplest example of a component whose state naturally changes over time. Next, let's look at another type of component like this one that controls layout, and learn about the ScrollView.
You can edit the content above on GitHub and send us a pull request!
Handling Touches #
Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map.
React Native provides components to handle common gestures, such as taps and swipes, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition.
Tappable Components #
You can use "Touchable" components when you want to capture a tapping gesture. They take a function through the onPress props which will be called when the touch begins and ends within the bounds of the component.
Example:
Handling Touches #
Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map.
React Native provides components to handle common gestures, such as taps and swipes, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition.
Tappable Components #
You can use "Touchable" components when you want to capture a tapping gesture. They take a function through the onPress props which will be called when the touch begins and ends within the bounds of the component.
Example:
Tappable components should provide feedback that show the user what is handling their touch, and what will happen when they lift their finger. The user should also be able to cancel a tap by dragging their finger away.
Which component you use will depend on what kind of feedback you want to provide:
Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.
You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.
TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.
If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.
Long presses #
In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the touchable components listed above.
Scrolling lists and swiping views #
A common pattern to many mobile apps is the scrollable list of items. Users interact with these using panning or swiping gestures. The ScrollView component displays a list of items that can be scrolled using these gestures.
ScrollViews can scroll vertically or horizontally, and can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPagerAndroid component.
A ListView is a special kind of ScrollView that is best suited for displaying long vertical lists of items. It can also display section headers and footers, similar to UITableViews on iOS.
Pinch-to-zoom #
A ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.
Handling additional gestures #
If you want to allow a user to drag a view around the screen, or you want to implement your own custom pan/drag gesture, take a look at the PanResponder API or the gesture responder system docs.
You can edit the content above on GitHub and send us a pull request!
Headless JS #
Headless JS is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.
The JS API #
A task is a simple async function that you register on AppRegistry, similar to registering React applications:
Then, in SomeTaskName.js:
Headless JS #
Headless JS is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.
The JS API #
A task is a simple async function that you register on AppRegistry, similar to registering React applications:
Then, in SomeTaskName.js:
You can do anything in your task as long as it doesn't touch UI: network requests, timers and so on. Once your task completes (i.e. the promise is resolved), React Native will go into "paused" mode (unless there are other tasks running, or there is a foreground app).
The Java API #
Yes, this does still require some native code, but it's pretty thin. You need to extend HeadlessJsTaskService and override getTaskConfig, e.g.:
Now, whenever you start your service, e.g. as a periodic task or in response to some system event / broadcast, JS will spin up, run your task, then spin down.
Caveats #
- By default, your app will crash if you try to run a task while the app is in the foreground. This is to prevent developers from shooting themselves in the foot by doing a lot of work in a task and slowing the UI. There is a way around this.
- If you start your service from a
BroadcastReceiver, make sure to callHeadlessJsTaskService.acquireWakelockNow()before returning fromonReceive().
You can edit the content above on GitHub and send us a pull request!
Height and Width #
A component's height and width determine its size on the screen.
Fixed Dimensions #
The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.
Height and Width #
A component's height and width determine its size on the screen.
Fixed Dimensions #
The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.
After you can control a component's size, the next step is to learn how to lay it out on the screen.
You can edit the content above on GitHub and send us a pull request!
Image #
A React component for displaying different types of images, +
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.
This example shows both fetching and displaying an image from local storage as well as one from network.
Also, if you use GIF with ProGuard, you will need to add this rule in proguard-rules.pro :
Props #
onError function #
Invoked on load error with {nativeEvent: {error}}.
onLayout function #
Invoked on mount and layout changes with
-{nativeEvent: {layout: {x, y, width, height}}}.
onLoad function #
Invoked when load completes successfully.
onLoadEnd function #
Invoked when load either succeeds or fails.
onLoadStart function #
Invoked on load start.
e.g., onLoadStart={(e) => this.setState({loading: true})}
resizeMode enum('cover', 'contain', 'stretch', 'repeat', 'center') #
Determines how to resize the image when the frame doesn't match the raw +}
Props #
onError?: function #
Invoked on load error with {nativeEvent: {error}}.
onLayout?: function #
Invoked on mount and layout changes with
+{nativeEvent: {layout: {x, y, width, height}}}.
onLoad?: function #
Invoked when load completes successfully.
onLoadEnd?: function #
Invoked when load either succeeds or fails.
onLoadStart?: function #
Invoked on load start.
e.g., onLoadStart={(e) => this.setState({loading: true})}
resizeMode?: enum('cover', 'contain', 'stretch', 'repeat', 'center') #
Determines how to resize the image when the frame doesn't match the raw image dimensions.
cover: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or larger than the corresponding dimension of the view (minus padding).contain: Scale the image uniformly (maintain the image's aspect ratio) so that both dimensions (width and height) of the image will be equal to or less than the corresponding dimension of the view (minus padding).stretch: Scale width and height independently, This may change the aspect ratio of the src.repeat: Repeat the image to cover the frame of the view. The -image will keep it's size and aspect ratio. (iOS only)
source ImageSourcePropType #
The image source (either a remote URL or a local file resource).
This prop can also contain several remote URLs, specified together with +image will keep it's size and aspect ratio. (iOS only)
source?: ImageSourcePropType #
The image source (either a remote URL or a local file resource).
This prop can also contain several remote URLs, specified together with
their width and height and potentially with scale/other URI arguments.
The native side will then choose the best uri to display based on the
measured size of the image container. A cache property can be added to
-control how networked request interacts with the local cache.
style style #
backfaceVisibility enum('visible', 'hidden')
backgroundColor color
borderBottomLeftRadius number
borderBottomRightRadius number
borderColor color
borderRadius number
borderTopLeftRadius number
borderTopRightRadius number
borderWidth number
opacity number
overflow enum('visible', 'hidden')
resizeMode Object.keys(ImageResizeMode)
tintColor color Changes the color of all the non-transparent pixels to the tintColor.
Changes the color of all the non-transparent pixels to the tintColor.
androidoverlayColor string When the image has rounded corners, specifying an overlayColor will
+control how networked request interacts with the local cache.
When the image has rounded corners, specifying an overlayColor will +control how networked request interacts with the local cache.
style?: style #
backfaceVisibility enum('visible', 'hidden')
backgroundColor color
borderBottomLeftRadius number
borderBottomRightRadius number
borderColor color
borderRadius number
borderTopLeftRadius number
borderTopRightRadius number
borderWidth number
opacity number
overflow enum('visible', 'hidden')
resizeMode Object.keys(ImageResizeMode)
tintColor color Changes the color of all the non-transparent pixels to the tintColor.
Changes the color of all the non-transparent pixels to the tintColor.
androidoverlayColor string When the image has rounded corners, specifying an overlayColor will
cause the remaining space in the corners to be filled with a solid color.
This is useful in cases which are not supported by the Android
implementation of rounded corners:
@@ -85,25 +85,25 @@ background and setting the overlayColor to the same color
as the background.
For details of how this works under the hood, see
http://frescolib.org/docs/rounded-corners-and-circles.html
When the image has rounded corners, specifying an overlayColor will
cause the remaining space in the corners to be filled with a solid color.
This is useful in cases which are not supported by the Android
implementation of rounded corners:
@@ -85,25 +85,25 @@ background and setting the overlayColor to the same color
as the background.
For details of how this works under the hood, see http://frescolib.org/docs/rounded-corners-and-circles.html
ImageResizeModeis anEnumfor different image resizing modes, set via theresizeModestyle property onImagecomponents. The values arecontain,cover, -stretch,center,repeat.
testID string #
A unique identifier for this element to be used in UI Automation -testing scripts.
androidresizeMethod enum('auto', 'resize', 'scale') #
The mechanism that should be used to resize the image when the image's dimensions
+stretch, center, repeat.
testID?: string #
A unique identifier for this element to be used in UI Automation +testing scripts.
androidresizeMethod?: enum('auto', 'resize', 'scale') #
The mechanism that should be used to resize the image when the image's dimensions
differ from the image view's dimensions. Defaults to auto.
auto: Use heuristics to pick betweenresizeandscale.resize: A software operation which changes the encoded image in memory before it gets decoded. This should be used instead ofscalewhen the image is much larger than the view.scale: The image gets drawn downscaled or upscaled. Compared toresize,scaleis faster (usually hardware accelerated) and produces higher quality images. This should be used if the image is smaller than the view. It should also be used if the -image is slightly bigger than the view.
More details about resize and scale can be found at http://frescolib.org/docs/resizing-rotating.html.
iosaccessibilityLabel string #
The text that's read by the screen reader when the user interacts with -the image.
iosaccessible bool #
When true, indicates the image is an accessibility element.
iosblurRadius number #
blurRadius: the blur radius of the blur filter added to the image
ioscapInsets {top: number, left: number, bottom: number, right: number} #
When the image is resized, the corners of the size specified +image is slightly bigger than the view.
More details about resize and scale can be found at http://frescolib.org/docs/resizing-rotating.html.
iosaccessibilityLabel?: string #
The text that's read by the screen reader when the user interacts with +the image.
iosaccessible?: bool #
When true, indicates the image is an accessibility element.
iosblurRadius?: number #
blurRadius: the blur radius of the blur filter added to the image
ioscapInsets?: {top: number, left: number, bottom: number, right: number} #
When the image is resized, the corners of the size specified
by capInsets will stay a fixed size, but the center content and borders
of the image will be stretched. This is useful for creating resizable
rounded buttons, shadows, and other resizable assets. More info in the
-official Apple documentation.
iosdefaultSource {uri: string, width: number, height: number, scale: number}, number #
A static image to display while loading the image source.
uri- a string representing the resource identifier for the image, which +official Apple documentation.
iosdefaultSource?: {uri: string, width: number, height: number, scale: number}, number #
A static image to display while loading the image source.
uri- a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource (which should be wrapped in therequire('./path/to/image.png')function).width,height- can be specified if known at build time, in which case these will be used to set the default<Image/>component dimensions.scale- used to indicate the scale factor of the image. Defaults to 1.0 if -unspecified, meaning that one image pixel equates to one display point / DIP.number- Opaque type returned by something likerequire('./image.jpg').
iosonPartialLoad function #
Invoked when a partial load of the image is complete. The definition of +unspecified, meaning that one image pixel equates to one display point / DIP.
number - Opaque type returned by something like require('./image.jpg').iosonPartialLoad?: function #
Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant -for progressive JPEG loads.
iosonProgress function #
Invoked on download progress with {nativeEvent: {loaded, total}}.
Methods #
static getSize(uri, success, failure): #
Retrieve the width and height (in pixels) of an image prior to displaying it. +for progressive JPEG loads.
iosonProgress?: function #
Invoked on download progress with {nativeEvent: {loaded, total}}.
Methods #
static getSize(uri: string, success: function, failure: function): #
Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.
In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not @@ -111,7 +111,7 @@ optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.
| Name and Type | Description |
|---|---|
| uri string | The location of the image. |
| success function | The function that will be called if the image was successfully found and width and height retrieved. |
| failure function | The function that will be called if there was an error, such as failing to -to retrieve the image. |
static prefetch(url): #
Prefetches a remote image for later use by downloading it to the disk +to retrieve the image.
static prefetch(url: string): #
Prefetches a remote image for later use by downloading it to the disk cache
| Name and Type | Description |
|---|---|
| url string | The remote location of the image. |
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
ImageEditor #
Methods #
static cropImage(uri, cropData, success, failure) #
Crop the image specified by the URI param. If URI points to a remote +
ImageEditor #
Methods #
static cropImage(uri, cropData, success, failure) #
Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.
If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the -cropped image from the ImageStore when you are done with it.
You can edit the content above on GitHub and send us a pull request!
Images #
Static Image Resources #
React Native provides a unified way of managing images and other media assets in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
The image name is resolved the same way JS modules are resolved. In the example above, the packager will look for my-icon.png in the same folder as the component that requires it. Also, if you have my-icon.ios.png and my-icon.android.png, the packager will pick the correct file for the platform.
You can also use the @2x and @3x suffixes to provide images for different screen densities. If you have the following file structure:
Images #
Static Image Resources #
React Native provides a unified way of managing images and other media assets in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
The image name is resolved the same way JS modules are resolved. In the example above, the packager will look for my-icon.png in the same folder as the component that requires it. Also, if you have my-icon.ios.png and my-icon.android.png, the packager will pick the correct file for the platform.
You can also use the @2x and @3x suffixes to provide images for different screen densities. If you have the following file structure:
Images.xcassets.< <Image source={...}> <Text>Inside</Text> </Image> -);
iOS Border Radius Styles #
Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:
borderTopLeftRadiusborderTopRightRadiusborderBottomLeftRadiusborderBottomRightRadius
Off-thread Decoding #
Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.
You can edit the content above on GitHub and send us a pull request!
ImageStore #
Methods #
static hasImageForTag(uri, callback) #
Check if the ImageStore contains image data for the specified URI. +
ImageStore #
Methods #
static hasImageForTag(uri, callback) #
Check if the ImageStore contains image data for the specified URI. @platform ios
static removeImageForTag(uri) #
Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to @@ -16,7 +16,7 @@ will be called.
Note that it is very inefficient to transfer large quantit
data between JS and native code, so you should avoid calling this more
than necessary. To display an image in the ImageStore, you can just pass
the URI to an <Image/> component; there is no need to retrieve the
-base64 data.
You can edit the content above on GitHub and send us a pull request!