Version: 7.x

原生底部标签导航器

警告

此导航器目前处于实验阶段。API 将在未来的版本中更改。

¥This navigator is currently experimental. The API will change in future releases.

目前仅支持 iOS 和 Android。使用 createBottomTabNavigator 以支持 Web。

¥Currently only iOS and Android are supported. Use createBottomTabNavigator for web support.

原生底部标签页 (Native Bottom Tabs) 显示带有标签栏的屏幕，用于在它们之间切换。

¥Native Bottom Tabs displays screens with a tab bar to switch between them.

导航器在 iOS 和 Android 上使用原生组件，以实现更好的平台集成。在 iOS 上，它使用 UITabBarController；在 Android 上，它使用 BottomNavigationView。

¥The navigator uses native components on iOS and Android for better platform integration. On iOS, it uses UITabBarController and on Android, it uses BottomNavigationView.

安装

¥Installation

要使用此导航器，请确保你有 @react-navigation/native 及其依赖（遵循本指南），然后安装 @react-navigation/bottom-tabs：

¥To use this navigator, ensure that you have @react-navigation/native and its dependencies (follow this guide), then install @react-navigation/bottom-tabs:

npm
Yarn
pnpm

npm install @react-navigation/bottom-tabs

yarn add @react-navigation/bottom-tabs

pnpm add @react-navigation/bottom-tabs

导航器需要 React Native 0.79 或更高版本。如果你使用 Expo，则需要 SDK 53 或更高版本。

¥The navigator requires React Native 0.79 or above is required. If you're using Expo, it requires SDK 53 or above.

用法

¥Usage

要使用此导航器，请从 @react-navigation/bottom-tabs/unstable 导入它：

¥To use this navigator, import it from @react-navigation/bottom-tabs/unstable:

Static
Dynamic

import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';

const MyTabs = createNativeBottomTabNavigator({
  screens: {
    Home: HomeScreen,
    Profile: ProfileScreen,
  },
});

import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';

const Tab = createNativeBottomTabNavigator();

function MyTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name='Home' component={HomeScreen} />
      <Tab.Screen name='Profile' component={ProfileScreen} />
    </Tab.Navigator>
  );
}

备注

¥Notes

iOS 26 及更高版本上的 Liquid Glass 效果需要你的应用使用 Xcode 26 或更高版本构建。

¥Liquid Glass effect on iOS 26+ requires your app to be built with Xcode 26 or above.
在 Android 上，最多支持 5 个标签页。这是底层原生组件的限制。

¥On Android, at most 5 tabs are supported. This is a limitation of the underlying native component.

API 定义

¥API Definition

属性

¥Props

除了所有导航器共享的常用属性之外，底部标签导航器还接受以下附加属性：

¥In addition to the common props shared by all navigators, the bottom tab navigator accepts the following additional props:

`backBehavior`

这控制在导航器中调用 goBack 时发生的情况。这包括在 Android 上按设备的后退按钮或后退手势。

¥This controls what happens when goBack is called in the navigator. This includes pressing the device's back button or back gesture on Android.

它支持以下值：

¥It supports the following values:

firstRoute - 返回导航器中定义的第一个屏幕（默认）

¥firstRoute - return to the first screen defined in the navigator (default)
initialRoute - 返回 initialRouteName prop 中传入的初始屏幕，如果不传则默认到第一屏幕

¥initialRoute - return to initial screen passed in initialRouteName prop, if not passed, defaults to the first screen
order - 返回到聚焦屏幕之前定义的屏幕

¥order - return to screen defined before the focused screen
history - 返回导航器中上次访问的屏幕；如果多次访问同一屏幕，较旧的条目将从历史记录中删除

¥history - return to last visited screen in the navigator; if the same screen is visited multiple times, the older entries are dropped from the history
fullHistory - 返回导航器中上次访问的屏幕；与 history 不同，不会删除重复条目 - 这种行为有助于模拟网页的工作方式

¥fullHistory - return to last visited screen in the navigator; doesn't drop duplicate entries unlike history - this behavior is useful to match how web pages work
none - 不处理后退按钮

¥none - do not handle back button

选项

¥Options

以下 options 可用于配置导航器中的屏幕。这些可以在 Tab.Navigator 的 screenOptions 属性或 Tab.Screen 的 options 属性下指定。

¥The following options can be used to configure the screens in the navigator. These can be specified under screenOptions prop of Tab.Navigator or options prop of Tab.Screen.

`title`

可用作 headerTitle 和 tabBarLabel 后备的通用标题。

¥Generic title that can be used as a fallback for headerTitle and tabBarLabel.

`tabBarSystemItem`

使用 iOS 内置的标签栏项目，并采用标准的 iOS 样式和本地化标题。支持的值：

