中文网
🌐 Nodejs.cn
首页指南EAS参考教程

Expo 路由原生标签页

一个 Expo Router 子模块，提供原生标签页布局。

Android
iOS
tvOS
Web
Included in Expo Go
Bundled version:
~55.0.5

重要 Native tabs 是一个 alpha 功能，可在 SDK 54 及更高版本中使用，其 API 可能会发生变化。

expo-router/unstable-native-tabs 是 expo-router 的一个子模块，导出组件以使用平台原生系统标签来构建标签布局。

有关本地和 Web 应用的基于文件的路由库的更多信息，请参阅 Expo Router 参考资料。

安装

🌐 Installation

要在你的项目中使用 expo-router/unstable-native-tabs，你需要在项目中安装 expo-router。请按照 Expo Router 的安装指南中的说明操作：

🌐 To use expo-router/unstable-native-tabs in your project, you need to install expo-router in your project. Follow the instructions from Expo Router's installation guide:

安装 Expo 路由

了解如何在项目中安装 Expo Router。

应用配置中的配置

🌐 Configuration in app config

如果你使用 default 模板创建新项目，expo-router 的 配置插件 已经在你的应用配置中设置好了。

🌐 If you are using the default template to create a new project, expo-router's config plugin is already configured in your app config.

Example app.json with config plugin

app.json
{
  "expo": {
    "plugins": ["expo-router"]
  }
}

用法

🌐 Usage

要了解如何使用原生标签页和 Expo Router，请阅读原生标签页指南：

🌐 To learn how to use native tabs, with Expo Router, read the native tabs guide:

原生标签页

了解如何在你的 Expo Router 应用中使用原生标签页。

应用接口

🌐 API

import { NativeTabs } from 'expo-router/unstable-native-tabs';

Components

NativeTabs

Android
iOS
tvOS
Web

Type: React.Element<NativeTabsProps>

The component used to create native tabs layout.

Example

app/_layout.tsx
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function Layout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="home" />
      <NativeTabs.Trigger name="settings" />
    </NativeTabs>
  );
}

NativeTabsProps

backBehavior

Android
Optional • Literal type: string

The behavior when navigating back with the back button.

Acceptable values are: 'history' | 'none' | 'initialRoute'

backgroundColor

Android
iOS
tvOS
Web
Optional • Type: ColorValue

The background color of the tab bar.

badgeBackgroundColor

Android
iOS
tvOS
Web
Optional • Type: ColorValue

The background color of every badge in the tab bar.

badgeTextColor

Android
Web
Optional • Type: ColorValue

The color of the badge text.

blurEffect

iOS
Optional • Literal type: string

The blur effect applied to the tab bar.

Acceptable values are: 'light' | 'dark' | 'none' | 'extraLight' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark' | 'systemDefault'

disableIndicator

Android
Optional • Type: boolean

Disables the active indicator for the tab bar.

disableTransparentOnScrollEdge

iOS
Optional • Type: boolean

When set to true, the tab bar will not become transparent when scrolled to the edge.

hidden

Android
iOS
tvOS
Web
Optional • Type: boolean • Default: false

When set to true, hides the tab bar.

iconColor

Android
iOS
tvOS
Web
Optional • Literal type: union

The color of every tab icon in the tab bar.

Acceptable values are: ColorValue | { default: ColorValue | undefined, selected: ColorValue | undefined }

indicatorColor

Android
Web
Optional • Type: ColorValue

The color of the tab indicator.

labelStyle

Android
iOS
tvOS
Web
Optional • Literal type: union

The style of the every tab label in the tab bar.

Acceptable values are: StyleProp<NativeTabsLabelStyle> | { default: StyleProp<NativeTabsLabelStyle>, selected: StyleProp<NativeTabsLabelStyle> }

labelVisibilityMode

Android
Optional • Literal type: string

The visibility mode of the tab item label.

See: Material Components documentation

Acceptable values are: 'auto' | 'selected' | 'labeled' | 'unlabeled'

minimizeBehavior

iOS 26+
Optional • Literal type: string • Default: automatic

