ReactNative系列（四）：react-navigatio

ReactNative.jpg

ReactNative整理：《ReactNative系列》

内容目录

1. react-navigation简介
2. react-navigation详解
 2.1 安装react-navigation库
 2.2 StackNavigator -- 堆栈式导航
 2.3 SwitchNavigator -- 单页式导航
 2.4 TabNavigator -- 标签式导航
 2.5 DrawerNavigator -- 抽屉式导航
3. 结束

---

一、react-navigation简介

 移动应用基本上不会由单个页面组成。管理多个页面的呈现、跳转的组件，就是我们所说的导航器（Navigator）。
 React Navigation 源于 React Native 社区对一个可扩展且易于使用的导航解决方案的需求，它完全使用 JavaScript 编写。是社区今后主推的导航库。到现在为止已经维护到3.x版本。
 react-navigation导航器类型包括：StackNavigator、TabNavigator、DrawerNavigator、SwitchNavigator、BottomTabNavigator和MaterialTabNavigator。创建导航器的方法变成了以create开头，例如：创建StackNavigator需要用createStackNavigator，其余类似。
几种重要导航：

• StackNavigator：堆栈式导航器，利用栈管理页面的顶部导航栏，用作页面跳转和参数传递。
• SwitchNavigator：单页式导航器，一次只显示一个页面。默认情况下，不处理返回操作，并在切换时将路由重置为默认状态。
• TabNavigator：标签式导航器，底部tabBar标签区分模块，同一页面中可以点击切换不同模块。英文文档有说明，在3.X版本中，该导航器已经被删除，请用createBottomTabNavigator或createMaterialTopTabNavigator来代替。
• DrawerNavigator： 抽屉式导航器，侧滑菜单切换页面。

下面的内容也是围绕这四个导航类型来展开。建议大家看英文文档，相比中文文档要更准确点，同时也锻炼英文阅读能力。

ReactNavigation官方文档：《React Navigation》

二、react-navigation使用

1. 安装react-navigation库

// 如果有安装Yarn工具
yarn add react-navigation
// or with npm
// npm install --save react-navigation

然后，需要安装react-native-gesture-handler。

yarn add react-native-gesture-handler
// or with npm
// npm install --save react-native-gesture-handler

之后，Link链接到原生依赖。

react-native link react-native-gesture-handler

2. StackNavigation -- 堆栈式导航

简单来说，StackNavigation是一种以栈形式来管理页面的页面切换方式，默认配置下，具有熟悉的Android和iOS感觉&外观。栈的特性是先进后出，所以最新生成的页面push入栈后，会在最顶层。

(1) API定义

// 需要两个配置参数对象
createStackNavigator(RouteConfigs, StackNavigatorConfig);

(2) RouteConfigs（路由配置对象）
路由配置对象是从路由名称到路由配置的映射，它告诉导航器该路由呈现的内容。

• screen - 路由页面必须有的属性，表示内容页面名称，是一个React组件。
• path - 深度链接路径或者在web页面跳转APP时会用到。
• navigationOptions - 用于导航器内部页面的配置对象。

(3) StackNavigatorConfig （导航器配置对象）
路由选项：

• initialRouteName - 设置导航器的默认页面，必须是路由配置中的某一个。
• initialRouteParams - 初始路由的参数。
• initialRouteKey - 初始路由的可选标识符。
• defaultNavigationOptions - 用于屏幕的默认导航选项。
• paths - 覆盖路由配置中设置的路径的映射。

视觉选项：

• mode - 定义渲染和转换的样式：
  • card - 使用标准的 iOS 和 Android 屏幕转换， 这是默认设置。
  • modal - 页面从屏幕底部滑入，这是iOS的常用模式， 只在 iOS 上生效，在 Android 上无效。
• headerMode - 指定页眉的呈现方式：
  • float - 呈现一个位于顶部的单个页眉, 并在屏幕被更改时进行动画显示， 这是 iOS 上常见的模式。
  • screen - 每个屏幕都有一个标头, 并且页眉随屏幕一起淡入和淡出， 这是 Android 的常见模式。
  • none - 不会呈现页眉。
