内置组件
Badge
Badge 组件用于展示状态的标记。使用方法如下:
index.mdx
import { Badge } from '@theme';
function App() {
return <Badge text="info" type="info" />;
}
效果如下:
info
warning
danger
其中包含的 props 类型如下:
interface BadgeProps {
// 用于设置 badge 的文本
text: string;
// 用于设置 badge 的类型
type: 'info' | 'warning' | 'danger';
}
Helmet
一般用于在文档中设置自定义 head 内容(基于 react-helmet-async)。使用方法如下:
index.tsx
// 以下为一个自定义组件,你可以将其引入到文档中
import { Helmet } from 'rspress/runtime';
function App() {
return (
<Helmet>
<meta property="og:description" value="Out-of-box Rspack build tools" />
</Helmet>
);
}
HomeFeature
Home 页面 Feature 组件,查看本站的效果
import { HomeFeature } from 'rspress/theme';
interface Feature {
title: string;
details: string;
icon: string;
// 卡片栅格的长度,目前仅支持[3, 4, 6]
span?: number;
// feature 卡片跳转链接,选填
link?: string;
}
export type Features = Feature[];
HomeHero
Home 页面 Hero 组件
import { HomeHero } from 'rspress/theme';
interface Hero {
name: string;
text: string;
tagline: string;
image?: {
src: string | { dark: string; light: string };
alt: string;
};
actions: {
text: string;
link: string;
theme: 'brand' | 'alt';
}[];
}
LastUpdated
LastUpdated 组件用来显示文章的最后更新时间。使用方法如下:
index.mdx
import { LastUpdated } from '@theme';
function App() {
return <LastUpdated />;
}
TIP
如果没有在默认主题中配置 lastUpdated: true
的话需要安装和注册 @rspress/plugin-last-updated
插件。
NoSSR
用于在服务端渲染时不渲染某些组件。使用方法如下:
import { NoSSR } from 'rspress/runtime';
const Component = () => {
return (
<NoSSR>
<div>这里的内容只会在客户端渲染</div>
</NoSSR>
);
};
Overview
预览组件,查看本站的效果
import { Overview } from 'rspress/theme';
interface GroupItem {
text?: string;
link?: string;
headers?: Header[];
}
interface Group {
name: string;
items: GroupItem[];
}
interface OverviewProps {
// 预览部分上方的内容
content?: React.ReactNode;
// 预览数据
groups?: Group[];
// 默认标题
defaultGroupTitle?: string;
// 在预览页中展示的标题级别
overviewHeaders?: number[];
}
PackageManagerTabs
PackageManagerTabs 组件用于在文档中展示不同包管理器的命令。使用方法如下:
index.mdx
import { PackageManagerTabs } from '@theme';
function App() {
return <PackageManagerTabs command="install rspress -D" />;
}
效果如下:
其中包含的 props 类型如下:
interface PackageManagerTabsProps {
command:
| string
| {
// 用于设置不同包管理器的命令
npm?: string;
yarn?: string;
pnpm?: string;
bun?: string;
};
// 用于设置额外的 tab
additionalTabs: {
// 用于设置额外的包管理器
tool: string;
// 用于设置包管理器的 icon
icon?: React.ReactNode;
}[];
}
当 command
设置为字符串时,会默认展示 npm、yarn、pnpm、bun 四个 tab,并且组件内部为自动在 command 前面添加对应的包管理器命令。如果你需要展示额外的 tab,可以通过 additionalTabs
来实现。
TIP
在 install 命令中,对 yarn 和 bun 做了特殊处理,如果你的命令是install some-packages
,在 yarn 和 bun 的 tab 中会自动将 install 替换为 add。
PrevNextPage
PrevNextPage 组件用来渲染上一页和下一页的链接。使用方法如下:
index.mdx
import { PrevNextPage } from '@theme';
function App() {
return <PrevNextPage type="prev" text="上一页" href="https://rspress.dev/" />;
}
其中包含的 props 类型如下:
interface PrevNextPageProps {
// 通过 type 来设置该链接是上一页还是下一页
type: 'prev' | 'next';
// 用于设置上一页或下一页的文本
text: string;
// 用于设置上一页或下一页的链接
href: string;
}
SourceCode
SourceCode 组件用来跳转到源代码。使用方法如下:
index.mdx
import { SourceCode } from '@theme';
function App() {
return (
<SourceCode href="https://github.com/web-infra-dev/rspress/blob/main/packages/theme-default/src/components/SourceCode/index.tsx" />
);
}
效果如下:
其中包含的 props 类型如下:
interface SourceCodeProps {
// 用于设置源代码的链接
href: string;
// 用于设置源平台
platform?: 'github' | 'gitlab';
}
Steps
Steps 组件用于将编号列表转换为步骤的可视化表示形式。使用方法如下:
index.mdx
import { Steps } from '@theme';
function App() {
return (
<Steps>
### 第 1 步
步骤 1 的正文
### 第 2 步
> 步骤 2 的正文
</Steps>
);
}
效果如下:
第 1 步
步骤 1 的正文
第 2 步
步骤 2 的正文
Tab/Tabs
你可以在文档中直接使用 Tab/Tabs 组件来实现 tab 切换的效果。比如
index.tsx
import { Tab, Tabs } from 'rspress/theme';
function App() {
return (
<Tabs>
<Tab label="Tab 1">Tab 1 content</Tab>
<Tab label="Tab 2">Tab 2 content</Tab>
</Tabs>
);
}
提醒
为了让你更方便地使用这些组件,框架内部对于 rspress/theme
这个包做了 alias 处理,所以你可以直接使用 @theme
来引入这些组件。
其中 Tabs 组件的 props 类型如下:
interface TabsProps {
children: React.ReactNode;
defaultValue?: string;
groupId?: string;
tabPosition?: 'left' | 'center';
}
defaultValue 用于设置默认选中的 tab 项,这个值会和 Tab 组件的 value 字段做比较,如果相等则选中该 tab。
groupId 用于设置 tab 项的分组,当你需要多个 Tabs 组件进行联动的时候,可以通过 groupId 来实现。groupId 相同的 Tabs 组件会进行联动。
tabPosition 用于设置 tab 列表的排列位置,目前支持 left 和 center 两个值,分为表示靠左和居中,默认为 left。
Tab 组件的 props 类型如下:
interface TabProps {
label: string;
// 用于标识当前 tab,如果不传则默认使用 label
value?: string;
children: React.ReactNode;
}
其中的 value
字段用于标识当前 tab,如果不传则默认使用 label。
Table of Contents
渲染当前页面的 TOC
index.mdx
import { Toc } from '@theme';
function App() {
return <Toc />;
}