diff --git a/Libraries/Components/Navigation/NavigatorIOS.ios.js b/Libraries/Components/Navigation/NavigatorIOS.ios.js index 66ea9ee3e27db3..8e8390d15ceac6 100644 --- a/Libraries/Components/Navigation/NavigatorIOS.ios.js +++ b/Libraries/Components/Navigation/NavigatorIOS.ios.js @@ -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. diff --git a/docs/JavaScriptEnvironment.md b/docs/JavaScriptEnvironment.md index 4e2e3c1f21d579..857a3fd71a7de9 100644 --- a/docs/JavaScriptEnvironment.md +++ b/docs/JavaScriptEnvironment.md @@ -4,7 +4,7 @@ title: JavaScript Environment layout: docs category: Guides permalink: docs/javascript-environment.html -next: navigator-comparison +next: navigation --- ## JavaScript Runtime diff --git a/docs/Navigation.md b/docs/Navigation.md new file mode 100644 index 00000000000000..f4a8fcab9880d1 --- /dev/null +++ b/docs/Navigation.md @@ -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 + { + // 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 ( + + Current Scene: { this.props.title } + + Tap me to load the next scene + + + Tap me to go back + + + ) + } +} + +class SimpleNavigationApp extends Component { + render() { + return ( + + { + 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 + +``` + +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 ( + + Current Scene: { this.props.title } + + Tap me to load the next scene + + + Tap me to go back + + + ) + } +} + +class NavigatorIOSApp extends Component { + render() { + return ( + + + } + /> + ) + } +} +``` + +> 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.