¥Uses iOS built-in tab bar items with standard iOS styling and localized titles. Supported values:

bookmarks
contacts
downloads
favorites
featured
history
more
mostRecent
mostViewed
recents
search
topRated

tabBarIcon 和 tabBarLabel 选项将覆盖系统项的图标和标签。如果你希望在 iOS 上保持系统行为，但需要为其他平台提供图标和标签，请使用 Platform.OS 或 Platform.select 有条件地为 iOS 上的 tabBarIcon 和 tabBarLabel 设置 undefined。

¥The tabBarIcon and tabBarLabel options will override the icon and label from the system item. If you want to keep the system behavior on iOS, but need to provide icon and label for other platforms, use Platform.OS or Platform.select to conditionally set undefined for tabBarIcon and tabBarLabel on iOS.

iOS 26+ 上的搜索标签页

¥Search tab on iOS 26+

在 iOS 26 及更高版本中，当 tabBarSystemItem 选项设置为 search 时，其样式和行为会有所不同。

¥The tabBarSystemItem option has special styling and behavior when set to search on iOS 26+.

此外，当选择 search 选项卡时，如果选项卡导航器中的屏幕或嵌套的原生堆栈导航器配置了 headerSearchBarOptions，并且使用 headerShown: true 显示原生标题，则选项卡栏将转换为搜索字段。如果 header 选项提供了自定义标题，则此选项将不起作用。

¥Additionally, when the search tab is selected, the tab bar transforms into a search field if the screen in the tab navigator or a nested native stack navigator has headerSearchBarOptions configured and the native header is shown with headerShown: true. This won't work if a custom header is provided with the header option.

示例：

¥Example:

tabBarSystemItem: 'search',
headerShown: true,
headerSearchBarOptions: {
  placeholder: 'Search',
},

`tabBarLabel`

显示在标签栏中的标签标题字符串。

¥Title string of a tab displayed in the tab bar.

覆盖 iOS 上 tabBarSystemItem 提供的标签。

¥Overrides the label provided by tabBarSystemItem on iOS.

如果未提供或设置为 undefined：

¥If not provided, or set to undefined:

如果在 iOS 上设置了 tabBarSystemItem，则使用系统值。

¥The system values are used if tabBarSystemItem is set on iOS.
否则，将回退到 title 或路由名称。

¥Otherwise, it falls back to the title or route name.

`tabBarLabelVisibilityMode`

标签栏项的标签可见性模式。支持的值：

¥The label visibility mode for the tab bar items. Supported values:

auto - 系统决定何时显示或隐藏标签

¥auto - the system decides when to show or hide labels
selected - 标签仅显示在选定的标签页中

¥selected - labels are shown only for the selected tab
labeled - 标签始终显示

¥labeled - labels are always shown
unlabeled - 标签从不显示

¥unlabeled - labels are never shown

仅在 Android 上支持。

¥Only supported on Android.

`tabBarLabelStyle`

选项卡标签的样式对象。支持的属性：

¥Style object for the tab label. Supported properties:

fontFamily
fontSize
fontWeight
fontStyle

示例：

¥Example:

tabBarLabelStyle: {
  fontSize: 16,
  fontFamily: 'Georgia',
  fontWeight: 300,
},

`tabBarIcon`

标签页显示的图标。它会覆盖 iOS 上 tabBarSystemItem 提供的图标。

¥Icon to display for the tab. It overrides the icon provided by tabBarSystemItem on iOS.

它可以是一个图标对象，也可以是一个函数，该函数接受 { focused: boolean, color: string, size: number } 作为参数并返回一个图标对象。

¥It can be an icon object or a function that given { focused: boolean, color: string, size: number } returns an icon object.

图标可以是以下类型：

¥The icon can be of following types:

本地图片 - 支持 iOS 和 Android

¥Local image - Supported on iOS and Android
```
tabBarIcon: {
  type: 'image',
  source: require('./path/to/icon.png'),
}
```
在 iOS 上，你还可以传递一个 tinted 属性来控制图标是否应根据激活/非激活状态着色：

¥On iOS, you can additionally pass a tinted property to control whether the icon should be tinted with the active/inactive color:
```
tabBarIcon: {
  type: 'image',
  source: require('./path/to/icon.png'),
  tinted: false,
}
```
默认情况下，图片带有颜色。

¥The image is tinted by default.
SF Symbols 名称 - iOS 支持

¥SF Symbols name - Supported on iOS
```
tabBarIcon: {
  type: 'sfSymbol',
  name: 'heart',
}
```
Drawable 资源名称 - Android 支持

¥Drawable resource name - Supported on Android
```
tabBarIcon: {
  type: 'drawableResource',
  name: 'sunny',
}
```

要为激活和非激活状态渲染不同的图标，你可以使用一个函数：

