This div is used to preload the font
指南
插件
API
指南
插件
API
简体中文

内置组件

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" />;
}

效果如下：

npm
yarn
pnpm
bun
npm 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" />
  );
}

效果如下：

Source

其中包含的 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>
  );
}
1
2

Tab 1 content

提醒

为了让你更方便地使用这些组件，框架内部对于 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 />;
}