Перейти к содержанию

Native Stack навигатор

Native Stack Navigator предоставляет возможность перехода между экранами, при котором каждый новый экран размещается на вершине стопки.

Этот навигатор использует нативные API UINavigationController для iOS и Fragment для Android, поэтому навигация, созданная с помощью createNativeStackNavigator, будет вести себя точно так же и иметь те же характеристики производительности, что и приложения, созданные на базе этих API. Также реализована базовая поддержка Web с помощью react-native-web.

Следует иметь в виду, что, хотя @react-navigation/native-stack обеспечивает нативную производительность и предоставляет нативные возможности, такие как большие заголовки на iOS и т.д., он может быть не таким настраиваемым, как @react-navigation/stack, в зависимости от ваших потребностей. Поэтому если вам нужна более широкая настройка, чем та, которая возможна в этом навигаторе, используйте вместо него @react-navigation/stack - это более настраиваемая реализация на основе JavaScript.

Установка

Чтобы использовать этот навигатор, убедитесь, что у вас есть @react-navigation/native и его зависимости (следуйте этому руководству), затем установите @react-navigation/native-stack:

1
npm install @react-navigation/native-stack

Определение API

💡 Если вы столкнулись с ошибками при использовании createNativeStackNavigator, пожалуйста, открывайте проблемы на react-native-screens, а не в репозитории react-navigation!

Чтобы использовать этот навигатор, импортируйте его из @react-navigation/native-stack:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
    return (
        <Stack.Navigator>
            <Stack.Screen name="Home" component={Home} />
            <Stack.Screen
                name="Notifications"
                component={Notifications}
            />
            <Stack.Screen
                name="Profile"
                component={Profile}
            />
            <Stack.Screen
                name="Settings"
                component={Settings}
            />
        </Stack.Navigator>
    );
}

Props

Компонент Stack.Navigator принимает следующие реквизиты:

id

Необязательный уникальный идентификатор навигатора. Он может быть использован с помощью navigation.getParent для ссылки на этот навигатор в дочернем навигаторе.

initialRouteName

Имя маршрута, которое должно отображаться при первой загрузке навигатора.

screenOptions

Параметры по умолчанию, используемые для экранов в навигаторе.

Options

Для настройки экранов в навигаторе можно использовать следующие options:

title

Строка, которая может быть использована в качестве запасного варианта для headerTitle.

headerBackButtonMenuEnabled

Булево значение, указывающее, показывать ли меню при длительном нажатии на кнопку назад в iOS >= 14. По умолчанию имеет значение true.

Требуется версия react-native-screens >=3.3.0.

Поддерживается только на iOS.

headerBackVisible

Видима ли кнопка "Назад" в заголовке. Вы можете использовать этот параметр для отображения кнопки "Назад" рядом с headerLeft, если вы его указали.

Это не будет иметь никакого эффекта для первого экрана в стеке.

headerBackTitle

Строка заголовка, используемая кнопкой "Назад" на iOS. По умолчанию используется заголовок предыдущей сцены или "Back", если не хватает места. Чтобы скрыть его, используйте headerBackTitleVisible: false.

Поддерживается только на iOS.

headerBackTitleVisible

Должен ли заголовок кнопки "Назад" быть видимым или нет.

Поддерживается только на iOS.

headerBackTitleStyle

Объект стиля для заднего заголовка. Поддерживаемые свойства:

  • fontFamily
  • fontSize

Поддерживается только на iOS.

headerBackImageSource

Изображение для отображения в заголовке в качестве иконки кнопки "Назад". По умолчанию используется изображение значка кнопки "Назад" для данной платформы

  • Шеврон на iOS
  • Стрелка на Android

headerLargeStyle

Стиль заголовка при отображении большого заголовка. Большой заголовок будет показан, если headerLargeTitle имеет значение true и край любого прокручиваемого содержимого достигает совпадающего края заголовка.

Поддерживаемые свойства:

  • backgroundColor

Поддерживается только в iOS.

headerLargeTitle

Включать ли заголовок с большим заголовком, который при прокрутке сворачивается в обычный заголовок.

Чтобы большой заголовок сворачивался при прокрутке, содержимое экрана должно быть обернуто в прокручиваемое представление, такое как ScrollView или FlatList. Если прокручиваемая область не заполняет экран, то большой заголовок не будет сворачиваться при прокрутке. Также необходимо указать contentInsetAdjustmentBehavior="automatic" в ваших ScrollView, FlatList и т.д.

