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¶
Объект стиля для заднего заголовка. Поддерживаемые свойства:
fontFamilyfontSize
Поддерживается только на iOS.
headerBackImageSource¶
Изображение для отображения в заголовке в качестве иконки кнопки "Назад". По умолчанию используется изображение значка кнопки "Назад" для данной платформы
- Шеврон на iOS
- Стрелка на Android
headerLargeStyle¶
Стиль заголовка при отображении большого заголовка. Большой заголовок будет показан, если headerLargeTitle имеет значение true и край любого прокручиваемого содержимого достигает совпадающего края заголовка.
Поддерживаемые свойства:
backgroundColor
Поддерживается только в iOS.
headerLargeTitle¶
Включать ли заголовок с большим заголовком, который при прокрутке сворачивается в обычный заголовок.
Чтобы большой заголовок сворачивался при прокрутке, содержимое экрана должно быть обернуто в прокручиваемое представление, такое как ScrollView или FlatList. Если прокручиваемая область не заполняет экран, то большой заголовок не будет сворачиваться при прокрутке. Также необходимо указать contentInsetAdjustmentBehavior="automatic" в ваших ScrollView, FlatList и т.д.
Поддерживается только на iOS.
headerLargeTitleShadowVisible¶
Будет ли видна падающая тень заголовка при показе большого заголовка.
headerLargeTitleStyle¶
Объект стиля для большого заголовка в заголовке. Поддерживаемые свойства:
fontFamilyfontSizefontWeightcolor
Поддерживается только на iOS.
headerShown¶
Показывать ли заголовок. По умолчанию заголовок отображается. Установка этого значения в false скрывает заголовок.
headerStyle¶
Объект стиля для заголовка. Поддерживаемые свойства:
backgroundColor
headerShadowVisible¶
Нужно ли скрывать тень подъема (Android) или нижнюю границу (iOS) на заголовке.
headerTransparent¶
Булево число, указывающее, является ли панель навигации полупрозрачной.
По умолчанию имеет значение false. Установка значения true делает заголовок абсолютно позиционированным - так, чтобы он плавал по экрану, перекрывая содержимое под ним, и изменяет цвет фона на transparent, если он не указан в headerStyle.
Это удобно, если требуется отобразить полупрозрачный заголовок или размытый фон.
Обратите внимание, что если вы не хотите, чтобы содержимое отображалось под заголовком, вам необходимо вручную добавить верхнее поле к содержимому. React Navigation не сделает этого автоматически.
Чтобы получить высоту заголовка, можно использовать HeaderHeightContext с помощью React's Context API или useHeaderHeight.
headerBlurEffect¶
Эффект размытия для полупрозрачного заголовка. Для работы этого эффекта опция headerTransparent должна быть установлена в значение true.
Поддерживаемые значения:
extraLightlightdarkregularprominentsystemUltraThinMaterialsystemThinMaterialsystemMaterialsystemThickMaterialsystemChromeMaterialsystemUltraThinMaterialLightsystemThinMaterialLightsystemMaterialLightsystemThickMaterialLightsystemChromeMaterialLightsystemUltraThinMaterialDarksystemThinMaterialDarksystemMaterialDarksystemThickMaterialDarksystemChromeMaterialDark
Поддерживается только на iOS.
headerBackground¶
Функция, возвращающая React-элемент для отображения в качестве фона заголовка. Это полезно для использования фонов, таких как изображение или градиент.
headerTintColor¶
Цвет оттенка для заголовка. Изменение цвета кнопки "Назад" и заголовка.
headerLeft¶
Функция, возвращающая React-элемент для отображения в левой части заголовка. Он заменяет кнопку "Назад". Для отображения кнопки "Назад" рядом с левым элементом смотрите headerBackVisible.
headerRight¶
Функция, возвращающая React-элемент для отображения в правой части заголовка.
headerTitle¶
Строка или функция, возвращающая React-элемент, который будет использоваться в заголовке. По умолчанию это title или название экрана.
При передаче функции в качестве аргумента ей передаются tintColor и children в объекте options. Строка заголовка передается в children.
Обратите внимание, что при рендеринге пользовательского элемента с передачей функции анимация для заголовка работать не будет.
headerTitleAlign¶
Как выровнять заголовок заголовка. Возможные значения:
leftcenter
По умолчанию принимает значение left на платформах, отличных от iOS.
Не поддерживается на iOS. На iOS оно всегда center и не может быть изменено.
headerTitleStyle¶
Объект стиля для заголовка. Поддерживаемые свойства:
fontFamilyfontSizefontWeightcolor
headerSearchBarOptions¶
Опции для отображения встроенной панели поиска на iOS. Строки поиска редко бывают статичными, поэтому обычно управление ими осуществляется путем передачи объекта навигационной опции headerSearchBarOptions в теле компонента. Также необходимо указать contentInsetAdjustmentBehavior="automatic" в ваших ScrollView, FlatList и т.д. Если у вас нет ScrollView, укажите headerTransparent: false.
Поддерживается только на iOS и Android.
Пример:
1 2 3 4 5 6 7 | |
Поддерживаемые свойства описаны ниже.
autoCapitalize¶
Служит для управления автоматическим выделением заглавных букв в тексте при его вводе пользователем.
Возможные значения:
nonewordssentencescharacters
По умолчанию принимается значение 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 | |