Specifies the minimize behavior for the tab bar.

Available starting from iOS 26.

The following values are currently supported:

  • automatic - resolves to the system default minimize behavior
  • never - the tab bar does not minimize
  • onScrollDown - the tab bar minimizes when scrolling down and expands when scrolling back up
  • onScrollUp - the tab bar minimizes when scrolling up and expands when scrolling back down

See: The supported values correspond to the official Apple documentation.

Acceptable values are: 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp'

rippleColor

Android
Optional • Type: ColorValue

The color of the ripple effect when the tab is pressed.

screenListeners

Android
iOS
tvOS
Web
Optional • Literal type: union

Listeners for navigation events on all tabs.

Supported events:

  • tabPress - called when a tab is pressed
  • focus - called when the screen comes into focus
  • blur - called when the screen loses focus

Example

<NativeTabs
  screenListeners={{
    tabPress: (e) => {
      console.log('Any tab pressed');
    },
  }}
>
  ...
</NativeTabs>

Acceptable values are: (prop: { route: RouteProp<ParamListBase, string> }) => ScreenListeners<TabNavigationState<ParamListBase>, NativeTabNavigationEventMap> | Partial<{ tabPress: EventListenerCallback<NativeTabNavigationEventMap & EventMapCore<TabNavigationState<ParamListBase>>, 'tabPress', false> }>

shadowColor

iOS
Optional • Type: ColorValue

The color of the shadow.

See: Apple documentation

sidebarAdaptable

iOS 18+
Optional • Type: boolean

When set to true, enables the sidebarAdaptable tab bar style on iPadOS and macOS. This prop has no effect on iPhone.

tintColor

Android
iOS
tvOS
Web
Optional • Type: ColorValue

The tint color of the tab icon.

Can be overridden by icon color and label color for each tab individually.

titlePositionAdjustment

iOS
Optional • Type: { horizontal: number, vertical: number }

Inherited Props

  • PropsWithChildren

NativeTabs.Trigger

Android
iOS
tvOS
Web

Type: React.Element<NativeTabTriggerProps>

The component used to customize the native tab options both in the _layout file and from the tab screen.

When used in the _layout file, you need to provide a name prop. When used in the tab screen, the name prop takes no effect.

Example

app/_layout.tsx
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function Layout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="home" />
      <NativeTabs.Trigger name="settings" />
    </NativeTabs>
  );
}

Example

app/home.tsx
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function HomeScreen() {
  return (
    <View>
      <NativeTabs.Trigger>
        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
      </NativeTabs.Trigger>
      <Text>This is home screen!</Text>
    </View>
  );
}

NativeTabTriggerProps

children

Android
iOS
tvOS
Web
Optional • Type: ReactNode

The children of the trigger.

Use Icon, Label, and Badge components to customize the tab.

contentStyle

Android
iOS
tvOS
Web
Optional • Type: Pick<ViewStyle, 'backgroundColor' | 'experimental_backgroundImage' | 'alignContent' | 'alignItems' | 'flexDirection' | 'gap' | 'justifyContent' | 'padding' | 'paddingBottom' | 'paddingEnd' | 'paddingHorizontal' | 'paddingLeft' | 'paddingRight' | 'paddingStart' | 'paddingTop' | 'paddingVertical' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'>

The style applied to the content of the tab

Note: Only certain style properties are supported.

disableAutomaticContentInsets

Android
iOS
Optional • Type: boolean

The default behavior differs between iOS and Android.

On Android, the content of a native tabs screen is automatically wrapped in a SafeAreaView, and the bottom inset is applied. Other insets must be handled manually.

On iOS, the first scroll view nested inside a native tabs screen has automatic content inset adjustment enabled

When this property is set to true, automatic content inset adjustment is disabled for the screen and must be managed manually. You can use SafeAreaView from react-native-screens/experimental to handle safe area insets.

disablePopToTop

iOS
Optional • Type: boolean • Default: false

If true, the tab will not pop stack to the root when selected again.

disableScrollToTop

iOS
Optional • Type: boolean • Default: false

