选项卡
Docusaurus提供了 <Tabs>
组件,你可以通过 MDX 在 Markdown 中使用:
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>
- 苹果
- 橙子
- 香蕉
这是个苹果 🍎
这是个橙子 🍊
这是个香蕉 🍌
It is also possible to provide values
and defaultValue
props to Tabs
:
<Tabs
defaultValue="apple"
values={[
{label: '苹果', value: 'apple'},
{label: '橙子', value: 'orange'},
{label: '香蕉', value: 'banana'},
]}>
- 苹果
- 橙子
- 香蕉
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>
- 苹果 1
- 橙子 1
- 香蕉 1
通常,所有选项卡都会在构建过程中被预渲染,以便搜索引擎爬取未显示的选项卡。
当你想仅呈现默认选项卡时,可以使用 <Tabs lazy />
。
显示默认选项卡
The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding default
to one of the tab items. You can also set the defaultValue
prop of the Tabs
component to the label value of your choice. For example, in the example above, either setting default
for the value="apple"
tab or setting defaultValue="apple"
for the tabs forces the "Apple" tab to be open by default.
Docusaurus will throw an error if a defaultValue
is provided for the Tabs
but it refers to a non-existing value. If you want none of the tabs to be shown by default, use defaultValue={null}
.
同步选项
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to change all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same groupId
prop. Note that doing this will persist the choice in localStorage
and all <Tab>
instances with the same groupId
will update automatically when the value of one of them is changed. Note that group IDs are globally namespaced.
<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>
- Windows
- macOS
- Windows
- macOS
For all tab groups that have the same groupId
, the possible values do not need to be the same. If one tab group is chosen a value that does not exist in another tab group with the same groupId
, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups don't change.
<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>
- Windows
- macOS
- Linux
带有不同 groupId 的选项卡不会互相干涉:
<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>
- Windows
- macOS
- Windows
- Unix
自定义选项卡外观
You might want to customize the appearance of a certain set of tabs. You can pass the string in className
prop, and the specified CSS class will be added to the Tabs
component:
<Tabs className="unique-tabs">
<TabItem value="苹果">这是个苹果 🍎</TabItem>
<TabItem value="橙子">这是个橙子 🍊</TabItem>
<TabItem value="香蕉">这是个香蕉 🍌</TabItem>
</Tabs>
- 苹果
- 橙子
- 香蕉
自定义选项标题外观
You can also customize each tab heading independently by using the attributes
field. The extra props can be passed to the headings either through the values
prop in Tabs
, or props of each TabItem
—in the same way as you declare label
.
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>
.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;
}
- 苹果
- 橙子
- 香蕉
这是个苹果 🍎
这是个橙子 🍊
这是个香蕉 🍌
className
would be merged with other default class names. You may also use a custom data-value
field ({'data-value': 'apple'}
) paired with CSS attribute selectors:
li[role='tab'][data-value='apple'] {
color: red;
}
Query string
It is possible to persist the selected tab into the url search parameters. This enables you to share a link to a page which pre-selects the tab - linking from your Android app to documentation with the Android tabs pre-selected. This feature does not provide an anchor link - the browser will not scroll to the tab.
Use the queryString
prop to enable this feature and define the search param name to use.
<Tabs queryString="current-os">
<TabItem value="android" label="Android">
Android
</TabItem>
<TabItem value="ios" label="iOS">
iOS
</TabItem>
</Tabs>
- Android
- iOS
As soon as a tab is clicked, a search parameter is added at the end of the url: ?current-os=android
or ?current-os=ios
.
queryString
can be used together with groupId
.
For convenience, when the queryString
prop is true
, the groupId
value will be used as a fallback.
<Tabs groupId="current-os" queryString>
<TabItem value="android" label="Android">
Android
</TabItem>
<TabItem value="ios" label="iOS">
iOS
</TabItem>
</Tabs>
- Android
- iOS
When the page loads, the tab query string choice will be restored in priority over the groupId
choice (using localStorage
).