kylefang/react-navigation
1
0
Fork 0
mirror of https://github.com/zhigang1992/react-navigation.git synced 2026-04-24 04:25:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Initial public release of React Navigation

Browse Source
This commit is contained in:
Adam Miskiewicz
2017-01-26 11:49:39 -08:00
committed by James Ide
commit c37ad8a0a9
391 changed files with 51942 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/api/navigators/DrawerNavigator.md Normal file
View File

@@ -0,0 +1,120 @@
# DrawerNavigator
Used to easily set up a screen with a drawer navigation.
```js
class MyHomeScreen extends React.Component {
static navigationOptions = {
drawer: () => ({
label: 'Home',
icon: ({ tintColor }) => (
<Image
source={require('./chats-icon.png')}
style={[styles.icon, {tintColor: tintColor}]}
/>
),
}),
}
render() {
return (
<Button
onPress={() => this.props.navigation.navigate('Notifications')}
label="Go to notifications"
/>
);
}
}
class MyNotificationsScreen extends React.Component {
static navigationOptions = {
drawer: () => ({
label: 'Notifications',
icon: ({ tintColor }) => (
<Image
source={require('./notif-icon.png')}
style={[styles.tabIcon, {tintColor: tintColor}]}
/>
),
}),
}
render() {
return (
<Button
onPress={() => this.props.navigation.goBack()}
label="Go back home"
/>
);
}
}
const styles = StyleSheet.create({
icon: {
width: 24,
height: 24,
},
});
const MyApp = DrawerNavigator({
Home: {
screen: MyHomeScreen,
},
Notifications: {
screen: MyNotificationsScreen,
},
});
```
To open and close drawer, navigate to `'DrawerOpen'` and `'DrawerClose'` respectively.
```js
this.props.navigation.navigate('DrawerOpen'); // open drawer
this.props.navigation.navigate('DrawerClose'); // close drawer
```
## API Definition
```js
DrawerNavigator(RouteConfigs, DrawerNavigatorConfig)
```
### Drawer Navigator Options
- `drawerWidth` - Width of the drawer
- `contentComponent` - Component to use to render the navigation items. Receives the `navigation` prop for the drawer. Defaults to `DrawerView.Items`.
- `contentOptions` - Configure the drawer content, see below.
Several options get passed to the underlying router to modify navigation logic:
- `initialRouteName` - The routeName for the initial route.
- `order` - Array of routeNames which defines the order of the drawer items.
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - Should the back button cause switch to the initial route? If yes, set to `initialRoute`, otherwise `none`. Defaults to `initialRoute` behavior.
### `contentOptions` for `DrawerView.Items`
- `activeTintColor` - label and icon color of the active label
- `activeBackgroundColor` - background color of the active label
- `inactiveTintColor` - label and icon color of the inactive label
- `inactiveBackgroundColor` - background color of the inactive label
- `style` - style object for the content section
Example:
```js
contentOptions: {
activeTintColor: '#e91e63',
style: {
marginVertical: 0,
}
}
```
### Navigator Props
The navigator component created by `DrawerNavigator(...)` takes the following props,
- `screenProps` - Props to pass to each child screen

21
docs/api/navigators/Navigators.md Normal file
View File

@@ -0,0 +1,21 @@
# Navigators
Navigators allow you define you application's navigation structure. Navigators also render common elements such as headers and tab bars which you can configure.
Under the hood, navigators are plain React components.
## Built-in Navigators
`react-navigation` includes the following functions to help you create navigators:
- [StackNavigator](/docs/navigators/stack) - Renders one screen at a time and provides transitions between screens. When a new screen is opened it is placed on top of the stack.
- [TabNavigator](/docs/navigators/tab) - Renders a tab bar that lets the user switch between several screens
- [DrawerNavigator](/docs/navigators/drawer) - Provides a drawer that slides in from the left of the screen
## Rendering screens with Navigators
The navigators render application screens which are just React components.
To learn how to create screens, read about:
- [Screen `navigation` prop](/docs/navigators/navigation-prop) to allow the screen to dispatch navigation actions, such as opening another screen
- [Screen `navigationOptions`](/docs/navigators/navigation-options) to customize how the screen gets presented by the navigator (e.g. header title, tab label)

