React-Native导航组件React-Navigation的详细介绍

深藏阁楼爱情的钟 2022-05-10 11:46 517阅读 0赞

### React-Native导航组件React-Navigation的详细介绍 ###

#### 一、 导航栏分类 ####

导航栏分为以下3类：

*  StackNavigator: 类似于普通的Navigator，屏幕上方导航栏
 *  TabNavigator: 相当于iOS里面的TabBarController，屏幕下方的标签栏
 *  DrawerNavigator: 抽屉效果，侧边滑出

#### 二、 具体说明 ####

官网：[StackNavigator][]  
有问题先去查查 [issues][]。  
我在这里使用的版本信息如下所示:

React-Navigation: "2.3.1"
     RN 版本：0.51

##### (一). StackNavigator 导航栏 #####

##### 1.1 API接口： #####

StackNavigator(RouteConfigs, StackNavigatorConfig)

其中接口中RouteConfigs用来设置路由路径，StackNavigatorConfig用来设置一些默认的响应或者样式,

##### 1.2 StackNavigatorConfig对象属性配置及意义如下： #####

initialRouteName:设置默认的页面组件，必须是上面已注册的页面组件
    initialRouteParams:初始路由的参数
    navigationOptions:屏幕导航的默认选项
    paths: RouteConfigs里面路径设置的映射
    mode:页面切换模式:
       card: 普通app常用的左右切换
       modal: 上下切换
    headerMode:导航栏的显示模式
       float: 无透明效果, 默认
       screen: 有渐变透明效果, 如微信QQ的一样
       none: 隐藏导航栏
    cardStyle:样式
    onTransitionStart:页面切换开始时的回调函数
    onTransitionEnd: 页面切换结束时的回调函数

##### 1.3 StackNavigatorConfig中属性navigationOptions对象属性说明: #####

title: 导航栏的标题
    header:导航栏设置对象
    headerTitle: 导航栏的标题, 可以是字符串也可以是个组件
    headerBackTitle: 左上角的返回键文字, 默认是上一个页面的title，设置这个属性会覆盖掉title的值headerRight: 导航栏右按钮
    headerLeft:导航栏左按钮
    headerStyle:导航栏的style
    headerTitleStyle:导航栏的title的style
    headerTintColor:返回按钮的颜色
    headerPressColorAndroid ：按压返回按钮显示的颜色 安卓系统 >= 5.0才有效。
    gesturesEnabled ：是否允许右滑返回，在iOS上默认为true，在Android上默认为false

##### 1.4代码，进行举例说明： #####

注意上面属性的使用，在旧的版本中可能不是这样的写法，如下面的使用方式,使用方法大概一致,只是将之前header对象中的属性拼接到一起放到了同header同级的属性下：

- title: 导航栏的标题
    - header: 导航栏设置对象
         - visible: 导航栏是否显示
         - title: 导航栏的标题, 可以是字符串也可以是个组件
         - backTitle: 左上角的返回键文字,默认是上一个页面title
         - right: 导航栏右按钮
         - left: 导航栏左按钮
         - style: 导航栏的style
         - titleStyle: 导航栏的title的style
         - tintColor: 导航栏颜色
    cardStack: 配置card stack
    gesturesEnabled: 是否允许右滑返回，在iOS上默认为true，在Android上默认为false

在使用的过程中,如果在新版本中使用了旧版本的用法,可能就会出现下面这样的错误,如下图所示:

![70][]

##### 1.5 界面跳转和数据传递 #####

对于数据的传递,我们在上面文章中有使用过initialRouteParams属性用来传递初始化参数,代码如下所示

initialRouteName: 'StackNavigatorOne',
      // 默认显示界面，在这里默认显示StackNavigatorOne组件
      initialRouteParams: { // 初始化路由的参数
        params: 'first page is StackNavigatorOne'
      },

在打开StackNavigatorOne默认页面的时候,我们能够看到params中参数,如下面界面

![70 1][] 上面方法传递了NavigatorConfig中配置的参数,在两个页面之间传递参数,需要使用下面的方法进行传递,首先需要了解navigation,在导航器中的每一个页面，都有navigation属性，该属性有以下几个属性/方法：

navigate – 跳到其他屏
    goBack – 关掉当前活跃屏
    addListener – 订阅导航生命周期事件
    isFocused – 一个函数，指出该屏是否处于聚焦状态(focused)
    state – 当前状态和路由 state/route
    setParams - 更改路由的参数
    getParam – 获取某个参数，带fallback机制
    dispatch – 发送一个指令Action到路由route

