status-im/react-navigation
2
0
Fork 0
mirror of https://github.com/status-im/react-navigation.git synced 2025-02-24 17:18:09 +00:00
Code Issues Projects Releases Wiki Activity

Add a "Quick Start" guide. (#2775)

Browse Source 
* Give docs some more room to breath

* Working on the new docs

* New intro

* Writing installation guide

* Finish tab intro.

* Write intro to drawernavigator.

* Add some space

* Rename guide

* Minimize changes

* Fix links

* Edits
This commit is contained in:
Spencer Carli 2017-10-24 03:51:00 -05:00 committed by Lorenzo Sciandra
parent f43e85e1c3
commit 5e26ced280
6 changed files with 596 additions and 233 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
docs/guides/Guide-Basic-Example.md Normal file
View File

@ -0,0 +1,235 @@
# Hello Mobile Navigation
Let's use React Navigation to build a simple chat-like application for Android and iOS.
## Setup and Installation
First, make sure you're [all set up to use React Native](http://facebook.github.io/react-native/docs/getting-started.html). Next, create a new project and add `react-navigation`:
```sh
# Create a new React Native App
react-native init SimpleApp
cd SimpleApp
# Install the latest version of react-navigation from npm
npm install --save react-navigation
# Run the new app
react-native run-android
# or:
react-native run-ios
```
If you are using `create-react-native-app` instead of `react-native init`, then:
```sh
# Create a new React Native App
create-react-native-app SimpleApp
cd SimpleApp
# Install the latest version of react-navigation from npm
npm install --save react-navigation
# Run the new app
npm start
# This will start a development server for you and print a QR code in your terminal.
```
Verify that you can successfully see the bare sample app run on iOS and/or Android:
```phone-example
bare-project
```
We want to share code on iOS and Android, so let's delete the contents of `index.js` (or `index.ios.js` and `index.android.js` if using a React Native version before 0.49) and replace it with `import './App';` - after which, we need to create the new file for our app implementation, `App.js` (if you used `create-react-native-app` this has been already done)
## Introducing Stack Navigator
For our app, we want to use the `StackNavigator` because conceptually we want to obtain a 'card stack' effect of movement, where each new screen is put on the top of the stack and going back removes a screen from the top of the stack. Let's start with just one screen:
```js
import React from 'react';
import {
AppRegistry,
Text,
} from 'react-native';
import { StackNavigator } from 'react-navigation';
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
return <Text>Hello, Navigation!</Text>;
}
}
export const SimpleApp = StackNavigator({
Home: { screen: HomeScreen },
});
AppRegistry.registerComponent('SimpleApp', () => SimpleApp);
```
If you used `create-react-native-app` the already existing `App.js` will be modified to
```js
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { StackNavigator } from 'react-navigation';
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome'
};
render() {
return <Text>Hello, Navigation!</Text>;
}
}
const SimpleApp = StackNavigator({
Home: { screen: HomeScreen }
});
export default class App extends React.Component {
render() {
return <SimpleApp />;
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
alignItems: 'center',
justifyContent: 'center'
}
});
```
The `title` of the screen is configurable on the [static `navigationOptions`](/docs/navigators/navigation-options), where many options can be set to configure the presentation of the screen in the navigator.
Now the same screen should appear on both iPhone and Android apps:
```phone-example
first-screen
```
## Adding a New Screen
In our `App.js` file, let's add a new screen called `ChatScreen`, defining it under `HomeScreen`:
```js
// ...
class HomeScreen extends React.Component {
//...
}
class ChatScreen extends React.Component {
static navigationOptions = {
title: 'Chat with Lucy',
};
render() {
return (
<View>
<Text>Chat with Lucy</Text>
</View>
);
}
}
```
We can then add a button to our `HomeScreen` component that links to `ChatScreen`: we need to use the provided method `navigate` (from the [screen navigation prop](/docs/navigators/navigation-prop)) by giving it the `routeName` of the screen we want to reach, in this case `Chat`.
```js
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
const { navigate } = this.props.navigation;
return (
<View>
<Text>Hello, Chat App!</Text>
<Button
onPress={() => navigate('Chat')}
title="Chat with Lucy"
/>
</View>
);
}
}
```
(*don't forget to import View and Button from react-native:* `import { AppRegistry, Text, View, Button } from 'react-native';`)
But that won't work until we say to our `StackNavigator` of the existence of the `Chat` screen, like so:
```js
export const SimpleApp = StackNavigator({
Home: { screen: HomeScreen },
Chat: { screen: ChatScreen },
});
```
Now you can navigate to your new screen, and go back:
```phone-example
first-navigation
```
## Passing params
Hardcoding a name into the `ChatScreen` isn't ideal. It'd be more useful if we could pass a name to be rendered instead, so let's do that.
In addition to specifying the target `routeName` in the navigate function, we can pass params that will be put into the new route. First, we'll edit our `HomeScreen` component to pass a `user` param into the route.
```js
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
const { navigate } = this.props.navigation;
return (
<View>
<Text>Hello, Chat App!</Text>
<Button
onPress={() => navigate('Chat', { user: 'Lucy' })}
title="Chat with Lucy"
/>
</View>
);
}
}
```
We can then edit our `ChatScreen` component to display the `user` param that was passed in through the route:
```js
class ChatScreen extends React.Component {
// Nav options can be defined as a function of the screen's props:
static navigationOptions = ({ navigation }) => ({
title: `Chat with ${navigation.state.params.user}`,
});
render() {
// The screen's current route is passed in to `props.navigation.state`:
const { params } = this.props.navigation.state;
return (
<View>
<Text>Chat with {params.user}</Text>
</View>
);
}
}
```
Now you can see the name when you navigate to the Chat screen. Try changing the `user` param in `HomeScreen` and see what happens!
```phone-example
first-navigation
```

240
docs/guides/Guide-Intro.md
View File

@ -1,235 +1,23 @@
# Hello Mobile Navigation
# Introduction
Let's use React Navigation to build a simple chat application for Android and iOS.
_Learn once, navigate anywhere._
## Setup and Installation
React Navigation is born from the React Native community's need for an extensible yet easy-to-use navigation solution based on Javascript.
First, make sure you're [all set up to use React Native](http://facebook.github.io/react-native/docs/getting-started.html). Next, create a new project and add `react-navigation`:
React Navigation is the result of a collaboration between developers from Facebook, Expo and the React community at large: it replaces and improves upon several navigation libraries in the ecosystem, including Ex-Navigation, React Native's Navigator and NavigationExperimental components.
```sh
# Create a new React Native App
react-native init SimpleApp
cd SimpleApp
## Getting Started
# Install the latest version of react-navigation from npm
npm install --save react-navigation
If you're already familiar with React Native then you'll be able to get moving with React Navigation in minimal time.
# Run the new app
react-native run-android
# or:
react-native run-ios
```
1. [Quick Start](/docs/intro/quick-start)
Quickly get a grasp on the React Navigation API with demonstrations of the StackNavigator, TabNavigator, and DrawerNavigator.
If you are using `create-react-native-app` instead of `react-native init`, then:
2. [Simple App](/docs/intro/basic-app)
Dive into the basics of React Navigation by creating a new React Native project, installing React Navigation, creating your first navigator, and learning how to interact with it.
```sh
# Create a new React Native App
create-react-native-app SimpleApp
cd SimpleApp
3. [Navigation Playground](https://github.com/react-community/react-navigation/tree/master/examples/NavigationPlayground)
Curious of the various capabilities of React Navigation? Browse the official example app, which will demonstrates various patterns with React Navigation.
# Install the latest version of react-navigation from npm
npm install --save react-navigation
# Run the new app
npm start
# This will start a development server for you and print a QR code in your terminal.
```
Verify that you can successfully see the bare sample app run on iOS and/or Android:
```phone-example
bare-project
```
We want to share code on iOS and Android, so let's delete the contents of `index.ios.js` and `index.android.js` and replace it with `import './App';` - after which, we need to create the new file for our app implementation, `App.js` (if you used `create-react-native-app` this has been already done)
## Introducing Stack Navigator
For our app, we want to use the `StackNavigator` because conceptually we want to obtain a 'card stack' effect of movement, where each new screen is put on the top of the stack and going back removes a screen from the top of the stack. Let's start with just one screen:
```js
import React from 'react';
import {
AppRegistry,
Text,
} from 'react-native';
import { StackNavigator } from 'react-navigation';
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
return <Text>Hello, Navigation!</Text>;
}
}
export const SimpleApp = StackNavigator({
Home: { screen: HomeScreen },
});
AppRegistry.registerComponent('SimpleApp', () => SimpleApp);
```
If you used `create-react-native-app` the already existing `App.js` will be modified to
```js
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { StackNavigator } from 'react-navigation';
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome'
};
render() {
return <Text>Hello, Navigation!</Text>;
}
}
const SimpleApp = StackNavigator({
Home: { screen: HomeScreen }
});
export default class App extends React.Component {
render() {
return <SimpleApp />;
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#fff',
alignItems: 'center',
justifyContent: 'center'
}
});
```
The `title` of the screen is configurable on the [static `navigationOptions`](/docs/navigators/navigation-options), where many options can be set to configure the presentation of the screen in the navigator.
Now the same screen should appear on both iPhone and Android apps:
```phone-example
first-screen
```
## Adding a New Screen
In our `App.js` file, let's add a new screen called `ChatScreen`, defining it under `HomeScreen`:
```js
// ...
class HomeScreen extends React.Component {
//...
}
class ChatScreen extends React.Component {
static navigationOptions = {
title: 'Chat with Lucy',
};
render() {
return (
<View>
<Text>Chat with Lucy</Text>
</View>
);
}
}
```
We can then add a button to our `HomeScreen` component that links to `ChatScreen`: we need to use the provided method `navigate` (from the [screen navigation prop](/docs/navigators/navigation-prop)) by giving it the `routeName` of the screen we want to reach, in this case `Chat`.
```js
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
const { navigate } = this.props.navigation;
return (
<View>
<Text>Hello, Chat App!</Text>
<Button
onPress={() => navigate('Chat')}
title="Chat with Lucy"
/>
</View>
);
}
}
```
(*don't forget to import View and Button from react-native: * `import { AppRegistry, Text, View, Button } from 'react-native';`)
But that won't work until we say to our `StackNavigator` of the existence of the `Chat` screen, like so:
```js
export const SimpleApp = StackNavigator({
Home: { screen: HomeScreen },
Chat: { screen: ChatScreen },
});
```
Now you can navigate to your new screen, and go back:
```phone-example
first-navigation
```
## Passing params
Hardcoding a name into the `ChatScreen` isn't ideal. It'd be more useful if we could pass a name to be rendered instead, so let's do that.
In addition to specifying the target `routeName` in the navigate function, we can pass params that will be put into the new route. First, we'll edit our `HomeScreen` component to pass a `user` param into the route.
```js
class HomeScreen extends React.Component {
static navigationOptions = {
title: 'Welcome',
};
render() {
const { navigate } = this.props.navigation;
return (
<View>
<Text>Hello, Chat App!</Text>
<Button
onPress={() => navigate('Chat', { user: 'Lucy' })}
title="Chat with Lucy"
/>
</View>
);
}
}
```
We can then edit our `ChatScreen` component to display the `user` param that was passed in through the route:
```js
class ChatScreen extends React.Component {
// Nav options can be defined as a function of the screen's props:
static navigationOptions = ({ navigation }) => ({
title: `Chat with ${navigation.state.params.user}`,
});
render() {
// The screen's current route is passed in to `props.navigation.state`:
const { params } = this.props.navigation.state;
return (
<View>
<Text>Chat with {params.user}</Text>
</View>
);
}
}
```
Now you can see the name when you navigate to the Chat screen. Try changing the `user` param in `HomeScreen` and see what happens!
```phone-example
first-navigation
```
4. [Community Contributions](https://github.com/react-community/react-navigation#community-contributions)
With the flexibility of React Navigation we won't be able to cover every possible situation, but another developer may have! Browse our list of community contributions to find topics that may answer your questions.

316
docs/guides/Guide-Quick-Start.md Normal file
View File

@ -0,0 +1,316 @@
# Quick Start Guide
To get started with React Navigation, all you have to do is install the `react-navigation` npm package.
### Install with NPM
```
npm install --save react-navigation
```
### Install with Yarn
```
yarn add react-navigation
```
To start using React Navigation you'll have to create a navigator. React Navigation comes with three default navigators.
- `StackNavigator` - Provides a way for your app to transition between screens where each new screen is placed on top of a stack.
- `TabNavigator` - Used to set up a screen with several tabs.
- `DrawerNavigator` - Used to set up a screen with drawer navigation.
## Creating a StackNavigator
StackNavigator's are the most common form of navigator so we'll use it as a basic demonstration. To get started, create a `StackNavigator`.
```javascript
import { StackNavigator } from 'react-navigation';
const RootNavigator = StackNavigator({
});
export default RootNavigator;
```
We can then add screens to this `StackNavigator`. Each key represents a screen.
```javascript
import React from 'react';
import { View, Text } from 'react-native';
import { StackNavigator } from 'react-navigation';
const HomeScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
</View>
);
const DetailsScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Details Screen</Text>
</View>
);
const RootNavigator = StackNavigator({
Home: {
screen: HomeScreen,
},
Details: {
screen: DetailsScreen,
},
});
export default RootNavigator;
```
Now let's add a title to the navigation bar.
```javascript
...
const RootNavigator = StackNavigator({
Home: {
screen: HomeScreen,
navigationOptions: {
headerTitle: 'Home',
},
},
Details: {
screen: DetailsScreen,
navigationOptions: {
headerTitle: 'Details',
},
},
});
export default RootNavigator;
```
Finally, we should be able to navigate from the home screen to the details screen. When you register a component with a navigator that component will then have a `navigation` prop added to it. This `navigation` prop drives how we use move between different screens.
To move from the home screen to the details screen we'll want to use `navigation.navigate`, like so:
```javascript
...
import { View, Text, Button } from 'react-native';
const HomeScreen = ({ navigation }) => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
<Button
onPress={() => navigation.navigate('Details')}
title="Go to details"
/>
</View>
);
...
```
And there you have it! That's the basics of using the [StackNavigator](/docs/navigators/stack), and React Navigation as a whole. Here's the full code from this example:
<div class="snack" data-snack-id="HJlnU0XTb" data-snack-platform="ios" data-snack-preview="true" data-snack-theme="light" style="overflow:hidden;background:#fafafa;border:1px solid rgba(0,0,0,.16);border-radius:4px;height:505px;width:100%"></div>
## Creating a TabNavigator
To get started with `TabNavigator` first import and create a new `RootTabs` component.
```javascript
import { TabNavigator } from 'react-navigation';
const RootTabs = TabNavigator({
});
export default RootTabs;
```
We then need to create some screens and add them to our `TabNavigator`.
```javascript
import React from 'react';
import { View, Text } from 'react-native';
import { TabNavigator } from 'react-navigation';
const HomeScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
</View>
);
const ProfileScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Profile Screen</Text>
</View>
);
const RootTabs = TabNavigator({
Home: {
screen: HomeScreen,
},
Profile: {
screen: ProfileScreen,
},
});
export default RootTabs;
```
Getting there! Now let's explicity set a label and icon for the tab bar.
> We'll be using [`react-native-vector-icons`](https://github.com/oblador/react-native-vector-icons) in the example. If you don't have it installed in your project already please do so.
```javascript
...
import Ionicons from 'react-native-vector-icons/Ionicons';
...
const RootTabs = TabNavigator({
Home: {
screen: HomeScreen,
navigationOptions: {
tabBarLabel: 'Home',
tabBarIcon: ({ tintColor, focused }) => (
<Ionicons
name={focused ? 'ios-home' : 'ios-home-outline'}
size={26}
style={{ color: tintColor }}
/>
),
},
},
Profile: {
screen: ProfileScreen,
navigationOptions: {
tabBarLabel: 'Profile',
tabBarIcon: ({ tintColor, focused }) => (
<Ionicons
name={focused ? 'ios-person' : 'ios-person-outline'}
size={26}
style={{ color: tintColor }}
/>
),
},
},
});
export default RootTabs;
```
This will ensure the `tabBarLabel` is consistent (important when using nested navigators) and it will set a `tabBarIcon`. This icon will only be visible on iOS by default given the tab bar component used, which aligns with standard design patterns on Android.
You can view the complete finished code below:
<div class="snack" data-snack-id="BJZ2GVVpb" data-snack-platform="ios" data-snack-preview="true" data-snack-theme="light" style="overflow:hidden;background:#fafafa;border:1px solid rgba(0,0,0,.16);border-radius:4px;height:505px;width:100%"></div>
## Creating a DrawerNavigator
To get started with `DrawerNavigator` first import and create a new `RootDrawer` component.
```javascript
import { DrawerNavigator } from 'react-navigation';
const RootDrawer = DrawerNavigator({
});
export default RootDrawer;
```
We then need to create some screens and add them to our `DrawerNavigator`.
```javascript
import React from 'react';
import { View, Text } from 'react-native';
import { DrawerNavigator } from 'react-navigation';
const HomeScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
</View>
);
const ProfileScreen = () => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Profile Screen</Text>
</View>
);
const RootDrawer = DrawerNavigator({
Home: {
screen: HomeScreen,
},
Profile: {
screen: ProfileScreen,
},
});
export default RootDrawer;
```
Getting there! Now let's explicity set a label and icon for the drawer items.
> We'll be using `react-native-vector-icons` in the example. If you don't have it installed in your project already please do so.
```javascript
...
import Ionicons from 'react-native-vector-icons/Ionicons';
...
const RootDrawer = DrawerNavigator({
Home: {
screen: HomeScreen,
navigationOptions: {
drawerLabel: 'Home',
drawerIcon: ({ tintColor, focused }) => (
<Ionicons
name={focused ? 'ios-home' : 'ios-home-outline'}
size={20}
style={{ color: tintColor }}
/>
),
},
},
Profile: {
screen: ProfileScreen,
navigationOptions: {
drawerLabel: 'Profile',
drawerIcon: ({ tintColor, focused }) => (
<Ionicons
name={focused ? 'ios-person' : 'ios-person-outline'}
size={20}
style={{ color: tintColor }}
/>
),
},
},
});
export default RootDrawer;
```
To open the drawer you can swipe from the left edge of the screen to the right. You've also got the option to open the drawer view `navigation.navigate('DrawerToggle')`, which we'll add to the Home component now. Make sure you import the `Button` component from `react-native`.
```javascript
...
const HomeScreen = ({ navigation }) => (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
<Button
onPress={() => navigation.navigate('DrawerToggle')}
title="Open Drawer"
/>
</View>
);
...
```
You can view the finished code below.
<div class="snack" data-snack-id="rk90N44a-" data-snack-platform="ios" data-snack-preview="true" data-snack-theme="light" style="overflow:hidden;background:#fafafa;border:1px solid rgba(0,0,0,.16);border-radius:4px;height:505px;width:100%"></div>

2
website/public/index.html
View File

@ -18,4 +18,6 @@
debug: false
});
</script>
<script async src="https://snack.expo.io/embed.js"></script>
</html>

18
website/src/App.css
View File

@ -67,13 +67,19 @@ a.editLink {
.md-section > ul,
.md-section > ol,
.md-section > pre,
.md-section > p {
.md-section > p,
.md-section > blockquote {
margin: 15px 0 0 0;
}
.md-section ul li,
.md-section ol li {
margin: 15px 0 0 0;
}
.md-section .snack {
margin: 15px 0 0 0;
}
.errorScreen {
height: 100%;
margin: 100px;
@ -137,7 +143,7 @@ a.cta:hover {
justify-content: space-between;
padding: 0 25px;
margin: 0 auto;
max-width: 980px;
max-width: 1280px;
display: flex;
flex-direction: row;
}
@ -189,7 +195,7 @@ li:hover .metabuttons {
flex: 1;
margin: 25px auto;
width: 100%;
max-width: 980px;
max-width: 1280px;
margin-top: 85px;
}
.inner-page-body {
@ -200,12 +206,12 @@ li:hover .metabuttons {
margin-left: 25px;
}
.left-sidebar {
width: 225px;
width: 260px;
margin-right: 25px;
}
.left-sidebar,
.left-sidebar .navmenu {
width: 225px;
width: 260px;
}
.footer {
@ -215,7 +221,7 @@ li:hover .metabuttons {
.inner-footer {
margin: 0 auto;
max-width: 980px;
max-width: 1280px;
padding: 25px;
}
img.logo {

18
website/src/App.js
View File

@ -63,10 +63,26 @@ const GuideDocs = createNavigator(
GettingStarted: {
screen: createDocPage({
doc: 'guides/Guide-Intro',
title: 'Introduction',
linkName: 'Introduction',
}),
path: '',
},
QuickStart: {
screen: createDocPage({
doc: 'guides/Guide-Quick-Start',
title: 'Quick Start',
linkName: 'Quick Start',
}),
path: 'quick-start',
},
BasicExample: {
screen: createDocPage({
doc: 'guides/Guide-Basic-Example',
title: 'Hello Mobile Navigation',
linkName: 'Hello Mobile Navigation',
}),
path: '',
path: 'basic-app',
},
NestedNavigator: {
screen: createDocPage({