130
docs/api/navigators/StackNavigator.md Normal file
View File

@@ -0,0 +1,130 @@
# StackNavigator
Provides a way for your app to transition between screens where each new screen is placed on top of a stack.
By default the StackNavigator is configured to have the familiar iOS and Android look & feel: new screens slide in from the right on iOS, fade in from the bottom on Android. On iOS the StackNavigator can also be configured to a modal style where screens slide in from the bottom.
```jsx
class MyHomeScreen extends React.Component {
static navigationOptions = {
title: 'Home',
}
render() {
return (
<Button
onPress={() => this.props.navigation.navigate('Profile', {name: 'Lucy'})}
label="Go to Lucy's profile"
/>
);
}
}
const ModalStack = StackNavigator({
Home: {
screen: MyHomeScreen,
},
Profile: {
path: 'people/:name',
screen: MyProfileScreen,
},
});
```
## API Definition
```js
StackNavigator(RouteConfigs, StackNavigatorConfig)
```
### RouteConfigs
The route configs object is a mapping from route name to a route config, which tells the navigator what to present for that route.
```js
StackNavigator({
// For each screen that you can navigate to, create a new entry like this:
Profile: {
// `ProfileScreen` is a React component that will be the main content of the screen.
screen: ProfileScreen,
// When `ProfileScreen` is loaded by the StackNavigator, it will be given a navigation prop.
// Optional: When deep linking or using react-navigation in a web app, this path is used:
path: 'people/:username',
// The action and route params are extracted from the path.
// Optional: Override the navigation options for the screen
navigationOptions: {
title: ({state}) => `${state.params.username}'s Profile'`,
},
},
...MyOtherRoutes,
});
```
### StackNavigatorConfig
Options for the router:
- `initialRouteName` - Sets the default screen of the stack. Must match one of the keys in route configs.
- `initialRouteParams` - The params for the initial route
- `paths` - A mapping of overrides for the paths set in the route configs
Visual options:
- `mode` - Defines the style for rendering and transitions:
- `card` - Use the standard iOS and Android screen transitions. This is the default.
- `modal` - Make the screens slide in from the bottom which is a common iOS pattern. Only works on iOS, has no effect on Android.
- `headerMode` - Specifies how the header should be rendered:
- `float` - Render a single header that stays at the top and animates as screens are changed. This is a common pattern on iOS.
- `screen` - Each screen has a header attached to it and the header fades in and out together with the screen. This is a common pattern on Android.
- `none` - No header will be rendered.
### Screen Navigation Options
Usually you define static `navigationOptions` on your screen component. For example:
```jsx
class ProfileScreen extends React.Component {
static navigationOptions = {
title: `${state.params.name}'s Profile!`,
header: ({ state, setParams }) => ({
// Render a button on the right side of the header
// When pressed switches the screen to edit mode.
right: (
<Button
title={state.params.editing ? 'Done' : 'Edit'}
onPress={() => setParams({editing: state.params.editing ? false : true})}
/>
),
}),
};
...
```
All `navigationOptions` for the `StackNavigator`:
- `title` - a title (string) displayed in the header
- `header` - a config object for the header bar:
- `visible` - Boolean toggle of header visibility. Only works when `headerMode` is `screen`.
- `title` - Title string used by the navigation bar, or a custom React component
- `right` - Custom component displayed on the right side of the header
### Examples
See the examples [SimpleStack.js](https://github.com/reactjs/react-navigation/tree/master/examples/NavigationPlayground/js/SimpleStack.js) and [ModalStack.js](https://github.com/reactjs/react-navigation/tree/master/examples/NavigationPlayground/js/ModalStack.js) which you can run locally as part of the [NavigationPlayground](https://github.com/reactjs/react-navigation/tree/master/examples/NavigationPlayground) app.
### Navigator Props
The navigator component created by `StackNavigator(...)` takes the following props,
- `screenProps` - Props to pass to each child screen

143
docs/api/navigators/TabNavigator.md Normal file
View File

@@ -0,0 +1,143 @@
# TabNavigator
Used to easily set up a screen with several tabs with a TabRouter.
```js
class MyHomeScreen extends React.Component {
static navigationOptions = {
tabBar: {
label: 'Home',
// Note: By default the icon is only shown on iOS. Search the showIcon option below.
icon: ({ tintColor }) => (
<Image
source={require('./chats-icon.png')}
style={[styles.icon, {tintColor: tintColor}]}
/>
),
},
}
render() {
return (
<Button
onPress={() => this.props.navigation.navigate('Notifications')}
label="Go to notifications"
/>
);
}
}
class MyNotificationsScreen extends React.Component {
static navigationOptions = {
tabBar: {
label: 'Notifications',
icon: ({ tintColor }) => (
<Image
source={require('./notif-icon.png')}
style={[styles.tabIcon, {tintColor: tintColor}]}
/>
),
},
}
render() {
return (
<Button
onPress={() => this.props.navigation.goBack()}
label="Go back home"
/>
);
}
}
const styles = StyleSheet.create({
icon: {
width: 26,
height: 26,
},
});
const MyApp = TabNavigator({
Home: {
screen: MyHomeScreen,
},
Notifications: {
screen: MyNotificationsScreen,
},
}, {
tabBarOptions: {
activeTintColor: '#e91e63',
},
});
```
### Tab Navigator Options
- `tabBarComponent` - component to use as the tab bar, e.g. `TabView.TabBarBottom`
(this is the default on iOS), `TabView.TabBarTop`
(this is the default on Android)
- `tabBarPosition` - position of the tab bar, can be `'top'` or `'bottom'`
- `swipeEnabled` - whether to allow swiping between tabs
- `animationEnabled` - whether to animate when changing tabs
- `lazyLoad` - whether to lazily render tabs as needed as opposed to rendering them upfront
- `tabBarOptions` - configure the tab bar, see below.
Several options get passed to the underlying router to modify navigation logic:
- `initialTab` - The routeName for the initial tab route when first loading
- `order` - Array of routeNames which defines the order of the tabs
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - Should the back button cause a tab switch to the initial tab? If yes, set to `initialTab`, otherwise `none`. Defaults to `initialTab` behavior.
### `tabBarOptions` for `TabBarBottom` (default tab bar on iOS)
- `activeTintColor` - label and icon color of the active tab
- `activeBackgroundColor` - background color of the active tab
- `inactiveTintColor` - label and icon color of the inactive tab
- `inactiveBackgroundColor` - background color of the inactive tab
- `style` - style object for the tab bar
Example:
```js
tabBarOptions: {
activeTintColor: '#e91e63',
style: {
backgroundColor: 'blue',
}
}
```
### `tabBarOptions` for `TabBarTop` (default tab bar on Android)
- `activeTintColor` - label and icon color of the active tab
- `inactiveTintColor` - label and icon color of the inactive tab
- `showIcon` - whether to show icon for tab, default is false
- `showLabel` - whether to show label for tab, default is true
- `upperCaseLabel` - whether to make label uppercase, default is true
- `pressColor` - color for material ripple (Android >= 5.0 only)
- `pressOpacity` - opacity for pressed tab (iOS and Android < 5.0 only)
- `scrollEnabled` - whether to enable scrollable tabs
- `tabStyle` - style object for the tab
- `indicatorStyle` - style object for the tab indicator (line at the bottom of the tab)
- `labelStyle` - style object for the tab label
- `style` - style object for the tab bar
Example:
```js
tabBarOptions: {
labelStyle: {
fontSize: 12,
},
style: {
backgroundColor: 'blue',
}
}
```
### Navigator Props
The navigator component created by `TabNavigator(...)` takes the following props,
- `screenProps` - Props to pass to each child screen

130
docs/api/routers/Routers.md Normal file
View File

@@ -0,0 +1,130 @@
# Routers
Routers define a component's navigation state, and they allow the developer to define paths and actions that can be handled.
## Built-In Routers
`react-navigation` ships with a few standard routers:
- [StackRouter](/docs/routers/stack)
- [TabRouter](/docs/routers/tabs)
## Using Routers
To make a navigator manually, put a static `router` on a component. (To quickly make a navigator with a built-in component, it may be easier to use a [Navigator Factory](/docs/navigators) instead)
```js
class MyNavigator extends React.Component {
static router = StackRouter(routes, config);
...
}
```
Now you can use this component as a `screen` in another navigator, and the navigation logic for `MyNavigator` will be defined by this `StackRouter`.
## Customizing Routers
See the [Custom Router API spec](/docs/routers/api) to learn about the API of `StackRouter` and `TabRouter`. You can override the router functions as you see fit:
### Custom Navigation Actions
To override navigation behavior, you can override the navigation state logic in `getStateForAction`, and manually manipulate the `routes` and `index`.
```js
const MyApp = StackNavigator({
Home: { screen: HomeScreen },
Profile: { screen: ProfileScreen },
}, {
initialRouteName: 'Home',
})
const MyApp.router = {
...MyApp.router,
getStateForAction(action, state) {
if (state && action.type === 'PushTwoProfiles') {
const routes = [
...state.routes,
{key: 'A', routeName: 'Profile', params: { name: action.name1 }},
{key: 'B', routeName: 'Profile', params: { name: action.name2 }},
];
return {
...state,
routes,
index: routes.length - 1,
};
}
return MyApp.router.getStateForAction(action, state);
},
};
```
### Blocking Navigation Actions
Sometimes you may want to prevent some navigation activity, depending on your route.
```js
const MyStackRouter = StackRouter({
Home: { screen: HomeScreen },
Profile: { screen: ProfileScreen },
}, {
initialRouteName: 'Home',
})
const MyAppRouter = {
...MyStackRouter,
getStateForAction(action, state) {
if (
state &&
action.type === 'Back' &&
state.routes[state.index].params.isEditing
) {
// Returning null from getStateForAction means that the action
// has been handled/blocked, but there is not a new state
return null;
}
return MyStackRouter.getStateForAction(action, state);
},
};
```
### Handling Custom URIs
Perhaps your app has a unique URI which the built-in routers cannot handle. You can always extend the router `getActionForPathAndParams`.
```js
const MyApp = StackNavigator({
Home: { screen: HomeScreen },
Profile: { screen: ProfileScreen },
}, {
initialRouteName: 'Home',
})
MyApp.router = {
...MyApp.router,
getActionForPathAndParams(path, params) {
if (
path === 'my/custom/path' &&
params.magic === 'yes'
) {
// returns a profile navigate action for /my/custom/path?magic=yes
return {
type: 'Navigate',
routeName: 'Profile',
action: {
// This child action will get passed to the child router
// ProfileScreen.router.getStateForAction to get the child
// navigation state.
type: 'Navigate',
routeName: 'Friends',
},
};
return null;
}
return MyApp.router.getStateForAction(action, state);
},
};
```

101
docs/api/routers/RoutersAPI.md Normal file
View File

@@ -0,0 +1,101 @@
## Custom Router API
You can make your own router by building an object with the following functions:
```js
const MyRouter = {
getStateForAction: (action) => ({}),
getActionForPathAndParams: (path, params) => null,
getPathAndParamsForState: (state) => null,
getComponentForState: (state) => MyScreen,
getComponentForRouteName: (routeName) => MyScreen,
};
// Now, you can make a navigator by putting the router on it:
class MyNavigator extends React.Component {
static router = MyRouter;
render() {
...
}
}
```
![Routers manage the relationship between URIs, actions, and navigation state](/assets/routers-concept-map.png)
### `getStateForAction(action, state)`
Defines the navigation state in response to a given action. This function will be run when an action gets passed into `props.navigation.dispatch(`, or when any of the helper functions are called, like `navigation.navigate(`.
Typically this should return a navigation state, with the following form:
```
{
index: 1, // identifies which route in the routes array is active
routes: [
{
// Each route needs a name to identify the type.
routeName: 'MyRouteName',
// A unique identifier for this route in the routes array:
key: 'myroute-123',
// (used to specify the re-ordering of routes)
// Routes can have any data, as long as key and routeName are correct
...randomRouteData,
},
...moreRoutes,
]
}
```
If the router has handled the action externally, or wants to swallow it without changing the navigation state, this function will return `null`.
### `getComponentRouteName(routeName)`
Returns the child component or navigator for the given route name.
Say a router `getStateForAction` outputs a state like this:
```js
{
index: 1,
routes: [
{ key: 'A', routeName: 'Foo' },
{ key: 'B', routeName: 'Bar' },
],
}
```
Based on the routeNames in the state, the router is responsible for returning valid components when calling `router.getComponentRouteName('Foo')` or `router.getComponentRouteName('Bar')`.
### `getComponentForState(state)`
Returns the active component for a deep navigation state.
### `getActionForPathAndParams`
Returns an optional navigation action that should be used when the user navigates to this path and provides optional query parameters.
### `getPathAndParamsForState`
Returns the path and params that can be put into the URL to link the user back to the same spot in the app.
The path/params that are output from this should form an action when passed back into the router's `getActionForPathAndParams`. That action should take you to a similar state once passed through `getStateForAction`.
### `getScreenConfig`
Used to retrieve the navigation options for a route. Must provide the screen's current navigation prop, and the name of the option to be retrieved.
- `navigation` - This is the navigation prop that the screen will use, where the state refers to the screen's route/state. Dispatch will trigger actions in the context of that screen.
- `optionName` - What named option is being fetched, such as 'title'
Inside an example view, perhaps you need to fetch the configured title:
```js
// First, prepare a navigation prop for your child, or re-use one if already available.
const childNavigation = addNavigationHelpers({
// In this case we use navigation.state.index because we want the title for the active route.
state: navigation.state.routes[navigation.state.index],
dispatch: navigation.dispatch,
})
const screenTitle = this.props.router.getScreenConfig(childNavigation, 'title');
```

64
docs/api/routers/StackRouter.md Normal file
View File

@@ -0,0 +1,64 @@
# StackRouter
Manage the logical navigation stack, including pushing, popping, and handling path parsing to create a deep stack.
Let's take a look at a simple stack router:
```js
const MyApp = StackRouter({
Home: { screen: HomeScreen },
Profile: { screen: ProfileScreen },
}, {
initialRouteName: 'Home',
})
```
### RouteConfig
A basic stack router have a route config. Here is an example configuration:
```js
const MyApp = StackRouter({ // This is the RouteConfig:
Home: {
screen: HomeScreen,
path: '',
},
Profile: {
screen: ProfileScreen,
path: 'profile/:name',
},
Settings {
// This can be handy to lazily require a screen:
getScreen: () => require('Settings').default,
// Note: Child navigators cannot be configured using getScreen because
// the router will not be accessible. Navigators must be configured
// using `screen: MyNavigator`
path: 'settings',
},
});
```
Each item in the config may have the following:
- `path` - Specify the path and params to be parsed for item in the stack
- `screen` - Specify the screen component or child navigator
- `getScreen` - Set a lazy getter for a screen component (but not navigators)
### StackConfig
Config options that are also passed to the stack router.
- `initalRouteName` - The routeName for the default route when the stack first loads
- `initialRouteParams` - Default params of the initial route
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
### Supported Actions
The stack router may respond to the following navigation actions. The router will generally delegate the action handling to a child router, if possible.
- Navigate - Will push a new route on the stack if the routeName matches one of the router's routeConfigs
- Back - Goes back (pops)
- Reset - Clears the stack and provides new actions to create a fully new navigation state
- SetParams - An action that a screen dispatches to change the params of the current route.

60
docs/api/routers/TabRouter.md Normal file
View File

@@ -0,0 +1,60 @@
# TabRouter
Manage a set of tabs in the application, handle jumping to tabs, and handle the back button press to jump to the initial tab.
Let's take a look at a simple tabs router:
```js
const MyApp = TabRouter({
Home: { screen: HomeScreen },
Settings: { screen: SettingsScreen },
}, {
initialTab: 'Home',
})
```
### RouteConfig
A tabs router has a routeConfig for each possible tab:
```js
const MyApp = TabRouter({ // This is the RouteConfig:
Home: {
screen: HomeScreen,
path: 'main',
},
Settings: {
// This can be handy to lazily require a tab:
getScreen: () => require('./SettingsScreen').default,
// Note: Child navigators cannot be configured using getScreen because
// the router will not be accessible. Navigators must be configured
// using `screen: MyNavigator`
path: 'settings',
},
});
```
Each item in the config may have the following:
- `path` - Specify the path for each tab
- `screen` - Specify the screen component or child navigator
- `getScreen` - Set a lazy getter for a screen component (but not navigators)
### Tab Router Config
Config options that are also passed to the router.
- `initialTab` - The routeName for the initial tab route when first loading
- `order` - Array of routeNames which defines the order of the tabs
- `paths` - Provide a mapping of routeName to path config, which overrides the paths set in the routeConfigs.
- `backBehavior` - Should the back button cause a tab switch to the initial tab? If yes, set to `initialTab`, otherwise `none`. Defaults to `initialTab` behavior.
### Supported Actions
The tabs router may respond to the following navigation actions. The router will generally delegate the action handling to a child router, if possible.
- Navigate - Will jump to the routeName if it matches a tab
- Back - Goes to the first tab, if not already selected
- SetParams - An action that a screen dispatches to change the params of the current route.

191
docs/api/views/Transitioner.md Normal file
View File

@@ -0,0 +1,191 @@
# Transitioner
`Transitioner` is a React component that helps manage transitions for complex animated components. It manages the timing of animations and keeps track of various screens as they enter and leave, but it doesn't know what anything looks like, because rendering is entirely deferred to the developer.
Under the covers, `Transitioner` is used to implement `CardStack`, and hence the `StackNavigator`.
The most useful thing `Transitioner` does is to take in a prop of the current navigation state. When routes are removed from that navigation state, `Transitioner` will coordinate the transition away from those routes, keeping them on screen even though they are gone from the navigation state.
## Example
```jsx
class MyNavView extends Component {
...
render() {
return (
<Transitioner
configureTransition={this._configureTransition}
navigationState={this.props.navigation.state}
render={this._render}
onTransitionStart={this.onTransitionStart}
onTransitionEnd={this.onTransitionEnd}
/>
);
}
```
## Props
### `configureTransition` function
Invoked on `Transitioner.componentWillReceiveProps`, this function allows customization of animation parameters such as `duration`. The value returned from this function will be fed into a timing function, by default `Animated.timing()`, as its config.
#### Examples
```js
_configureTransition(transitionProps, prevTransitionProps) {
return {
// duration in milliseconds, default: 250
duration: 500,
// An easing function from `Easing`, default: Easing.inOut(Easing.ease)
easing: Easing.bounce,
}
}
```
Note: `duration` and `easing` are only applicable when the timing function is `Animated.timing`. We can also use a different timing function and its corresponding config parameters, like so:
```js
_configureTransition(transitionProps, prevTransitionProps) {
return {
// A timing function, default: Animated.timing.
timing: Animated.spring,
// Some parameters relevant to Animated.spring
friction: 1,
tension: 0.5,
}
}
```
#### Flow definition
```js
configureTransition: (
transitionProps: NavigationTransitionProps,
prevTransitionProps: ?NavigationTransitionProps,
) => NavigationTransitionSpec,
```
#### Parameters
- `transitionProps`: the current [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the current navigation state and props
- `prevTransitionProps`: the previous [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the previous navigation state and props
#### Returns
- An object of type [NavigationTransitionSpec](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L316) that will be fed into an Animated timing function as its config
### `navigationState` object
A plain object that represents the navigation state
#### Example value
```js
{
// Index refers to the active child route in the routes array.
index: 1,
routes: [
{ key: 'DF2FGWGAS-12', routeName: 'ContactHome' },
{ key: 'DF2FGWGAS-13', routeName: 'ContactDetail', params: { personId: 123 } }
]
}
```
#### Flow definition
```js
export type NavigationState = {
index: number,
routes: Array<NavigationRoute>,
};
```
For more information about the `NavigationRoute` type, check out its [flow definition](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L32).
### `render` function
Invoked from `Transitioner.render()`. This function performs the actual rendering delegated from `Transitioner`. In this function, we can use the information included in the `transitionProps` and `prevTransitionProps` parameters to render scenes, create animations and handle gestures.
There are a few important properties of the `transitionProps` and `prevTransitionProps` parameters that are useful for the tasks mentioned above:
- `scenes: Array<NavigationScene>` - a list of all available scenes
- `position: NavigationAnimatedValue` - the progressive index of the transitioner's navigation state
- `progress: NavigationAnimatedValue` - the value that represents the progress of the transition when navigation state changes from one to another. Its numberic value will range from 0 to 1.
For the complete list of properties of `NavigationTransitionProps`, check out its [flow definition](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273).
#### Examples
`transitionProps.scenes` is the list of all available scenes. It is up to the implementor to determine how to lay them out on the screen. For example, we can render the scenes as a stack of cards like so:
```jsx
_render(transitionProps, prevTransitionProps) {
const scenes = transitionProps.scenes.map(scene => this._renderScene(transitionProps, scene));
return (
<View style={styles.stack}>
{scenes}
</View>
);
}
```
We can then use an `Animated.View` to animate the transition. To create necessary animated style properties, such as `opacity`, we can interpolate on `position` and `progress` values that come with `transitionProps`:
```jsx
_renderScene(transitionProps, scene) {
const { position } = transitionProps;
const { index } = scene;
const opacity = position.interpolate({
inputRange: [index-1, index, index+1],
outputRange: [0, 1, 0],
});
// The prop `router` is populated when we call `createNavigator`.
const Scene = this.props.router.getComponent(scene.route.routeName);
return (
<Animated.View style={{ opacity }}>
{ Scene }
</Animated.View>
)
}
```
The above code creates a cross fade animation during transition.
For a comprehensive tutorial on how to create custom transitions, see this [blog post](http://www.reactnativediary.com/2016/12/20/navigation-experimental-custom-transition-1.html).
#### Flow definition
```js
render: (transitionProps: NavigationTransitionProps, prevTransitionProps: ?NavigationTransitionProps) => React.Element<*>,
```
#### Parameters
- `transitionProps`: the current [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the current state and props
- `prevTransitionProps`: the previous [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the previous state and props
#### Returns
- A ReactElement, which will be used to render the Transitioner component
### `onTransitionStart` function
Invoked when the transition animation is about to start.
#### Flow definition
```js
onTransitionStart: (transitionProps: NavigationTransitionProps, prevTransitionProps: ?NavigationTransitionProps) => void,
```
#### Parameters
- `transitionProps`: the current [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the current state and props
- `prevTransitionProps`: the previous [NavigationTransitionProps](https://github.com/reactjs/react-navigation/blob/master/src/TypeDefinition.js#L273) created from the previous state and props
#### Returns
- none.
### `onTransitionEnd` function
Invoked once the transition animation completes.
#### Flow definition
```js
onTransitionEnd: () => void
```
#### Parameters
- none.
#### Returns
- none.

17
docs/api/views/Views.md Normal file
View File

@@ -0,0 +1,17 @@
# Views
Navigation views are presentation components that take a [`router`](/docs/api/routers) and a [`navigation`](/docs/navigators/navigation-prop) prop, and can display several screens, as specified by the `navigation.state`.
Navigation views are controlled React components that can present the current navigation state. They manage switching of screens, animations and gestures. They also present persistent navigation views such as tab bars and headers.
## Built in Views
- [CardStack](https://github.com/reactjs/react-navigation/blob/master/src/views/CardStack.js) - Present a stack that looks suitable on any platform
+ [Card](https://github.com/reactjs/react-navigation/blob/master/src/views/Card.js) - Present one card from the card stack, with gestures
+ [Header](https://github.com/reactjs/react-navigation/blob/master/src/views/Header.js) - The header view for the card stack
- [Tabs](https://github.com/reactjs/react-navigation/blob/master/src/views/TabView) - A configurable tab switcher / pager
- [Drawer](https://github.com/reactjs/react-navigation/tree/master/src/views/Drawer) - A view with a drawer that slides from the left
## [Transitioner](/docs/views/transitioner)
`Transitioner` manages the animations during the transition and can be used to build fully custom navigation views. It is used inside the `CardStack` view. [Learn more about Transitioner here.](/docs/views/transitioner)