Expo 路由器 UI

一个 Expo Router 子模块，提供无头选项卡组件以创建自定义选项卡布局。

Android

iOS

tvOS

Web

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.0

expo-router/ui 是 expo-router 库的一个子模块，它导出用于构建自定义标签页布局的组件和 hooks，而不是使用 expo-router 提供的默认 React Navigation 导航器。

有关适用于原生和 Web 应用的基于文件的路由库的更多信息，请参阅 Expo Router 参考文档。

安装

要在你的项目中使用 expo-router/ui，你需要先在项目中安装 expo-router。请按照 Expo Router 的安装指南进行操作：

安装 Expo Router

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

应用配置中的配置

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

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": ["expo-router"]
  }
}

用法

有关在自定义标签布局指南中使用 expo-router/ui 的信息：

自定义标签布局

API

import { Tabs, TabList, TabTrigger, TabSlot } from 'expo-router/ui';

Components

`TabContext`

Type: React.Element<Context<ExpoTabsNavigatorScreenOptions>>

`TabList`

Type: React.Element<TabListProps>

Wrapper component for TabTriggers. TabTriggers within the TabList define the tabs.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabListProps

`asChild`

Optional • Type: boolean

Forward props to child component and removes the extra <View>. Useful for custom wrappers.

Inherited props

ViewProps

`Tabs`

Type: React.Element<TabsProps>

Root component for the headless tabs.

See: useTabsWithChildren for a hook version of this component.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabsProps

`asChild`

Optional • Type: boolean

Forward props to child component and removes the extra <View>. Useful for custom wrappers.

`options`

Optional • Type: UseTabsOptions

Inherited props

ViewProps

`TabSlot`

Type: React.Element<TabSlotProps>

Renders the current tab.

See: useTabSlot for a hook version of this component.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabSlotProps

`detachInactiveScreens`

Optional • Type: boolean

Remove inactive screens.

`renderFn`

Optional • Type: defaultTabsSlotRender

Override how the Screen component is rendered.

Inherited props

ComponentProps<ScreenContainer>

`TabTrigger`

Type: React.Element<TabTriggerProps>

Creates a trigger to navigate to a tab. When used as child of TabList, its functionality slightly changes since the href prop is required, and the trigger also defines what routes are present in the Tabs.

When used outside of TabList, this component no longer requires an href.

Example

<Tabs>
 <TabSlot />
 <TabList>
  <TabTrigger name="home" href="/" />
 </TabList>
</Tabs>

TabTriggerProps

`asChild`

Optional • Type: boolean

Forward props to child component. Useful for custom wrappers.

`href`

Optional • Type: Href

Name of tab. Required when used within a TabList.

`name`

Type: string

Name of tab. When used within a TabList this sets the name of the tab. Otherwise, this references the name.

`resetOnFocus`

Optional • Type: boolean

Resets the route when switching to a tab.

Inherited props

PressablePropsWithoutFunctionChildren

`useTabSlot`

Type: React.Element<TabSlotProps>

Returns a ReactElement of the current tab.

Example

function MyTabSlot() {
  const slot = useTabSlot();

  return slot;
}

Hooks

`useTabSlot(namedParameters)`

Parameter	Type
namedParameters(optional)	`TabSlotProps`

Returns a ReactElement of the current tab.

Returns:

Element

Example

function MyTabSlot() {
  const slot = useTabSlot();

  return slot;
}

`useTabsWithChildren(options)`

Parameter	Type
options	`UseTabsWithChildrenOptions`

Hook version of Tabs. The returned NavigationContent component should be rendered. Using the hook requires using the <TabList /> and <TabTrigger /> components exported from Expo Router.

The useTabsWithTriggers() hook can be used for custom components.

Returns:

{
  describe: (route: RouteProp<ParamListBase>, placeholder: boolean) => Descriptor<ExpoTabsNavigatorScreenOptions, Omit<NavigationHelpersCommon<ParamListBase, TabNavigationState<any>>, 'getParent'> & {
} & NavigationHelpersRoute<ParamListBase, string> & EventConsumer<TabNavigationEventMap & EventMapCore<TabNavigationState<any>>> & PrivateValueStore<[ParamListBase, string, TabNavigationEventMap]> & TabActionHelpers<ParamListBase>, RouteProp<ParamListBase>>, 
  descriptors: Record<string, Descriptor<ExpoTabsNavigatorScreenOptions, Omit<NavigationHelpersCommon<ParamListBase, TabNavigationState<any>>, 'getParent'> & {
} & NavigationHelpersRoute<ParamListBase, string> & EventConsumer<TabNavigationEventMap & EventMapCore<TabNavigationState<any>>> & PrivateValueStore<[ParamListBase, string, TabNavigationEventMap]> & TabActionHelpers<ParamListBase>, RouteProp<ParamListBase>>>, 
  navigation: {
} & PrivateValueStore<[ParamListBase, unknown, unknown]> & EventEmitter<TabNavigationEventMap> & NavigationHelpersRoute<ParamListBase, string> & TabActionHelpers<ParamListBase>, 
  NavigationContent: (__namedParameters: {
  children: ReactNode
}) => Element, 
  state: TabNavigationState<any>
}

See: Tabs for the component version of this hook.

Example

export function MyTabs({ children }) {
 const { NavigationContent } = useTabsWithChildren({ children })

 return <NavigationContent />
}

