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全解（中）
有问题的地方欢迎指出，大家一起讨论，喜欢的话可以点赞关注。
