自定义标签页布局

了解如何使用无头标签页组件在 Expo Router 中创建自定义标签页布局。

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

重要 这是一个实验性功能。

Expo Router 提供了一组组件，可通过子模块 expo-router/ui 创建自定义标签页布局。与 React Navigation 风格化的 Tabs 不同，这些组件没有样式且非常灵活。它们旨在让你在项目中从零开始构建复杂的 UI 模式。

有关其他标签页布局，请参见：

自定义 Tabs 组件的结构

expo-router/ui 提供了四个组件来创建自定义标签页布局：

一个最基本的自定义标签页布局结构应由 TabList（包含每个标签页的 TabTrigger 组件）和 TabSlot 组成，且都位于 Tabs 组件内，如下所示：

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

// 定义自定义标签导航器的布局
export default function Layout() {
  return (
    <Tabs>
      <TabSlot />
      <TabList>
        <TabTrigger name="home" href="/">
          <Text>主页</Text>
        </TabTrigger>
        <TabTrigger name="article" href="/article">
          <Text>文章</Text>
        </TabTrigger>
      </TabList>
    </Tabs>
  );
}

创建路由

TabList 包含标签导航器中可用的所有路由。它必须是 Tabs 的直接子组件。每条路由都由 TabList 内的一个 TabTrigger 定义。TabList 中的 TabTrigger 必须包含 name 和 href 属性。

通常，TabList 同时定义可用的标签页路由和标签页的外观，而每个 TabTrigger 的子组件则定义每个标签按钮的外观。

注意： name 可以是任意 string。这是为 Tab 自定义定义的名称。

动态路由

允许使用动态路由，并且可以通过 href 提供值。

触发器 <TabTrigger name="dynamic page" href="/hello-world" /> 将为 [slug].tsx 创建一个标签页，参数为 { slug: 'hello-world' }。这种设置对于根据最终用户数据在标签栏中显示任意数量的标签页很有用，例如为应用中的每个用户资料显示一个单独的标签页。

歧义路由

传递给 TabTrigger 的 href 值必须始终指向单一路由。在上面的共享路由示例中，不允许使用 href="/route"，因为它可能指向 /(one)/route 或 /(two)/route。不过，在 href 中指定路由组是可以的（例如，href="/(one)/route"）。

嵌套路由

TabTrigger 可以链接到深层嵌套路由。<TabTrigger name="route" href="/route" /> 将显示 (stack-one)/(stack-two)/route.tsx 路由。此标签页将由该路由的父导航器控制（也就是 stack-two_layout.tsx 中的导航器）。这种导航类似于深层链接。

渲染路由

TabSlot 组件会渲染当前路由。TabSlot 可以嵌套在 Tabs 内的其他组件中，但不能位于 TabList 中。

<Tabs>
  <TabList>
    <TabTrigger name="home" href="/">
      <Text>主页</Text>
    </TabTrigger>
  </TabList>
  {/* 自定义 `<TabSlot />` 的渲染方式。 */}
  <View>
    <View>
      <TabSlot />
    </View>
  </View>
</Tabs>

切换标签页

可以通过 Link 或使用命令式 API 来切换标签页。不过，这些 API 始终会执行导航操作（它们会切换标签页，并且可能更改 URL）。如果你想在不执行任何导航的情况下切换标签页，应使用 TabTrigger。TabTrigger 是一个无样式的 <View>，在按下时会切换标签页，类似于将文本和组件包裹在 Link 中以使其成为可点击的导航元素。

重置导航

TabTrigger 的 reset 属性可用于控制标签页何时重置其导航状态。可选值为 always、onLongPress 和 never。这对于嵌套在标签页内的堆栈导航器尤其有用。例如，<TabTrigger name="home" reset="always" /> 会将用户返回到标签页内嵌套堆栈导航器中的索引路由。

TabTrigger

TabTrigger 用于切换标签页，同时也承担着定义哪些路由可作为标签页使用的双重角色。

在 TabList 内

当 TabTrigger 作为 TabList 的子组件时，它定义了标签导航器中可用的路由。这些 TabTrigger 需要同时包含 name 和 href 属性，因为它们定义了该标签页的 URL，以及可用于引用该标签页的自定义名称。如果 TabTrigger 组件还包含文本或其他组件作为子元素，那么这些内容也会作为标签按钮渲染出来。不过，你也可以在 TabList 内定义没有任何 UI 的 TabTrigger，然后再由 TabList 外部的 TabTrigger 来触发它们。

