API 参考 {#api-reference}

辅助方法 {#helper-methods}

以下方法通常用于自定义主题 Vue 组件，可以从 vitepress 全局导入。但是，因为 markdown 文件都会被编译成 Vue 单文件组件，所以它们也可以在 .md 文件中使用。

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

useData

返回特定页面数据。返回的对象类型如下：

  1. interface VitePressData {
  2.   site: Ref<SiteData>
  3.   page: Ref<PageData>
  4.   theme: Ref<any> // themeConfig from .vitepress/config.js
  5.   frontmatter: Ref<PageData['frontmatter']>
  6.   title: Ref<string>
  7.   description: Ref<string>
  8.   lang: Ref<string>
  9.   localePath: Ref<string>
  10. }

例子：

  1. <script setup>
  2. import { useData } from 'vitepress'
  3. const { theme } = useData()
  4. </script>
  6. <template>
  7.   <h1>{{ theme.heroText }}</h1>
  8. </template>

useRoute

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

  1. interface Route {
  2.   path: string
  3.   data: PageData
  4.   component: Component | null
  5. }

useRouter

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

  1. interface Router {
  2.   route: Route
  3.   go: (href?: string) => Promise<void>
  4. }

withBase

  • Type: (path: string) => string

    将已配置的 base 追加到给定的 URL 路径。参见 根 URL。

全局组件 {#global-components}

VitePress 只有很少的内置组件可以在全局范围内使用。你可以在你的 markdown 或自定义主题配置中使用这些组件。

<Content/>

<Content/> 组件呈现渲染出来的 markdown 内容。这在创建你自己的主题时很有用。

  1. <template>
  2.   <h1>Custom Layout!</h1>
  3.   <Content />
  4. </template>

<ClientOnly/>

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

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

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

  1. <ClientOnly>
  2.   <NonSSRFriendlyComponent />
  3. </ClientOnly>