This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 路由器原生标签页
一个提供原生标签页布局的 Expo Router 子模块。
重要 原生标签页是一项 alpha 功能，适用于 SDK 54 及更高版本，其 API 可能会发生变化。
expo-router/unstable-native-tabs 是 expo-router 的一个子模块，导出用于使用平台原生系统标签页构建标签页布局的组件。
有关适用于原生和 Web 应用的基于文件路由库的更多信息，请参阅 Expo Router 参考文档。
安装
要在你的项目中使用 expo-router/unstable-native-tabs，你需要先在项目中安装 expo-router。请按照 Expo Router 的安装指南操作：
了解如何在你的项目中安装 Expo Router。
在 app 配置中进行配置
如果你使用 默认 模板创建新项目，expo-router 的 配置插件 已经在你的 app 配置中完成配置。
Example app.json with config plugin
用法
要了解如何在 Expo Router 中使用原生标签页，请阅读原生标签页指南：
了解如何在你的 Expo Router 应用中使用原生标签页。
API
import { NativeTabs, Icon, Label, Badge, VectorIcon } from 'expo-router/unstable-native-tabs';
Components
Type: React.Element<BadgeProps>
stringThe text to display as the badge for the tab. If not provided, the badge will not be displayed.
ColorValueType: React.Element<LabelProps>
NativeTabsLabelStyleType: React.Element<NativeTabsProps>
The component used to create native tabs layout.
Example
// In _layout file import { NativeTabs } from 'expo-router/unstable-native-tabs'; export default function Layout() { return ( <NativeTabs> <NativeTabs.Trigger name="home" /> <NativeTabs.Trigger name="settings" /> </NativeTabs> ); }
stringThe behavior when navigating back with the back button.
Acceptable values are: 'history' | 'none' | 'initialRoute'
unionThe background color of the tab bar.
Acceptable values are: null | ColorValue
ColorValueThe background color of every badge in the tab bar.
stringThe blur effect applied to the tab bar.
Acceptable values are: 'none' | 'systemDefault' | 'extraLight' | 'light' | 'dark' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark'
booleanWhen set to true, the tab bar will not become transparent when scrolled to the edge.
unionThe color of every tab icon in the tab bar.
Acceptable values are: ColorValue | {
default: ColorValue | undefined,
selected: ColorValue | undefined
}
unionThe style of the every tab label in the tab bar.
Acceptable values are: NativeTabsLabelStyle | {
default: NativeTabsLabelStyle,
selected: NativeTabsLabelStyle
}
stringThe visibility mode of the tab item label.
Acceptable values are: 'auto' | 'selected' | 'labeled' | 'unlabeled'
string • Default: automaticSpecifies 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 behaviornever- the tab bar does not minimizeonScrollDown- the tab bar minimizes when scrolling down and expands when scrolling back uponScrollUp- the tab bar minimizes when scrolling up and expands when scrolling back down
See: The supported values correspond to the official UIKit documentation.
Acceptable values are: 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp'
ColorValueThe color of the ripple effect when the tab is pressed.
ColorValueThe tint color of the tab icon.
Can be overridden by icon color and label color for each tab individually.
{
horizontal: number,
vertical: number
}See: Apple documentation
Type: React.Element<NativeTabsTriggerTabBarProps>
The component used to customize the style of the tab bar, when given trigger is selected.
Prefer this to global changes of tab bar styles, directly in the page.
Note: You can use the alias
NativeTabs.Trigger.TabBarfor this component.
Example
<NativeTabs backgroundColor="black" > <NativeTabs.Trigger name="page"> <NativeTabs.Trigger.TabBar backgroundColor="white" /> <Label>Page</Label> </NativeTabs.Trigger> </NativeTabs>
ColorValueThe background color of the tab bar, when the tab is selected
ColorValueThe background color of every badge in the tab bar.
stringThe blur effect applied to the tab bar, when the tab is selected
Acceptable values are: 'none' | 'systemDefault' | 'extraLight' | 'light' | 'dark' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark'
booleanWhen set to true, the tab bar will not become transparent when scrolled to the edge.
NativeTabsLabelStyleThe style of the every tab label in the tab bar.
ColorValueThe color of the shadow when the tab is selected.
See: Apple documentation
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
// In _layout file import { NativeTabs } from 'expo-router/unstable-native-tabs'; export default function Layout() { return ( <NativeTabs> <NativeTabs.Trigger name="home" /> <NativeTabs.Trigger name="settings" /> </NativeTabs> ); }
Example
// In a tab screen import { NativeTabs } from 'expo-router/unstable-native-tabs'; export default function HomeScreen() { return ( <View> <NativeTabs.Trigger> <Label>Home</Label> </NativeTabs.Trigger> <Text>This is home screen!</Text> </View> ); }
Note: You can use the alias
NativeTabs.Triggerfor this component.
ReactNodeThe children of the trigger.
Use Icon, Label, and Badge components to customize the tab.
boolean • Default: falseIf true, the tab will not pop stack to the root when selected again.
boolean • Default: falseIf true, the tab will not scroll to the top when selected again.
stringThe name of the route.
This is required when used inside a Layout component.
When used in a route it has no effect.
NativeTabOptionsThe options for the trigger.
Use Icon, Label, and Badge components as children to customize the tab, rather then raw options.
stringSystem-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.
Acceptable values are: 'search' | 'history' | 'bookmarks' | 'contacts' | 'downloads' | 'favorites' | 'featured' | 'more' | 'mostRecent' | 'mostViewed' | 'recents' | 'topRated'
Type: React.Element<VectorIconProps<NameT>>
Helper component which can be used to load vector icons for NativeTabs.
Example
import { NativeTabs, VectorIcon } from 'expo-router'; import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons'; export default Layout(){ return ( <NativeTabs> <NativeTabs.Trigger name="index"> <Icon src={<VectorIcon family={MaterialCommunityIcons} name="home" />} /> </NativeTabs.Trigger> </NativeTabs> ); }
{
getImageSource: (name: NameT, size: number, color: ColorValue) => Promise<null | ImageSourcePropType>
}The family of the vector icon.
Example
import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';