React NativeAccessibility # | Edit on GitHub |
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 # | Edit on GitHub |
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:
ActionSheetIOS # | Edit on GitHub |
Methods #
static showActionSheetWithOptions(options, callback) #
Display an iOS action sheet. The options object must contain one or more
+
ActionSheetIOS # | Edit on GitHub |
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 activites to exclude from the ActionSheet
NOTE: if url points to a local file, or is a base64-encoded
diff --git a/releases/next/docs/activityindicator.html b/releases/next/docs/activityindicator.html
index 34c7a559d84..b5128c3eb8d 100644
--- a/releases/next/docs/activityindicator.html
+++ b/releases/next/docs/activityindicator.html
@@ -1,4 +1,4 @@
-
ActivityIndicator # | Edit on GitHub |
Displays a circular loading indicator.
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36. +
ActivityIndicator # | Edit on GitHub |
Displays a circular loading indicator.
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36. Other sizes can be obtained using a scale transform.
ioshidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
Examples # | Edit on GitHub |
Alert # | Edit on GitHub |
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the +
Alert # | Edit on GitHub |
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, diff --git a/releases/next/docs/alertios.html b/releases/next/docs/alertios.html index 9988eae4623..6dbf615bb0f 100644 --- a/releases/next/docs/alertios.html +++ b/releases/next/docs/alertios.html @@ -1,4 +1,4 @@ -
AlertIOS # | Edit on GitHub |
AlertIOS provides functionality to create an iOS alert dialog with a
+
AlertIOS # | Edit on GitHub |
AlertIOS provides functionality to create an iOS alert dialog with a
message or create a prompt for user input.
Creating an iOS alert:
Building React Native from source # | Edit on GitHub |
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Local Maven repository for Support Libraries (formerly
Android Support Repository) >= 17 (for Android Support Library) - Android NDK (download links and installation instructions below)
Point Gradle to your Android SDK: either have $ANDROID_SDK and $ANDROID_NDK defined, or create a local.properties file in the root of your react-native checkout with the following contents:
Building React Native from source # | Edit on GitHub |
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Local Maven repository for Support Libraries (formerly
Android Support Repository) >= 17 (for Android Support Library) - Android NDK (download links and installation instructions below)
Point Gradle to your Android SDK: either have $ANDROID_SDK and $ANDROID_NDK defined, or create a local.properties file in the root of your react-native checkout with the following contents:
Example:
Download links for Android NDK #
- Mac OS (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-darwin-x86_64.zip
- Linux (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip
- Windows (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-windows-x86_64.zip
- Windows (32-bit) - http://dl.google.com/android/repository/android-ndk-r10e-windows-x86.zip
You can find further instructions on the official page.
Building the source #
1. Installing the fork #
First, you need to install react-native from your fork. For example, to install the master branch from the official repo, run the following:
Alternatively, you can clone the repo to your node_modules directory and run npm install inside the cloned repo.
2. Adding gradle dependencies #
Add gradle-download-task as dependency in android/build.gradle:
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Animated # | Edit on GitHub |
Animations are an important part of modern UX, and the Animated
+
Animated # | Edit on GitHub |
Animations are an important part of modern UX, and the Animated
library 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
@@ -85,14 +85,14 @@ mechanism at a time. Using a new mechanism (e.g. starting a new animation,
or calling setValue) will stop any previous ones.
Methods #
constructor(value) #
setValue(value) #
Directly set the value. This will stop any animations running on the value and update all the bound properties.
setOffset(offset) #
Sets an offset that is applied on top of whatever value is set, whether via
setValue, an animation, or Animated.event. Useful for compensating
-things like the start of a pan gesture.
flattenOffset() #
Merges the offset value into the base value and resets the offset to zero. +things like the start of a pan gesture.
flattenOffset(0) #
Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.
addListener(callback) #
Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to -synchronously read the value because it might be driven natively.
removeListener(id) #
removeAllListeners() #
stopAnimation(callback?) #
Stops any running animation or tracking. callback is invoked with the
+synchronously read the value because it might be driven natively.
removeListener(id) #
removeAllListeners(0) #
stopAnimation(callback?) #
Stops any running animation or tracking. callback is invoked with the
final value after stopping the animation, which is useful for updating
state to match the animation position with layout.
interpolate(config) #
Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.
animate(animation, callback) #
Typically only used internally, but could be used by a custom Animation -class.
stopTracking() #
Typically only used internally.
track(tracking) #
Typically only used internally.
class AnimatedValueXY #
2D Value for driving 2D animations, such as pan gestures. Almost identical +class.
stopTracking(0) #
Typically only used internally.
track(tracking) #
Typically only used internally.
class AnimatedValueXY #
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 state that occurs when transitioning between @@ -26,7 +26,7 @@ render: funct ); },
2D Value for driving 2D animations, such as pan gestures. Almost identical
API to normal Animated.Value, but multiplexed. Contains two regular
Animated.Values under the hood. Example:
Animated.Value, but multiplexed. Contains two regula
</Animated.View>
);
}
- }Methods #
constructor(valueIn?) #
setValue(value) #
setOffset(offset) #
flattenOffset() #
stopAnimation(callback?) #
addListener(callback) #
removeListener(id) #
getLayout() #
Converts {x, y} into {left, top} for use in style, e.g.
getTranslateTransform() #
Converts {x, y} into a useable translation transform, e.g.
Methods #
constructor(valueIn?) #
setValue(value) #
setOffset(offset) #
flattenOffset(0) #
stopAnimation(callback?) #
addListener(callback) #
removeListener(id) #
getLayout(0) #
Converts {x, y} into {left, top} for use in style, e.g.
getTranslateTransform(0) #
Converts {x, y} into a useable translation transform, e.g.
Examples # | Edit on GitHub |
Animations # | Edit on GitHub |
Fluid, meaningful animations are essential to the mobile user experience. Like +
Animations # | Edit on GitHub |
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:
LayoutAnimation for animated global layout transactions, and Animated for
diff --git a/releases/next/docs/appregistry.html b/releases/next/docs/appregistry.html
index 459b41cfac1..c17eaabea62 100644
--- a/releases/next/docs/appregistry.html
+++ b/releases/next/docs/appregistry.html
@@ -1,4 +1,4 @@
-
AppRegistry # | Edit on GitHub |
AppRegistry is the JS entry point to running all React Native apps. App
+
AppRegistry # | Edit on GitHub |
AppRegistry is the JS entry point to running all React Native apps. App
root components should register themselves with
AppRegistry.registerComponent, then the native system can load the bundle
for the app and then actually run the app when it's ready by invoking
@@ -6,7 +6,7 @@ for the app and then actually run the app when it's ready by invoking
AppRegistry.unmountApplicationComponentAtRootTag with the tag that was
pass into runApplication. These should always be used as a pair.
AppRegistry should be required early in the require sequence to make
sure the JS execution environment is setup before other modules are
-required.
Methods #
AppState # | Edit on GitHub |
AppState can tell you if the app is in the foreground or background,
+
AppState # | Edit on GitHub |
AppState can tell you if the app is in the foreground or background,
and notify you when the state changes.
AppState is frequently used to determine the intent and proper behavior when handling push notifications.
App States #
This example will only ever appear to say "Current state is: active" because
the app is only visible to the user when in the active state, and the null
-state will happen only momentarily.
Methods #
constructor() #
addEventListener(type, handler) #
Add a handler to AppState changes by listening to the change event type
+state will happen only momentarily.
Methods #
constructor(0) #
addEventListener(type, handler) #
Add a handler to AppState changes by listening to the change event type
and providing the handler
TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate
addEventListener and removeEventListener and just use addListener and
listener.remove() directly. That will be a breaking change though, as both
diff --git a/releases/next/docs/asyncstorage.html b/releases/next/docs/asyncstorage.html
index de1e964ed56..0b73266c31e 100644
--- a/releases/next/docs/asyncstorage.html
+++ b/releases/next/docs/asyncstorage.html
@@ -1,20 +1,35 @@
-
AsyncStorage # | Edit on GitHub |
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.
On iOS, AsyncStorage is backed by native code that stores small values in a serialized
-dictionary and larger values in separate files. On Android, AsyncStorage will use either
-RocksDB or SQLite based on what is available. This JS code is a simple facade that
-provides a clear JS API, real Error objects, and simple non-multi functions. Each
-method returns a Promise object.
Methods #
static getItem(key, callback?) #
Fetches key and passes the result to callback, along with an Error if
-there is any. Returns a Promise object.
static setItem(key, value, callback?) #
Sets value for key and calls callback on completion, along with an
-Error if there is any. Returns a Promise object.
static removeItem(key, callback?) #
Returns a Promise object.
static mergeItem(key, value, callback?) #
Merges existing value with input value, assuming they are stringified json.
-Returns a Promise object. Not supported by all native implementations.
Example:
AsyncStorage # | Edit on GitHub |
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.
On iOS, AsyncStorage is backed by native code that stores small values in a
+serialized dictionary and larger values in separate files. On Android,
+AsyncStorage will use either RocksDB or SQLite
+based on what is available.
The AsyncStorage JavaScript code is a simple facade that provides a clear
+JavaScript API, real Error objects, and simple non-multi functions. Each
+method in the API returns a Promise object.
Persisting data:
Fetching data:
Methods #
static getItem(key, callback?) #
Fetches an item for a key and invokes a callback upon completion.
+Returns a Promise object.
| Name and Type | Description |
|---|---|
| key string | Key of the item to fetch. |
| [callback] ?(error: ?Error, result: ?string) => void | Function that will be called with a result if found or + any error. |
static setItem(key, value, callback?) #
Sets the value for a key and invokes a callback upon completion.
+Returns a Promise object.
| Name and Type | Description |
|---|---|
| key string | Key of the item to set. |
| value string | Value to set for the |
| [callback] ?(error: ?Error) => void | Function that will be called with any error. |
static removeItem(key, callback?) #
Removes an item for a key and invokes a callback upon completion.
+Returns a Promise object.
| Name and Type | Description |
|---|---|
| key string | Key of the item to remove. |
| [callback] ?(error: ?Error) => void | Function that will be called with any error. |
static mergeItem(key, value, callback?) #
Merges an existing key value with an input value, assuming both values
+are stringified JSON. Returns a Promise object.
NOTE: This is not supported by all native implementations.
| Name and Type | Description |
|---|---|
| key string | Key of the item to modify. |
| value string | New value to merge for the |
| [callback] ?(error: ?Error) => void | Function that will be called with any error. |
Example:
static clear(callback?) #
Erases all AsyncStorage for all clients, libraries, etc. You probably
-don't want to call this - use removeItem or multiRemove to clear only your
-own keys instead. Returns a Promise object.
static getAllKeys(callback?) #
Gets all keys known to the app, for all callers, libraries, etc. Returns a Promise object.
Example: see multiGet for example
static flushGetRequests() #
Flushes any pending requests using a single multiget
static multiGet(keys, callback?) #
multiGet invokes callback with an array of key-value pair arrays that
-matches the input format of multiSet. Returns a Promise object.
multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])
Example:
static clear(callback?) #
Erases all AsyncStorage for all clients, libraries, etc. You probably
+don't want to call this; use removeItem or multiRemove to clear only
+your app's keys. Returns a Promise object.
| Name and Type | Description |
|---|---|
| [callback] ?(error: ?Error) => void | Function that will be called with any error. |
static getAllKeys(callback?) #
Gets all keys known to your app; for all callers, libraries, etc.
+Returns a Promise object.
| Name and Type | Description |
|---|---|
| [callback] ?(error: ?Error, keys: ?Array<string>) => void | Function that will be called the keys found and any error. |
static flushGetRequests() #
Flushes any pending requests using a single batch call to get the data.
static multiGet(keys, callback?) #
This allows you to batch the fetching of items given an array of key
+inputs. Your callback will be invoked with an array of corresponding
+key-value pairs found:
The method returns a Promise object.
| Name and Type | Description |
|---|---|
| keys Array<string> | Array of key for the items to get. |
| [callback] ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => void | Function that will be called with a key-value array of + the results, plus an array of any key-specific errors found. |
Example:
Promise object.
let value = store[i][1];
});
});
-});static multiSet(keyValuePairs, callback?) #
multiSet and multiMerge take arrays of key-value array pairs that match
-the output of multiGet, e.g. Returns a Promise object.
multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
Example: see multiMerge for an example
static multiRemove(keys, callback?) #
Delete all the keys in the keys array. Returns a Promise object.
Example:
static multiSet(keyValuePairs, callback?) #
Use this as a batch operation for storing multiple key-value pairs. When +the operation completes you'll get a single callback with any errors:
The method returns a Promise object.
| Name and Type | Description |
|---|---|
| keyValuePairs Array<Array<string>> | Array of key-value array for the items to set. |
| [callback] ?(errors: ?Array<Error>) => void | Function that will be called with an array of any + key-specific errors found. |
static multiRemove(keys, callback?) #
Call this to batch the deletion of all keys in the keys array. Returns
+a Promise object.
| Name and Type | Description |
|---|---|
| keys Array<string> | Array of key for the items to delete. |
| [callback] ?(errors: ?Array<Error>) => void | Function that will be called an array of any key-specific + errors found. |
Example:
static multiMerge(keyValuePairs, callback?) #
Merges existing values with input values, assuming they are stringified
-json. Returns a Promise object.
Not supported by all native implementations.
Example:
static multiMerge(keyValuePairs, callback?) #
Batch operation to merge in existing and new values for a given set of
+keys. This assumes that the values are stringified JSON. Returns a
+Promise object.
NOTE: This is not supported by all native implementations.
| Name and Type | Description |
|---|---|
| keyValuePairs Array<Array<string>> | Array of key-value array for the items to merge. |
| [callback] ?(errors: ?Array<Error>) => void | Function that will be called with an array of any + key-specific errors found. |
Example:
Properties #
Examples # | Edit on GitHub |
Examples # | Edit on GitHub |
BackAndroid # | Edit on GitHub |
Detect hardware back button presses, and programmatically invoke the default back button +
BackAndroid # | Edit on GitHub |
Detect hardware back button presses, and programmatically invoke the default back button functionality to exit the app if there are no listeners or if none of the listeners return true.
Example:
Methods #
Image # | Edit on GitHub |
Another basic React Native component is the Image component. Like Text, the Image component simply renders an image.
An
Imageis analogous to the<img>HTML tag when building websites.
The simplest way to render an image is to provide a source file to that image via the source attribute.
This example displays a checkbox Image on the device.
Image # | Edit on GitHub |
Another basic React Native component is the Image component. Like Text, the Image component simply renders an image.
An
Imageis analogous to the<img>HTML tag when building websites.
The simplest way to render an image is to provide a source file to that image via the source attribute.
This example displays a checkbox Image on the device.
ListView # | Edit on GitHub |
On mobile devices, lists are a core element in many applications. The ListView component is a special type of View that displays a vertically scrolling list of changing, but similarly structured, data.
ListView works best for possibly lengthy datasources (e.g., from an endpoint or database), where the number of items may not be known a priori.
Unlike the more generic
ScrollView, theListViewonly renders elements that are currently showing on the screen, not all the elements at once.
The ListView component requires two properties, dataSource and renderRow. dataSource is the source of information for the list. renderRow takes one item from the source and returns a formatted component to render.
This example creates a simple ListView of hardcoded data. It first initializes the dataSource that will be used to populate the ListView. Each item in the dataSource is then rendered as a Text component. Finally it renders the ListView and all Text components.
A
rowHasChangedfunction is required to useListView. Here we just say a row has changed if the row we are on is not the same as the previous row.
ListView # | Edit on GitHub |
On mobile devices, lists are a core element in many applications. The ListView component is a special type of View that displays a vertically scrolling list of changing, but similarly structured, data.
ListView works best for possibly lengthy datasources (e.g., from an endpoint or database), where the number of items may not be known a priori.
Unlike the more generic
ScrollView, theListViewonly renders elements that are currently showing on the screen, not all the elements at once.
The ListView component requires two properties, dataSource and renderRow. dataSource is the source of information for the list. renderRow takes one item from the source and returns a formatted component to render.
This example creates a simple ListView of hardcoded data. It first initializes the dataSource that will be used to populate the ListView. Each item in the dataSource is then rendered as a Text component. Finally it renders the ListView and all Text components.
A
rowHasChangedfunction is required to useListView. Here we just say a row has changed if the row we are on is not the same as the previous row.
ScrollView # | Edit on GitHub |
Given the screen sizes of mobile devices, the ability to scroll through data is generally paramount for a proper usability experience.
The ScrollView is a generic scrolling container that can host multiple components and views. The scrollable items need not be homogenous, and you can scroll both vertically and horizontally (by setting the horizontal property).
ScrollView works best to present a list of short, static items of a known quantity. All the elements and views of a ScrollView are rendered a priori, even if they are not currently shown on the screen. Contrast this with a ListView, which render only those views that are on the screen and remove views that go off-screen.
TextViewandListVieware specialized scrollable containers.
This contrived example creates a horizontal ScrollView with a static amount of heterogenous elements (images and text).
ScrollView # | Edit on GitHub |
Given the screen sizes of mobile devices, the ability to scroll through data is generally paramount for a proper usability experience.
The ScrollView is a generic scrolling container that can host multiple components and views. The scrollable items need not be homogenous, and you can scroll both vertically and horizontally (by setting the horizontal property).
ScrollView works best to present a list of short, static items of a known quantity. All the elements and views of a ScrollView are rendered a priori, even if they are not currently shown on the screen. Contrast this with a ListView, which render only those views that are on the screen and remove views that go off-screen.
TextViewandListVieware specialized scrollable containers.
This contrived example creates a horizontal ScrollView with a static amount of heterogenous elements (images and text).
Text # | Edit on GitHub |
The most basic component in React Native is the Text component. The Text component simply renders text.
This example displays the string "Hello World!" on the device.
Text # | Edit on GitHub |
The most basic component in React Native is the Text component. The Text component simply renders text.
This example displays the string "Hello World!" on the device.
TextInput # | Edit on GitHub |
Direct text-based user input is a foundation for many apps. Writing a post or comment on a page is a canonical example of this. TextInput is a basic component that allows the user to enter text.
This example creates a simple TextInput box with the string Type something here as the placeholder when the TextInput is empty.
TextInput # | Edit on GitHub |
Direct text-based user input is a foundation for many apps. Writing a post or comment on a page is a canonical example of this. TextInput is a basic component that allows the user to enter text.
This example creates a simple TextInput box with the string Type something here as the placeholder when the TextInput is empty.
View # | Edit on GitHub |
A View is the most basic building block for a React Native application. The View is an abstraction on top of the target platform's native equivalent, such as iOS's UIView.
A
Viewis analogous to using a<div>HTML tag for building websites.
It is recommended that you wrap your components in a View to style and control layout.
The example below creates a View that aligns the string Hello in the top center of the device, something which could not be done with a Text component alone (i.e., a Text component without a View would place the string in a fixed location in the upper corner):
View # | Edit on GitHub |
A View is the most basic building block for a React Native application. The View is an abstraction on top of the target platform's native equivalent, such as iOS's UIView.
A
Viewis analogous to using a<div>HTML tag for building websites.
It is recommended that you wrap your components in a View to style and control layout.
The example below creates a View that aligns the string Hello in the top center of the device, something which could not be done with a Text component alone (i.e., a Text component without a View would place the string in a fixed location in the upper corner):
Components # | Edit on GitHub |
Components are the building blocks for a React Native application. A React Native user interface (UI) is specified by declaring components, often nested. Those components are then mapped to the native UI on the targeted platform.
Props #
this.props #
Components can be configured by passing properties props to the constructor. You can access props from your component's methods by accessing this.props. You should not alter your props within component methods.
State #
this.state #
Components maintain their state using the state object. You can access your component state via this.state. Each component should manage its own state. Parent components should not manage children state and children components should not manage parent component state.
this.setState({key: value, ...}) #
To update or change the state of your component passing a new object representing your newly desired state to this.setState(obj). The specificed keys will be merged into this.state. Any existing keys will be overridden by new values.
Core Components. #
React Native has a number of core components that are commonly used in applications, either on their own or combined to build new components.
Components # | Edit on GitHub |
Components are the building blocks for a React Native application. A React Native user interface (UI) is specified by declaring components, often nested. Those components are then mapped to the native UI on the targeted platform.
Props #
this.props #
Components can be configured by passing properties props to the constructor. You can access props from your component's methods by accessing this.props. You should not alter your props within component methods.
State #
this.state #
Components maintain their state using the state object. You can access your component state via this.state. Each component should manage its own state. Parent components should not manage children state and children components should not manage parent component state.
this.setState({key: value, ...}) #
To update or change the state of your component passing a new object representing your newly desired state to this.setState(obj). The specificed keys will be merged into this.state. Any existing keys will be overridden by new values.
Core Components. #
React Native has a number of core components that are commonly used in applications, either on their own or combined to build new components.
Dimensions # | Edit on GitHub |
A component's dimensions 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.
Dimensions # | Edit on GitHub |
A component's dimensions 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.
Layout # | Edit on GitHub |
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 flexDirection, alignItems, and justifyContent to achieve the right layout.
Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The most notable one: the defaults are different, with
flexDirectiondefaulting tocolumninstead ofrow, andalignItemsdefaulting tostretchinstead offlex-start.
Flex Direction #
Adding flexDirection to a component's style determines the primary axis of its layout. Should the children be organized horizontally (row) or vertically (column)? The default is column.
Justify Content #
Adding justifyContent to a component's style determines the distribution of children along the primary axis. Should children be distributed at the start, the center, the end, or spaced evenly? Available options are flex-start, center, flex-end, space-around, and space-between.
Align Items #
Adding alignItems to a component's style determines the alignment of children along the secondary axis (if the primary axis is row, then the secondary is column, and vice versa). Should children be aligned at the start, the center, the end, or stretched to fill? Available options are flex-start, center, flex-end, and stretch.
For
stretchto have an effect, children must not have a fixed dimension along the secondary axis. In the following example, settingalignItems: stretchdoes nothing until thewidth: 50is removed from the children.
API Reference #
We've covered the basics, but there are many other styles you may need for layouts. The full list is available here.
CameraRoll # | Edit on GitHub |
CameraRoll provides access to the local camera roll / gallery.
Methods #
static saveImageWithTag(tag) #
static saveToCameraRoll(tag, type?) #
Saves the photo or video to the camera roll / gallery.
On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".
On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) +
CameraRoll # | Edit on GitHub |
CameraRoll provides access to the local camera roll / gallery.
Methods #
static saveImageWithTag(tag) #
static saveToCameraRoll(tag, type?) #
Saves the photo or video to the camera roll / gallery.
On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".
On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) or a local video file URI (remote or data URIs are not supported for saving video at this time).
If the tag has a file extension of .mov or .mp4, it will be inferred as a video. Otherwise
it will be treated as a photo. To override the automatic choice, you can pass an optional
type parameter that must be one of 'photo' or 'video'.
Returns a Promise which will resolve with the new URI.
static getPhotos(params) #
Returns a Promise with photo identifier objects from the local camera diff --git a/releases/next/docs/clipboard.html b/releases/next/docs/clipboard.html index 55516fa5013..b22a9d9621c 100644 --- a/releases/next/docs/clipboard.html +++ b/releases/next/docs/clipboard.html @@ -1,4 +1,4 @@ -
Clipboard # | Edit on GitHub |
Clipboard gives you an interface for setting and getting content from Clipboard on both iOS and Android
Methods #
static getString() #
Get content of string type, this method returns a Promise, so you can use following code to get clipboard content
Clipboard # | Edit on GitHub |
Clipboard gives you an interface for setting and getting content from Clipboard on both iOS and Android
Methods #
static getString(0) #
Get content of string type, this method returns a Promise, so you can use following code to get clipboard content
static setString(content) #
Set content of string type. You can use following code to set clipboard content