运行时 API

更新于

总字数 0

阅读量

此页面展示了 VitePress 一些常用的 运行时 API，它可以让你访问站点内部的应用程序数据。

注意

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

useData

返回特定页面的数据，可用于访问当前页面的网站、主题和页面数据，它在 .md 和 .vue 文件中都有效。

数据类型

interface VitePressData<T = any> {
  /**
   * 站点级元数据
   */
  site: Ref<SiteData<T>>
  /**
   * .vitepress/config.js 中的 themeConfig
   */
  theme: Ref<T>
  /**
   * 页面级元数据
   */
  page: Ref<PageData>
  /**
   * 页面 frontmatter
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * 动态路由参数
   */
  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, page, frontmatter } = useData()
</script>

主题数据
<pre>{{ theme }}</pre>

页面数据
<pre>{{ page }}</pre>

页面格式
<pre>{{ frontmatter }}</pre>

数据展示

frontmatter数据

    {
  "title": "运行时 API",
  "description": "VitePress 运行时 API 示例",
  "tags": [
    "vitepress"
  ]
}
  

useRouter

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

数据类型

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

interface Router {
  /**
   * 当前路由
   */
  route: Route
  /**
   * 导航到新的 URL
   */
  go: (to?: string) => Promise<void>
  /**
   * 在路由更改前调用。返回 `false` 表示取消导航
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * 在页面组件加载前（history 状态更新后）调用。返回 `false` 表示取消导航
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * 在页面组件加载后（页面组件实际更新前）调用
   */
  onAfterPageLoad?: (to: string) => Awaitable<void>
  /**
   * 在路由更改后调用
   */
  onAfterRouteChanged?: (to: string) => Awaitable<void>
}

用法示例

<a @click="goUseRouter">点我去 userouter</a>

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

const routeData = useRouter()

const goUseRouter = () => {
  routeData.go(routeData.route.path + '#userouter')
}
</script>

效果展示

点我去 userouter

withBase

将配置的 URL 路径 追加到给定的 URL 路径 (也许是根目录下)。另请参阅 Base URL。

参数类型

withBase(path: string) => string

用法示例

<img width="100" :src="withBase('../../logo.png')" alt="head-avatar" />
<img width="100" :src="withBase(theme.logoPath)" alt="head-avatar" />

<script setup lang="ts">
import { withBase } from 'vitepress'

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

提示

此示例中，../../logo.png 是 logo图片 相对于本文档的位置，theme.logoPath 则是站点数据配置中的 logo图片 位置，两者都指向了同一个图片。

效果展示

$frontmatter

在 Vue 表达式中直接访问当前页面的 frontmatter 数据，效果等同于 useData() 里的 frontmatter。

用法示例

<pre>{{ $frontmatter }}</pre>

数据展示

    {
  "title": "运行时 API",
  "description": "VitePress 运行时 API 示例",
  "tags": [
    "vitepress"
  ]
}
  

更多

请查看官方文档 VitePress 运行时 API。