`useTabsWithTriggers(options)`

Parameter	Type
options	`UseTabsWithTriggersOptions`

Alternative hook version of Tabs that uses explicit triggers instead of children.

Returns:

{
  describe: (route: RouteProp<ParamListBase>, placeholder: boolean) => Descriptor<ExpoTabsNavigatorScreenOptions, Omit<NavigationHelpersCommon<ParamListBase, TabNavigationState<any>>, 'getParent'> & {
} & NavigationHelpersRoute<ParamListBase, string> & EventConsumer<TabNavigationEventMap & EventMapCore<TabNavigationState<any>>> & PrivateValueStore<[ParamListBase, string, TabNavigationEventMap]> & TabActionHelpers<ParamListBase>, RouteProp<ParamListBase>>, 
  descriptors: Record<string, Descriptor<ExpoTabsNavigatorScreenOptions, Omit<NavigationHelpersCommon<ParamListBase, TabNavigationState<any>>, 'getParent'> & {
} & NavigationHelpersRoute<ParamListBase, string> & EventConsumer<TabNavigationEventMap & EventMapCore<TabNavigationState<any>>> & PrivateValueStore<[ParamListBase, string, TabNavigationEventMap]> & TabActionHelpers<ParamListBase>, RouteProp<ParamListBase>>>, 
  navigation: {
} & PrivateValueStore<[ParamListBase, unknown, unknown]> & EventEmitter<TabNavigationEventMap> & NavigationHelpersRoute<ParamListBase, string> & TabActionHelpers<ParamListBase>, 
  NavigationContent: (__namedParameters: {
  children: ReactNode
}) => Element, 
  state: TabNavigationState<any>
}

See: Tabs for the component version of this hook.

Example

export function MyTabs({ children }) {
  const { NavigationContent } = useTabsWithChildren({ triggers: [] })

  return <NavigationContent />
}

`useTabTrigger(options)`

Parameter	Type
options	`TabTriggerProps`

Utility hook creating custom TabTrigger.

Returns:

UseTabTriggerResult

Types

`ExpoTabsNavigationProp`

Type: NavigationProp<ParamList, RouteName, NavigatorID, TabNavigationState<ParamListBase>, ExpoTabsScreenOptions, TabNavigationEventMap>

`ExpoTabsNavigatorOptions`

Literal type: union

Acceptable values are: DefaultNavigatorOptions<ParamListBase, string | undefined, TabNavigationState<ParamListBase>, ExpoTabsScreenOptions, TabNavigationEventMap, ExpoTabsNavigationProp<ParamListBase>> | Omit<TabRouterOptions, 'initialRouteName'> | ExpoTabsNavigatorScreenOptions

`ExpoTabsNavigatorScreenOptions`

Property	Type	Description
detachInactiveScreens(optional)	`boolean`	-
freezeOnBlur(optional)	`boolean`	-
lazy(optional)	`boolean`	-
unmountOnBlur(optional)	`boolean`	-

`ExpoTabsScreenOptions`

Type: Pick<BottomTabNavigationOptions, 'title' | 'lazy' | 'freezeOnBlur'> extended by:

Property	Type	Description
action	`NavigationAction`	-
params(optional)	`object`	-
title	`string`	-

`SwitchToOptions`

Options for switchTab function.

Property	Type	Description
resetOnFocus(optional)	`boolean`	Navigate and reset the history on route focus.

`TabNavigationEventMap`

Property	Type	Description
tabLongPress	`{ data: undefined }`	Event which fires on long press on the tab in the tab bar.
tabPress	`{ canPreventDefault: true, data: undefined }`	Event which fires on tapping on the tab in the tab bar.

`TabsContextValue`

Type: ReturnType<useNavigationBuilder>

The React Navigation custom navigator.

See: useNavigationBuilder hook from React Navigation for more information.

`TabsSlotRenderOptions`

Options provided to the UseTabSlotOptions.

Property	Type	Description
detachInactiveScreens	`boolean`	Should the screen be unloaded when inactive.
index	`number`	Index of screen.
isFocused	`boolean`	Whether the screen is focused.
loaded	`boolean`	Whether the screen has been loaded.

`TabTriggerOptions`

Property	Type	Description
href	`Href`	-
name	`string`	-

`Trigger`

Type: extended by:

Property	Type	Description
isFocused	`boolean`	-
resolvedHref	`string`	-
route	`[number]`	-

`UseTabsOptions`

Options to provide to the Tab Router.

Type: Omit<DefaultNavigatorOptions<ParamListBase, any, TabNavigationState<any>, ExpoTabsScreenOptions, TabNavigationEventMap, any>, 'children'> extended by:

Property	Type	Description
backBehavior(optional)	`TabRouterOptions[backBehavior]`	-

`UseTabsWithChildrenOptions`

Type: PropsWithChildren<UseTabsOptions>

`UseTabsWithTriggersOptions`

Type: UseTabsOptions extended by:

Property	Type	Description
triggers	`ScreenTrigger[]`	-

`UseTabTriggerResult`

Property	Type	Description
getTrigger	`(name: string) => Trigger \| undefined`	-
switchTab	`(name: string, options: SwitchToOptions) => void`	-
trigger(optional)	`Trigger`	-
triggerProps	`TriggerProps`	-