下面我们就来详细的说明以下这些方法:

###### (1).navigate()-调用这个方法可以跳转到导航器中的其他页面 ######

此方法有三个参数：

*  routeName 导航器中配置的路由名称
 *  params 传递参数到下一个页面
 *  action action（高级）如果屏幕是导航器，则在子路由器中运行的子操作。有关支持的操作的完整列表，请参阅Actions Doc
 *  key 要导航到的路线的可选标识符。如果已存在，则导航回此路线

如下所示进行具体使用:

const { navigation } = this.props;
        navigation.navigate('StackNavigatorTwo', { params: '0030' });

需要重点指出的是,navigation不是传递给所有组件；而是只有在RouteConfigs中配置的screen组件会自动接收该属性!比如，如果你想定义一个MyBackButton组件用作一个screen组件的子节点，在这个MyBackButton组件上，你是访问不到navigation属性的。  
如果是StackNavigator,this.props.navigation上还会有一些其他的功能函数。这些函数可以作为navigate和goBack的替代。这些函数是 :

push - 在导航栈中向前导航到一个新的路由,跟navigate类似
     pop - 在导航栈中返回,带你到导航栈中的上一屏。如果你提供一个数字n,它会指定从导航栈中帮你调回多少屏。
     popToTop - 回到导航栈的顶部
     replace - 使用新的路由替换当前路由

具体使用如下所示:

import React, { Component } from 'react';
    import { Text, View, TouchableOpacity } from 'react-native';
    
    export default class StackNavigatorOne extends Component {
      TWO = () => {
        const { navigation } = this.props;
        navigation.navigate('StackNavigatorTwo', { params: '0030' });
      };
    
      render() {
        return (
          <View style={
       { flex: 1, alignItems: 'center', paddingHorizontal: 15 }}>
            <View style={
       { alignItems: 'center', justifyContent: 'center' }}>
              <Text>StackNavigatorOne.js</Text>
              <TouchableOpacity
                onPress={this.TWO}
                style={
       { backgroundColor: '#fff' }}
              >
                <Text>跳转到StackNavigatorOne.js</Text>
              </TouchableOpacity>
            </View>
          </View>
        );
      }
    }

###### (2) goBack() -关闭当前活跃屏,相当于功能 ######

带一个可选参数key,指出从哪个路由返回。缺省情况下，`goBack`会关闭调用它的那个路由。这里一定要注意两点 :

1. 参数key 是路由的key属性，而不是路由名称 
    2. 参数key 指出的是返回动作的起点路由，而不是目标路由

如果目标路由是返回任何地方而不指定关闭什么，调用 `.goBack(null)`

import React, { Component } from 'react';
    import { Text, View, TouchableOpacity } from 'react-native';
    
    export default class StackNavigatorTwo extends Component {
      ONE = () => {
        const { navigation } = this.props;
        navigation.goBack();
      }
    
      render() {
        return (
          <View style={
       { flex: 1, alignItems: 'center', paddingHorizontal: 15 }}>
            <View style={
       { alignItems: 'center', justifyContent: 'center' }}>
              <Text>StackNavigatorTwo.js</Text>
              <TouchableOpacity
                onPress={this.ONE}
                style={
       { backgroundColor: '#fff' }}
              >
                <Text>跳转到StackNavigatorOne.js</Text>
              </TouchableOpacity>
            </View>
          </View>
        );
      }
    }

goBack(key) – 指定起始屏的返回,考虑一下如下导航栈历史:

navigation.navigate(SCREEN_KEY_A);
    navigation.navigate(SCREEN_KEY_B);
    navigation.navigate(SCREEN_KEY_C);
    navigation.navigate(SCREEN_KEY_D);

现在在屏D(也就是路由D)想返回屏A(需要弹出屏D,C,B)。想达到该效果，你需要提供一个参数指定返回起始路由给goBack：

navigation.goBack(SCREEN_KEY_B) // 会从屏B回到屏A，注意：这里参数用的不是当前屏D

###### (3)addListener() – 订阅导航生命周期事件变化 ######

React Navigation 会向做了订阅的screen屏组件发送事件:

willBlur – 屏幕将要被取消聚焦
    didBlur – 屏幕被取消了聚焦(如果有过渡动画，在过渡完成时)
    willFocus – 屏幕将要被聚焦
    didFocus – 屏幕被聚焦(如果有过渡动画，在过渡完成时)

例子 :

const didBlurSubscription = this.props.navigation.addListener(
      'didBlur',
      payload => {
        console.debug('didBlur', payload);
      }
    );
    
    // Remove the listener when you are done
    didBlurSubscription.remove();

