标签页 (Tabs)

得益于 MDX和React功能，道格龙（Docusaurus）提供了可以在 Markdown 中使用的 <Tabs> 组件：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="苹果" default>
    这是一个苹果 🍎
  </TabItem>
  <TabItem value="orange" label="橘子">
    这是一个橘子 🍊
  </TabItem>
  <TabItem value="banana" label="香蕉">
    这是一个香蕉 🍌
  </TabItem>
</Tabs>

http://localhost:3000

苹果
橘子
香蕉

这是一个苹果 🍎

也可以向 Tabs 组件提供 values 和 defaultValue 属性(props)：

<Tabs
  defaultValue="apple"
  values={[
    {label: '苹果', value: 'apple'},
    {label: '橘子', value: 'orange'},
    {label: '香蕉', value: 'banana'},
  ]}>
  <TabItem value="apple">这是一个苹果 🍎</TabItem>
  <TabItem value="orange">这是一个橘子 🍊</TabItem>
  <TabItem value="banana">这是一个香蕉 🍌</TabItem>
</Tabs>

http://localhost:3000

苹果
橘子
香蕉

这是一个苹果 🍎

Tabs 组件的属性(props) 优先于 TabItem 的属性(props) ：

<Tabs
  defaultValue="apple"
  values={[
    {label: '苹果 1', value: 'apple'},
    {label: '橘子 1', value: 'orange'},
    {label: '香蕉 1', value: 'banana'},
  ]}>
  <TabItem value="apple" label="苹果 2">
    这是一个苹果 🍎
  </TabItem>
  <TabItem value="orange" label="橘子 2">
    这是一个橘子 🍊
  </TabItem>
  <TabItem value="banana" label="香蕉 2" default>
    这是一个香蕉 🍌
  </TabItem>
</Tabs>

http://localhost:3000

苹果 1
橘子 1
香蕉 1

这是一个苹果 🍎

提示

默认情况下，所有标签页在构建过程中都会被即时渲染（eagerly rendered），因此搜索引擎可以索引隐藏的标签页内容。

可以通过设置 <Tabs lazy /> 来实现惰性加载，即只渲染默认选中的标签页。

显示默认标签页

默认情况下，第一个标签页会被显示。要覆盖此行为，你可以通过向其中一个 TabItem 添加 default 属性来指定一个默认标签页。你也可以将 Tabs 组件的 defaultValue 属性设置为你选择的 value 值。例如，在上面的例子中，为 value="apple" 的标签页设置 default 属性，或者为 Tabs 组件设置 defaultValue="apple"，都会强制"苹果"标签页默认打开。

如果为 Tabs 组件提供了一个 defaultValue，但它指向一个不存在的 value，道格龙（Docusaurus）将会抛出一个错误。如果你希望默认不显示任何标签页，请使用 defaultValue={null}。

同步标签页选择

你可能希望同类型的标签页组之间的选择能够相互同步。例如，你可能想为 Windows 和 macOS 用户提供不同的操作指南，并希望一键切换所有与操作系统相关的指南标签页。要实现这一点，你可以给所有相关的 <Tabs> 组件一个相同的 groupId 属性。请注意，这样做会将选择持久化到 localStorage 中，所有具有相同 groupId 的 <Tabs> 实例在其中一个的值改变时都会自动更新。groupId 是全局命名空间的。

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">使用 Ctrl + C 复制。</TabItem>
  <TabItem value="mac" label="macOS">使用 Command + C 复制。</TabItem>
</Tabs>

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">使用 Ctrl + V 粘贴。</TabItem>
  <TabItem value="mac" label="macOS">使用 Command + V 粘贴。</TabItem>
</Tabs>

http://localhost:3000

Windows
macOS

使用 Ctrl + C 复制。

Windows
macOS

使用 Ctrl + V 粘贴。

