内置组件

Rspress 提供一套强大的内置组件,帮助您创建丰富、交互式的文档体验。本章探讨所有可用的内置组件及其使用方法。

组件概述

可用组件

Rspress 包含以下内置组件:

布局组件: Tab, Card, Grid
内容组件: Alert, Badge, Button
代码组件: CodeBlock, CodeGroup
媒体组件: Image, Video
交互组件: Collapse, Steps
导航组件: Link, TOC

导入方式

从 rspress/theme 导入组件:

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

标签组件

基本标签

创建标签式内容:

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

<Tabs>
  <Tab label="npm">
    ```bash
    npm install rspress
    ```
  </Tab>
  <Tab label="yarn">
    ```bash
    yarn add rspress
    ```
  </Tab>
  <Tab label="pnpm">
    ```bash
    pnpm add rspress
    ```
  </Tab>
</Tabs>

默认激活标签

设置默认选中的标签:

<Tabs defaultValue="yarn">
  <Tab label="npm" value="npm">
    npm 说明...
  </Tab>
  <Tab label="yarn" value="yarn">
    yarn 说明...
  </Tab>
  <Tab label="pnpm" value="pnpm">
    pnpm 说明...
  </Tab>
</Tabs>

垂直标签

创建垂直布局的标签:

<Tabs orientation="vertical">
  <Tab label="选项 1">
    选项 1 的内容
  </Tab>
  <Tab label="选项 2">
    选项 2 的内容
  </Tab>
  <Tab label="选项 3">
    选项 3 的内容
  </Tab>
</Tabs>

标签样式

自定义标签外观:

<Tabs
  variant="pills"  // 或 "line", "enclosed"
  colorScheme="blue"
>
  <Tab label="选项 1">内容 1</Tab>
  <Tab label="选项 2">内容 2</Tab>
</Tabs>

卡片组件

基本卡片

创建内容卡片:

import { Card } from 'rspress/theme';

<Card title="功能 1" icon="⚡">
  这是一个带图标和标题的卡片。
</Card>

卡片网格

在网格中排列多个卡片:

<div className="card-grid">
  <Card title="快速" icon="⚡">
    使用 Vite 构建,实现闪电般快速的开发
  </Card>

  <Card title="简单" icon="✨">
    直观的配置和最小的设置
  </Card>

  <Card title="强大" icon="💪">
    功能完整的文档框架
  </Card>

  <Card title="灵活" icon="🎨">
    完全可定制的主题和组件
  </Card>
</div>

可点击卡片

带链接的卡片:

<Card
  title="入门指南"
  href="/guide/getting-started"
  hoverable
>
  学习如何开始使用 Rspress
</Card>

卡片变体

不同风格的卡片:

<Card variant="outlined" title="轮廓卡片">
  带边框无阴影
</Card>

<Card variant="filled" title="填充卡片">
  带背景色
</Card>

<Card variant="elevated" title="浮起卡片">
  带阴影效果
</Card>

提示框组件

提示类型

不同类型的提示框:

::: tip 提示
这是一条有用的提示!
:::

::: info 信息
这提供了额外信息。
:::

::: warning 警告
这警告用户潜在问题。
:::

::: danger 危险
这是关键信息或危险操作。
:::

::: details 详情
这是可以展开的详细内容。
点击查看更多...
:::

自定义标题

自定义提示框标题:

::: tip 专业提示
您可以自定义提示框的标题!
:::

::: warning 重要提示
记得备份您的数据。
:::

嵌套内容

提示框中的复杂内容:

::: info 安装步骤
1. 安装依赖:
   ```bash
   npm install rspress

创建配置文件:

export default defineConfig({
  title: 'My Docs'
});

运行开发服务器:
```
npm run dev
```

:::


## 代码组件

### 代码块增强

带特殊功能的代码块:

````mdx
```javascript title="app.js" showLineNumbers

function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet('World');


### 行高亮

高亮特定行:

````mdx
```javascript {2,4-6}

function calculate(a, b) {
  const sum = a + b;  // 高亮

  // 这些行被高亮
  if (sum > 100) {
    return 100;
  }

  return sum;
}
```

代码组

组合多个代码片段:

import { CodeGroup } from 'rspress/theme';

<CodeGroup>
  ```javascript tab="JavaScript"
  const greeting = 'Hello';
  console.log(greeting);
  ```
  ```typescript tab="TypeScript"
  const greeting: string = 'Hello';
  console.log(greeting);
  ```
  ```python tab="Python"
  greeting = 'Hello'
  print(greeting)
  ```
</CodeGroup>

代码差异

显示代码更改:

```diff

function oldFunction() {
-  return 'old value';
+  return 'new value';
}

-const deprecated = true;
+const current = true;
```

徽章组件

基本徽章

添加状态徽章:

import { Badge } from 'rspress/theme';

<Badge type="info">New</Badge>
<Badge type="success">Stable</Badge>
<Badge type="warning">Beta</Badge>
<Badge type="danger">Deprecated</Badge>

内联徽章

文本中的徽章:

## API 参考 <Badge type="info">v3.0+</Badge>

此功能在版本 3.0 <Badge type="success">Stable</Badge> 中可用。

自定义徽章

自定义样式的徽章:

<Badge
  type="custom"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white'
  }}
>
  Premium
</Badge>

按钮组件

基本按钮

创建操作按钮:

import { Button } from 'rspress/theme';

<Button href="/guide/getting-started">
  开始使用
</Button>

<Button
  href="https://github.com/example/repo"
  target="_blank"
  variant="outline"
>
  GitHub
</Button>

按钮变体

不同风格的按钮:

<Button variant="solid">实心按钮</Button>
<Button variant="outline">轮廓按钮</Button>
<Button variant="ghost">幽灵按钮</Button>
<Button variant="link">链接按钮</Button>

按钮大小

不同尺寸的按钮:

<Button size="sm">小按钮</Button>
<Button size="md">中按钮</Button>
<Button size="lg">大按钮</Button>

按钮组

组合多个按钮:

<div className="button-group">
  <Button href="/guide">查看指南</Button>
  <Button href="/api" variant="outline">API 参考</Button>
  <Button href="/examples" variant="ghost">示例</Button>
</div>

折叠组件

基本折叠

可展开的内容:

import { Collapse } from 'rspress/theme';

<Collapse title="点击展开">
  这是隐藏的内容,只在展开时显示。

  可以包含任何 Markdown 内容:
  - 列表项
  - 代码块
  - 其他组件
</Collapse>

默认展开

默认打开的折叠:

<Collapse title="常见问题" defaultOpen>
  这个内容默认可见。
</Collapse>

多个折叠

手风琴式折叠:

<Collapse title="问题 1">
  答案 1
</Collapse>

<Collapse title="问题 2">
  答案 2
</Collapse>

<Collapse title="问题 3">
  答案 3
</Collapse>

步骤组件

步骤指南

创建步骤式教程:

import { Steps } from 'rspress/theme';

<Steps>

### 步骤 1: 安装

安装 Rspress 到您的项目:

````bash

npm install rspress
```
### 步骤 2: 配置

创建 `rspress.config.ts`:

```typescript

export default defineConfig({
  title: 'My Docs'
});
```
### 步骤 3: 运行

启动开发服务器:

```bash

npm run dev
```
</Steps>
```

### 编号步骤

自定义步骤编号:

````mdx
<Steps start={1}>

### 首先

做这个...

### 然后

做那个...

### 最后

完成!

</Steps>

图片组件

基本图片

增强的图片组件:

import { Image } from 'rspress/theme';

<Image
  src="/screenshot.png"
  alt="应用截图"
  width={800}
  height={600}
/>

图片放大

可点击放大的图片:

<Image
  src="/screenshot.png"
  alt="应用截图"
  zoom
  caption="点击放大"
/>

图片网格

多图片网格:

<div className="image-grid">
  <Image src="/img1.png" alt="图片 1" />
  <Image src="/img2.png" alt="图片 2" />
  <Image src="/img3.png" alt="图片 3" />
  <Image src="/img4.png" alt="图片 4" />
</div>

链接组件

内部链接

链接到文档页面:

import { Link } from 'rspress/theme';

<Link href="/guide/getting-started">
  阅读入门指南
</Link>

外部链接

带图标的外部链接:

<Link
  href="https://github.com/example/repo"
  external
>
  查看 GitHub
</Link>

卡片链接

大型可点击区域:

<Link href="/guide" card>
  <h3>入门指南</h3>
  <p>学习 Rspress 的基础知识</p>
</Link>

目录组件

页面目录

显示页面大纲:

import { TOC } from 'rspress/theme';

<TOC />

自定义深度

控制标题层级:

<TOC
  minDepth={2}
  maxDepth={3}
/>

网格布局

响应式网格

创建响应式网格布局:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card title="项目 1">内容 1</Card>
  <Card title="项目 2">内容 2</Card>
  <Card title="项目 3">内容 3</Card>
  <Card title="项目 4">内容 4</Card>
  <Card title="项目 5">内容 5</Card>
  <Card title="项目 6">内容 6</Card>
</div>

两列布局

并排内容:

<div className="grid grid-cols-2 gap-6">
  <div>
    ### 左侧内容
    这里是左侧的内容...
  </div>

  <div>
    ### 右侧内容
    这里是右侧的内容...
  </div>
</div>

组件组合

复杂布局

组合多个组件:

<Card title="API 示例" icon="📚">
  <Tabs>
    <Tab label="JavaScript">
      ```javascript
      const api = new API();
      api.getData();
      ```
    </Tab>

    <Tab label="Python">
      ```python
      api = API()
      api.get_data()
      ```
    </Tab>
  </Tabs>

  <Badge type="info">v2.0+</Badge>

  ::: tip
  此 API 在版本 2.0 中引入。
  :::
</Card>

功能展示

展示产品功能:

<div className="feature-showcase">
  <Card title="⚡ 快速开发" hoverable>
    使用 Vite 实现即时 HMR 和快速构建

    <Button href="/guide/quick-start">了解更多</Button>
  </Card>

  <Card title="🎨 完全可定制" hoverable>
    使用 CSS 变量和自定义组件自定义一切

    <Button href="/guide/customization">了解更多</Button>
  </Card>

  <Card title="📱 响应式" hoverable>
    在所有设备上完美工作

    <Button href="/guide/responsive">了解更多</Button>
  </Card>
</div>

样式化组件

自定义样式

为组件添加自定义样式:

<Card
  title="自定义卡片"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
    border: 'none'
  }}
>
  带自定义样式的卡片
</Card>

CSS 类

使用 CSS 类:

<div className="custom-container">
  <Card className="custom-card">
    内容...
  </Card>
</div>

CSS:

.custom-container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

.custom-card {
  border: 2px solid var(--rp-c-brand);
  border-radius: 12px;
}

最佳实践

组件使用

一致性: 在整个站点中一致使用组件
可访问性: 确保所有组件可访问
性能: 避免过度嵌套组件
语义化: 使用语义化 HTML

内容组织

<!-- ✅ 好的 -->
<Card title="功能">
  <p>描述...</p>
  <Button href="/docs">了解更多</Button>
</Card>

<!-- ❌ 不好的 -->
<Card>
  <Card>
    <Card>
      过度嵌套...
    </Card>
  </Card>
</Card>

响应式设计

<!-- 响应式网格 -->
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card>移动: 1 列, 平板: 2 列, 桌面: 3 列</Card>
</div>

故障排除

组件未渲染

问题: 组件不显示

检查:

正确导入组件
检查组件名称拼写
验证 props 类型
确保 MDX 语法正确

样式问题

问题: 样式不按预期工作

解决方案:

<!-- ✅ 使用 className -->
<Card className="my-card">

<!-- ❌ 不要使用 class -->
<Card class="my-card">

嵌套问题

问题: 组件嵌套问题

解决方案:

<!-- ✅ 正确的嵌套 -->
<Tabs>
  <Tab label="选项 1">
    <Card>内容</Card>
  </Tab>
</Tabs>

<!-- ❌ 避免深度嵌套 -->
<Tabs>
  <Tab>
    <Card>
      <Collapse>
        <Tabs>...</Tabs>
      </Collapse>
    </Card>
  </Tab>
</Tabs>

下一步

::: tip 组件提示

始终为图片提供 alt 文本
对交互元素使用语义化 HTML
测试移动设备上的组件
保持组件简单和专注
重用组件以保持一致性 :::

::: warning 性能

避免在一个页面上使用过多组件
优化图片尺寸
懒加载重型组件
最小化嵌套深度 :::

::: info 资源

#内置组件

#组件概述

#可用组件

#导入方式

#标签组件

#基本标签

#默认激活标签

#垂直标签

#标签样式

#卡片组件

#基本卡片

#卡片网格

#可点击卡片

#卡片变体

#提示框组件

#提示类型

#自定义标题

#嵌套内容

#代码组

#代码差异

#徽章组件

#基本徽章

#内联徽章

#自定义徽章

#按钮组件

#基本按钮

#按钮变体

#按钮大小

#按钮组

#折叠组件

#基本折叠

#默认展开

#多个折叠

#步骤组件

#步骤指南

#图片组件

#基本图片

#图片放大

#图片网格

#链接组件

#内部链接

#外部链接

#卡片链接

#目录组件

#页面目录

#自定义深度

#网格布局

#响应式网格

#两列布局

#组件组合

#复杂布局

#功能展示

#样式化组件

#自定义样式

#CSS 类

#最佳实践

#组件使用

#内容组织

#响应式设计

#故障排除

#组件未渲染

#样式问题

#嵌套问题

#下一步