垦荒学园

简体中文

English

简体中文

English

切换主题

内置组件 ​

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

组件概述 ​

可用组件 ​

Rspress 包含以下内置组件:

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

导入方式 ​

从 rspress/theme 导入组件:

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

标签组件 ​

基本标签 ​

创建标签式内容:

mdx
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>

默认激活标签 ​

设置默认选中的标签:

mdx
<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>

垂直标签 ​

创建垂直布局的标签:

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

标签样式 ​

自定义标签外观:

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

卡片组件 ​

基本卡片 ​

创建内容卡片:

mdx
import { Card } from 'rspress/theme';

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

卡片网格 ​

在网格中排列多个卡片:

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

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

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

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

可点击卡片 ​

带链接的卡片:

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

卡片变体 ​

不同风格的卡片:

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

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

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

提示框组件 ​

提示类型 ​

不同类型的提示框:

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

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

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

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

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

自定义标题 ​

自定义提示框标题:

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

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

嵌套内容 ​

提示框中的复杂内容:

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

  1. 创建配置文件:

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

  2. 运行开发服务器:

    bash
    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;
}
```

代码组 ​

组合多个代码片段:

mdx
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>

代码差异 ​

显示代码更改:

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

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

徽章组件 ​

基本徽章 ​

添加状态徽章:

mdx
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>

内联徽章 ​

文本中的徽章:

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

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

自定义徽章 ​

自定义样式的徽章:

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

按钮组件 ​

基本按钮 ​

创建操作按钮:

mdx
import { Button } from 'rspress/theme';

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

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

按钮变体 ​

不同风格的按钮:

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

按钮大小 ​

不同尺寸的按钮:

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

按钮组 ​

组合多个按钮:

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

折叠组件 ​

基本折叠 ​

可展开的内容:

mdx
import { Collapse } from 'rspress/theme';

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

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

默认展开 ​

默认打开的折叠:

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

多个折叠 ​

手风琴式折叠:

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

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

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

步骤组件 ​

步骤指南 ​

创建步骤式教程:

mdx
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>

图片组件 ​

基本图片 ​

增强的图片组件:

mdx
import { Image } from 'rspress/theme';

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

图片放大 ​

可点击放大的图片:

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

图片网格 ​

多图片网格:

mdx
<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>

链接组件 ​

内部链接 ​

链接到文档页面:

mdx
import { Link } from 'rspress/theme';

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

外部链接 ​

带图标的外部链接:

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

卡片链接 ​

大型可点击区域:

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

目录组件 ​

页面目录 ​

显示页面大纲:

mdx
import { TOC } from 'rspress/theme';

<TOC />

自定义深度 ​

控制标题层级:

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

网格布局 ​

响应式网格 ​

创建响应式网格布局:

mdx
<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>

两列布局 ​

并排内容:

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

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

组件组合 ​

复杂布局 ​

组合多个组件:

mdx
<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>

功能展示 ​

展示产品功能:

mdx
<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>

样式化组件 ​

自定义样式 ​

为组件添加自定义样式:

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

CSS 类 ​

使用 CSS 类:

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

CSS:

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

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

最佳实践 ​

组件使用 ​

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

内容组织 ​

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

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

响应式设计 ​

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

故障排除 ​

组件未渲染 ​

问题: 组件不显示

检查:

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

样式问题 ​

问题: 样式不按预期工作

解决方案:

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

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

嵌套问题 ​

问题: 组件嵌套问题

解决方案:

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

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

下一步 ​

组件提示

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

性能

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

资源