对于所有具有相同 groupId 的标签页组，它们的 value 不必完全相同。如果一个标签页组选择了一个在另一个同 groupId 的标签页组中不存在的 value，那么缺少该 value 的标签页组将不会改变其当前选中的标签页。你可以从下面的例子中看到这一点。尝试选择 Linux，上面的标签页组不会改变。

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">
    我是 Windows。
  </TabItem>
  <TabItem value="mac" label="macOS">
    我是 macOS。
  </TabItem>
  <TabItem value="linux" label="Linux">
    我是 Linux。
  </TabItem>
</Tabs>

http://localhost:3000

Windows
macOS
Linux

我是 Windows。

具有不同 groupId 的标签页选择不会相互干扰：

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows in windows.</TabItem>
  <TabItem value="mac" label="macOS">macOS is macOS.</TabItem>
</Tabs>

<Tabs groupId="non-mac-operating-systems">
  <TabItem value="win" label="Windows">Windows is windows.</TabItem>
  <TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>

http://localhost:3000

Windows
macOS

Windows in windows.

Windows
Unix

Windows is windows.

自定义标签页

你可能想要自定义某一组标签页的外观。你可以通过 className 属性传递一个字符串，指定的 CSS 类将被添加到 Tabs 组件上：

<Tabs className="unique-tabs">
  <TabItem value="Apple">这是一个苹果 🍎</TabItem>
  <TabItem value="Orange">这是一个橘子 🍊</TabItem>
  <TabItem value="Banana">这是一个香蕉 🍌</TabItem>
</Tabs>

http://localhost:3000

Apple
Orange
Banana

这是一个苹果 🍎

自定义标签页标题

你也可以通过使用 attributes 字段来独立地自定义每个标签页的标题。额外的属性可以通过 Tabs 组件的 values 属性或每个 TabItem 的 props 来传递——与你声明 label 的方式相同。

some-doc.mdx
import styles from './styles.module.css';

<Tabs>
  <TabItem value="apple" label="苹果" attributes={{className: styles.red}}>
    这是一个苹果 🍎
  </TabItem>
  <TabItem value="orange" label="橘子" attributes={{className: styles.orange}}>
    这是一个橘子 🍊
  </TabItem>
  <TabItem value="banana" label="香蕉" attributes={{className: styles.yellow}}>
    这是一个香蕉 🍌
  </TabItem>
</Tabs>

styles.module.css
.red {
  color: red;
}
.red[aria-selected='true'] {
  border-bottom-color: red;
}

.orange {
  color: orange;
}
.orange[aria-selected='true'] {
  border-bottom-color: orange;
}

.yellow {
  color: yellow;
}
.yellow[aria-selected='true'] {
  border-bottom-color: yellow;
}

http://localhost:3000

苹果
橘子
香蕉

这是一个苹果 🍎

提示

className 会与其他默认的类名合并。你也可以使用一个自定义的 data-value 字段（{'data-value': 'apple'}）配合 CSS 属性选择器：

styles.module.css
li[role='tab'][data-value='apple'] {
  color: red;
}

查询字符串

可以将选中的标签页持久化到 URL 的查询参数中。这使你能够分享一个预先选中了特定标签页的页面链接——例如，从你的 Android 应用链接到预选了 Android 标签页的文档。此功能不提供锚点链接——浏览器不会滚动到标签页的位置。

使用 queryString 属性来启用此功能，并定义要使用的查询参数名称。

<Tabs queryString="current-os">
  <TabItem value="android" label="Android">
    安卓
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>

http://localhost:3000

Android
iOS

安卓

一旦点击了一个标签页，一个查询参数就会被添加到 URL 的末尾：?current-os=android 或 ?current-os=ios。

提示

queryString 可以与 groupId 一起使用。

为了方便起见，当 queryString 属性为 true 时，groupId 的值将被用作备用。

<Tabs groupId="current-os" queryString>
  <TabItem value="android" label="Android">
    安卓
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>

http://localhost:3000

Android
iOS

安卓

当页面加载时，标签页的查询字符串选择将优先于 groupId 的选择（使用 localStorage）被恢复。

显示默认标签页​

同步标签页选择​

自定义标签页​

自定义标签页标题​

查询字符串​

显示默认标签页

同步标签页选择

自定义标签页

自定义标签页标题

查询字符串