Поддерживается только на iOS.

headerLargeTitleShadowVisible

Будет ли видна падающая тень заголовка при показе большого заголовка.

headerLargeTitleStyle

Объект стиля для большого заголовка в заголовке. Поддерживаемые свойства:

  • fontFamily
  • fontSize
  • fontWeight
  • color

Поддерживается только на iOS.

headerShown

Показывать ли заголовок. По умолчанию заголовок отображается. Установка этого значения в false скрывает заголовок.

headerStyle

Объект стиля для заголовка. Поддерживаемые свойства:

  • backgroundColor

headerShadowVisible

Нужно ли скрывать тень подъема (Android) или нижнюю границу (iOS) на заголовке.

headerTransparent

Булево число, указывающее, является ли панель навигации полупрозрачной.

По умолчанию имеет значение false. Установка значения true делает заголовок абсолютно позиционированным - так, чтобы он плавал по экрану, перекрывая содержимое под ним, и изменяет цвет фона на transparent, если он не указан в headerStyle.

Это удобно, если требуется отобразить полупрозрачный заголовок или размытый фон.

Обратите внимание, что если вы не хотите, чтобы содержимое отображалось под заголовком, вам необходимо вручную добавить верхнее поле к содержимому. React Navigation не сделает этого автоматически.

Чтобы получить высоту заголовка, можно использовать HeaderHeightContext с помощью React's Context API или useHeaderHeight.

headerBlurEffect

Эффект размытия для полупрозрачного заголовка. Для работы этого эффекта опция headerTransparent должна быть установлена в значение true.

Поддерживаемые значения:

  • extraLight
  • light
  • dark
  • regular
  • prominent
  • systemUltraThinMaterial
  • systemThinMaterial
  • systemMaterial
  • systemThickMaterial
  • systemChromeMaterial
  • systemUltraThinMaterialLight
  • systemThinMaterialLight
  • systemMaterialLight
  • systemThickMaterialLight
  • systemChromeMaterialLight
  • systemUltraThinMaterialDark
  • systemThinMaterialDark
  • systemMaterialDark
  • systemThickMaterialDark
  • systemChromeMaterialDark

Поддерживается только на iOS.

headerBackground

Функция, возвращающая React-элемент для отображения в качестве фона заголовка. Это полезно для использования фонов, таких как изображение или градиент.

headerTintColor

Цвет оттенка для заголовка. Изменение цвета кнопки "Назад" и заголовка.

headerLeft

Функция, возвращающая React-элемент для отображения в левой части заголовка. Он заменяет кнопку "Назад". Для отображения кнопки "Назад" рядом с левым элементом смотрите headerBackVisible.

headerRight

Функция, возвращающая React-элемент для отображения в правой части заголовка.

headerTitle

Строка или функция, возвращающая React-элемент, который будет использоваться в заголовке. По умолчанию это title или название экрана.

При передаче функции в качестве аргумента ей передаются tintColor и children в объекте options. Строка заголовка передается в children.

Обратите внимание, что при рендеринге пользовательского элемента с передачей функции анимация для заголовка работать не будет.

headerTitleAlign

Как выровнять заголовок заголовка. Возможные значения:

  • left
  • center

По умолчанию принимает значение left на платформах, отличных от iOS.

Не поддерживается на iOS. На iOS оно всегда center и не может быть изменено.

headerTitleStyle

Объект стиля для заголовка. Поддерживаемые свойства:

  • fontFamily
  • fontSize
  • fontWeight
  • color

headerSearchBarOptions

Опции для отображения встроенной панели поиска на iOS. Строки поиска редко бывают статичными, поэтому обычно управление ими осуществляется путем передачи объекта навигационной опции headerSearchBarOptions в теле компонента. Также необходимо указать contentInsetAdjustmentBehavior="automatic" в ваших ScrollView, FlatList и т.д. Если у вас нет ScrollView, укажите headerTransparent: false.

Поддерживается только на iOS и Android.

Пример:

1
2
3
4
5
6
7
React.useLayoutEffect(() => {
    navigation.setOptions({
        headerSearchBarOptions: {
            // search bar options
        },
    });
}, [navigation]);

Поддерживаемые свойства описаны ниже.

autoCapitalize