JSON 格式的参数 payload ,可以根据payload进行数据的处理:

{
      action: { type: 'Navigation/COMPLETE_TRANSITION', key: 'StackRouterRoot' },
      context: 'id-1518521010538-2:Navigation/COMPLETE_TRANSITION_Root',
      lastState: undefined,
      state: undefined,
      type: 'didBlur',
    };

###### (4) isFocused() – 查看屏的聚焦状态 ######

如果屏处于聚焦状态返回true,否则返回false。

let isFocused = this.props.navigation.isFocused();

你可能不想直接使用该方法，而是使用高阶组件\[withNavigationFocus\]\{ [https://reactnavigation.org/docs/navigation-prop.html][https_reactnavigation.org_docs_navigation-prop.html]\},它会传递一个isFocused布尔变量属性到你的组件。如下面描述withNavigationFocus.  
withNavigationFocus是一个高阶组件，它将聚焦的属性传递到包裹的组件中。如果您需要在屏幕组件的呈现函数中或在屏幕内部的某个地方呈现的其他组件的呈现函数中使用焦点状态，那么它很有用。  
使用时,只要将需要聚焦的组件包含其中就可以了,返回值是一个新组件

withNavigationFocus(Component).

如下面,具体的使用代码:

import React from 'react';
    import { Text } 'react-native';
    import { withNavigationFocus } from 'react-navigation';
    class FocusStateLabel extends React.Component {
      render() {
        return <Text>{this.props.isFocused ? 'Focused' : 'Not focused'}</Text>;
      }
    }
    // withNavigationFocus returns a component that wraps FocusStateLabel and passes
    // in the navigation prop
    export default withNavigationFocus(FocusStateLabel);

###### (5)state – 屏幕的当前状态/路由 ######

一个屏screen组件可以通过this.props.navigation.state访问它的路由。其格式如下所示,其中params就是我们传递下来的参数 :

{
      // 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' }
    }

下面是访问navigate或者setParams中传递的params的最常用的方法 :

class ProfileScreen extends React.Component {
      render() {
        return <Text>Name: {this.props.navigation.state.params.name}</Text>;
      }
    }

###### (6)setParams() – 设置路由参数,通过此方法能够实时传递或者改变路由中的参数 ######

调用setParams允许一个屏幕组件修改路由中的参数params,该功能再修改屏幕头部按钮和标题文字时很有用，比如:

class ProfileScreen extends React.Component {
      render() {
        return (
          <Button
            onPress={() => this.props.navigation.setParams({ name: 'Lucy' })}
            title="Set title name to 'Lucy'"
          />
        );
      }
    }

###### (7)getParam – 获取指定参数值或用缺省值 ######

过去，你可能遇到过这中可怕的场景，想访问一个params中的一个参数时却发现整个params都未被定义。现在，不用再直接访问参数了，你可以调用getParam。  
**以前**:

const { name } = this.props.navigation.state.params;
    // 想直接访问params中的参数name，但有可能发现整个params都是undefined

**现在**:

const name = this.props.navigation.getParam('name', 'Peter');
    // 即使params或者params.name未定义，也不会有问题，会使用指定的fallback缺省值Peter

##### 1.6 高级API #####

###### (1) dispatch() ######

dispatch函数通常用的比较少，但是如果navigate或者goBack搞不定，它是一个很好的逃生舱口。  
dispatch – 发送指令给路由,可以向路由发送任何导航指令。其他的导航函数背后使用的都是dispatch。  
注意如果你想使用dispatch,你需要使用该库提供的指令创建器(action creator)。  
导航指令文档中列出了所有可用的指令。

import { NavigationActions } from 'react-navigation';
    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(navigateAction);

###### (2)reset() ######

reset()操作将擦除整个导航状态，并将其替换为多个操作的结果。  
参数使用如下所示:

index - number - required - 导航状态下路径数组上活动路由的索引.
    actions - array - required - 将替换导航状态的导航操作数组.
    key - string or null - optional - 如果设置，具有给定键的导航器将重置。 如果为null，则根导航器将重置.需要传递的参数能够通过params进行传递下去

下面是具体使用代码:

import { NavigationActions } from 'react-navigation';
    const resetAction = NavigationActions.reset({
      index: 0,
      actions: [NavigationActions.navigate({ routeName: 'Profile', params: { title: '配置文件' } })],
    });
    this.props.navigation.dispatch(resetAction);

如何使用reset()方法中索引参数?  
索引参数通常是用来指定当前活动的路由  
给出了具有两个路径的基本堆栈导航Profile和Settings。 要将状态重置为活动屏幕为“Settings”,但将其堆叠在“Profile”屏幕顶部的位置，您将执行以下操作：

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);

实现效果如下所示:

![70 2][]

##### (二). TabNavigator 标签栏 #####

##### 1.1 API接口： #####

TabNavigator(RouteConfigs, TabNavigatorConfig)

其中接口中RouteConfigs用来设置路由路径，TabNavigatorConfig用来设置一些默认的响应或者样式

##### 1.2 TabNavigatorConfig参数说明 #####

tabBarComponent - 提供给标签栏的组件.ios默认 TabBarBottom, Android默认TabBarTop.
    tabBarPosition - 标签栏的位置, 'top' 或者'bottom'.
    swipeEnabled - 是否允许在tabs之间滑动.
    animationEnabled - 当发生改变时,是否伴随有动画.
    lazy - 默认为true。 如果为false，则立即呈现所有选项卡。 如果为true，则仅在选项卡处于活动状态时才会呈现选项卡.
    removeClippedSubviews - 默认为true。通过释放非活动选项卡使用的资源来减少内存使用的优化.
    configureTransition - 给定currentTransitionProps和nextTransitionProps的函数，返回描述选项卡之间动画的配置对象.
    initialLayout - 可以传递包含初始高度和宽度的可选对象，以防止react-native-tab-view呈现中的一帧延迟.
    tabBarOptions - 配置标签栏，如下所示.

有些选项被传递给底层路由器以修改导航逻辑,如下所示:

initialRouteName - 首次加载时初始标签页路径的routeName.
    order - routeNames数组，用于定义选项卡的顺序.
    paths - 提供routeName到path config的映射，它覆盖routeConfigs中设置的路径.
    backBehavior - 后退按钮是否会导致选项卡切换到初始选项卡？如果是，则设置为initialRoute，否则为none。默认为initialRoute行为.

TabBarBottom的tabBarOptions属性说明（iOS上的默认标签栏）

activeTintColor -活动选项卡的标签和图标颜色。
    activeBackgroundColor -活动选项卡的背景色。
    inactiveTintColor -"非活动" 选项卡的标签和图标颜色。
    inactiveBackgroundColor -非活动选项卡的背景色。
    showLabel -是否显示选项卡的标签, 默认值为 true。
    style -选项卡栏的样式对象。
    labelStyle -选项卡标签的样式对象。
    tabStyle -选项卡的样式对象。
    allowFontScaling -无论标签字体是否应缩放以尊重文字大小可访问性设置，默认值都是 true。

TabBarTop的tabBarOptions（Android 上的默认选项卡栏）

activeTintColor -活动选项卡的标签和图标颜色。
    inactiveTintColor -"非活动" 选项卡的标签和图标颜色。
    showLabel -是否显示选项卡的图标，默认值为 false。
    showLabel -是否显示选项卡的标签, 默认值为 true。
    upperCaseLabel -是否使标签大写，默认为 true。
    pressColor -Color for material ripple（仅支持 Android >= 5.0）
    pressOpacity -按下标签时的不透明度（支持 iOS 和 Android < 5.0）。
    scrollEnabled -是否支持 选项卡滚动
    tabStyle -选项卡的样式对象。
    indicatorStyle -选项卡指示器的样式对象（选项卡底部的行）。
    labelStyle -选项卡标签的样式对象。
    iconStyle -选项卡图标的样式对象。
    style -选项卡栏的样式对象。
    allowFontScaling -无论标签字体是否应缩放以尊重文字大小可访问性设置，默认值都是 true。

navigationOptions used by TabNavigator

标题,可用作headerTitle和tabBarLabel的后备的通用标题。
    tabBarVisible-显示或隐藏标签栏，如果未设置则默认为true。
    swipeEnabled-启用或禁用标签之间的滑动操作，如果未设置，则默认为 TabNavigatorConfig 选项的 swipeEnabled。
    tabBarIcon-React Element or a function that given { focused: boolean, tintColor: string } returns a React.Node, to display in tab bar.
    tabBarLabel-标签栏或 React 元素中显示的选项卡的标题字符串或给定{ focused: boolean, tintColor: string }的函数返回 React.Node，用于显示在标签栏中。 未定义时，使用场景title。 要隐藏，请参阅上一节中的tabBarOptions.showLabel。
    tabBarOnPress-处理点击事件的回调; 该参数是一个对象，其中包含：
    		previousScene: { route, index } 这是我们要离开的场景
    		scene: { route, index }被点击的场景
    		jumpToIndex：可以为你执行导航的方法,在开始转换到下一个场景之前添加自定义逻辑（点击的场景）。

Navigator props  
The navigator component created by TabNavigator(…) takes the following props:

screenProps - Pass down extra options to child screens and navigation options, for example:

const TabNav = TabNavigator({
    // config
    });
    <TabNav
    screenProps={/* this prop will get passed to the screen components as this.props.screenProps */}
    />

##### (三). DrawerNavigator抽屉 #####

##### 1.1 API接口： #####

DrawerNavigator(RouteConfigs, DrawerNavigatorConfig)

##### 1.2 DrawerNavigatorConfig属性配置说明 #####

drawerWidth -抽屉的宽度或返回它的函数。
    drawerPosition -选项为 左 或 右. 默认值为 左 位置。
    contentComponent -用于呈现抽屉内容 (例如, 导航项) 的组件。 接收用于抽屉的 navigation 支柱。 默认为 DrawerItems。 有关详细信息, 请参阅下文。
    useNativeAnimations -启用本机动画。默认值为 true。
    drawerBackgroundColor -使用某种颜色的抽屉背景。默认值为 白色。
    contentOptions -配置抽屉内容, 请参阅下面。

contentOptions参数被传递到底层路由以修改导航逻辑的选项：  
contentOptions参数配置说明:

initialRouteName -第一次加载时初始选项卡路由的 routeName。
    order -定义选项卡顺序的 routeNames 数组。
    paths - 提供 routeName 到 path 配置的映射, 它重写 routeConfigs 中设置的路径。
    backBehavior - 控制 "返回" 按钮是否会导致 Tab 页切换到初始 Tab 页? 如果是, 设置为 initialRoute, 否则 none。 默认为 initialRoute的行为。

##### 1.3 提供一个自定义的contentComponent #####

抽屉的默认组件是可滚动的，只包含 RouteConfig 中路由的链接。 你可以轻松地覆盖默认组件，以向抽屉中添加页眉，页脚或其他内容。 默认情况下，抽屉可滚动并支持 iPhone X 安全区域。 如果您自定义内容，请务必将内容包装在 SafeAreaView 中：

import { DrawerItems, SafeAreaView } from 'react-navigation';
    const CustomDrawerContentComponent = (props) => (
      <ScrollView>
        <SafeAreaView style={styles.container} forceInset={
       { top: 'always', horizontal: 'never' }}>
          <DrawerItems {...props} />
        </SafeAreaView>
      </ScrollView>
    );
    
    const styles = StyleSheet.create({
      container: {
        flex: 1,
      },
    });

##### 1.4 DrawerItems的contentOptions #####

items - 路由数组，可以修改或覆盖
    activeItemKey - 识别活动路线的关键字
    activeTintColor -活动选项卡的标签和图标颜色。
    activeBackgroundColor -活动选项卡的背景色。
    inactiveTintColor -"非活动" 选项卡的标签和图标颜色。
    inactiveBackgroundColor -非活动选项卡的背景色。
    onItemPress (路由) -按下某项时调用的函数
    itemsContainerStyle -内容节的样式对象
    itemStyle 样式对象的单个项, 可以包含图标和/或标签
    labelStyle 样式对象要覆盖 文本 样式内部内容部分, 当您的标签是一个字符串
    iconContainerStyle - 用于覆盖View图标容器样式的样式对象。

#### 三、参考资料 ####

1.[https://blog.csdn.net/qq\_24867873/article/category/7306138][https_blog.csdn.net_qq_24867873_article_category_7306138]  
2.[https://www.cnblogs.com/qiyecao/p/8334507.html][https_www.cnblogs.com_qiyecao_p_8334507.html]

[StackNavigator]: https://reactnavigation.org/docs/en/getting-started.html
[issues]: https://github.com/react-navigation/react-navigation/issues
[70]: /images/20220510/b57a4772359c4c5a843716a56343530b.png
[70 1]: /images/20220510/69cd5e9a73fd48119db1d11035826687.png
[https_reactnavigation.org_docs_navigation-prop.html]: https://reactnavigation.org/docs/navigation-prop.html
[70 2]: /images/20220510/808890922c754d1e9638ffa5632170f2.png
[https_blog.csdn.net_qq_24867873_article_category_7306138]: https://blog.csdn.net/qq_24867873/article/category/7306138
[https_www.cnblogs.com_qiyecao_p_8334507.html]: https://www.cnblogs.com/qiyecao/p/8334507.html