If true, the tab will not scroll to the top when selected again.

disableTransparentOnScrollEdge

iOS
Optional • Type: boolean

When set to true, the tab bar will not become transparent when scrolled to the edge.

When set on a trigger, it takes precedence over the value set on NativeTabs.

hidden

Android
iOS
tvOS
Web
Optional • Type: boolean

If true, the tab will be hidden from the tab bar.

Note: Marking a tab as hidden means it cannot be navigated to in any way.

Note: Dynamically hiding tabs will remount the navigator and the state will be reset.

listeners

Android
iOS
tvOS
Web
Optional • Literal type: union

Listeners for navigation events on this tab.

Supported events:

  • tabPress - called when this tab is pressed
  • focus - called when this screen comes into focus
  • blur - called when this screen loses focus

Example

<NativeTabs.Trigger
  name="home"
  listeners={{
    tabPress: (e) => {
      console.log('Home tab pressed');
    },
  }}
/>

Acceptable values are: Partial<undefined> | (prop: { route: RouteProp<ParamListBase, string> }) => ScreenListeners<NavigationState, EventMapBase>

name

Android
iOS
tvOS
Web
Optional • Type: string

The name of the route.

This is required when used inside a Layout component.

When used in a route it has no effect.

role

iOS
Optional • Literal type: string

System-provided tab bar item with predefined icon and title

Uses Apple's built-in tab bar items (e.g., bookmarks, contacts, downloads) with standard iOS styling and localized titles. Custom icon or selectedIcon properties will override the system icon, but the system-defined title cannot be customized.

See: The supported values correspond to the official Apple documentation.

Acceptable values are: 'search' | 'history' | 'bookmarks' | 'contacts' | 'downloads' | 'favorites' | 'featured' | 'more' | 'mostRecent' | 'mostViewed' | 'recents' | 'topRated'

unstable_nativeProps

Android
iOS
Optional • Type: Partial<Omit<TabsScreenProps, 'isFocused' | 'tabKey'>>

Props passed to the underlying native tab screen implementation. Use this to configure props not directly exposed by Expo Router, but available in react-native-screens.

Note: This will override any other props set by Expo Router and may lead to unexpected behavior.

Note: This is an unstable API and may change or be removed in minor versions.

NativeTabs.BottomAccessory

Android
iOS
tvOS
Web

Type: React.Element<FC<NativeTabsBottomAccessoryProps> & { usePlacement: () => 'regular' | 'inline' }>

NativeTabsBottomAccessoryProps

children

Android
iOS
tvOS
Web
Optional • Type: ReactNode

NativeTabs.Trigger.Badge

Android
iOS
tvOS
Web

Type: React.Element<FC<NativeTabsTriggerBadgeProps>>

NativeTabsTriggerBadgeProps

children

Android
iOS
tvOS
Web
Optional • Type: string

The text to display as the badge for the tab. If not provided, the badge will not be displayed.

hidden

Android
iOS
tvOS
Web
Optional • Type: boolean • Default: false

If true, the badge will be hidden.

selectedBackgroundColor

Android
iOS
tvOS
Web
Optional • Type: ColorValue

NativeTabs.Trigger.Icon

Android
iOS
tvOS
Web

Type: React.Element<FC<NativeTabsTriggerIconProps>>

NativeTabsTriggerIconProps

Inherited Props

NativeTabs.Trigger.Label

Android
iOS
tvOS
Web

Type: React.Element<FC<NativeTabsTriggerLabelProps>>

NativeTabsTriggerLabelProps

children

Android
iOS
tvOS
Web
Optional • Type: string

The text to display as the label for the tab.

hidden

Android
iOS
tvOS
Web
Optional • Type: boolean • Default: false

If true, the label will be hidden.

selectedStyle

Android
iOS
tvOS
Web
Optional • Type: StyleProp<NativeTabsLabelStyle>

NativeTabs.Trigger.VectorIcon

Android
iOS
tvOS
Web

Type: React.Element<VectorIconProps<NameT>>

Helper component for loading vector icons.