• headerBackTitleVisible - 提供合理的默认值以确定后退按钮标题是否可见，但如果要覆盖它，则可以使用true或false在此选项中。
• headerTransitionPreset - 在headerMode: float启用的情况下，指定标题在屏幕切换时的过渡方式。
  • fade-in-place - Header组件在不移动的情况下淡入淡出，类似iOS应用的Twitter, Instagram和Facebook。这个是默认值。
  • uikit - iOS默认行为的近似值（不懂这个是啥意思~~）。
• headerLayoutPreset - 指定Header组件的布局方式：
  • left - 将标题锚定在左侧，靠近返回键或其他左侧组件。在Android上是默认的。当在iOS上使用时，Header组件的返回标题是隐藏的，左侧组件的内容会溢出到标题下方，如果需要调整，可以用headerLeftContainerStyle和headerLeftContainerStyle两个属性。此外，该属性与headerTransitionPreset:uikit不兼容。
  • center - 标题居中，在iOS上是默认值。
• cardStyle - 用这个属性覆盖或扩展堆栈中单个Card的默认样式。
• cardShadowEnabled - 使用这个属性在转换的时候会展示可见的阴影。默认是true。
• cardOverlayEnabled - 使用这个属性在切换时显示堆栈卡片浮层。默认是false。
• transitionConfig - 返回一个合并默认屏幕切换效果的对象的函数。提供的函数将传递一下参数：
  • transitionProps - 新屏幕的过渡道具。
  • prevTransitionProps - 旧屏幕过渡道具。
  • isModal - 布尔值，指定屏幕是否为模态。
• onTransitionStart - 当卡转换动画即将开始时调用的函数。
• onTransitionEnd - 在卡转换动画完成后调用的函数。
• transparentCard - 该属性能够保持堆栈中所有卡片可见，并添加一个透明背景而不是白色的。这对于像实现模式对话框是很有用的，前面的场景在当前场景下方仍然是可见的。

(4) navigationOptions - 用于导航内部的页面配置
属性值太多，这里只列举一部分，有兴趣的可以去官网对照，

• title - 可以用作HeaderTitle回退的字符串。此外，将被用作tabBarLabel的回退（如果嵌套在TabNavigator中），或者drawerLabel（如果嵌套在DrawerNavigator中）。会在导航栏和标签栏中都生效。
• header - 返回一个React元素，显示为标题。设置null会隐藏标题。
• headerTitle - 可以是字符串、React元素或React组件，默认为场景标题。使用组件时，它能接收allowFontScaling，style和children为属性值。标题字符串通过children属性传入。
• headerTitleAllowFontScaling - Header标题字体是否缩放以符合系统设置的文字大小。默认值是true。
• headerBackImage - 用React元素或组件展示自定义返回按钮的图片。使用组件时，接收许多属性值用作渲染（如：tintColor，title）。
• headerBackTitle - iOS上返回键使用的标题字符串，或者用null会禁用标签。默认为上一个场景标题。该属性必须在初始屏幕中定义，不能在目标页面中定义。
• headerTruncatedBackTitle - 当headerBackTitle属性不适配屏幕时（内容过多），返回按钮会用该属性标题字符串。默认是Back。
• gesturesEnabled - 是否可以用手势关闭当前页面，iOS上默认为true，Android上默认为false。
• gestureResponseDistance - 用于覆盖从屏幕便于开始识别手势距离的对象。它有以下属性：
  • horizontal - number - 水平方向的距离。默认为25。
  • vertical - number - 垂直方向的距离。默认为135。
• gestureDirection - 用来覆盖关闭手势方向的字符串。default是正常行为，inverted是从右向左滑动。

3. SwitchNavigator -- 单页式导航

SwitchNavigator的用途是一次只显示一个页面。默认情况下，它不处理返回操作，并在页面切换的时候将路由重置为默认状态。该导航器适合用于首页需要广告或者需要安全验证的场景。

