vitepress/docs/ru/reference/runtime-api.md

description
Справочник по Runtime API VitePress, включая композаблы, вспомогательные функции и встроенные компоненты.

Runtime API

VitePress предлагает несколько встроенных API, позволяющих получить доступ к данным приложения. VitePress также поставляется с несколькими встроенными компонентами, которые можно использовать глобально.

Вспомогательные методы глобально импортируются из vitepress и обычно используются в компонентах Vue для пользовательских тем. Однако их можно использовать и внутри страниц .md, так как файлы markdown компилируются в однофайловые компоненты Vue.

Методы, начинающиеся с use*, указывают на то, что это функция Vue 3 Composition API («композабл»), которая может быть использована только внутри setup() или <script setup>.

useData

Возвращает данные, относящиеся к конкретной странице. Возвращаемый объект имеет следующий тип:

interface VitePressData<T = any> {
  /**
   * Метаданные на уровне сайта
   */
  site: Ref<SiteData<T>>
  /**
   * themeConfig из .vitepress/config.js
   */
  theme: Ref<T>
  /**
   * Метаданные на уровне страницы
   */
  page: Ref<PageData>
  /**
   * Метаданные страницы
   */
  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>
  /**
   * Текущий хеш адреса
   */
  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
}

page.headers заполняется только в том случае, если включён параметр markdown.headers. Без него это свойство остаётся пустым массивом. Оглавление в теме по умолчанию получает заголовки из уже отрендеренного содержимого страницы, поэтому оно может отображаться, даже если page.headers пуст.

Пример:

<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 {
  /**
   * Текущий маршрут.
   */
  route: Route
  /**
   * Переход к новому URL-адресу.
   */
  go: (to?: string) => Promise<void>
  /**
   * Вызывается перед изменением маршрута. Верните `false`, чтобы отменить навигацию.
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * Вызывается перед загрузкой компонента страницы (после того, как состояние истории
   * обновлено). Верните `false`, чтобы отменить навигацию.
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * Вызывается после загрузки компонента страницы (перед обновлением компонента страницы).
   */
  onAfterPageLoad?: (to: string) => Awaitable<void>
  /**
   * Вызывается после изменения маршрута.
   */
  onAfterRouteChange?: (to: string) => Awaitable<void>
}

Назначьте обработчики изменения маршрутов для экземпляра маршрутизатора:

const router = useRouter()

router.onBeforeRouteChange = (to) => {
  console.log('переход к', to)
}

В пользовательских темах этот же экземпляр маршрутизатора доступен через enhanceApp.

useIcon

• Тип: (icon: MaybeRefOrGetter<string | { svg: string } | undefined>, el?: MaybeRefOrGetter<HTMLElement | null>) => ComputedRef<string | undefined>

Отрисовывает иконку iconify через пайплайн иконок VitePress. Принимает полностью квалифицированное имя collection:name (разрешается относительно пакетов @iconify-json/* в зависимостях вашего проекта) и возвращает класс, который нужно поставить на элемент — vpi-<collection>-<name>.

Во время SSR имя регистрируется в SSGContext страницы, поэтому сборка добавляет стили иконки в сгенерированную таблицу стилей; в режиме разработки иконки отдаются dev-сервером по требованию из локально установленных коллекций. Ни одна иконка никогда не загружается с внешнего сервиса.

<script setup>
import { useIcon } from 'vitepress'
import { useTemplateRef } from 'vue'
const el = useTemplateRef('el')
const iconClass = useIcon('lucide:rocket', el)
</script>
<template>
  <span ref="el" :class="iconClass" />
</template>

Передайте шаблонную ссылку элемента, несущего класс, чтобы dev-режим мог разрешить на нём иконку. Элементу нужны правила mask, которые поставляются с темой по умолчанию; в кастомной теме без них dev применяет встроенный эквивалент, а сгенерированная таблица стилей включает базовые правила с нулевой специфичностью для продакшена.

При использовании темы по умолчанию компонент VPIcon из vitepress/theme оборачивает этот композабл (а также принимает сырую строку { svg }):

<VPIcon icon="lucide:rocket" />

Иконки, отрисовываемые только на клиенте (например, внутри <ClientOnly />), не могут быть собраны во время сборки — вместо этого перечислите их в icons.include.

withBase

• Тип: (path: string) => string

Добавляет настроенный base к заданному URL-пути. Также смотрите секцию Базовый URL.

<Content />

Компонент <Content /> отображает отрисованное содержимое Markdown. Полезно при создании собственной темы.

<template>
  <h1>Пользовательский макет!</h1>
  <Content />
</template>

<ClientOnly />

Компонент <ClientOnly /> отображает свой слот только на стороне клиента.

Поскольку приложения VitePress при генерации статических сборок рендерятся в Node.js, любое использование Vue должно соответствовать универсальным требованиям к коду. Короче говоря, убедитесь, что доступ к API Browser / DOM осуществляется только в хуках beforeMount или mounted.

Если вы используете или демонстрируете компоненты, которые не являются SSR-дружественными (например, содержат пользовательские директивы), вы можете обернуть их внутри компонента ClientOnly.

<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>

• См. также: Совместимость с SSR

$frontmatter

Прямой доступ к метаданным текущей страницы в выражениях Vue.

---
title: Привет
---

# {{ $frontmatter.title }}

$params

Прямой доступ к параметрам динамических маршрутов текущей страницы в выражениях Vue.

- имя пакета: {{ $params.pkg }}
- версия: {{ $params.version }}