内置组件

提醒

为了让用户更方便地使用这些组件，Rspress 内部对于 rspress/theme 这个包做了 alias 处理，所以你可以直接使用 @theme 来引入这些组件。

Badge

Badge 组件用于展示状态的标记。使用方法如下：

index.mdx

import { Badge } from '@theme';

function App() {
  // 使用 text 属性
  return <Badge text="info" type="info" />;

  // 使用自定义子元素
  return (
    <Badge>
      <img
        style={{ height: '18px' }}
        src="https://assets.rspack.rs/rspress/rspress-logo.svg"
      />
      <span>Rspress</span>
    </Badge>
  );
}

效果如下：

tip info warning danger outlined

自定义子元素：

Rspress Github

内联文本 Tip

H5 Info

H4 Warning

H3 Danger

其中包含的 props 类型如下：

interface BadgeProps {
  /**
   * 在徽章内显示的内容。可以是字符串或 React 节点。
   */
  children?: React.ReactNode;
  /**
   * 徽章的类型，决定其颜色和样式。
   * @default 'tip'
   */
  type?: 'tip' | 'info' | 'warning' | 'danger';
  /**
   * 在徽章内显示的文本内容（为了向后兼容）。
   */
  text?: string;
  /**
   * 是否以轮廓样式显示徽章。
   * @default false
   */
  outline?: boolean;
}

Head

一般用于在文档中设置自定义 head 内容（基于 unhead）。使用方法如下：

index.tsx

// 以下为一个自定义组件，你可以将其引入到文档中
import { Head } from '@rspress/core/runtime';

function App() {
  return (
    <Head>
      <meta property="og:description" content="Out-of-box Rspack build tools" />
    </Head>
  );
}

HomeFeature

Home 页面 Feature 组件，查看本站的效果

import { HomeFeature } from '@rspress/core/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/core/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/core/runtime';

const Component = () => {
  return (
    <NoSSR>
      <div>这里的内容只会在客户端渲染</div>
    </NoSSR>
  );
};

Overview

预览组件，查看本站的效果

import { Overview } from '@rspress/core/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 -D @rspress/core" />;
}

效果如下：

npm

yarn

pnpm

bun

deno

npm install -D @rspress/core

其中包含的 props 类型如下：

type PackageManagerTabProps = (
  | {
      command: string;
      /**
       * 如果为 true，使用本地包执行（npx、yarn、pnpm、bun、deno run）。
       * 用于 node_modules 中安装的本地包。
       */
      exec?: boolean;
      /**
       * 如果为 true，使用远程包执行（npx、yarn dlx、pnpm dlx、bunx、deno run）。
       * 用于直接从源下载并执行包而无需本地安装。
       * 优先于 exec 属性。
       */
      dlx?: boolean;
    }
  | {
      command: {
        // 用于为不同的包管理器设置命令
        npm?: string;
        yarn?: string;
        pnpm?: string;
        bun?: string;
        deno?: string;
      };
      exec?: never;
      dlx?: never;
    }
) &
  // 用于设置额外的 tabs
  {
    additionalTabs?: {
      // 用于设置额外的包管理器
      tool: string;
      // 用于设置额外包管理器的图标
      icon?: ReactNode;
    }[];
  };

当 command 设置为字符串时，会默认展示 npm、yarn、pnpm、bun、deno 五个 tab，并且组件内部为自动在 command 前面添加对应的包管理器命令。如果你需要展示额外的 tab，可以通过 additionalTabs 来实现。

你也可以使用对象形式为每个包管理器设置不同的命令：

index.mdx

import { PackageManagerTabs } from '@theme';

function App() {
  return (
    <PackageManagerTabs
      command={{
        npm: 'npm create rspress@latest',
        yarn: 'yarn create rspress',
        pnpm: 'pnpm create rspress@latest',
        bun: 'bun create rspress@latest',
        deno: 'deno init --npm rspress@latest',
      }}
    />
  );
}

Tip

在 install 命令中，对 yarn、pnpm、bun 和 deno 做了特殊处理，如果你的命令是install some-packages，在 yarn、pnpm、bun 和 deno 的 tab 中会自动将 install 替换为 add。
在 deno 的 tab 中会默认为没有指定来源的包加上 npm: 前缀。

PrevNextPage

PrevNextPage 组件用来渲染上一页和下一页的链接。使用方法如下：

index.mdx

import { PrevNextPage } from '@theme';

function App() {
  return <PrevNextPage type="prev" text="上一页" href="https://rspress.rs/" />;
}

其中包含的 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 组件来实现标签页切换的效果。比如：

index.mdx

import { Tab, Tabs } from '@rspress/core/theme';

<Tabs>
  <Tab label="Tab 1">Tab 1 content</Tab>
  <Tab label="Tab 2">Tab 2 content</Tab>
</Tabs>

Tab 1

Tab 2

Tab 1 content

代码块切换

使用 Tabs 组件来切换多个代码块。

index.mdx

import { Tab, Tabs } from '@rspress/core/theme';

<Tabs>
  <Tab label="Tab 1">

```tsx title="src/index.mjs"
import foo from 'foo';
import bar from 'bar';
```

  </Tab>
  <Tab label="Tab 2">

```tsx title="src/index.cjs"
const foo = require('foo');
const bar = require('bar');
```

  </Tab>
</Tabs>

Tab 1

Tab 2

src/index.mjs

import foo from 'foo';
import bar from 'bar';

Props

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。

CodeBlockRuntime

运行时渲染代码块

index.mdx

import { CodeBlockRuntime } from '@theme';

function App() {
  return (
    <CodeBlockRuntime
      lang="js"
      title="index.js"
      code={`console.log('Hello World!')`}
      shikiOptions={{
        {/* shikiOptions */}
      }}
    />
  );
}

#内置组件

#Badge

#H5 Info

#H4 Warning

#H3 Danger

#Head

#HomeFeature

#HomeHero

#LastUpdated

#NoSSR

#Overview

#PackageManagerTabs

#PrevNextPage

#SourceCode

#Steps

#第 1 步

#第 2 步

#Tab/Tabs

#代码块切换

#Props

#CodeBlockRuntime

内置组件

Badge

H5 Info

H4 Warning

H3 Danger

Head

HomeFeature

HomeHero

LastUpdated

NoSSR

Overview

PackageManagerTabs

PrevNextPage

SourceCode

Steps

第 1 步

第 2 步

Tab/Tabs

代码块切换

Props

CodeBlockRuntime