(1) API定义

createSwitchNavigator(RouteConfigs, SwitchNavigatorConfig);

(2) RouteConfigs（路由配置对象）
路由配置对象是从路由名称到路由配置的映射，它告诉导航器该路由呈现的内容。具体属性值可以参照createStackNavigator，两者类似。

(3) SwitchNavigatorConfig （导航配置对象）
有几个传递给底层路由器以修改路由逻辑的选项：

• initialRouteName - 首次加载时初始选项卡路由的路由名称。
• navigationOptions - 航器本身的导航选项，用于配置父导航器。
• defaultNavigationOptions - 用于屏幕的默认导航选项。
• resetOnBlur - 从屏幕切换时重置任何嵌套导航器的状态。默认值是true。
• paths - 提供RouteName到路径配置的映射，该映射会覆盖RouteConfigs中设置的路径值。
• backBehavior - initialRoute返回到初始路由，order返回到上一个路由，history返回上次访问路线的历史记录，或者none。

4. TabNavigator -- 标签式导航

TabNavigator在3.x版本中已经被移除，用createBottomTabNavigator或createMaterialTopTabNavigator来代替。

4.1 BottomTabNavigator -- 底部标签导航
 页面底部的标签栏，可以在不同路由之间切换。路由会懒加载，屏幕组件只有在第一次获取焦点时才会加载。

(1) API定义

createBottomTabNavigator(RouteConfigs, BottomTabNavigatorConfig);

(2) RouteConfigs（路由配置对象）
还是和上面一样，参照createStackNavigator属性配置。

(3) BottomTabNavigatorConfig （导航配置对象）

• initialRouteName - 首次加载时初始选项卡路由的路由名称。
• navigationOptions - 导航器本身的导航选项，用于配置父导航器。
• defaultNavigationOptions - 用于屏幕的默认导航选项。
• resetOnBlur - 屏幕切换时重置任何嵌套导航器的状态。默认为false。
• order - 定义选项卡顺序的路由名称数组。
• paths - 提供RouteName到路径配置的映射，该映射会覆盖RouteConfigs中设置的路径值。
• backBehavior - initialRoute返回到初始路由，order返回到上一个路由，history返回上次访问路线的历史记录，或者none。
• lazy - 默认为true。如果为false，则立即呈现所有选项卡。如果为true，则仅当选项卡第一次处于活动状态时才会呈现选项卡。注意：以后访问时不会重新呈现选项卡。
• tabBarComponent - 可选，覆盖要用作选项卡栏的组件。
• tabBarOptions - 具有以下属性的对象：
  • activeTintColor - 活动选项卡的标签和图标颜色。
  • activeBackgroundColor - 活动选项卡的背景色。
  • inactiveTintColor - 非活动选项卡的标签和图标颜色。
  • inactiveBackgroundColor - 非活动选项卡的背景色。
  • showLabel - 是否显示选项卡的标签，默认值为true。
  • showIcon - 是否显示选项卡的图标，默认值为true。
  • style - 选项卡栏的样式对象。
  • labelStyle - 选项卡标签的样式对象。
  • tabStyle - 选项卡的样式对象。
  • allowFontScaling - 标签字体是否应缩放以符合文本大小辅助功能设置，默认值为true。
  • adaptive - 选项卡图标和标签对齐方式是否应根据屏幕大小更改？对于iOS 11，默认为true。如果为false，则选项卡图标和标签始终垂直对齐。如果为true，则选项卡图标和标签在区域上水平对齐。
  • safeAreaInset - 覆盖SafeAreaView组件的forceInset属性，默认值是{ bottom: 'always', top: 'never' }。可用的key值有top、bottom、left和right，提供的value值有always 和never。

(4) navigationOptions - 用于导航内部的页面配置

