运行时 API

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

helper 方法可以从 vitepress 全局导入，通常用于自定义主题 Vue 组件。然而，它们也可以在 .md 页面中使用，因为 markdown 文件被编译成 [Vue 单文件组件]。

以 use* 开头的方法表示它是一个 Vue 3 Composition API 函数（“Composable”），只能在 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>;
}

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 helper

• Type: (path: string) => string

将配置的 base 追加到给定的 URL 路径。另见 Base URL。

<Content /> component

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

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

<ClientOnly /> component

<ClientOnly />组件仅在客户端呈现其槽。

由于 VitePress 应用程序在生成静态构建时是在 Node.js 中进行服务器渲染的，因此任何 Vue 的使用都必须符合通用代码要求。简而言之，确保只访问 beforeMount 或 mounted hook 中的 Browser / DOM API。

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

<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>

$frontmatter 模板全局

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

---
title: Hello
---

# {{ $frontmatter.title }}

$params 模板全局

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

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