Add Navigation Overview
Summary: Initial stab at writing a high level guide on navigation. Its main focus is on Navigator due to it being cross-platform and fairly simple to use. This guide should be expanded to cover tabbed applications in a future pull request. The Navigation (Experimental) section will be similarly expanded upon as the API stabilizes.  Closes https://github.com/facebook/react-native/pull/8390 Differential Revision: D3480304 Pulled By: caabernathy fbshipit-source-id: 280da9185fca295bc107a2df20106c783b461be7
This commit is contained in:
Héctor Ramos
Facebook Github Bot 5
parent
ab4684551f
commit
35f5ce296b
|
|
@ -98,9 +98,6 @@ type Event = Object;
|
|||
* [`Navigator`](/docs/navigator.html) for a similar solution for your
|
||||
* cross-platform needs.
|
||||
*
|
||||
* > **NOTE**: This component is not maintained by Facebook and is the
|
||||
* > community's responsibility.
|
||||
*
|
||||
* To set up the navigator, provide the `initialRoute` prop with a route
|
||||
* object. A route object is used to describe each scene that your app
|
||||
* navigates to. `initialRoute` represents the first route in your navigator.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ title: JavaScript Environment
|
|||
layout: docs
|
||||
category: Guides
|
||||
permalink: docs/javascript-environment.html
|
||||
next: navigator-comparison
|
||||
next: navigation
|
||||
---
|
||||
|
||||
## JavaScript Runtime
|
||||
|
|
|
|||
|
|
@ -0,0 +1,165 @@
|
|||
---
|
||||
id: navigation
|
||||
title: Navigation
|
||||
layout: docs
|
||||
category: Guides
|
||||
permalink: docs/navigation.html
|
||||
next: navigator-comparison
|
||||
---
|
||||
|
||||
Mobile apps rarely consist of just one screen or scene. As soon as you add a second scene to your app, you will have to take into consideration how the user will navigate from one scene to the other.
|
||||
|
||||
Navigators in React Native allow you to push and pop scenes in a master/detail stack, or to pop up modal scenes. Navigators handle the transitions between scenes, and also maintain the navigational state of your application.
|
||||
|
||||
If you are just getting started with React Native, you will probably want to start with the `Navigator` component.
|
||||
|
||||
## Navigator
|
||||
|
||||
`Navigator` is a cross-platform implementation of a navigation stack, so it works on both iOS and Android. It is easy to customize and includes simple navigation bars.
|
||||
|
||||
```js
|
||||
<Navigator
|
||||
initialRoute={{ title: 'My Initial Scene', index: 0}}
|
||||
renderScene={(route, navigator) => {
|
||||
// We'll get to this function soon.
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
Something you will encounter a lot when dealing with navigation is the concept of routes. A route is an object that contains information about a scene. It is used to provide all the context the `renderScene` function needs to render a scene.
|
||||
|
||||
The `push` and `pop` functions provided by Navigator can be used to push and pop routes into the navigation stack. A more complete example that demonstrates the pushing and popping of routes could therefore look something like this:
|
||||
|
||||
```js
|
||||
class MyScene extends Component {
|
||||
static propTypes = {
|
||||
title: PropTypes.string.isRequired,
|
||||
onForward: PropTypes.func.isRequired,
|
||||
onBack: PropTypes.func.isRequired,
|
||||
}
|
||||
render() {
|
||||
return (
|
||||
<View>
|
||||
<Text>Current Scene: { this.props.title }</Text>
|
||||
<TouchableHighlight onPress={this.props.onForward}>
|
||||
<Text>Tap me to load the next scene</Text>
|
||||
</TouchableHighlight>
|
||||
<TouchableHighlight onPress={this.props.onBack}>
|
||||
<Text>Tap me to go back</Text>
|
||||
</TouchableHighlight>
|
||||
</View>
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
class SimpleNavigationApp extends Component {
|
||||
render() {
|
||||
return (
|
||||
<Navigator
|
||||
initialRoute={{ title: 'My Initial Scene', index: 0 }}
|
||||
renderScene={(route, navigator) =>
|
||||
<MyScene
|
||||
title={route.title}
|
||||
onForward={ () => {
|
||||
const nextIndex = route.index + 1;
|
||||
navigator.push({
|
||||
title: 'Scene ' + nextIndex,
|
||||
index: nextIndex,
|
||||
});
|
||||
}}
|
||||
onBack={() => {
|
||||
if (route.index > 0) {
|
||||
navigator.pop();
|
||||
}
|
||||
}}
|
||||
/>
|
||||
}
|
||||
/>
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the `MyScene` component is passed the title of the current route via the `title` prop. It displays two tappable components that call the `onForward` and `onBack` functions passed through its props, which in turn will call `navigator.push()` and `navigator.pop()` as needed.
|
||||
|
||||
While this is a very basic example, it can easily be adapted to render an entirely different component based on the route that is passed to the `renderScene` function. Navigator will push new scenes from the right by default, and you can control this behavior by using the `configureScene` function. Check out the [Navigator API reference](docs/navigator.html) to learn more.
|
||||
|
||||
## NavigatorIOS
|
||||
|
||||
If you are targeting iOS only, you may also want to consider using `NavigatorIOS`. It looks and feels just like `UINavigationController`, because it is actually built on top of it.
|
||||
|
||||
```js
|
||||
<NavigatorIOS
|
||||
initialRoute={{
|
||||
component: MyScene,
|
||||
title: 'My Initial Scene',
|
||||
passProps: { myProp: 'foo' },
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
Just like Navigator, it it uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the `component` key in the route, and any props that should be passed to this component can be specified in `passProps`. A navigator object is automatically passed as a prop to the component, allowing you to call `push` and `pop` as needed.
|
||||
|
||||
Check out the [NavigatorIOS reference docs](docs/navigatorios.html) to learn more about this component.
|
||||
|
||||
```js
|
||||
class MyScene extends Component {
|
||||
static propTypes = {
|
||||
title: PropTypes.string.isRequired,
|
||||
navigator: PropTypes.object.isRequired,
|
||||
}
|
||||
|
||||
constructor(props, context) {
|
||||
super(props, context);
|
||||
this._onForward = this._onForward.bind(this);
|
||||
this._onBack = this._onBack.bind(this);
|
||||
}
|
||||
|
||||
_onForward() {
|
||||
this.props.navigator.push({
|
||||
title: 'Scene ' + nextIndex,
|
||||
});
|
||||
}
|
||||
|
||||
_onBack() {
|
||||
this.props.navigator.pop();
|
||||
}
|
||||
|
||||
render() {
|
||||
return (
|
||||
<View>
|
||||
<Text>Current Scene: { this.props.title }</Text>
|
||||
<TouchableHighlight onPress={this._onForward}>
|
||||
<Text>Tap me to load the next scene</Text>
|
||||
</TouchableHighlight>
|
||||
<TouchableHighlight onPress={this._onBack}>
|
||||
<Text>Tap me to go back</Text>
|
||||
</TouchableHighlight>
|
||||
</View>
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
class NavigatorIOSApp extends Component {
|
||||
render() {
|
||||
return (
|
||||
<NavigatorIOS
|
||||
initialRoute={{
|
||||
component: MyScene,
|
||||
title: 'My Initial Scene',
|
||||
index: 0
|
||||
}}
|
||||
renderScene={ (route, navigator) =>
|
||||
<MyScene title={route.title} />
|
||||
}
|
||||
/>
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> You may also want to check out [react-native-navigation](https://github.com/wix/react-native-navigation), a component that aims to provide native navigation on both iOS and Android.
|
||||
|
||||
## Navigation (Experimental)
|
||||
|
||||
If you are looking for a more powerful navigation API, check out [NavigationExperimental](https://github.com/facebook/react-native/tree/master/Examples/UIExplorer/NavigationExperimental). It provides greater customization over your transitions, uses single-directional data flow using reducers to manipulate state at a top-level object, and offloads transition animations to the GPU.
|
||||
Loading…
Reference in New Issue