¥To render different icons for active and inactive states, you can use a function:

tabBarIcon: ({ focused }) => {
  return {
    type: 'sfSymbol',
    name: focused ? 'heart' : 'heart-outline',
  };
},

仅 iOS 支持此功能。在 Android 上，为非活动状态指定的图标将同时用于活动和非活动状态。

¥This is only supported on iOS. On Android, the icon specified for inactive state will be used for both active and inactive states.

要为不同的平台提供不同的图标，你可以使用 Platform.select：

¥To provide different icons for different platforms, you can use Platform.select:

tabBarIcon: Platform.select({
  ios: {
    type: 'sfSymbol',
    name: 'heart',
  },
  android: {
    type: 'drawableResource',
    name: 'heart_icon',
  },
});

`tabBarBadge`

要在选项卡图标上的徽章中显示的文本。接受 string 或 number。

¥Text to show in a badge on the tab icon. Accepts a string or a number.

`tabBarBadgeStyle`

选项卡图标上的徽章样式。支持的属性：

¥Style for the badge on the tab icon. Supported properties:

backgroundColor
color

示例：

¥Example:

tabBarBadgeStyle: {
  backgroundColor: 'yellow',
  color: 'black',
},

仅在 Android 上支持。

选项卡栏的样式对象。支持的属性：

¥Style object for the tab bar. Supported properties:

backgroundColor - 仅支持 Android 和 iOS 18 及更低版本。

¥backgroundColor - Only supported on Android and iOS 18 and below.
shadowColor - 仅支持 iOS 18 及更低版本。

¥shadowColor - Only supported on iOS 18 and below.

在 iOS 26 及更高版本中，背景颜色会根据标签栏后面的内容自动更改，且无法手动覆盖。

¥On iOS 26+, the background color automatically changes based on the content behind the tab bar and can't be overridden.

`tabBarBlurEffect`

在 iOS 18 及更低版本中，选中标签页时，标签栏会应用模糊效果。

¥Blur effect applied to the tab bar on iOS 18 and lower when tab screen is selected.

支持的值：

¥Supported values:

none - 无模糊效果

¥none - no blur effect
systemDefault - 系统默认应用的模糊效果

¥systemDefault - default blur effect applied by the system
extraLight
light
dark
regular
prominent
systemUltraThinMaterial
systemThinMaterial
systemMaterial
systemThickMaterial
systemChromeMaterial
systemUltraThinMaterialLight
systemThinMaterialLight
systemMaterialLight
systemThickMaterialLight
systemChromeMaterialLight
systemUltraThinMaterialDark
systemThinMaterialDark
systemMaterialDark
systemThickMaterialDark
systemChromeMaterialDark

默认为 systemDefault。

¥Defaults to systemDefault.

仅支持 iOS 18 及更低版本。

¥Only supported on iOS 18 and below.

`tabBarControllerMode`

标签栏的显示模式。支持的值：

¥The display mode for the tab bar. Supported values:

auto - 系统根据标签的内容设置显示模式

¥auto - the system sets the display mode based on the tab’s content
tabBar - 系统仅将内容显示为标签栏

¥tabBar - the system displays the content only as a tab bar
tabSidebar - 标签栏显示为侧边栏

¥tabSidebar - the tab bar is displayed as a sidebar

仅支持 iOS 18 及更高版本。tvOS 不支持。

¥Only supported on iOS 18 and above. Not supported on tvOS.

`tabBarMinimizeBehavior`

标签栏的最小化行为。支持的值：

¥The minimize behavior for the tab bar. Supported values:

auto - 解析为系统默认的最小化行为

¥auto - resolves to the system default minimize behavior
never - 标签栏不会最小化

¥never - the tab bar does not minimize
onScrollDown - 向下滚动时标签栏最小化，向上滚动时标签栏展开

¥onScrollDown - the tab bar minimizes when scrolling down and expands when scrolling back up
onScrollUp - 向上滚动时标签栏最小化，向下滚动时标签栏展开

¥onScrollUp - the tab bar minimizes when scrolling up and expands when scrolling back down

仅支持 iOS 26 及更高版本。

¥Only supported on iOS 26 and above.

`lazy`

此屏幕是否应仅在首次访问后渲染。默认为 true。如果你想在导航器的初始渲染上渲染屏幕，请将其设置为 false。

¥Whether this screen should render only after the first time it's accessed. Defaults to true. Set it to false if you want to render the screen on the initial render of the navigator.

`popToTopOnBlur`

布尔值，表示离开此选项卡时是否应将任何嵌套堆栈弹出到堆栈顶部。默认为 false。

¥Boolean indicating whether any nested stack should be popped to the top of the stack when navigating away from this tab. Defaults to false.

