运行时 API

VitePress 提供了一些内置 API，让您能够访问应用程序数据。VitePress 还附带了一些内置组件，可以在全局范围内使用。

这些辅助方法可以从 vitepress 中全局导入，通常用于自定义主题的 Vue 组件。但是，它们也可以在 .md 页面中使用，因为 markdown 文件被编译成 Vue 单文件组件。

以 use* 开头的函数表示它是一个 Vue 3 组合式 API 函数（“组合式函数”），只能在 setup() 或 <script setup> 中使用。

useData 组合式函数

返回页面特定的数据。返回的对象具有以下类型

interface VitePressData<T = any> {
  /**
   * Site-level metadata
   */
  site: Ref<SiteData<T>>
  /**
   * themeConfig from .vitepress/config.js
   */
  theme: Ref<T>
  /**
   * Page-level metadata
   */
  page: Ref<PageData>
  /**
   * Page frontmatter
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * Dynamic route params
   */
  params: Ref<PageData['params']>
  title: Ref<string>
  description: Ref<string>
  lang: Ref<string>
  isDark: Ref<boolean>
  dir: Ref<string>
  localeIndex: Ref<string>
  /**
   * Current location hash
   */
  hash: Ref<string>
}

interface PageData {
  title: string
  titleTemplate?: string | boolean
  description: string
  relativePath: string
  filePath: string,
  headers: Header[]
  frontmatter: Record<string, any>
  params?: Record<string, any>
  isNotFound?: boolean
  lastUpdated?: number
}

示例

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

const { theme } = useData()
</script>

<template>
  <h1>{{ theme.footer.copyright }}</h1>
</template>

useRoute 组合式函数

返回当前路由对象，具有以下类型

interface Route {
  path: string
  data: PageData
  component: Component | null
}

useRouter 组合式函数

返回 VitePress 路由实例，以便您可以以编程方式导航到另一个页面。

interface Router {
  /**
   * Current route.
   */
  route: Route
  /**
   * Navigate to a new URL.
   */
  go: (to?: string) => Promise<void>
  /**
   * Called before the route changes. Return `false` to cancel the navigation.
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * Called before the page component is loaded (after the history state is
   * updated). Return `false` to cancel the navigation.
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * Called after the route changes.
   */
  onAfterRouteChanged?: (to: string) => Awaitable<void>
}

withBase 辅助函数

• 类型: (path: string) => string

将配置的 base 附加到给定的 URL 路径。另请参阅 基本 URL。

<Content /> 组件

<Content /> 组件显示渲染后的 markdown 内容。在 创建自己的主题 时很有用。

<template>
  <h1>Custom Layout!</h1>
  <Content />
</template>

<ClientOnly /> 组件

<ClientOnly /> 组件仅在客户端渲染其插槽。

因为 VitePress 应用程序在生成静态构建时在 Node.js 中进行服务器端渲染，所以任何 Vue 使用都必须符合通用代码要求。简而言之，确保仅在 beforeMount 或 mounted 钩子中访问浏览器/DOM API。

如果您正在使用或演示不适合 SSR 的组件（例如，包含自定义指令），则可以将它们包装在 ClientOnly 组件中。

<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>

• 相关：SSR 兼容性

$frontmatter 模板全局变量

在 Vue 表达式中直接访问当前页面的 前置信息 数据。

---
title: Hello
---

# {{ $frontmatter.title }}

$params 模板全局变量

在 Vue 表达式中直接访问当前页面的 动态路由参数。

- package name: {{ $params.pkg }}
- version: {{ $params.version }}