在 TabList 外

可以在 TabList 外部定义一个额外的 TabTrigger，从而执行与 TabList 中定义的 TabTrigger 相同的操作。在这种情况下，TabTrigger 不会有 href 属性。相反，它会执行与具有相同 name 属性的主 TabTrigger 相同的操作。这样你就可以创建能够切换标签页、且不依赖当前导航状态的组件。请注意，所有 TabTrigger 至少需要是 Tabs 组件的后代，否则它们会被视为在标签导航器之外，无法触发它。

自定义外观

除 TabTrigger 会渲染为 <Pressable> 外，所有组件都会以无样式的 <View> 形式渲染。这使你可以通过自定义 style 属性来定制它们的外观。为 TabList 设置样式与在 React Navigation 中自定义标签栏类似，而为 TabTrigger 设置样式则会影响标签按钮的外观。

如果你需要更改某个组件的结构，可以通过使用 asChild 属性来覆盖其底层组件。此时该组件会充当一个插槽，并将其属性转发给紧邻的子组件。

<Tabs>
  <TabSlot />
  <TabList asChild>
    {/* 渲染一个自定义的 TabList */}
    <CustomTabList>
      <TabTrigger name="home" href="/">
        <Text>主页</Text>
      </TabTrigger>
    </CustomTabList>
  </TabList>
</Tabs>

<Tabs>
  <TabSlot />
  <TabList asChild>
    <TabTrigger name="home" href="/" asChild>
      {/* 渲染一个自定义按钮 */}
      <CustomButton>
        <Text>主页</Text>
      </CustomButton>
    </TabTrigger>
  </TabList>
</Tabs>

多个标签栏

TabList 既是 Tabs 的配置，也是其默认外观，但它并不是渲染标签栏的唯一方式。通过隐藏 TabList，你可以使用 TabTrigger 构建自定义标签栏。

<Tabs>
  <TabSlot />
  {/* 自定义标签栏 */}
  <View>
    <View>
      <TabTrigger name="home">
        <Text>主页</Text>
      </TabTrigger>
      <TabTrigger name="article">
        <Text>文章</Text>
      </TabTrigger>
    </View>
  </View>
  <TabList style={{ display: 'none' }}>
    <TabTrigger name="home" href="/">
      <Text>主页</Text>
    </TabTrigger>
    <TabTrigger name="article" href="/article">
      <Text>文章</Text>
    </TabTrigger>
  </TabList>
</Tabs>

TabTrigger 会传递一个 isFocused 属性，因此你可以创建一个单独的标签按钮组件来响应聚焦状态。

import FontAwesome from '@expo/vector-icons/FontAwesome';
import { TabTriggerSlotProps } from 'expo-router/ui';
import { ComponentProps, Ref } from 'react';
import { Text, Pressable, View } from 'react-native';

type Icon = ComponentProps<typeof FontAwesome>['name'];

export type TabButtonProps = TabTriggerSlotProps & {
  icon?: Icon;
  ref: Ref<View>;
};

export function TabButton({ icon, children, isFocused, ...props }: TabButtonProps) {
  return (
    <Pressable
      {...props}
      style={[
        {
          display: 'flex',
          justifyContent: 'space-between',
          alignItems: 'center',
          flexDirection: 'column',
          gap: 5,
          padding: 10,
        },
        isFocused ? { backgroundColor: 'white' } : undefined,
      ]}>
      <FontAwesome name={icon} />
      <Text style={[{ fontSize: 16 }, isFocused ? { color: 'white' } : undefined]}>{children}</Text>
    </Pressable>
  );
}

Hooks

所有组件也都有对应的 hook 版本，让你可以控制渲染树。有关可用 hooks 的完整列表，请参阅 Router UI Reference。

使用 hooks 被认为是该库的高级用法。对于大多数使用场景，使用带有 asChild 的组件应该已经足够让你控制渲染树。

如果你正在开发自定义的 <TabTrigger />，你可能还需要开发自定义的 <TabList />，因为 <TabList /> 使用了 useTabsWithChildren()，而这要求使用导出的 <TabTrigger /> 组件。

自定义标签页屏幕的渲染方式

TabSlot 接受一个 renderFn 属性。该函数可用于覆盖屏幕的渲染方式，使你能够实现动画或屏幕持久化/卸载等高级功能。有关更多信息，请参阅 Router UI Reference。

常见问题