跳到主要内容

选项卡

Docusaurus 提供了 <Tabs> 组件，您可以在 Markdown 中通过 MDX 使用：

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 属性：

<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 属性优先于 TabItem 属性：
<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
这是一个苹果 🍎
提示

默认情况下，所有选项卡都在构建过程中立即渲染，搜索引擎可以索引隐藏的选项卡。

可以通过 <Tabs lazy /> 仅渲染默认选项卡。

显示默认选项卡​

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

如果为 Tabs 提供了 defaultValue，但它引用了不存在的值，Docusaurus 将抛出错误。如果您希望默认情况下不显示任何选项卡，请使用 defaultValue={null}。

同步选项卡选择​

您可能希望同步相同类型的选项卡选择。例如，您可能想为 Windows 用户和 macOS 用户提供不同的说明，并希望通过单击一次更改所有操作系统特定的说明选项卡。为实现这一点，您可以为所有相关选项卡提供相同的 groupId 属性。请注意，这将在 localStorage 中保留选择，并且当其中一个选项卡的值更改时，所有具有相同 groupId 的 <Tab> 实例都将自动更新。请注意，组 ID 是全局命名空间。

<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
使用 Ctrl + C 复制。
使用 Ctrl + V 粘贴。

对于具有相同 groupId 的所有选项卡组，可能的值不需要相同。如果选择了一个在另一个具有相同 groupId 的选项卡组中不存在的值，则该选项卡组将不会更改其选项卡。您可以从以下示例中看到这一点。尝试选择 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。

具有不同组 ID 的选项卡选择不会相互干扰：

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows 在 Windows 中。</TabItem>
  <TabItem value="mac" label="macOS">macOS 是 macOS。</TabItem>
</Tabs>

<Tabs groupId="non-mac-operating-systems">
  <TabItem value="win" label="Windows">Windows 是 Windows。</TabItem>
  <TabItem value="unix" label="Unix">Unix 是 Unix。</TabItem>
</Tabs>
http://localhost:3000
Windows 在 Windows 中。
Windows 是 Windows。

自定义选项卡​

您可能想自定义某组选项卡的外观。可以传递 className 属性中的字符串，指定的 CSS 类将添加到 Tabs 组件：

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

自定义选项卡标题​

您还可以通过使用 attributes 字段独立自定义每个选项卡标题。额外的属性可以通过 Tabs 中的 values 属性或每个 TabItem 的属性传递 - 方式与声明 label 相同。

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

<Tabs>
  <TabItem value="apple" label="Apple" attributes={{className: styles.red}}>
    这是一个苹果 🍎
  </TabItem>
  <TabItem value="orange" label="Orange" attributes={{className: styles.orange}}>
    这是一个橙子 🍊
  </TabItem>
  <TabItem value="banana" label="Banana" 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">
    Android
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>
http://localhost:3000
Android

一旦点击选项卡，就会在 URL 末尾添加搜索参数：?current-os=android 或 ?current-os=ios。

提示

queryString 可以与 groupId 一起使用。

为方便起见，当 queryString 属性为 true 时，将使用 groupId 值作为后备。

<Tabs groupId="current-os" queryString>
  <TabItem value="android" label="Android">
    Android
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>
http://localhost:3000
Android

页面加载时，选项卡查询字符串选择将优先于 groupId 选择（使用 localStorage）。