简体中文

内置组件

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://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/rspress/rspress-logo.png"
      />
      <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;
}

Card

Card 组件用于展示卡片。使用方法如下：

index.mdx

import { Card } from '@theme';

function App() {
  return <Card title="Card Title" content="Card Content" />;
}

效果如下：

Card Title

Card Content

其中包含的 props 类型如下：

interface CardProps {
  /**
   * 卡片标题。
   */
  title: React.ReactNode;
  /**
   * 卡片内容。
   */
  content?: React.ReactNode;
  /**
   * 卡片图标。
   */
  icon?: React.ReactNode;
  /**
   * 卡片样式。
   */
  style?: React.CSSProperties;
}

LinkCard

LinkCard 组件用于展示链接卡片。使用方法如下：

index.mdx

import { LinkCard } from '@theme';

function App() {
  return (
    <LinkCard
      href="https://example.com"
      title="Link Card Title"
      description="Link Card Description"
    />
  );
}

效果如下：

Link Card TitleLink Card Description

其中包含的 props 类型如下：

interface LinkCardProps {
  /**
   * 链接的 URL。
   */
  href: string;
  /**
   * 链接的标题。
   */
  title: string;
  /**
   * 链接的描述。
   */
  description?: React.ReactNode;
  /**
   * 链接卡片的样式。
   */
  style?: React.CSSProperties;
}

Helmet

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

index.tsx

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

function App() {
  return (
    <Helmet>
      <meta property="og:description" content="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>
  );
}

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。

渲染当前页面的 TOC

index.mdx

import { Toc } from '@theme';

function App() {
  return <Toc />;
}

Badge
H4
H3
Card
LinkCard
Helmet
HomeFeature
HomeHero
LastUpdated
NoSSR
Overview
PackageManagerTabs
PrevNextPage
SourceCode
Steps
Tab/Tabs
Table of Contents

ON THIS PAGE

内置组件#

Badge#

H5 Info#

H4 Warning#

H3 Danger#

Card#

LinkCard#

Helmet#

HomeFeature#

HomeHero#

LastUpdated#

NoSSR#

Overview#

PackageManagerTabs#

PrevNextPage#

SourceCode#

Steps#

第 1 步

第 2 步

Tab/Tabs#

Table of Contents#

内置组件

Badge

H5 Info

H4 Warning

H3 Danger

Card

LinkCard

Helmet

HomeFeature

HomeHero

LastUpdated

NoSSR

Overview

PackageManagerTabs

PrevNextPage

SourceCode

Steps

Tab/Tabs

Table of Contents