Служит для управления автоматическим выделением заглавных букв в тексте при его вводе пользователем.

Возможные значения:

  • none
  • words
  • sentences
  • characters

По умолчанию принимается значение sentences.

autoFocus

Нужно ли автоматически фокусировать строку поиска при ее отображении. По умолчанию имеет значение false.

Поддерживается только в Android.

barTintColor

Цвет фона поля поиска. По умолчанию цвет фона поля полупрозрачный.

Поддерживается только в iOS.

tintColor

Цвет для каретки курсора и текста кнопки отмены.

Поддерживается только на iOS.

cancelButtonText

Текст, который будет использоваться вместо текста кнопки Cancel по умолчанию.

Поддерживается только на iOS.

disableBackButtonOverride

Должна ли кнопка "Назад" закрывать текстовый ввод строки поиска или нет. По умолчанию имеет значение false.

Поддерживается только в Android.

hideNavigationBar

Булево значение, указывающее, следует ли скрывать панель навигации во время поиска. По умолчанию имеет значение true.

Поддерживается только на iOS.

hideWhenScrolling

Булево значение, указывающее, следует ли скрывать строку поиска при прокрутке. По умолчанию имеет значение true.

Поддерживается только на iOS.

inputType

Тип вводимой информации. По умолчанию имеет значение "text".

Поддерживаемые значения:

  • "text"
  • "phone"
  • "number"
  • "email"

Поддерживается только на платформе Android.

obscureBackground

Булево значение, указывающее, следует ли скрывать основное содержимое полупрозрачным наложением. По умолчанию имеет значение true.

placeholder

Текст, отображаемый при пустом поле поиска.

textColor

Цвет текста в поле поиска.

hintTextColor

Цвет текста подсказки в поле поиска.

Поддерживается только в Android.

headerIconColor

Цвет значков поиска и закрытия, отображаемых в заголовке

Поддерживается только в ОС Android.

shouldShowHintSearchIcon

Показывать ли значок поисковой подсказки при фокусировке строки поиска. По умолчанию имеет значение true.

Поддерживается только в Android.

onBlur

Обратный вызов, который вызывается, когда панель поиска потеряла фокус.

onCancelButtonPress

Обратный вызов, который вызывается при нажатии кнопки отмены.

onChangeText

Обратный вызов, который вызывается при изменении текста. Он получает текущее значение текста строки поиска.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const [search, setSearch] = React.useState('');

React.useLayoutEffect(() => {
    navigation.setOptions({
        headerSearchBarOptions: {
            onChangeText: (event) =>
                setSearch(event.nativeEvent.text),
        },
    });
}, [navigation]);

Пользовательский заголовок, используемый вместо заголовка по умолчанию.

Функция принимает функцию, возвращающую React-элемент для отображения в качестве заголовка. В качестве аргумента функция получает объект, содержащий следующие свойства:

  • navigation - Объект навигации для текущего экрана.
  • route - Объект маршрута для текущего экрана.
  • options - Опции для текущего экрана
  • back - Опции для кнопки "Назад", содержит объект со свойством title для использования в качестве метки кнопки "Назад".

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import { getHeaderTitle } from '@react-navigation/elements';

// ..

header: ({ navigation, route, options, back }) => {
    const title = getHeaderTitle(options, route.name);

    return (
        <MyHeader
            title={title}
            leftButton={
                back ? (
                    <MyBackButton
                        onPress={navigation.goBack}
                    />
                ) : undefined
            }
            style={options.headerStyle}
        />
    );
};

Чтобы задать пользовательский заголовок для всех экранов навигатора, можно указать эту опцию в свойстве screenOptions навигатора.

Обратите внимание, что при задании пользовательского заголовка не будут работать встроенные функции, такие как большой заголовок, строка поиска и т.д.

statusBarAnimation

Устанавливает анимацию строки состояния (аналогично компоненту StatusBar). По умолчанию имеет значение fade для iOS и none для Android.

Поддерживаемые значения:

  • "fade"
  • "none"
  • "slide"

В Android установка опции fade или lide задает переход цвета строки состояния. На iOS эта опция применяется к анимации внешнего вида строки состояния.

Требуется установить значение View controller-based status bar appearance -> YES (или удалить конфигурацию) в файле Info.plist.

Поддерживается только на Android и iOS.

statusBarHidden

Должна ли строка состояния быть скрыта на этом экране.