• title - 可用作HeaderTitle和TabbarLabel回退的通用标题。
• tabBarVisible - true或false以显示或隐藏选项卡栏，如果不设置则默认为true。
• tabBarIcon - React元素或给定{ focused: boolean, horizontal: boolean, tintColor: string }返回React.Node的函数，展示在选项卡栏中。设备处于横向时horizontal属性是true，纵向时为false。每当设备方向改变时，图标都会重新渲染。
• tabBarLabel - 在选项卡栏或React元素中显示的选项卡的标题字符串，或给定{ focused: boolean, tintColor: string }返回要在选项卡栏中显示的react.node的函数。未定义时，将使用场景title。要隐藏，请参见上一节中的TabBarOptions.ShowLabel。
• tabBarButtonComponent - React组件包裹着图标和标签并实现onPress方法。默认值是一个围绕TouchableWithOutFeedback的包装器，使其成为行为与其他触摸事件相同。TabbarButtonComponent:TouchableOpacity将改用TouchableOpacity。
• tabBarAccessibilityLabel - 选项卡按钮的辅助功能标签。当用户点击选项卡时，屏幕阅读器将读取此信息。如果选项卡没有标签，建议设置此选项。
• tabBarTestID - 在测试中定位此选项卡按钮的ID。
• tabBarOnPress - 用于处理点击事件的回调，用于在转换到下一个场景（点击的场景）开始之前添加自定义逻辑；参数是一个包含以下内容的对象：
  • navigation - 屏幕导航属性。
  • defaultHandler - 选项卡按下的默认处理。
• tabBarOnLongPress - 用于处理长按事件的回调；参数是一个包含以下内容的对象：
  • navigation - 屏幕导航属性。
  • defaultHandler - 选项卡按下的默认处理。

4.2 MaterialTopTabNavigator -- 顶部标签导航
 屏幕顶部以材料设计为主题的选项卡栏，可通过点击路线或水平滑动在不同路线之间切换。默认情况下，转换是动态的。每个路由的屏幕组件会立即装载。

(1) API定义

createMaterialTopTabNavigator(RouteConfigs, TabNavigatorConfig);

(2) RouteConfigs（路由配置对象）
依旧参照createStackNavigator属性配置。

(3) TabNavigatorConfig （导航配置对象）
与BottomTabNavigatorConfig类似，里面的很多相同属性这里就不再重复了，只说几个不同属性：

• tabBarPosition - 标签栏的位置, 可以是top 或 bottom。默认值是top。
• swipeEnabled - 是否允许在标签页之间进行滑动。
• animationEnabled - 是否在更改标签页时进行动画处理。
• optimizationsEnabled - 是否将场景包装到ResourceSavingScene中，以便在场景未聚焦后将其移出屏幕，从而提高内存使用率。
• initialLayout - 可传递包含初始height和width的可选对象，以防止在react-native-tab-view视图渲染中出现单帧延迟。

(4) navigationOptions - 用于导航内部的页面配置
同样，该配置对象中相同的属性就不再这里重复了，只介绍不同的属性。

• swipeEnabled - 如果为true或false，则启用或禁用选项卡之间的滑动，如果未设置，则默认为TabNavigatorConfig选项中swipeEnabled。

5. DrawerNavigator -- 抽屉式导航

抽屉式导航不用多说，很多应用中都有这种操作方式。

(1) API定义

createDrawerNavigator(RouteConfigs, DrawerNavigatorConfig);

(2)RouteConfigs（路由配置对象）
依旧参照createStackNavigator属性配置。

(3) DrawerNavigatorConfig（导航配置对象）

• drawerWidth - 抽屉或返回抽屉的函数的宽度。
• drawerPosition - 选项有left和right。默认是left位置。
• contentComponent - 用于呈现抽屉内容的组件，例如，导航项。为抽屉接收navigation属性的。默认为DrawerItems。有关更多信息，请参见下文。
• contentOptions - 配置抽屉内容，见下文。
• useNativeAnimations - 启用本机动画。默认为true。
• drawerBackgroundColor - 使用抽屉背景来选择一些颜色。默认值为white。
• navigationOptions - 导航器本身的导航选项，用于配置父导航器。
• defaultNavigationOptions - 用于屏幕的默认导航选项。