它仅在选项卡导航器下嵌套有堆栈导航器（例如堆栈导航器或原生堆栈导航器）时才有效。

¥It only works when there is a stack navigator (e.g. stack navigator or native stack navigator) nested under the tab navigator.

¥Header related options

导航器默认不显示标题栏。如果在屏幕选项中显式地将 headerShown 设置为 true，或者使用 header 选项提供了自定义标题，则会渲染原生堆栈标题。与头部相关的选项需要显示头部。

¥The navigator does not show a header by default. It renders a native stack header if headerShown is set to true in the screen options explicitly, or if a custom header is provided with the header option. Header related options require a header to be shown.

它支持 @react-navigation/native-stack 中支持的标头相关选项的大部分功能，但与返回按钮相关的选项（以 headerBack 为前缀）除外。

¥It supports most of the header related options supported in @react-navigation/native-stack apart from the options related to the back button (prefixed with headerBack).

活动

¥Events

导航器可以对某些操作进行触发事件。支持的事件有：

¥The navigator can emit events on certain actions. Supported events are:

`tabPress`

当用户按下选项卡栏中当前屏幕的选项卡按钮时会触发此事件。默认情况下，按 Tab 键会执行以下几项操作：

¥This event is fired when the user presses the tab button for the current screen in the tab bar. By default a tab press does several things:

如果选项卡未获得焦点，按下选项卡将使该选项卡获得焦点

¥If the tab is not focused, tab press will focus that tab
如果该选项卡已获得焦点：

¥If the tab is already focused:
- 如果选项卡的屏幕渲染滚动视图，你可以使用 useScrollToTop 将其滚动到顶部
  
  ¥If the screen for the tab renders a scroll view, you can use useScrollToTop to scroll it to top
- 如果选项卡的屏幕渲染堆栈导航器，则会在堆栈上执行 popToTop 操作
  
  ¥If the screen for the tab renders a stack navigator, a popToTop action is performed on the stack

Tab 键按下的默认行为由 React 原生控制，无法阻止。

¥The default behavior of the tab press is controlled natively and cannot be prevented.

React.useEffect(() => {
  const unsubscribe = navigation.addListener('tabPress', (e) => {
    // Do something manually
    // ...
  });

  return unsubscribe;
}, [navigation]);

`transitionStart`

当前屏幕的过渡动画开始时会触发此事件。

¥This event is fired when the transition animation starts for the current screen.

示例：

¥Example:

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionStart', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

`transitionEnd`

当前屏幕的过渡动画结束时会触发此事件。

¥This event is fired when the transition animation ends for the current screen.

示例：

¥Example:

React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionEnd', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);

帮手

¥Helpers

选项卡导航器向导航对象添加以下方法：

¥The tab navigator adds the following methods to the navigation object:

`jumpTo`

导航到选项卡导航器中的现有屏幕。该方法接受以下参数：

¥Navigates to an existing screen in the tab navigator. The method accepts following arguments:

name - string - 要跳转到的路由名称。

¥name - string - Name of the route to jump to.
params - object - 用于目标路由的屏幕参数。

¥params - object - Screen params to use for the destination route.

navigation.jumpTo('Profile', { owner: 'Michaś' });

安装​

用法​

备注​

API 定义​

属性​

backBehavior​

选项​

title​

tabBarSystemItem​

iOS 26+ 上的搜索标签页​

tabBarLabel​

tabBarLabelVisibilityMode​

tabBarLabelStyle​

tabBarIcon​

tabBarBadge​

tabBarBadgeStyle​

tabBarActiveTintColor​

tabBarInactiveTintColor​

tabBarActiveIndicatorColor​

tabBarActiveIndicatorEnabled​

tabBarRippleColor​

tabBarStyle​

tabBarBlurEffect​

tabBarControllerMode​

tabBarMinimizeBehavior​

lazy​

popToTopOnBlur​

标题相关选项​

活动​

tabPress​

transitionStart​

transitionEnd​

帮手​

jumpTo​

安装

用法

备注

API 定义

属性

`backBehavior`

选项

`title`

`tabBarSystemItem`

iOS 26+ 上的搜索标签页

`tabBarLabel`

`tabBarLabelVisibilityMode`

`tabBarLabelStyle`

`tabBarIcon`

`tabBarBadge`

`tabBarBadgeStyle`

`tabBarActiveTintColor`

`tabBarInactiveTintColor`

`tabBarActiveIndicatorColor`

`tabBarActiveIndicatorEnabled`

`tabBarRippleColor`

`tabBarStyle`

`tabBarBlurEffect`

`tabBarControllerMode`

`tabBarMinimizeBehavior`

`lazy`

`popToTopOnBlur`

标题相关选项

活动

`tabPress`

`transitionStart`

`transitionEnd`

帮手

`jumpTo`