Prefer using the md and sf props on Icon rather than using this component directly. Only use this component when you need to load a specific icon from a vector icon family.

Example

import { Icon, VectorIcon } from 'expo-router';
import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';

<Icon src={<VectorIcon family={MaterialCommunityIcons} name="home" />} />

Interfaces

DrawableIcon

Android
iOS
tvOS
Web
PropertyTypeDescription
drawable(optional)string
Only for: 
Android

The name of the drawable resource to use as an icon.

MaterialIcon

Android

Material icon name for Android native tabs.

PropertyTypeDescription
mdSee description for available values.

Material icon glyph name. See the Material icons for the complete catalog.

SFSymbolIcon

Android
iOS
tvOS
Web
PropertyTypeDescription
sf(optional)SFSymbols7_0 | { default: SFSymbols7_0 | undefined, selected: SFSymbols7_0 }
Only for: 
iOS

The name of the SF Symbol to use as an icon.

The value can be provided in two ways:

  • As a string with the SF Symbol name
  • As an object specifying the default and selected states

Example

<Icon sf="magnifyingglass" />

Example

<Icon sf={{ default: "house", selected: "house.fill" }} />

SrcIcon

Android
iOS
tvOS
Web
PropertyTypeDescription
renderingMode(optional)'template' | 'original'
Only for: 
iOS

Controls how the image icon is rendered on iOS.

  • 'template': iOS applies tint color to the icon (selected/unselected states)
  • 'original': Preserves original icon colors

Default behavior:

  • If tab bar icon color is configured, defaults to 'template'
  • If no icon color is set, defaults to 'original'

See: Apple documentation for more information.

src(optional)ReactElement<unknown, string | JSXElementConstructor<any>> | ImageSourcePropType | { default: ReactElement<unknown, string | JSXElementConstructor<any>> | ImageSourcePropType | undefined, selected: ReactElement<unknown, string | JSXElementConstructor<any>> | ImageSourcePropType }
Only for: 
Android
iOS

The image source to use as an icon.

When sf prop is used it will override this prop on iOS.

When drawable or material prop is used it will override this prop on Android.

The value can be provided in two ways:

  • As an image source
  • As an object specifying the default and selected states

Example

<Icon src={require('./path/to/icon.png')} />

Example

<Icon src={{ default: require('./path/to/icon.png'), selected: require('./path/to/icon-selected.png') }} />

XcassetIcon

Android
iOS
tvOS
Web
PropertyTypeDescription
xcasset(optional)string | { default: string, selected: string }
Only for: 
iOS

The name of the iOS asset catalog image to use as an icon.

Xcassets provide automatic multi-resolution (@1x/@2x/@3x), dark mode variants, and device-specific images via [UIImage imageNamed:].

The rendering mode (template vs original) can be controlled via the renderingMode prop on the Icon component. By default, icons are tinted when iconColor is set, and rendered as original otherwise.

The value can be provided in two ways:

  • As a string with the asset catalog image name
  • As an object specifying the default and selected states

Example

<Icon xcasset="custom-icon" />

Example

<Icon xcasset={{ default: "home-outline", selected: "home-filled" }} />

Types

NativeTabsLabelStyle

Android
iOS
tvOS
Web

Type: Pick<TextStyle, 'fontFamily' | 'fontSize' | 'fontStyle' | 'fontWeight' | 'color'>

SymbolOrImageSource

Android
iOS
tvOS
Web

Type: object shaped as below:

PropertyTypeDescription
drawable(optional)string
Only for: 
Android

The name of the drawable resource to use as an icon.

sf(optional)SFSymbol
Only for: 
iOS

The name of the SF Symbol to use as an icon.

xcasset(optional)string
Only for: 
iOS

The name of the iOS asset catalog image to use as an icon.

Or object shaped as below:

PropertyTypeDescription
renderingMode(optional)'template' | 'original'
Only for: 
iOS

Controls how the icon is rendered on iOS.

Default:'template'
src(optional)ImageSourcePropType | Promise<ImageSourcePropType | null>

The image source to use as an icon.