DrawerNavigator在引擎下使用DrawerLayout，因此它继承了以下特性：

• drawerType - front、back和slide其中一个。
• edgeWidth - 允许定义离内容视图边缘有多远时滑动手势应该激活。
• hideStatusBar - 设置为true时，当抽屉被拉出或者处于打开状态下，Drawer组件会隐藏系统状态栏。
• overlayColor - 当抽屉打开时，要在内容视图的上层展示的遮罩层颜色。应该使用实心的颜色，因为不透明度是由Drawer本身添加的，并且遮罩的不透明度是动态的（从0%到70%）。

有几个选项传递给底层路由器以修改导航逻辑：

• initialRouteName - 初始路由的路由名称。
• order - 定义抽屉项顺序的路由名称数组。
• paths - 提供RouteName到路径配置的映射，该映射会覆盖RouteConfigs中设置的路径值。
• backBehavior - 后退按钮是否应导致切换到初始路线？如果是，则设置为initialRoute，否则为none。默认为initialRoute行为。

contentComponent还可以接收一个名为drawerOpenProgress的属性，它是表示抽屉动画位置的动画值（0为关闭，1为打开）。该属性允许你在contentComponent执行有趣的动画，像抽屉的视差运动。

(4) DrawerItems的内容选项：

• items - 路由数组，可以修改或重写。
• activeItemKey - 识别活动路线的Key值。
• activeTintColor - 活动标签的标签和图标颜色。
• activeBackgroundColor - 活动标签的背景色。
• inactiveTintColor - 非活动标签的标签和图标颜色。
• inactiveBackgroundColor - 非活动标签的背景色。
• onItemPress(route) - 当按下某个item时要调用的函数。
• itemsContainerStyle - 内容容器的样式对象。
• itemStyle - 单个项的样式对象，可以包含图标和（或）标签。
• labelStyle - 当标签是字符串时，样式对象覆盖内容容器内的Text样式。
• activeLabelStyle - Style对象在标签是字符串（与labelStyle合并）时覆盖活动标签的Text样式。
• inactiveLabelStyle - Style对象在标签是字符串（与LabelStyle合并）时覆盖非活动标签的文本样式。
• iconContainerStyle - 样式对象覆盖View图标容器样式。

(5) navigationOptions - 用于导航内部的页面配置

• title - 可用作headerTitle和drawerLabel回退的通用标题。
• drawerLabel - 字符串、react元素或给定{ focused: boolean, tintColor: string }返回一个react.node的函数，显示在抽屉边栏中。未定义时，使用场景标题。
• drawerIcon - react元素或函数，如果给定{ focused: boolean, tintColor: string }返回react.node，显示在抽屉边栏中。
• drawerLockMode - 指定抽屉的锁定模式。也可以通过在顶级路由器上使用screenProps.drawerLockMode动态更新。

将抽屉导航器嵌套在其他内部

如果抽屉导航器嵌套在另一个提供某些UI的导航器中，例如选项卡导航器或堆栈导航器，则抽屉将呈现在这些导航器UI的下方。抽屉将出现在标签栏下方和堆栈标题下方。嵌套时需要使抽屉导航器成为任何导航器的父级，其中抽屉应在其UI顶部呈现。

三、结束

 React-Navigation中的几种导航类型就都介绍完了，这里主要是罗列了各个导航器的属性配置（如果开发中遇到导航相关的BUG可以查找这些属性来调整解决，大部分是可以解决掉的）。由于篇幅问题，这篇文章只介绍属性，后面两篇会介绍每种导航器的用法及相互嵌套时的使用方式。另外，这几个导航的中文名称是我自己根据功能加上去的，大家可以不用在意。

  下一篇：ReactNative系列（五）：react-natigation 3.x全解（中）

 有问题的地方欢迎指出，大家一起讨论，喜欢的话可以点赞关注。