运行时 API

VitePress 提供了几个内置 API 来让你访问应用数据。VitePress 还附带了一些可以全局使用的内置组件。

全局 API 通过 vitepress 虚拟模块全局可用。

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

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

useData

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

interface VitePressData<T = any> {
  /**
   * 站点级元数据
   */
  site: Ref<SiteData<T>>
  /**
   * themeConfig from .vitepress/config.js
   */
  theme: Ref<T>
  /**
   * 页面级元数据
   */
  page: Ref<PageData>
  /**
   * 页面 frontmatter 数据
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * 动态路由参数
   */
  params: Ref<PageData['params']>
  /**
   * 页面标题 ref
   */
  title: Ref<string>
  /**
   * 页面描述 ref
   */
  description: Ref<string>
  /**
   * 当前语言环境
   */
  lang: Ref<string>
  /**
   * 当前语言环境
   */
  localeIndex: Ref<string>
  /**
   * 是否为深色主题
   */
  isDark: Ref<boolean>
  /**
   * 页面目录数据
   */
  dir: Ref<string>
}

interface SiteData<T = any> {
  base: string
  cleanUrls?: boolean
  lang: string
  dir: string
  title: string
  titleTemplate?: string | boolean
  description: string
  head: HeadConfig[]
  appearance?: boolean | 'dark'
  themeConfig?: T
  locales?: LocaleConfig<T>
  scrollOffset?: number | string
  contentProps?: Record<string, any>
}

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
}

interface Header {
  /**
   * 标题级别 `1` 到 `6`
   */
  level: number
  /**
   * 标题的标题
   */
  title: string
  /**
   * 标题的锚链接
   */
  anchor: string
  /**
   * 标题的子项
   */
  children: Header[]
}

示例：

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

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

<h1>{{ page.title }}</h1>
<p>当前主题配置：{{ theme }}</p>

useRouter

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

interface Router {
  /**
   * 当前路由
   */
  route: Route
  /**
   * 导航到 url
   */
  go: (to?: string) => Promise<void>
}

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

示例：

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

const router = useRouter()

function goToHome() {
  router.go('/')
}
</script>

useRoute

返回当前路由对象。

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

withBase

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

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

$frontmatter

直接访问当前页面的 frontmatter 数据。

---
title: Hello
---

# {{ $frontmatter.title }}

$params

直接访问当前页面的动态路由参数。

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