From a1b395f14da889780a6734a3206ef0a2a3f749a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrycja=20Kali=C5=84ska?= Date: Mon, 26 Feb 2024 10:02:54 +0100 Subject: [PATCH 1/3] Add static examples --- .../version-7.x/navigation-object.md | 984 +++++++++++++++++- 1 file changed, 930 insertions(+), 54 deletions(-) diff --git a/versioned_docs/version-7.x/navigation-object.md b/versioned_docs/version-7.x/navigation-object.md index 5b345e5d8e4..8f910ac772e 100755 --- a/versioned_docs/version-7.x/navigation-object.md +++ b/versioned_docs/version-7.x/navigation-object.md @@ -4,6 +4,9 @@ title: Navigation object reference sidebar_label: Navigation object --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + The `navigation` object contains various convenience functions that dispatch navigation actions. It looks like this: - `navigation` @@ -69,24 +72,139 @@ The `navigate` method lets us navigate to another screen in your app. It takes t - `name` - A destination name of the route that has been defined somewhere - `params` - Params to pass to the destination route. - + + -```js +```js name="Navigate method" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { + useNavigation, + createStaticNavigation, +} from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +// codeblock-focus-start +function HomeScreen() { + const navigation = useNavigation(); + + return ( + + This is the home screen of the app + + + ); +} +// codeblock-focus-end + +function ProfileScreen({ route }) { + const navigation = useNavigation(); + + return ( + + Profile Screen + Friends: + {route.params.names[0]} + {route.params.names[1]} + {route.params.names[2]} + + + ); +} + +const Stack = createNativeStackNavigator({ + initialRouteName: 'Home', + screens: { + Home: HomeScreen, + Profile: ProfileScreen, + }, +}); + +const Navigation = createStaticNavigation(Stack); + +function App() { + return ; +} + +export default App; +``` + + + + +```js name="Navigate method" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +// codeblock-focus-start function HomeScreen({ navigation: { navigate } }) { return ( - + This is the home screen of the app ); } +// codeblock-focus-end + +function ProfileScreen({ navigation, route }) { + return ( + + Profile Screen + Friends: + {route.params.names[0]} + {route.params.names[1]} + {route.params.names[2]} + + + ); +} + +const Stack = createNativeStackNavigator(); + +function App() { + return ( + + + + + + + ); +} + +export default App; ``` + + + In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack-navigator.md)), calling `navigate` with a screen name will have the following behavior: - If you're already on a screen with the same name, it will update its params and not push a new screen. @@ -97,10 +215,33 @@ By default, the screen is identified by its name. But you can also customize it For example, say you have specified a `getId` prop for `Profile` screen: + + + ```js - params.userId} /> +const Tabs = createBottomTabNavigator({ + screens: { + Profile: { + screen: ProfileScreen, + getId: ({ params }) => params.userId, + }, + }, +}); ``` + + + +```js + params.userId} +/> +``` + + + Now, if you have a stack with the history `Home > Profile (userId: bob) > Settings` and you call `navigate(Profile, { userId: 'alice' })`, the resulting screens will be `Home > Profile (userId: bob) > Settings > Profile (userId: alice)` since it'll add a new `Profile` screen as no matching screen was found. ### `goBack` @@ -109,31 +250,370 @@ The `goBack` method lets us go back to the previous screen in the navigator. By default, `goBack` will go back from the screen that it is called from: - + + + +```js name="Navigate method" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { + useNavigation, + createStaticNavigation, +} from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen() { + const navigation = useNavigation(); + + return ( + + This is the home screen of the app + + + ); +} + +// codeblock-focus-start +function ProfileScreen({ route }) { + const navigation = useNavigation(); -```js -function ProfileScreen({ navigation: { goBack } }) { return ( - - ); } +// codeblock-focus-end + +const Stack = createNativeStackNavigator({ + initialRouteName: 'Home', + screens: { + Home: HomeScreen, + Profile: ProfileScreen, + }, +}); + +const Navigation = createStaticNavigation(Stack); + +function App() { + return ; +} + +export default App; ``` + + + +```js name="Navigate method" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen({ navigation: { navigate } }) { + return ( + + This is the home screen of the app + + + ); +} + +// codeblock-focus-start +function ProfileScreen({ navigation, route }) { + return ( + + Profile Screen + Friends: + {route.params.names[0]} + {route.params.names[1]} + {route.params.names[2]} + // highlight-next-line + + + ); +} +// codeblock-focus-end + +const Stack = createNativeStackNavigator(); + +function App() { + return ( + + + + + + + ); +} + +export default App; +``` + + + + ### `reset` The `reset` method lets us replace the navigator state with a new state: - + + -```js -navigation.reset({ - index: 0, - routes: [{ name: 'Profile' }], +```js name="Navigate - replace and reset" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { Button } from '@react-navigation/elements'; +import { View, Text } from 'react-native'; +import { + useNavigation, + createStaticNavigation, +} from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen() { + const navigation = useNavigation(); + + return ( + + This is the home screen of the app + + + ); +} + +function ProfileScreen({ route }) { + const navigation = useNavigation(); + + return ( + + Profile Screen + Friends: + {route.params.names[0]} + {route.params.names[1]} + {route.params.names[2]} + + + + + + + ); +} + +function SettingsScreen({ route }) { + const navigation = useNavigation(); + + return ( + + Settings screen + {route.params.someParam} + + + + ); +} + +const Stack = createNativeStackNavigator({ + initialRouteName: 'Home', + screens: { + Home: HomeScreen, + Profile: ProfileScreen, + Settings: SettingsScreen, + }, }); + +const Navigation = createStaticNavigation(Stack); + +function App() { + return ; +} + +export default App; ``` + + + +```js name="Navigate - replace and reset" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { Button } from '@react-navigation/elements'; +import { View, Text } from 'react-native'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen({ navigation: { navigate } }) { + return ( + + This is the home screen of the app + + + ); +} + +function ProfileScreen({ navigation, route }) { + return ( + + Profile Screen + Friends: + {route.params.names[0]} + {route.params.names[1]} + {route.params.names[2]} + + + + + + + ); +} + +function SettingsScreen({ navigation, route }) { + return ( + + Settings screen + {route.params.someParam} + + + + ); +} + +const Stack = createNativeStackNavigator(); + +function App() { + return ( + + + + + + + + ); +} + +export default App; +``` + + + + The state object specified in `reset` replaces the existing [navigation state](navigation-state.md) with the new one, i.e. removes existing screens and add new ones. If you want to preserve the existing screens when changing the state, you can use [`CommonActions.reset`](navigation-actions.md#reset) with [`dispatch`](#dispatch) instead. :::warning @@ -146,59 +626,329 @@ Consider the navigator's state object to be internal and subject to change in a The `setParams` method lets us update the params (`route.params`) of the current screen. `setParams` works like React's `setState` - it shallow merges the provided params object with the current params. - + + -```js -function ProfileScreen({ navigation: { setParams } }) { - return ( - + + ); +} + +// codeblock-focus-start +function ProfileScreen({ route }) { + const navigation = useNavigation(); + + return ( + + Profile Screen + Friends: + {route.params.friends[0]} + {route.params.friends[1]} + {route.params.friends[2]} + + + ); } +// codeblock-focus-end + +const Stack = createNativeStackNavigator({ + initialRouteName: 'Home', + screens: { + Home: HomeScreen, + Profile: { + screen: ProfileScreen, + options: ({ route }) => ({ title: route.params.title }), + }, + }, +}); + +const Navigation = createStaticNavigation(Stack); + +function App() { + return ; +} + +export default App; ``` + + + +```js name="Navigate - setParams" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { Button } from '@react-navigation/elements'; +import { View, Text } from 'react-native'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen({ navigation: { navigate } }) { + return ( + + This is the home screen of the app + + + ); +} + +// codeblock-focus-start +function ProfileScreen({ navigation, route }) { + return ( + + Profile Screen + Friends: + {route.params.friends[0]} + {route.params.friends[1]} + {route.params.friends[2]} + + + + ); +} +// codeblock-focus-end + +const Stack = createNativeStackNavigator(); + +function App() { + return ( + + + + ({ title: route.params.title })} + /> + + + ); +} + +export default App; +``` + + + + ### `setOptions` The `setOptions` method lets us set screen options from within the component. This is useful if we need to use the component's props, state or context to configure our screen. - + + -```js +```js name="Navigate - setOptions" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text, TextInput } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { + useNavigation, + createStaticNavigation, +} from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen() { + const navigation = useNavigation(); + + return ( + + This is the home screen of the app + + + ); +} + +// codeblock-focus-start +function ProfileScreen({ route }) { + const navigation = useNavigation(); + const [value, onChangeText] = React.useState(route.params.title); + + React.useEffect(() => { + // highlight-start + navigation.setOptions({ + title: value === '' ? 'No title' : value, + }); + // highlight-end + }, [navigation, value]); + + return ( + + onChangeText(text)} + value={value} + /> + + + ); +} +// codeblock-focus-end + +const Stack = createNativeStackNavigator({ + initialRouteName: 'Home', + screens: { + Home: HomeScreen, + Profile: { + screen: ProfileScreen, + options: ({ route }) => ({ title: route.params.title }), + }, + }, +}); + +const Navigation = createStaticNavigation(Stack); + +function App() { + return ; +} + +export default App; +``` + + + + +```js name="Navigate - setOptions" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text, TextInput } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function HomeScreen({ navigation: { navigate } }) { + return ( + + This is the home screen of the app + + + ); +} + +// codeblock-focus-start function ProfileScreen({ navigation, route }) { const [value, onChangeText] = React.useState(route.params.title); React.useEffect(() => { + // highlight-start navigation.setOptions({ title: value === '' ? 'No title' : value, }); + // highlight-end }, [navigation, value]); return ( onChangeText(text)} value={value} /> - ); } +// codeblock-focus-end + +const Stack = createNativeStackNavigator(); + +function App() { + return ( + + + + ({ title: route.params.title })} + /> + + + ); +} + +export default App; ``` + + + Any options specified here are shallow merged with the options specified when defining the screen. When using `navigation.setOptions`, we recommend specifying a placeholder in the screen's `options` prop and update it using `navigation.setOptions`. This makes sure that the delay for updating the options isn't noticeable to the user. It also makes it work with lazy-loaded screens. @@ -215,22 +965,132 @@ You can also use `React.useLayoutEffect` to reduce the delay in updating the opt Screens can add listeners on the `navigation` object with the `addListener` method. For example, to listen to the `focus` event: - + + -```js -function Profile({ navigation }) { - React.useEffect(() => { - const unsubscribe = navigation.addListener('focus', () => { - // do something - }); +```js name="Navigation events" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { + useNavigation, + createStaticNavigation, +} from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; - return unsubscribe; - }, [navigation]); +function SettingsScreen() { + const navigation = useNavigation(); - return ; + return ( + + Settings Screen + + + ); +} + +// codeblock-focus-start +function ProfileScreen() { + const navigation = useNavigation(); + + React.useEffect( + () => navigation.addListener('focus', () => alert('Screen was focused')), + [navigation] + ); + + React.useEffect( + () => navigation.addListener('blur', () => alert('Screen was unfocused')), + [navigation] + ); + + return ( + + Profile Screen + + + ); +} +// codeblock-focus-end + +const SettingsStack = createNativeStackNavigator({ + screens: { + Settings: SettingsScreen, + Profile: ProfileScreen, + }, +}); + +const Navigation = createStaticNavigation(SettingsStack); + +export default function App() { + return ; } ``` + + + +```js name="Navigation events" snack version=7 dependencies=@react-navigation/elements +import * as React from 'react'; +import { View, Text } from 'react-native'; +import { Button } from '@react-navigation/elements'; +import { NavigationContainer } from '@react-navigation/native'; +import { createNativeStackNavigator } from '@react-navigation/native-stack'; + +function SettingsScreen({ navigation }) { + return ( + + Settings Screen + + + ); +} + +// codeblock-focus-start +function ProfileScreen({ navigation }) { + React.useEffect( + () => navigation.addListener('focus', () => alert('Screen was focused')), + [navigation] + ); + + React.useEffect( + () => navigation.addListener('blur', () => alert('Screen was unfocused')), + [navigation] + ); + + return ( + + Profile Screen + + + ); +} +// codeblock-focus-end + +const SettingsStack = createNativeStackNavigator(); + +export default function App() { + return ( + + + + + + + ); +} +``` + + + + See [Navigation events](navigation-events.md) for more details on the available events and the API usage. ### `isFocused` @@ -348,12 +1208,28 @@ It accepts an optional ID parameter to refer to a specific parent navigator. For To use an ID for a navigator, first pass a unique `id` prop: + + + +```js +const Drawer = createDrawerNavigator({ + id: 'LeftDrawer', + screens: { + /* content */ + }, +}); +``` + + + + ```js - - {/* .. */} - +{/* .. */} ``` + + + Then when using `getParent`, instead of: ```js From db74dc66711c7e407b9869350b7f15cc2e378c9f Mon Sep 17 00:00:00 2001 From: kacperkapusciak Date: Mon, 26 Feb 2024 12:38:14 +0100 Subject: [PATCH 2/3] code formatting --- .../version-7.x/navigation-object.md | 211 +++++++++--------- 1 file changed, 100 insertions(+), 111 deletions(-) diff --git a/versioned_docs/version-7.x/navigation-object.md b/versioned_docs/version-7.x/navigation-object.md index 8f910ac772e..cd70f77a5b0 100755 --- a/versioned_docs/version-7.x/navigation-object.md +++ b/versioned_docs/version-7.x/navigation-object.md @@ -93,16 +93,14 @@ function HomeScreen() { This is the home screen of the app @@ -120,7 +118,7 @@ function ProfileScreen({ route }) { {route.params.names[0]} {route.params.names[1]} {route.params.names[2]} - + ); } @@ -158,14 +156,12 @@ function HomeScreen({ navigation: { navigate } }) { This is the home screen of the app @@ -270,13 +266,12 @@ function HomeScreen() { This is the home screen of the app @@ -295,7 +290,7 @@ function ProfileScreen({ route }) { {route.params.names[1]} {route.params.names[2]} // highlight-next-line - + ); } @@ -333,11 +328,10 @@ function HomeScreen({ navigation: { navigate } }) { This is the home screen of the app @@ -354,7 +348,7 @@ function ProfileScreen({ navigation, route }) { {route.params.names[1]} {route.params.names[2]} // highlight-next-line - + ); } @@ -403,13 +397,13 @@ function HomeScreen() { This is the home screen of the app ); @@ -427,31 +421,30 @@ function ProfileScreen({ route }) { {route.params.names[2]} + @@ -517,11 +510,11 @@ function HomeScreen({ navigation: { navigate } }) { This is the home screen of the app ); @@ -546,22 +539,21 @@ function ProfileScreen({ navigation, route }) { Replace this screen with Settings + ); @@ -646,12 +637,12 @@ function HomeScreen() { This is the home screen of the app @@ -671,21 +662,20 @@ function ProfileScreen({ route }) { {route.params.friends[1]} {route.params.friends[2]} @@ -730,12 +720,12 @@ function HomeScreen({ navigation: { navigate } }) { This is the home screen of the app @@ -753,21 +743,20 @@ function ProfileScreen({ navigation, route }) { {route.params.friends[1]} {route.params.friends[2]} @@ -824,9 +813,9 @@ function HomeScreen() { This is the home screen of the app From 7417b07410d2eb8fa0db47d1488e0dbe0fd89662 Mon Sep 17 00:00:00 2001 From: kacperkapusciak Date: Mon, 26 Feb 2024 12:41:09 +0100 Subject: [PATCH 3/3] revert some code --- versioned_docs/version-7.x/navigation-object.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-7.x/navigation-object.md b/versioned_docs/version-7.x/navigation-object.md index cd70f77a5b0..7cf17a4cc72 100755 --- a/versioned_docs/version-7.x/navigation-object.md +++ b/versioned_docs/version-7.x/navigation-object.md @@ -840,7 +840,7 @@ function ProfileScreen({ route }) { onChangeText(text)} + onChangeText={onChangeText} value={value} /> @@ -906,7 +906,7 @@ function ProfileScreen({ navigation, route }) { onChangeText(text)} + onChangeText={onChangeText} value={value} />