Требуется установить значение View controller-based status bar appearance -> YES (или удалить конфигурацию) в файле Info.plist.

Поддерживается только на Android и iOS.

statusBarStyle

Устанавливает цвет строки состояния (аналогично компоненту StatusBar). По умолчанию имеет значение auto.

Поддерживаемые значения:

  • "auto"
  • "inverted" (iOS only)
  • "dark"
  • "light"

Требуется установить значение View controller-based status bar appearance -> YES (или удалить конфигурацию) в файле Info.plist.

Поддерживается только на Android и iOS.

statusBarColor

Устанавливает цвет строки состояния (аналогично компоненту StatusBar). По умолчанию устанавливается начальный цвет строки состояния.

Поддерживается только в Android.

statusBarTranslucent

Устанавливает полупрозрачность строки состояния (аналогично компоненту StatusBar). По умолчанию имеет значение false.

Поддерживается только в Android.

contentStyle

Объект стиля для содержимого сцены.

customAnimationOnGesture

Должен ли жест увольнения использовать анимацию, предоставленную в свойстве animation. По умолчанию имеет значение false.

Не влияет на поведение экранов, представленных модально.

Поддерживается только в iOS.

fullScreenGestureEnabled

Должен ли жест увольнения работать на весь экран. Использование жеста для отмены с этой опцией приводит к той же анимации перехода, что и simple_push. Это поведение можно изменить, задав параметр customAnimationOnGesture. Достижение анимации iOS по умолчанию невозможно из-за ограничений платформы. По умолчанию имеет значение false.

Не влияет на поведение экранов, представленных модально.

Поддерживается только на iOS.

gestureEnabled

Можно ли использовать жесты для выключения этого экрана. По умолчанию имеет значение true. Поддерживается только в iOS.

animationTypeForReplace

Тип анимации, используемой, когда этот экран заменяет другой экран. По умолчанию используется pop.

Поддерживаемые значения:

  • push: новый экран будет выполнять анимацию нажатия.
  • pop: новый экран будет выполнять анимацию всплытия.

animation

Как должен анимироваться экран при нажатии или отталкивании.

Поддерживаемые значения:

  • default: использовать анимацию по умолчанию платформы
  • fade: затухание экрана при входе или выходе
  • fade_from_bottom: затухание нового экрана снизу
  • flip: перевернуть экран, требуется presentation: "modal" (только для iOS)
  • simple_push: анимация по умолчанию, но без тени и собственного перехода заголовка (только для iOS, для Android используется анимация по умолчанию)
  • slide_from_bottom: переход на новый экран снизу
  • slide_from_right: переход на новый экран справа (только для Android, для iOS используется анимация по умолчанию)
  • slide_from_left: переход на новый экран слева (только для Android, для iOS используется анимация по умолчанию)
  • none: не анимировать экран

Поддерживается только на Android и iOS.

presentation

Как должен быть представлен экран.

Поддерживаемые значения:

  • card: новый экран будет помещен в стек, что означает, что анимация по умолчанию будет сползать сбоку на iOS, анимация на Android будет зависеть от версии ОС и темы.
  • modal: новый экран будет представлен модально. Это также позволяет отображать вложенный стек внутри экрана.
  • transparentModal: новый экран будет представлен модально, но при этом предыдущий экран останется, так что содержимое ниже будет видно, если экран имеет полупрозрачный фон.
  • containedModal: будет использоваться модальный стиль "UIModalPresentationCurrentContext" на iOS и откат к "modal" на Android.
  • containedTransparentModal: использует модальный стиль "UIModalPresentationOverCurrentContext" на iOS и возвращается к "transparentModal" на Android.
  • fullScreenModal: будет использоваться модальный стиль "UIModalPresentationFullScreen" на iOS и откат к "modal" на Android. Экран, использующий этот стиль представления, не может быть отвергнут жестом.
  • formSheet: будет использовать модальный стиль "UIModalPresentationFormSheet" на iOS и возвращаться к "modal" на Android.

Поддерживается только на Android и iOS.

orientation

Ориентация дисплея, используемая для экрана.

