Navigators
Navigators允許你定義你的導航結構.Navigators也可以渲染普通的元素,例如你配置好的header和tab bar.
navigators可以是單純的React組件.
內建的Navigators
react-navigation包含下面的幾個函數幫助你創建navigators：
- StackNavigator-一次渲染一個screen,在screen之間切換.當一個新的screen被打開的時候,他被放在棧頂.
- TabNavigator-渲染出一個tab bar讓用戶可以在多個screen之間切換.
- DrawNavigator-渲染一個抽屜,可以從屏幕左邊側滑出.
使用Navigators渲染screen
navigators實際渲染的就是React組件
瞭解怎麼創建screen,讀讀一下內容:
- Screennavigationprops允許screen分發navigation動作,例如操作另外一個screen.
- Screen navigationOptions定製screen的展示方式(例如：header title,tab label)
在頂層組件上調用導航
萬一你想在同一級別的Navigation screen之間使用Navigator,你可以使用react的ref選項:
const AppNavigator = StackNavigator(SomeAppRouteConfigs);
class App extends React.Component {
someEvent() {
// call navigate for AppNavigator here:
this.navigator && this.navigator.dispatch({ type: 'Navigate', routeName, params });
}
render() {
return (
<appnavigator> { this.navigator = nav; }} />
);
}
}
/<appnavigator>
注意:這個解決辦法只能用在頂層navigator上.
Navigation Containers
如果navigators沒有props的話,他就會表現為頂層navigators.這個方式提供了一個透明的navigator container,這是頂層導航props的來源.
當渲染其中一個navigators的時候,navigation prop是可選的.如果沒有navigation prop,container將會管理自己的導航state.他也可以使用URLs,外部鏈接以及整合android的back button.
為了使用方便,在幕後內建的navigators有這個能力,因為在幕後他們使用了createNavigationContainer.通常,navigators需要一個navigation prop來執行一定的功能.
onNavigationStateChange(prevState, newState)
當navigation state由頂層navigator變化管理的時候,這一點非常有用.為了達到這個目的,這個函數在每次調用的時候都會使用導航之前的state和導航之後的新state作為參數.
containerOptions
當一個navigator在頂層被使用的時候,這些選項可以來配置這個navigator.
如果一個navigator配置了containerOptions,但是也接受了navigationprop,會拋出錯誤.因為在這種情況下,navigator有兩種選擇,它就不知道怎麼做了.
- URIPrefic-app可以處理的URI前綴.在處理deep link的時候，可以提取路徑,並且傳遞到router.
StackNavigator
給你的app提供screen之間轉變的方法,每個轉變到的screen會存放在堆棧的棧頂.
默認情況下,StackNavigator配置有iOS和android的外觀和感覺:在iOS下,新的screen從屏幕的右側滑入,在android下,新的screen從底部淡入.iOS下也可以配置為從屏幕底部滑入.
class MyHomeScreen extends React.Component {
static navigationOptions = {
title: 'Home',
}
render() {
return (
<button> onPress={() => this.props.navigation.navigate('Profile', {name: 'Lucy'})}
title="Go to Lucy's profile"
/>
);
}
}
const ModalStack = StackNavigator({
Home: {
screen: MyHomeScreen,
},
Profile: {
path: 'people/:name',
screen: MyProfileScreen,
},
});
/<button>定義API
StackNavigator(Routeconfigs,StackNavigatorConfig)
RouteConfigs
route的配置對象是route name到route config的映射(譯者:這才是重點),配置對象告訴navigator什麼來代表route.
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 `navigationOptions` for the screen
navigationOptions: {
title: ({state}) => `${state.params.username}'s Profile'`,
},
},
...MyOtherRoutes,
});
StackNavigatorConfig
Router的Options:
- initialRouteName-設定默認的堆棧的screen.需要和route config的鍵之一相同.
- initalRouteParams-初始化route的參數
- navigationOptions-默認需要使用的可選參數
- path-覆蓋route configs的路徑設置
可視化選項:
- mode-定義渲染和切換之間的樣式:
- card-使用iOS和android標準的切換方法.默認值
- modal-使screen從底部滑動顯示.僅僅在iOS下使用,Andorid下沒有效果
- headerMode-定製header渲染的方法
- float-切換界面的時候,用動畫效果在screen的頂部渲染header
- screen-每一個screen都有一個header附著到頭部,切換的時候有淡入和淡出的效果.andorid的基本模式
- none-沒有header的渲染.
- cardStyle-使用這個prop來重寫或者擴展單個card的默認style
- onTransitionStart-當card開始切換動畫的時候,這個函數被調用
- onTransitionEnd-當切換動畫完成的時候,這個函數被調用
Screen Navigation Options
通常在screen組件中定義靜態的navigationOptions.例如:
class ProfileScreen extends React.Component {
static navigationOptions = {
title: ({ state }) => `${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})}
/>
),
}),
};
/<button>所有的stackNavigator的navigationOptions:
- title-scene的標題(字符串)
- header-header bar的配置對象
- visible-header可視性的切換.只有當headerMode是screen的時候才可以工作
- title-header可以使用的字符串或者React組件,默認是scene的title
- backTitle-iOS back按鈕的title字符串或者null到disable標籤,默認設定到scene的title.
- right-顯示在header右側的React組件
- left-同上,左側
- style-header的Style對象
- titleStyle-title組建的Style對象
- tintColor-header的著色
- cardStack-card stack的配置對象
- gesturesEnabled-不管你是不是用手勢,在iOS上是true,在android裡是false.
Navigator Props
由StackNavigator(...)創建的navigator組件接收兩個props:
screenProps-向下傳遞到子screen,例如:
const SomeStack = StackNavigator({
// config
});
<somestack> screenProps={/* this prop will get passed to the screen components as this.props.screenProps */}
/>
/<somestack>Examples
看看實例SimpleStack.js和ModalStack.js,可以在本地的NavigationPlaygroundapp中運行.
TabNavigator
通常很容易使用TabRouter來創建有幾個tabs的screen.
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')}
title="Go to notifications"
/>
);
}
}
class MyNotificationsScreen extends React.Component {
static navigationOptions = {
tabBar: {
label: 'Notifications',
icon: ({ tintColor }) => (
<image> source={require('./notif-icon.png')}
style={[styles.icon, {tintColor: tintColor}]}
/>
),
},
}
render() {
return (
<button> onPress={() => this.props.navigation.goBack()}
title="Go back home"
/>
);
}
}
const styles = StyleSheet.create({
icon: {
width: 26,
height: 26,
},
});
const MyApp = TabNavigator({
Home: {
screen: MyHomeScreen,
},
Notifications: {
screen: MyNotificationsScreen,
},
}, {
tabBarOptions: {
activeTintColor: '#e91e63',
},
});
/<button>/<image>/<button>/<image>定義API
TabNavigator(RouteConfigs,TabNavigator)
RouteConfigs
route的配置對象是route name到route config的映射(譯者:這才是重點),配置對象告訴navigator什麼來代表route.
TabNavigatorConfig
- tabBarComponent-作為tab bar的組件.例如,TabView.TabBarBottom(ios的默認配置),TabView.TabBarTop(android的默認配置)
- tabBarPosition-tab bar的位置,可以是top和bottom
- swipeEnabled-是否在tab之間滑動
- animationEnabled-變換tabs的時候是否開啟動畫效果
- lazyLoad-是否在需要的時候才惰性加載tabs,代替預渲染
- tabBarOption-配置tab bar,看下面
- 幾個Options可以傳遞到潛在的的router,修改導航的邏輯
- initialRouteName-初始化時加載的tab route
- order-定義tabs順序的routeName的數組
- paths-提供routeName到path配置的映射,重寫routeConfigs裡的paths設置
- backBehavior-back button是不是應該導致tab切換到初始的tab？入如果是的話,設定initialRoute,否則就是none.默認到initialRoute的行為.
TabBarTop的tabBarOptions設置(android默認的tab bar)
- activeTintColor-激活tab的標籤和icon的顏色
- inactiveTintColor-未激活tab的標籤和icon的顏色
- showIcon-是否在tab中顯示icon,默認是false
- showLabel-是否在tab顯示label,默認是true
- upperCaseLabel-tab的label是否是大寫,默認是true
- pressColor-material漣漪效果的顏色(Android>=5.0)
- pressOpacity-按下tab的透明度變化(iOS和Android<5.0)
- scrollEnabled-是否是滑動式tabs.
- tabStyle-tab的樣式配置對象
- indicatorStyle-tab指示器的樣式對象(tab底部的劃線)
- labelStyle-tab label的樣式對象
- style-tab bar的樣式對象
實例:
tabBarOptions: {
labelStyle: {
fontSize: 12,
},
style: {
backgroundColor: 'blue',
},
}
Screen導航的選項
通常在screen組件中定義靜態的navigationOptions.例如:
class ProfileScreen extends React.Component {
static navigationOptions = {
title: ({ state }) => `${state.params.name}'s Profile!`,
tabBar: ({ state, setParams }) => ({
icon: (
<image>
),
}),
};
所有TabNavigator的navigationOption:
- title-scene的title(字符串)
- tabBar-tab bar的config對象:
- visible-tab bar的可見性的切換
- icon-React組件或者函數給出{focused:boolean,tintColor:string},返回一個React組件,顯示在tab bar
- label-顯示在tab bar中的tab的名字.如果定義為undefined,scene的title會被使用.如果要隱藏,看前面部分的tabBarOption.showLabel.
Navigator Props
由TabNavigator(...)創建的navigator組件接收下面的props:
- screenProps-向下傳遞額外的options給子screen,例如:
const TabNav = TabNavigator({
// config
});
<tabnav> screenProps={/* this prop will get passed to the screen components as this.props.screenProps */}
/>
/<tabnav>抽屜式導航
用來構建抽屜式導航
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')}
title="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()}
title="Go back home"
/>
);
}
}
const styles = StyleSheet.create({
icon: {
width: 24,
height: 24,
},
});
const MyApp = DrawerNavigator({
Home: {
screen: MyHomeScreen,
},
Notifications: {
screen: MyNotificationsScreen,
},
});
/<button>/<image>/<button>/<image>打開抽屜或者關閉抽屜,分別導航到DrawerOpen和Drawerclose.
this.props.navigation.navigate('DrawerOpen'); // open drawer
this.props.navigation.navigate('DrawerClose'); // close drawer
定義API
DrawerNavigator(RouteConfigs, DrawerNavigatorConfig)
RouteConfigs
參看前面的內容
DrawerNavigatonConfig
- drawerWidth-抽屜的寬度
- drawerPosition-選項是left和right.默認是left.
- contentComponent-用來渲染抽屜內容的組件,例如,navigation item.接收navigationprop.默認是DrawerView.Items.瞭解更多內容看下面內容.
- contentOptions-配置drawer的內容,看下面內容
- 幾個選項傳遞給潛在的router,用來修改navigation的邏輯:
- initialRouteName-初始化route的routeName
- order-定義drawer item順序的routeName數組
- path-提供一個routeName到path config的映射,重寫掉routeConfigs中的path配置
- backBehavior-back按鈕一定要返回到初始化的route嗎？如果是的話,設置到initialRoute,否則就用none.默認到initialRoute的行為.
提供定製化的contentComponent
可以使用react-navigation重寫默認的組件.
const CustomDrawerContentComponent = (props) => (
<view>
<drawerview.items>
/<view>
);
const styles = StyleSheet.create({
container : {
flex : 1,
},
});
DrawerView.Item的contentOptions配置
- activeTintColor-激活的標籤的label和icon的顏色
- activeBackgroundColor-激活的標籤的背景顏色
- inactiveTintColor-未激活的標籤的label和icon的顏色
- inactiveBackgroundColor-未激活的標籤的背景顏色
- style-內容部分的樣式對象
示例:
contentOptions: {
activeTintColor: '#e91e63',
style: {
marginVertical: 0,
}
}
Screen導航的選項
通常在組件中定義靜態的navigationOptions.
class ProfileScreen extends React.Component {
static navigationOptions = {
title: ({ state }) => `${state.params.name}'s Profile!`,
drawer: {
icon: (
<image>
),
},
};
...
所有的DrawerNavigation navigationOption配置項
- title-scene的標題
- drawer-drawer的配置對象
- label-字符串,React組件或者函數被設定{fcoused:boolean,tinColor:string}返回一個React組件,顯示在drawer的邊欄上.當label定義為undefined時,scene的``title被使用.
- icon-React組件或者函數被設定為{fcoused:boolean,tintColor:string}返回一個React元素,顯示在drawer的邊欄上.
Navigator 的Props
由DrawerNavigator(...)創建的navigator組件接受下面的props:
- screenProps-向下傳遞額外的options到子screen,例如:
const DrawerNav = DrawerNavigator({
// config
});
<drawernav> screenProps={/* this prop will get passed to the screen components as this.props.screenProps */}
/>
/<drawernav>Screen Navigation Prop
app中的每個screen都接收navigation prop 包含下面的內容:
- navigate-(helper)鏈接的其他的screens
- state-screen的當前state和routes
- setParam-(helper)改變route的參數
- goBack-(helper)關閉激活的screen並且返回
- dispatch-發送一個action到router
Navigation Actions
所有的Navigation Actions都會返回一個對象,這個對象可以使用navigation.dispatch方法傳遞到router.
注意：如果你想dispatch react-navigation,你應該使用這個庫提供的action creators.
下面的actions是可以使用的:
- Navigate-導航到其他的route
- Reset-使用新的state代替目前的state
- Back-返回上一個state
- Set Params-給定的route設置參數
- Init-如果state沒有定義,用來初始化第一個state
Navigate
Navigatie action會使用Navigate action的結果來更新當前的state.
- routeName-字符串-必選項,在app的router裡註冊的導航目的地的routeName.
- params-對象-可選項-融合進目的地route的參數
- actions-對象-可選項-(高級)-如果screen也是一個navigator,次級action可以在子router中運行.在文檔中描述的任何actions都可以作為次級action.
import { NavigationActions } from 'react-navigation'
const navigateAction = NavigationActions.navigate({
routeName: 'Profile',
params: {},
action: NavigationActions.navigate({ routeName: 'SubProfileRoute'})
})
this.props.navigation.dispatch(navigateAction)
Reset
Resetaction刪掉所有的navigation state並且使用幾個actions的結果來代替.
- index—數組-必選-navigation state中route數組中激活route的index.
- actions-數組-必選項-Navigation Actions數組,將會替代navigation state
import { NavigationActions } from 'react-navigation'
const resetAction = NavigationActions.reset({
index: 0,
actions: [
NavigationActions.navigate({ routeName: 'Profile'})
]
})
this.props.navigation.dispatch(resetAction)
怎麼使用index參數
index參數被用來定製化當前激活的route
例如：使用兩個routes Profile和Settings給一個基礎的stakc navigation設置.為了重置route到經過Settings的激活screen那一點,但是在堆棧中他又存放在Settingscreen之上,你可以這麼做:
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)
Back
返回到前一個screen並且關閉當前screen.backaction creator接受一個可選的參數:
- key-字符串或者空-可選項-如果設定了,navigation將會從設定的key返回.如果是null,navigation將返回到任何地方.
import { NavigationActions } from 'react-navigation'
const backAction = NavigationActions.back({
key: 'Profile'
})
this.props.navigation.dispatch(backAction)
SetParams
當dispatching setParams的時候,router將會產出一個新的state,這個state是已經改變了特定route的參數,以key作為身份驗證
- params-對象-必選參數-融合進已經存在的route參數中的新參數
- key-字符串-必選參數-Route的key,應該分配給新的參數
import { NavigationActions } from 'react-navigation'
const setParamsAction = NavigationActions.setParams({
params: { title: 'Hello' },
key: 'screen-123',
})
this.props.navigation.dispatch(setParamsAction)
Screen Navigation Options
每個screen都可以配置幾個方面的內容,這些內容影響到在父navigators中怎麼得到展示.
定製每一個可選項的兩種方法
靜態配置方法:每一個navigation 可選項都可以被直接設定:
class MyScreen extends React.Component {
static navigationOptions = {
title: 'Great',
};
...
動態配置方法
要麼就採用函數式的方法,接受參數,然後返回可選項的值.
- navigation-screen的navigation prop和navigation.state中screen的route
- childRouter-如果screen是一個navigator,這個參數就是子代router.
class ProfileScreen extends React.Component {
static navigationOptions = {
title: (navigation, childRouter) => {
return navigation.state.params.name + "'s Profile!";
},
};
...
通用的Navigation Options
navigation的可選項title在每一個navigator之間是通用的,用來設定每一個screen的標題字符串.
class MyScreen extends React.Component {
static navigationOptions = {
title: 'Great',
};
不像其他的navigation的可配置項僅僅由navigator view來使用,title 選項可以被環境變量使用來更新瀏覽器的標題或者app切換時候的標題.
默認的Navigation選項
在screen中定義navigationOption非常普遍,但是有時候在navigator中定義navitationOptions也是非常有用
想象下面的場景:你的TabNavigator代表app中的一個screen.他在頂層StackNavigator之內:
StackNavigator:
- route1: A screen
- route2: A TabNavigator
現在route2是激活的,你可能會隱藏header,隱藏route1的header非常容易,route2的header應該也很容易隱藏.這就是默認Navigation Option 要做的.可以在navigationOptions中設定:
TabNavigator({
profile: ProfileScreen,
...
}, {
navigationOptions: {
header: {
visible: false,
},
},
});
提示:你仍然可以在子代導航screen上定製navigationOptions.-例如,上面的ProfileScreen.從screen獲得的navigationOptions會和從navigator來的配置按照鍵-鍵的方式融合在一起.無論在什麼而時間,navigator和screen定義相同的配置(例如:header),screen會優先使用.因此,當ProfileScreen激活的時候,你可以使header再次可見.
擴展默認配置:為了使用screen特定的properties擴展默認配置,而不是重寫它,你可以像下面一樣配置選項:
class ProfileScreen extends React.Component {
static navigationOptions = {
header: (navigation, defaultHeader) => ({
...defaultHeader,
visible: true,
}),
}
...
}
傳遞到函數的第二個參數作為在navigator中定義的header的默認值.
Tab Navigation Options
class TabScreen extends React.Component {
static navigationOptions = {
tabBar: ({ state }) => ({
label: 'Tab Label',
icon: ({ tintColor }) => (
<image> source={require('./tab-icon.png')}
style={[styles.icon, {tintColor: tintColor}]}
/>
),
visible: true
}),
};
};
/<image>- label-可以是字符串或者是React組件
- icon-函數返回icon組件
- visible-true或者false,顯示或者隱藏tab bar,默認是true
Custom Navigation
一個navigator是任何包含router的React組件.這裡是一個基本navigator,使用router的API去獲得激活組件來渲染
class MyNavigator extends React.Component {
static router = MyRouter;
render() {
const { state, dispatch } = this.props.navigation;
const { routes, index } = state;
// Figure out what to render based on the navigation state and the router:
const Component = MyRouter.getComponentForState(state);
// The state of the active child screen can be found at routes[index]
let childNavigation = { dispatch, state: routes[index] };
// If we want, we can also tinker with the dispatch function here, to limit
// or augment our children's actions
// Assuming our children want the convenience of calling .navigate() and so on,
// we should call addNavigationHelpers to augment our navigation prop:
childNavigation = addNavigationHelpers(childNavigation);
return <component>;
}
}
Navigation Prop
navigation prop傳遞給navigator的僅僅包含state和dispatch,這是當前的navigator的state,但是還有一個事件頻道用來發送action request.
所有的navigators都是受控組件:他們總是顯示根據props.navigation.state來顯示,他們要改變state,唯一的辦法是發送actions到props.navigation.dispatch.
Navigators可以通過定製他們的router來改變父navigators的行為.例如,當action應該從router.getStateForAction返回null來阻止其運行的時候.或者一個navigator可以為了定製URI的操作而改寫router.getActionForPathParams,為了輸出相對navigation action以及操作router.getStateForAction的action.
Navigation State
傳遞到props.navigation.state的navigation state有下面的結構:
{
index: 1, // identifies which route in the routes array is active
routes: [
{
// Each route needs a name, which routers will use to associate each route
// with a react component
routeName: 'MyRouteName',
// A unique id for this route, used to keep order in the routes array:
key: 'myroute-123',
// Routes can have any additional data. The included routers have `params`
...customRouteData,
},
...moreRoutes,
]
}
Navigation Dispatchers
navigator可以dispatch navigation actions,例如Go to URI,Go back.
如果action被成功操作了,dispatcher將會返回true,否則就是false
構建定製navigators的API
為了幫助開發者實施定製navigators,React Navigation提供了下面的工具
createNavigator
這個工具使用標準方法把router和navigation view合併在一起.
const MyApp = createNavigator(MyRouter)(MyView);
幕後所做的是:
const MyApp = ({ navigation }) => (
<myview>
);
MyApp.router = MyRouter;
addNavigationHelpers
接收一個擁有state和dispatch的純navigator的prop,傳遞的參數是在screen navigation prop中的各種函數,例如navigation.navigate()和navigation.goBack().這些函數是簡單的助手函數幫助創建action並且發送到dispatch.
createNavigationContainer
如果你想讓你的navigator作為頂層組件使用(沒有navigation prop傳入),你可以使用createNavigationContainer.當缺少navigtion prop的時候,這個工具使你的navigator看起來像一個頂層的導航組件.它將管理app的state,和app級別的導航特性整合在一起,例如操作進出的鏈接和android的返回按鈕行為。
【附錄】
資料圖
關注我私信回覆【學習】獲取免費學習視頻，學習大綱另外還有像高級UI、性能優化、架構師課程、NDK、混合式開發（ReactNative+Weex）等Android高階開發資料免費分享。
閱讀更多 Android架構 的文章
