组件使用

VitePress 提供了内置组件，并支持创建和使用自定义 Vue 组件。

内置组件

Badge 徽章

用于显示标签或状态，常用于侧边栏导航、版本标识等场景。

基本用法

<Badge type="info" text="默认" />
<Badge type="tip" text="推荐" />
<Badge type="warning" text="警告" />
<Badge type="danger" text="危险" />

效果：

默认推荐警告危险

自定义文字

<Badge type="tip">自定义文字</Badge>
<Badge type="info" text="v2.0" />
<Badge type="warning">Beta</Badge>
<Badge type="danger">Deprecated</Badge>

在导航栏中使用

// docs/.vitepress/config.mts
export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '介绍', link: '/guide/' },
          { 
            text: '新特性', 
            link: '/guide/new-features',
            badge: { text: '新', type: 'tip' }
          },
          { 
            text: 'Beta 功能', 
            link: '/guide/beta',
            badge: { text: 'Beta', type: 'warning' }
          }
        ]
      }
    ]
  }
})

徽章类型说明

类型	用途	颜色
info	信息、默认	蓝色
tip	推荐、提示	绿色
warning	警告、Beta	黄色
danger	危险、废弃	红色

自定义样式

通过 CSS 变量自定义徽章颜色：

/* docs/.vitepress/theme/custom.css */

/* 自定义 info 徽章颜色 */
:root {
  --vp-badge-info-border: transparent;
  --vp-badge-info-text: #3b82f6;
  --vp-badge-info-bg: rgba(59, 130, 246, 0.14);
}

/* 自定义 tip 徽章颜色 */
:root {
  --vp-badge-tip-border: transparent;
  --vp-badge-tip-text: #10b981;
  --vp-badge-tip-bg: rgba(16, 185, 129, 0.14);
}

/* 自定义 warning 徽章颜色 */
:root {
  --vp-badge-warning-border: transparent;
  --vp-badge-warning-text: #f59e0b;
  --vp-badge-warning-bg: rgba(245, 158, 11, 0.14);
}

/* 自定义 danger 徽章颜色 */
:root {
  --vp-badge-danger-border: transparent;
  --vp-badge-danger-text: #ef4444;
  --vp-badge-danger-bg: rgba(239, 68, 68, 0.14);
}

CodeGroup 代码组

用于显示多语言代码切换：

使用 ::: code-group 语法：

::: code-group

```bash [npm]
npm install vitepress
```

```bash [yarn]
yarn add vitepress
```

```bash [pnpm]
pnpm add vitepress
```

:::

ClientOnly 客户端渲染

仅在客户端渲染内容：

<ClientOnly>
  <div>{{ window.innerWidth }}</div>
</ClientOnly>

在 Markdown 中使用 Vue

使用脚本

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

当前计数：{{ count }}

<button @click="count++">+1</button>

访问页面数据

<script setup>
import { useData } from 'vitepress'

const { page, frontmatter } = useData()
</script>

页面标题：{{ frontmatter.title }}

自定义组件

创建组件

创建 docs/.vitepress/theme/components/ 目录：

<!-- docs/.vitepress/theme/components/Alert.vue -->
<script setup>
defineProps({
  type: {
    type: String,
    default: 'info'
  },
  title: String
})
</script>

<template>
  <div :class="['alert', `alert-${type}`]">
    <strong v-if="title">{{ title }}</strong>
    <slot />
  </div>
</template>

<style scoped>
.alert {
  padding: 12px 16px;
  border-radius: 6px;
  margin: 16px 0;
}

.alert-info {
  background: var(--vp-c-brand-soft);
  border-left: 4px solid var(--vp-c-brand-1);
}

.alert-warning {
  background: var(--vp-c-warning-soft);
  border-left: 4px solid var(--vp-c-warning-1);
}
</style>

注册全局组件

// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import Alert from './components/Alert.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('Alert', Alert)
  }
}

在 Markdown 中使用

<Alert type="info" title="提示">
  这是一个自定义提示组件。
</Alert>

<Alert type="warning">
  这是警告内容。
</Alert>

常用组件示例

版本选择器

<!-- docs/.vitepress/theme/components/VersionPicker.vue -->
<script setup>
import { ref } from 'vue'

const versions = [
  { label: 'v2.x', link: '/' },
  { label: 'v1.x', link: '/v1/' }
]

const current = ref(versions[0])
</script>

<template>
  <select v-model="current" @change="$emit('change', current)">
    <option v-for="v in versions" :key="v.label" :value="v">
      {{ v.label }}
    </option>
  </select>
</template>

分页组件

<!-- docs/.vitepress/theme/components/Pagination.vue -->
<script setup>
defineProps({
  current: Number,
  total: Number
})

const emit = defineEmits(['change'])
</script>

<template>
  <div class="pagination">
    <button 
      :disabled="current <= 1"
      @click="emit('change', current - 1)"
    >
      上一页
    </button>
    <span>{{ current }} / {{ total }}</span>
    <button 
      :disabled="current >= total"
      @click="emit('change', current + 1)"
    >
      下一页
    </button>
  </div>
</template>

目录组件

<!-- docs/.vitepress/theme/components/Toc.vue -->
<script setup>
import { useData } from 'vitepress'

const { page } = useData()
const headers = page.value.headers
</script>

<template>
  <nav class="toc">
    <ul>
      <li v-for="h in headers" :key="h.slug">
        <a :href="`#${h.slug}`">{{ h.title }}</a>
      </li>
    </ul>
  </nav>
</template>

评论组件

使用 Giscus 作为评论系统：

<!-- docs/.vitepress/theme/components/Comment.vue -->
<script setup>
import Giscus from '@giscus/vue'
</script>

<template>
  <div class="comment-container">
    <Giscus
      repo="user/repo"
      repo-id="xxx"
      category="Announcements"
      category-id="xxx"
      mapping="pathname"
      theme="preferred_color_scheme"
    />
  </div>
</template>

响应式设计

响应式组件

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const isMobile = ref(false)

function checkMobile() {
  isMobile.value = window.innerWidth < 768
}

onMounted(() => {
  checkMobile()
  window.addEventListener('resize', checkMobile)
})

onUnmounted(() => {
  window.removeEventListener('resize', checkMobile)
})
</script>

<template>
  <div v-if="isMobile">移动端内容</div>
  <div v-else>桌面端内容</div>
</template>

下一步

学习 数据加载 来处理动态数据。

本章检查清单

0 / 10 已完成

0%

内置组件

• 掌握 Badge 徽章组件的基本用法和类型（info/tip/warning/danger）
• 能在导航栏配置中使用 badge 属性
• 会用 CodeGroup 实现多语言代码切换展示
• 理解 ClientOnly 客户端渲染的使用场景

在 Markdown 中使用 Vue

• 能在 .md 文件中使用 <script setup> 定义响应式数据
• 通过 useData() 访问页面数据和 frontmatter

自定义组件开发

• 在 theme/components/ 下创建并导出 Vue 组件
• 在 theme/index.ts 中注册全局组件
• 在 .md 文件中直接使用自定义组件标签
• 实现 props 传递和 slot 插槽