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 |
|
Определение 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 |
|
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 |
|
Поддерживаемые свойства описаны ниже.
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 |
|
header
¶
Пользовательский заголовок, используемый вместо заголовка по умолчанию.
Функция принимает функцию, возвращающую 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 |
|
Чтобы задать пользовательский заголовок для всех экранов навигатора, можно указать эту опцию в свойстве 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.
navigationBarColor
¶
Устанавливает цвет строки навигации. По умолчанию устанавливается исходный цвет строки состояния.
Поддерживается только в Android.
navigationBarHidden
¶
Булево значение, указывающее, должна ли панель навигации быть скрыта. По умолчанию имеет значение 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 |
|
transitionEnd
¶
Это событие вызывается, когда заканчивается анимация перехода для текущего экрана.
Данные события:
e.data.closing
- булево значение, указывающее, был ли экран открыт или закрыт.
Пример:
1 2 3 4 5 6 7 8 9 10 |
|
Хелперы¶
Собственный навигатор стека добавляет в реквизит навигации следующие методы:
replace
¶
Заменяет текущий экран на новый экран в стеке. Метод принимает следующие аргументы:
name
- string - Имя маршрута, который необходимо поместить в стек.params
- object - Параметры экрана для передачи маршруту назначения.
1 |
|
push
¶
Помещает новый экран на вершину стека и осуществляет переход к нему. Метод принимает следующие аргументы:
name
- string - Имя маршрута, который необходимо поместить в стек.params
- object - Параметры экрана для передачи маршруту назначения.
1 |
|
pop
¶
Выводит текущий экран из стека и осуществляет переход к предыдущему экрану. Принимает один необязательный аргумент (count
), который позволяет указать, на сколько экранов нужно вернуться назад.
1 |
|
popToTop
¶
Вызывает все экраны в стопке, кроме первого, и осуществляет переход к нему.
1 |
|
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 |
|