kylefang/react-navigation
1
0
Fork 0
mirror of https://github.com/zhigang1992/react-navigation.git synced 2026-03-06 22:39:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README to match latest API

Browse Source
This commit is contained in:
satyajit.happy
2019-07-18 22:09:44 +02:00
parent d3099c18b8
commit 38aa8e447b
4 changed files with 53 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
README.md
View File

@@ -20,11 +20,7 @@ Hook which can access the navigation state from the context. Along with the stat
### Router
An object that provides a reducer to update the state as well as some action creators. The router object should implement several properties:
- `getInitialState`
- `getStateForAction`
- `actionCreators`
The router object provides various helper methods to deal with the state and actions, a reducer to update the state as well as some action creators.
The router is responsible for handling actions dispatched by calling methods on the `navigation` object. If the router cannot handle an action, it can return `null`, which would propagate the action to other routers until it's handled.
@@ -38,16 +34,23 @@ A simple navigator could look like this:
function StackNavigator({ initialRouteName, children, ...rest }) {
// The `navigation` object contains the navigation state and some helpers (e.g. push, pop)
// The `descriptors` object contains the screen options and a helper for rendering a screen
const { navigation, descriptors } = useNavigationBuilder(StackRouter, {
const { state, navigation, descriptors } = useNavigationBuilder(StackRouter, {
initialRouteName,
children,
});
return (
// The view determines how to animate any state changes
<StackView navigation={navigation} descriptors={descriptors} {...rest} />
<StackView
state={state}
navigation={navigation}
descriptors={descriptors}
{...rest}
/>
);
}
export default createNavigator(StackNavigator);
```
The navigator can render a screen by calling `descriptors[route.key].render()`. Internally, the descriptor adds appropriate wrappers to handle nested state.
@@ -63,28 +66,31 @@ If an initial state is specified, e.g. as a result of `Linking.getInitialURL()`,
## Basic usage
```js
const Stack = StackNavigator();
const Tab = TabNavigator();
function App() {
return (
<NavigationContainer>
<StackNavigator initialRouteName="home">
<Screen name="settings" component={Settings} />
<Screen
<Stack.Navigator initialRouteName="home">
<Stack.Screen name="settings" component={Settings} />
<Stack.Screen
name="profile"
component={Profile}
options={{ title: 'John Doe' }}
/>
<Screen name="home">
<Stack.Screen name="home">
{() => (
<TabNavigator initialRouteName="feed">
<Screen name="feed" component={Feed} />
<Screen name="article" component={Article} />
<Screen name="notifications">
<Tab.Navigator initialRouteName="feed">
<Tab.Screen name="feed" component={Feed} />
<Tab.Screen name="article" component={Article} />
<Tab.Screen name="notifications">
{props => <Notifications {...props} />}
</Screen>
</TabNavigator>
</Tab.Screen>
</Tab.Navigator>
)}
</Screen>
</StackNavigator>
</Stack.Screen>
</Stack.Navigator>
</NavigationContainer>
);
}
@@ -101,7 +107,7 @@ When a React component is specified, the navigator takes care of adding a `React
A render callback which doesn't have such limitation and is easier to use for this purpose. However, performance optimization for the component is left to the user in such case.
The rendered component will receives a `navigation` prop with various helpers.
The rendered component will receives a `navigation` prop with various helpers and a `route` prop which represents the route being rendered.
## Type-checking
@@ -125,13 +131,15 @@ type TabParamList = {
};
```
In a component, it's possible to annotate the `navigation` prop using these types:
In a component, it's possible to annotate the `navigation` and `route` props using these types:
```ts
function Profile({
navigation,
route,
}: {
navigation: StackNavigationProp<StackParamList, 'profile'>;
route: RouteProp<StackParamList, 'profile'>;
}) {
// Content
}
@@ -152,18 +160,15 @@ function Feed({
}
```
Annotating the `navigation` prop will be enough for provide type-checking for actions such as `navigate`, as well as accessing `params` for the current route etc.
Annotating the `navigation` prop will be enough for provide type-checking for actions such as `navigate` etc. Annotating `route` will provide type-checking for accessing `params` for the current route.
It's also possible to type-check the navigator to some extent. To do this, we need to create a typed navigator object:
It's also possible to type-check the navigator to some extent. To do this, we need to pass a generic when creating the navigator object:
```ts
const Stack: TypedNavigator<StackParamList, typeof StackNavigator> = {
Navigator: StackNavigator,
Screen,
};
const Stack = StackNavigator<StackParamList>();
```
And then we use the typed navigator instead:
And then we can use it:
```js
<Stack.Navigator initialRouteName="profile">

8
example/index.tsx
View File

@@ -7,8 +7,8 @@ import {
NavigationHelpers,
RouteProp,
} from '../src';
import Stack, { StackNavigationProp } from './StackNavigator';
import Tab, { TabNavigationProp } from './TabNavigator';
import StackNavigator, { StackNavigationProp } from './StackNavigator';
import TabNavigator, { TabNavigationProp } from './TabNavigator';
type StackParamList = {
first: { author: string };
@@ -21,9 +21,9 @@ type TabParamList = {
fifth: undefined;
};
const MyStack = Stack<StackParamList>();
const MyStack = StackNavigator<StackParamList>();
const MyTab = Tab<TabParamList>();
const MyTab = TabNavigator<TabParamList>();
const First = ({
navigation,

24
src/types.tsx
View File

@@ -104,6 +104,14 @@ export type Router<Action extends NavigationAction = CommonAction> = {
action: Action
): NavigationState | null;
/**
* Update state for a child navigator and focus it
*
* @param state State object to apply the action on.
* @param options.update Updated navigation state for the child navigator.
* @param options.focus Whether to focus the new child.
* @param options.key Route key of the child to update.
*/
getStateForChildUpdate(
state: NavigationState,
payload: {
@@ -116,21 +124,17 @@ export type Router<Action extends NavigationAction = CommonAction> = {
/**
* Whether the action bubbles to other navigators
* When an action isn't handled by current navigator, it can be passed to nested navigators
*
* @param action Action object to check.
*/
shouldActionPropagateToChildren(
action: NavigationAction,
navigatorKey: string,
sourceNavigatorKey?: string
): boolean;
shouldActionPropagateToChildren(action: NavigationAction): boolean;
/**
* Whether the action should also change focus in parent navigator
*
* @param action Action object to check.
*/
shouldActionChangeFocus(
action: NavigationAction,
navigatorKey: string,
sourceNavigatorKey?: string
): boolean;
shouldActionChangeFocus(action: NavigationAction): boolean;
/**
* Action creators for the router.

14
src/useOnAction.tsx
View File

@@ -41,11 +41,7 @@ export default function useOnAction({
if (result !== null) {
if (handleChildUpdateParent) {
const shouldFocus = router.shouldActionChangeFocus(
action,
state.key,
sourceNavigatorKey
);
const shouldFocus = router.shouldActionChangeFocus(action);
handleChildUpdateParent(result, shouldFocus, key);
} else if (state !== result) {
@@ -62,13 +58,7 @@ export default function useOnAction({
}
}
if (
router.shouldActionPropagateToChildren(
action,
state.key,
sourceNavigatorKey
)
) {
if (router.shouldActionPropagateToChildren(action)) {
for (let i = actionListeners.length - 1; i >= 0; i--) {
const listener = actionListeners[i];