React Navigation API Reference Manual 2: StackNavigator Stack Navigation

Provides a screen switching method that puts the new screen on top of the stack.

Annotation: In this article, screen switching, transformation, and transition refer to the same meaning, corresponding to English screen transition.

By default, on Apple and Android, StackNavigator is configured to have a similar look and feel: new screens slide out from the right on Apple iOS, and new screens fade out from the bottom on Android. The StackNavigator on Apple's iOS platform can also be configured in a modal style, where the screen slides out from the bottom.

API Definition

StackNavigator(RouteConfigs, StackNavigatorConfig);

RouteConfigs

RouteConfigs is a route configuration object that specifies a route configuration for each route name, telling the navigator what to display for that route.

StackNavigator({
  // 对每一个你可能要导航切换到的屏幕，创建一个类似这样的项:
  Profile: {
    // `ProfileScreen` 是一个用于表示屏幕主要内容的React组件.
    screen: ProfileScreen,
    // 当屏幕`ProfileScreen`被导航器StackNavigator加载时,它会被赋予一个属性`navigation`.

    // 可选项: 在web中深度链接或者使用react-navigation时,会用到path:
    path: 'people/:name',
    // Action 和 route 参数会从 path 中提取.

    // 可选项: Override the `navigationOptions` for the screen
    navigationOptions: ({ navigation }) => ({
      title: `${navigation.state.params.name}'s Profile'`,
    }),
  },

  ...MyOtherRoutes,
});

StackNavigatorConfig

Route configuration items:
- initialRouteName - The default screen of the entire navigation stack, which must be a route name used in the route configuration item.
- initialRouteParams - initial route parameters
- navigationOptions - default navigationOptions for each screen within the navigator
- paths - A mapping of overrides for the paths set in the route configs

Visual effects configuration items:

• mode - defines the screen rendering and switching style:
  
  • card - Use standard iOS and Android screen switching styles. Default.
  • modal - The screen slides out from the bottom, a common modal on iOS. Only works on iOS, not on Android.
• headerMode - Specifies how the header should be rendered:
  
  • float - only renders a header that stays on top, the header animates when the screen switches. Common pattern on iOS.
  • screen - Each screen has its own head and the head appears or disappears with the screen. Common pattern on Android.
  • none - no headers are used.
• headerTransitionPreset - Specifies headerMode: floathow the header transitions from one screen to another when used.
  
  • fade-in-place - The head component does not move but cross-fade, similar to Twitter, Instagram, and Facebook apps for iOS platforms. Default value.
  • uikit - Approximate iOS platform default behavior.
• cardStyle - Use this property to override or extend the default behavior of a card-style screen on the stack.
• transitionConfig - function, returns an object that will be merged with the default screen transition parameters. (See TransitionConfig in the type definition ). The returned function will be passed the following parameters:
  
  • transitionProps - New screen transition properties.
  • prevTransitionProps - Legacy screen transition properties.
  • isModal - Boolean variable indicating whether the screen is a modal screen.
• onTransitionStart - The function that will be called when the screen card transition animation is about to start.
• onTransitionEnd - a function that will be called once the screen card transition animation ends.

StackNavigatorin usenavigationOptions

title

headerTitleThis parameter is used when not specified headerTitle. Also, if it is TabNavigator, it will act tabBarLabelwhen it does not exist ; if it is , it will act when it does not exist .headerTitletabBarLabelDrawerNavigatordrawerLabelheaderTitledrawerLabel

header

HeaderPropsThe React element to be used as the entire header, or a function that returns the React element for the given property , if set to nullno header.

headerTitle

The string used in the header, React element or component. By default, the current screen is used title. When using a React component, it receives allowFontScaling, styleand childrenproperties. The title string is passed in through the childrenproperty.

headerTitleAllowFontScaling

Accessibility setting whether to allow the header header font to be enlarged to fit the text size. The default is true.

headerBackImage

Returns the image source of the image used by the button (it can be a remote image corresponding to the URL, for example {{uri: 'path/to/image'}}, or a local image resource, for example {require('path/to/image')}). The default is to use react-navigation/views/assets/back-icon.png, and also the default return icon on the corresponding platform (a V-shaped badge icon on the iOS platform, an arrow icon on the Android platform).

headerBackTitle

The title string used for the back button on the iOS platform, if you don't want to display it set to null. Defaults to the previous screen headerTitle.

headerTruncatedBackTitle

headerBackTitleThe title string to use when it doesn't fit the screen size. The default is "Back".

headerRight

React elements, displayed to the right of the header.

headerLeft

React elements or components, displayed to the left of the header. When using a component, it accepts some properties when rendered (onPress, title, titleStyle and a few others - there is a full list of properties in Header.js ).

headerStyle

The style object used to render the header.

headerForceInset

Allows passing forceInsetobjects to be used in the header SafeAreaView.

headerTitleStyle

The style object used to render the header header component.

headerBackTitleStyle

Rendering the header returns the style object used by the header.

headerTintColor

header text color

headerPressColorAndroid

Color for material ripple (valid for Android >= 5.0)

headerTransparent

The default is false. If set , truethe header has no background unless explicitly passed headerStyleor headerBackgroundset, in other words, the header is transparent in this case.

headerBackground

Used together headerTransparent, provides a component to render to the header background. For example, here you can use a blur view to create a semi-transparent head.

gesturesEnabled

Is it possible to turn off the screen by gesture. The default on iOS is true, and the default on Android is false.

gestureResponseDistance

An object used to cover the recognition distance of touch gestures from the edge of the screen, receiving the following properties:

• horizontal - number - distance in the horizontal direction. Default 25.
• vertical - number - distance in the vertical direction. Default 135.

gestureDirection

String used to override the direction of the screen off gesture. Defaults to normal behavior, or invertedmeans to swipe from right to left.

Navigator Props

StackNavigator(...)The navigator created by the function has the following properties:

• screenProps- Pass additional properties to the subscreen, such as:

const SomeStack = StackNavigator({
  // 配置
});

<SomeStack
  screenProps={/* 此属性会作为每个子屏幕的属性`this.props.screenProps`传入 */}
/>

example

If you can run the application locally NavigationPlayground, take a look at the examples SimpleStack.jsand ModalStack.js. You can watch these examples directly on your phone or use our expo demo .

Modal with custom toggleStackNavigator

const ModalNavigator = StackNavigator(
  {
    Main: { screen: Main },
    Login: { screen: Login },
  },
  {
    headerMode: 'none',
    mode: 'modal',
    navigationOptions: {
      gesturesEnabled: false,
    },
    transitionConfig: () => ({
      transitionSpec: {
        duration: 300,
        easing: Easing.out(Easing.poly(4)),
        timing: Animated.timing,
      },
      screenInterpolator: sceneProps => {
        const { layout, position, scene } = sceneProps;
        const { index } = scene;

        const height = layout.initHeight;
        const translateY = position.interpolate({
          inputRange: [index - 1, index, index + 1],
          outputRange: [height, 0, 0],
        });

        const opacity = position.interpolate({
          inputRange: [index - 1, index - 0.99, index],
          outputRange: [0, 1, 1],
        });

        return { opacity, transform: [{ translateY }] };
      },
    }),
  }
);

The switching of the head can also be set transitionConfigby headerLeftInterpolator, headerTitleInterpolatorand headerRightInterpolator.

English original