551 lines
11 KiB
Markdown
551 lines
11 KiB
Markdown
---
|
|
id: navigatorios
|
|
title: NavigatorIOS
|
|
layout: docs
|
|
category: components
|
|
permalink: docs/navigatorios.html
|
|
next: picker
|
|
previous: modal
|
|
---
|
|
`NavigatorIOS` is a wrapper around
|
|
[`UINavigationController`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/),
|
|
enabling you to implement a navigation stack. It works exactly the same as it
|
|
would on a native app using `UINavigationController`, providing the same
|
|
animations and behavior from UIKit.
|
|
|
|
As the name implies, it is only available on iOS. Take a look at
|
|
[`React Navigation`](https://reactnavigation.org/) for a cross-platform
|
|
solution in JavaScript, or check out either of these components for native
|
|
solutions: [native-navigation](http://airbnb.io/native-navigation/),
|
|
[react-native-navigation](https://github.com/wix/react-native-navigation).
|
|
|
|
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.
|
|
|
|
```
|
|
import PropTypes from 'prop-types';
|
|
import React, { Component } from 'react';
|
|
import { NavigatorIOS, Text } from 'react-native';
|
|
|
|
export default class NavigatorIOSApp extends Component {
|
|
render() {
|
|
return (
|
|
<NavigatorIOS
|
|
initialRoute={{
|
|
component: MyScene,
|
|
title: 'My Initial Scene',
|
|
}}
|
|
style={{flex: 1}}
|
|
/>
|
|
);
|
|
}
|
|
}
|
|
|
|
class MyScene extends Component {
|
|
static propTypes = {
|
|
title: PropTypes.string.isRequired,
|
|
navigator: PropTypes.object.isRequired,
|
|
}
|
|
|
|
_onForward = () => {
|
|
this.props.navigator.push({
|
|
title: 'Scene ' + nextIndex,
|
|
});
|
|
}
|
|
|
|
render() {
|
|
return (
|
|
<View>
|
|
<Text>Current Scene: { this.props.title }</Text>
|
|
<TouchableHighlight onPress={this._onForward}>
|
|
<Text>Tap me to load the next scene</Text>
|
|
</TouchableHighlight>
|
|
</View>
|
|
)
|
|
}
|
|
}
|
|
```
|
|
|
|
In this code, the navigator renders the component specified in initialRoute,
|
|
which in this case is `MyScene`. This component will receive a `route` prop
|
|
and a `navigator` prop representing the navigator. The navigator's navigation
|
|
bar will render the title for the current scene, "My Initial Scene".
|
|
|
|
You can optionally pass in a `passProps` property to your `initialRoute`.
|
|
`NavigatorIOS` passes this in as props to the rendered component:
|
|
|
|
```
|
|
initialRoute={{
|
|
component: MyScene,
|
|
title: 'My Initial Scene',
|
|
passProps: { myProp: 'foo' }
|
|
}}
|
|
```
|
|
|
|
You can then access the props passed in via `{this.props.myProp}`.
|
|
|
|
#### Handling Navigation
|
|
|
|
To trigger navigation functionality such as pushing or popping a view, you
|
|
have access to a `navigator` object. The object is passed in as a prop to any
|
|
component that is rendered by `NavigatorIOS`. You can then call the
|
|
relevant methods to perform the navigation action you need:
|
|
|
|
```
|
|
class MyView extends Component {
|
|
_handleBackPress() {
|
|
this.props.navigator.pop();
|
|
}
|
|
|
|
_handleNextPress(nextRoute) {
|
|
this.props.navigator.push(nextRoute);
|
|
}
|
|
|
|
render() {
|
|
const nextRoute = {
|
|
component: MyView,
|
|
title: 'Bar That',
|
|
passProps: { myProp: 'bar' }
|
|
};
|
|
return(
|
|
<TouchableHighlight onPress={() => this._handleNextPress(nextRoute)}>
|
|
<Text style={{marginTop: 200, alignSelf: 'center'}}>
|
|
See you on the other nav {this.props.myProp}!
|
|
</Text>
|
|
</TouchableHighlight>
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
You can also trigger navigator functionality from the `NavigatorIOS`
|
|
component:
|
|
|
|
```
|
|
class NavvyIOS extends Component {
|
|
_handleNavigationRequest() {
|
|
this.refs.nav.push({
|
|
component: MyView,
|
|
title: 'Genius',
|
|
passProps: { myProp: 'genius' },
|
|
});
|
|
}
|
|
|
|
render() {
|
|
return (
|
|
<NavigatorIOS
|
|
ref='nav'
|
|
initialRoute={{
|
|
component: MyView,
|
|
title: 'Foo This',
|
|
passProps: { myProp: 'foo' },
|
|
rightButtonTitle: 'Add',
|
|
onRightButtonPress: () => this._handleNavigationRequest(),
|
|
}}
|
|
style={{flex: 1}}
|
|
/>
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
The code above adds a `_handleNavigationRequest` private method that is
|
|
invoked from the `NavigatorIOS` component when the right navigation bar item
|
|
is pressed. To get access to the navigator functionality, a reference to it
|
|
is saved in the `ref` prop and later referenced to push a new scene into the
|
|
navigation stack.
|
|
|
|
#### Navigation Bar Configuration
|
|
|
|
Props passed to `NavigatorIOS` will set the default configuration
|
|
for the navigation bar. Props passed as properties to a route object will set
|
|
the configuration for that route's navigation bar, overriding any props
|
|
passed to the `NavigatorIOS` component.
|
|
|
|
```
|
|
_handleNavigationRequest() {
|
|
this.refs.nav.push({
|
|
//...
|
|
passProps: { myProp: 'genius' },
|
|
barTintColor: '#996699',
|
|
});
|
|
}
|
|
|
|
render() {
|
|
return (
|
|
<NavigatorIOS
|
|
//...
|
|
style={{flex: 1}}
|
|
barTintColor='#ffffcc'
|
|
/>
|
|
);
|
|
}
|
|
```
|
|
|
|
In the example above the navigation bar color is changed when the new route
|
|
is pushed.
|
|
|
|
### Props
|
|
|
|
- [`initialRoute`](docs/navigatorios.html#initialroute)
|
|
- [`barStyle`](docs/navigatorios.html#barstyle)
|
|
- [`barTintColor`](docs/navigatorios.html#bartintcolor)
|
|
- [`interactivePopGestureEnabled`](docs/navigatorios.html#interactivepopgestureenabled)
|
|
- [`itemWrapperStyle`](docs/navigatorios.html#itemwrapperstyle)
|
|
- [`navigationBarHidden`](docs/navigatorios.html#navigationbarhidden)
|
|
- [`shadowHidden`](docs/navigatorios.html#shadowhidden)
|
|
- [`tintColor`](docs/navigatorios.html#tintcolor)
|
|
- [`titleTextColor`](docs/navigatorios.html#titletextcolor)
|
|
- [`translucent`](docs/navigatorios.html#translucent)
|
|
|
|
|
|
|
|
|
|
### Methods
|
|
|
|
- [`push`](docs/navigatorios.html#push)
|
|
- [`popN`](docs/navigatorios.html#popn)
|
|
- [`pop`](docs/navigatorios.html#pop)
|
|
- [`replaceAtIndex`](docs/navigatorios.html#replaceatindex)
|
|
- [`replace`](docs/navigatorios.html#replace)
|
|
- [`replacePrevious`](docs/navigatorios.html#replaceprevious)
|
|
- [`popToTop`](docs/navigatorios.html#poptotop)
|
|
- [`popToRoute`](docs/navigatorios.html#poptoroute)
|
|
- [`replacePreviousAndPop`](docs/navigatorios.html#replacepreviousandpop)
|
|
- [`resetTo`](docs/navigatorios.html#resetto)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
# Reference
|
|
|
|
## Props
|
|
|
|
### `initialRoute`
|
|
|
|
NavigatorIOS uses `route` objects to identify child views, their props,
|
|
and navigation bar configuration. Navigation operations such as push
|
|
operations expect routes to look like this the `initialRoute`.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| object: {component: function,title: string,titleImage: Image.propTypes.source,passProps: object,backButtonIcon: Image.propTypes.source,backButtonTitle: string,leftButtonIcon: Image.propTypes.source,leftButtonTitle: string,leftButtonSystemIcon: Object.keys(SystemIcons),onLeftButtonPress: function,rightButtonIcon: Image.propTypes.source,rightButtonTitle: string,rightButtonSystemIcon: Object.keys(SystemIcons),onRightButtonPress: function,wrapperStyle: ViewPropTypes.style,navigationBarHidden: bool,shadowHidden: bool,tintColor: string,barTintColor: string,barStyle: enum('default', 'black'),titleTextColor: string,translucent: bool} | Yes |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `barStyle`
|
|
|
|
The style of the navigation bar. Supported values are 'default', 'black'.
|
|
Use 'black' instead of setting `barTintColor` to black. This produces
|
|
a navigation bar with the native iOS style with higher translucency.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| enum('default', 'black') | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `barTintColor`
|
|
|
|
The default background color of the navigation bar.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| string | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `interactivePopGestureEnabled`
|
|
|
|
Boolean value that indicates whether the interactive pop gesture is
|
|
enabled. This is useful for enabling/disabling the back swipe navigation
|
|
gesture.
|
|
|
|
If this prop is not provided, the default behavior is for the back swipe
|
|
gesture to be enabled when the navigation bar is shown and disabled when
|
|
the navigation bar is hidden. Once you've provided the
|
|
`interactivePopGestureEnabled` prop, you can never restore the default
|
|
behavior.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| bool | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `itemWrapperStyle`
|
|
|
|
The default wrapper style for components in the navigator.
|
|
A common use case is to set the `backgroundColor` for every scene.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| ViewPropTypes.style | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `navigationBarHidden`
|
|
|
|
Boolean value that indicates whether the navigation bar is hidden
|
|
by default.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| bool | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `shadowHidden`
|
|
|
|
Boolean value that indicates whether to hide the 1px hairline shadow
|
|
by default.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| bool | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `tintColor`
|
|
|
|
The default color used for the buttons in the navigation bar.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| string | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `titleTextColor`
|
|
|
|
The default text color of the navigation bar title.
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| string | No |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `translucent`
|
|
|
|
Boolean value that indicates whether the navigation bar is
|
|
translucent by default
|
|
|
|
| Type | Required |
|
|
| - | - |
|
|
| bool | No |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Methods
|
|
|
|
### `push()`
|
|
|
|
```javascript
|
|
push(route: object)
|
|
```
|
|
|
|
Navigate forward to a new route.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route to navigate to. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `popN()`
|
|
|
|
```javascript
|
|
popN(n: number)
|
|
```
|
|
|
|
Go back N scenes at once. When N=1, behavior matches `pop()`.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| n | number | No | The number of scenes to pop. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `pop()`
|
|
|
|
```javascript
|
|
pop()
|
|
```
|
|
|
|
Pop back to the previous scene.
|
|
|
|
|
|
|
|
---
|
|
|
|
### `replaceAtIndex()`
|
|
|
|
```javascript
|
|
replaceAtIndex(route: object, index: number)
|
|
```
|
|
|
|
Replace a route in the navigation stack.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route that will replace the specified one. |
|
|
| index | number | No | The route into the stack that should be replaced. If it is negative, it counts from the back of the stack. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `replace()`
|
|
|
|
```javascript
|
|
replace(route: object)
|
|
```
|
|
|
|
Replace the route for the current scene and immediately
|
|
load the view for the new route.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route to navigate to. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `replacePrevious()`
|
|
|
|
```javascript
|
|
replacePrevious(route: object)
|
|
```
|
|
|
|
Replace the route/view for the previous scene.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route to will replace the previous scene. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `popToTop()`
|
|
|
|
```javascript
|
|
popToTop()
|
|
```
|
|
|
|
Go back to the topmost item in the navigation stack.
|
|
|
|
|
|
|
|
---
|
|
|
|
### `popToRoute()`
|
|
|
|
```javascript
|
|
popToRoute(route: object)
|
|
```
|
|
|
|
Go back to the item for a particular route object.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route to navigate to. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `replacePreviousAndPop()`
|
|
|
|
```javascript
|
|
replacePreviousAndPop(route: object)
|
|
```
|
|
|
|
Replaces the previous route/view and transitions back to it.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route that replaces the previous scene. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
### `resetTo()`
|
|
|
|
```javascript
|
|
resetTo(route: object)
|
|
```
|
|
|
|
Replaces the top item and pop to it.
|
|
|
|
**Parameters:**
|
|
|
|
| Name | Type | Required | Description |
|
|
| - | - | - | - |
|
|
| route | object | No | The new route that will replace the topmost item. |
|
|
|
|
|
|
|
|
|