Поддерживаемые значения:

  • default - разрешается как "all" без "portrait_down" на iOS. В Android это значение позволяет системе самой определять оптимальную ориентацию.
  • all: разрешены все ориентации.
  • portrait: разрешена портретная ориентация.
  • portrait_up: разрешена правосторонняя портретная ориентация.
  • portrait_down: разрешена перевернутая портретная ориентация.
  • landscape: разрешены альбомные ориентации.
  • landscape_left: разрешена альбомная ориентация слева.
  • landscape_right: разрешена альбомно-правая ориентация.

Поддерживается только на Android и iOS.

autoHideHomeIndicator

Булево значение, указывающее, должен ли домашний индикатор оставаться скрытым. По умолчанию имеет значение false.

Поддерживается только в iOS.

gestureDirection

Устанавливает направление, в котором следует проводить пальцем по экрану для его удаления.

Поддерживаемые значения:

  • vertical - отклонение экрана по вертикали
  • horizontal - отклонение экрана по горизонтали (по умолчанию).

При использовании опции vertical по умолчанию устанавливаются опции fullScreenGestureEnabled: true, customAnimationOnGesture: true и animation: 'slide_from_bottom'.

Поддерживается только на iOS.

animationDuration

Изменяет длительность (в миллисекундах) переходов slide_from_bottom, fade_from_bottom, fade и simple_push на iOS. По умолчанию равно 350.

Длительность переходов default и flip не настраивается.

Поддерживается только на iOS.

Устанавливает цвет строки навигации. По умолчанию устанавливается исходный цвет строки состояния.

Поддерживается только в Android.

Булево значение, указывающее, должна ли панель навигации быть скрыта. По умолчанию имеет значение false.

Поддерживается только в Android.

freezeOnBlur

Булево значение, указывающее, следует ли запретить повторное отображение неактивных экранов. По умолчанию имеет значение false.

По умолчанию принимает значение true, если enableFreeze() из пакета react-native-screens запущен в верхней части приложения.

Требуется версия react-native-screens >=3.16.0.

Поддерживается только на iOS и Android.

События

Навигатор может выдавать события на определенные действия. Поддерживаются следующие события:

transitionStart

Это событие вызывается, когда начинается анимация перехода для текущего экрана.

Данные события:

  • e.data.closing - булево значение, указывающее, открывается или закрывается экран.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
React.useEffect(() => {
    const unsubscribe = navigation.addListener(
        'transitionStart',
        (e) => {
            // Do something
        }
    );

    return unsubscribe;
}, [navigation]);

transitionEnd

Это событие вызывается, когда заканчивается анимация перехода для текущего экрана.

Данные события:

  • e.data.closing - булево значение, указывающее, был ли экран открыт или закрыт.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
React.useEffect(() => {
    const unsubscribe = navigation.addListener(
        'transitionEnd',
        (e) => {
            // Do something
        }
    );

    return unsubscribe;
}, [navigation]);

Хелперы

Собственный навигатор стека добавляет в реквизит навигации следующие методы:

replace

Заменяет текущий экран на новый экран в стеке. Метод принимает следующие аргументы:

  • name - string - Имя маршрута, который необходимо поместить в стек.
  • params - object - Параметры экрана для передачи маршруту назначения.
1
navigation.replace('Profile', { owner: 'Michaś' });

push

Помещает новый экран на вершину стека и осуществляет переход к нему. Метод принимает следующие аргументы:

  • name - string - Имя маршрута, который необходимо поместить в стек.
  • params - object - Параметры экрана для передачи маршруту назначения.
1
navigation.push('Profile', { owner: 'Michaś' });

pop

Выводит текущий экран из стека и осуществляет переход к предыдущему экрану. Принимает один необязательный аргумент (count), который позволяет указать, на сколько экранов нужно вернуться назад.

1
navigation.pop();

popToTop

Вызывает все экраны в стопке, кроме первого, и осуществляет переход к нему.

1
navigation.popToTop();

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

function MyStack() {
    return (
        <Stack.Navigator
            initialRouteName="Home"
            screenOptions={{
                headerTintColor: 'white',
                headerStyle: { backgroundColor: 'tomato' },
            }}
        >
            <Stack.Screen
                name="Home"
                component={Home}
                options={{
                    title: 'Awesome app',
                }}
            />
            <Stack.Screen
                name="Profile"
                component={Profile}
                options={{
                    title: 'My profile',
                }}
            />
            <Stack.Screen
                name="Settings"
                component={Settings}
                options={{
                    gestureEnabled: false,
                }}
            />
        </Stack.Navigator>
    );
}

Ссылки

Комментарии