mirror of
https://github.com/status-im/react-navigation.git
synced 2025-02-24 09:08:15 +00:00
Navigation Actions Doc (#338)
* Initial saving * Updated docs * Adding navigation actions into website App.js * Updated navigation prop structure * Added in missing link
This commit is contained in:
Elliott Ro
Eric Vicenti
parent
498f329005
commit
dff746a83c
108
docs/guides/Navigation-Actions.md
Normal file
108
docs/guides/Navigation-Actions.md
Normal file
@ -0,0 +1,108 @@
|
||||
# Navigation Actions
|
||||
|
||||
All Navigation Actions return an object that can be sent to the router using `navigation.dispatch()` method.
|
||||
|
||||
Note that if you want to dispatch react-navigation actions you should use the action creators provided in this library.
|
||||
|
||||
The following actions are supported:
|
||||
* [Navigate](#navigate) - Navigate to another route
|
||||
* [Reset](#reset) - Replace current state with a new state
|
||||
* [Back](#back) - Go back to previous state
|
||||
* [Set Params](#setparams) - Set Params for given route
|
||||
* [Init](#init) - Used to initialize first state if state is undefined
|
||||
|
||||
### Navigate
|
||||
The `Navigate` action will update the current state with the result of a `Navigate` action.
|
||||
|
||||
- `routeName` - *String* - Required - A destination routeName that has been registered somewhere in the app's router
|
||||
- `params` - *Object* - Optional - Params to merge into the destination route
|
||||
- `action` - *Object* - Optional - (advanced) The sub-action to run in the child router, if the screen is a navigator. Any one of the actions described in this doc can be set as a sub-action.
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const navigateAction = NavigationActions.navigate({
|
||||
|
||||
routeName: 'Profile',
|
||||
|
||||
params: {},
|
||||
|
||||
action: NavigationActions.navigate({ routeName: 'SubProfileRoute'})
|
||||
})
|
||||
|
||||
this.props.navigation.dispatch(navigateAction)
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Reset
|
||||
|
||||
The `Reset` action wipes the whole navigation state and replaces it with the result of several actions.
|
||||
|
||||
- `index` - *number* - required - Index of the active route on `routes` array in navigation `state`.
|
||||
- `actions` - *array* - required - Array of Navigation Actions that will replace the navigation state.
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const resetAction = NavigationActions.reset({
|
||||
index: 0,
|
||||
actions: [
|
||||
NavigationActions.navigate({ routeName: 'Profile'})
|
||||
]
|
||||
})
|
||||
this.props.navigation.dispatch(resetAction)
|
||||
|
||||
```
|
||||
#### How to use the `index` parameter
|
||||
The `index` param is used to specify the current active route.
|
||||
|
||||
eg: given a basic stack navigation with two routes `Profile` and `Settings`.
|
||||
To reset the state to a point where the active screen was `Settings` but have it stacked on top of a `Profile` screen, you would do the following:
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const resetAction = NavigationActions.reset({
|
||||
index: 1,
|
||||
actions: [
|
||||
NavigationActions.navigate({ routeName: 'Profile'}),
|
||||
NavigationActions.navigate({ routeName: 'Settings'})
|
||||
]
|
||||
})
|
||||
this.props.navigation.dispatch(resetAction)
|
||||
|
||||
```
|
||||
|
||||
### Back
|
||||
|
||||
Go back to previous screen and close current screen. `back` action creator takes in one optional parameter:
|
||||
- `key` - *string or null* - optional - If set, navigation will go back from the given key. If null, navigation will go back anywhere.
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const backAction = NavigationActions.back({
|
||||
key: 'Profile'
|
||||
})
|
||||
this.props.navigation.dispatch(backAction)
|
||||
|
||||
```
|
||||
|
||||
### SetParams
|
||||
|
||||
When dispatching `SetParams`, the router will produce a new state that has changed the params of a particular route, as identified by the key
|
||||
|
||||
- `params` - *object* - required - New params to be merged into existing route params
|
||||
- `key` - *string* - required - Route key that should get the new params
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const setParamsAction = NavigationActions.setParams({
|
||||
params: { title: 'Hello' },
|
||||
key: 'screen-123',
|
||||
})
|
||||
this.props.navigation.dispatch(setParamsAction)
|
||||
|
||||
```
|
||||
@ -1,16 +1,28 @@
|
||||
|
||||
# Screen Navigation Prop
|
||||
|
||||
Each screen in your app will recieve a navigation prop, which contains the following:
|
||||
Each *screen* in your app will receive a navigation prop which contain the following:
|
||||
* `navigate` - (helper) link to other screens
|
||||
* `state` - screen's current state/routes
|
||||
* `setParams` - (helper) make changes to route's params
|
||||
* `goBack` - (helper) close active screen and move back
|
||||
* `dispatch` - send an action to router
|
||||
|
||||
*NOTE:* The `navigation` prop is passed down to every navigation-aware component including navigators. The big exception is that a navigator's `navigation` prop may not have the helper functions (`navigate`, `goBack`, etc); it may only have `state` and `dispatch`. In order to `navigate` using the navigator's `navigation` prop, you will have to `dispatch` using an [action creator](navigation-actions).
|
||||
|
||||
*Notes regarding hooking things up with Redux*
|
||||
|
||||
> People don't always hook things up to redux correctly, because they mis-understand the navigator's top-level API, where the navigation prop is optional. The navigator will maintain its own state if it doesn't get a navigation prop, but this is not a feature you generally want to use when hooking your app up with redux. For navigators that are nested inside of your main navigator, you always want to pass the screen's navigation prop down. This allows your top-level navigator to communicate and provide state for all the children navigators. Only your top-level router needs to be integrated with redux, because all the other routers are inside it.
|
||||
|
||||
## `navigate` - Link to other screens
|
||||
|
||||
Call this to link to another screen in your app. Takes the following arguments:
|
||||
|
||||
`navigate(routeName, params, action)`
|
||||
|
||||
- `routeName` - A destination routeName that has been registered somewhere in the app's router
|
||||
- `params` - Params to merge into the destination route
|
||||
- `action` - (advanced) The sub-action to run in the child router, if the screen is a navigator.
|
||||
- `action` - (advanced) The sub-action to run in the child router, if the screen is a navigator. See [Actions Doc](navigation-actions) for a full list of supported actions.
|
||||
|
||||
```js
|
||||
class HomeScreen extends React.Component {
|
||||
@ -32,11 +44,18 @@ class HomeScreen extends React.Component {
|
||||
|
||||
## `state` - The screen's current state/route
|
||||
|
||||
A screen has access to its route via `this.props.navigation.state`. Each will contain:
|
||||
A screen has access to its route via `this.props.navigation.state`. Each will return an object with the following:
|
||||
|
||||
- `routeName` - the name of the route config in the router
|
||||
- `key` - a unique identifier used to sort routes
|
||||
- `params` - an optional object of string options for this screen
|
||||
```js
|
||||
{
|
||||
// the name of the route config in the router
|
||||
routeName: 'profile',
|
||||
//a unique identifier used to sort routes
|
||||
key: 'main0',
|
||||
//an optional object of string options for this screen
|
||||
params: { hello: 'world' }
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
class ProfileScreen extends React.Component {
|
||||
@ -71,6 +90,8 @@ class ProfileScreen extends React.Component {
|
||||
|
||||
## `goBack` - Close the active screen and move back
|
||||
|
||||
Optionally provide a key, which specifies the route to go back from. By default, goBack will close the route that it is called from. If the goal is to go back *anywhere*, without specifying what is getting closed, call `.goBack(null);`
|
||||
|
||||
```js
|
||||
class HomeScreen extends React.Component {
|
||||
render() {
|
||||
@ -95,78 +116,24 @@ class HomeScreen extends React.Component {
|
||||
}
|
||||
```
|
||||
|
||||
Optionally provide a key, which specifies the route to go back from. By default, goBack will close the route that it is called from. If the goal is to go back *anywhere*, without specifying what is getting closed, call `.goBack(null);`
|
||||
|
||||
|
||||
## `dispatch` - Send an action to the router
|
||||
|
||||
Use dispatch to send any navigation action to the router. The other navigation functions use dispatch behind the scenes.
|
||||
|
||||
Note that if you want to dispatch react-navigation actions you should use the action creators provided in this library.
|
||||
|
||||
The following actions are supported:
|
||||
See [Navigation Actions Docs](navigation-actions) for a full list of available actions.
|
||||
|
||||
### Navigate
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const navigationAction = NavigationActions.navigate({
|
||||
const navigateAction = NavigationActions.navigate({
|
||||
routeName: 'Profile',
|
||||
params: {},
|
||||
|
||||
// navigate can have a nested navigate action that will be run inside the child router
|
||||
action: NavigationActions.navigate({ routeName: 'SubProfileRoute'})
|
||||
})
|
||||
this.props.navigation.dispatch(navigationAction)
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Reset
|
||||
|
||||
The `Reset` action wipes the whole navigation state and replaces it with the result of several actions.
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const resetAction = NavigationActions.reset({
|
||||
index: 0,
|
||||
actions: [
|
||||
NavigationActions.navigate({ routeName: 'Profile'})
|
||||
]
|
||||
})
|
||||
this.props.navigation.dispatch(resetAction)
|
||||
|
||||
```
|
||||
|
||||
You can issue multiple actions, but make sure to set `index` correctly:
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const resetAction = NavigationActions.reset({
|
||||
index: 1,
|
||||
actions: [
|
||||
NavigationActions.navigate({ routeName: 'Profile'}),
|
||||
NavigationActions.navigate({ routeName: 'Settings'})
|
||||
]
|
||||
})
|
||||
this.props.navigation.dispatch(resetAction)
|
||||
|
||||
```
|
||||
|
||||
### SetParams
|
||||
|
||||
When dispatching `SetParams`, the router will produce a new state that has changed the params of a particular route, as identified by the key
|
||||
|
||||
```js
|
||||
import { NavigationActions } from 'react-navigation'
|
||||
|
||||
const setParamsAction = NavigationActions.setParams({
|
||||
params: {}, // these are the new params that will be merged into the existing route params
|
||||
// The key of the route that should get the new params
|
||||
key: 'screen-123',
|
||||
})
|
||||
this.props.navigation.dispatch(setParamsAction)
|
||||
this.props.navigation.dispatch(navigateAction)
|
||||
|
||||
```
|
||||
|
||||
@ -117,7 +117,7 @@ const GuidesDocs = createNavigator(TabRouter({
|
||||
linkName: 'Screen Tracking',
|
||||
}),
|
||||
path: 'screen-tracking',
|
||||
},
|
||||
},
|
||||
Contributors: {
|
||||
screen: createDocPage({
|
||||
doc: 'guides/Contributors',
|
||||
@ -174,6 +174,14 @@ const NavigatorsDocs = createNavigator(TabRouter({
|
||||
}),
|
||||
path: 'navigation-prop',
|
||||
},
|
||||
NavigationActions: {
|
||||
screen: createDocPage({
|
||||
doc: 'guides/Navigation-Actions',
|
||||
title: 'Navigation Actions',
|
||||
linkName: 'Navigation Actions',
|
||||
}),
|
||||
path: 'navigation-actions',
|
||||
},
|
||||
NavigationOptions: {
|
||||
screen: createDocPage({
|
||||
doc: 'guides/Screen-Nav-Options',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user