API em Tempo de Execução

VitePress oferece várias APIs embutidas para permitir o acesso aos dados da aplicação. VitePress vem também com alguns componentes embutidos que podem ser usados globalmente.

Os métodos auxiliares são importáveis globais de vitepress e geralmente são usados em componentes Vue de temas personalizados. No entanto, eles também podem ser usados dentro de páginas .md porque os arquivos markdown são compilados em Componentes de Arquivo Único Vue (SFC).

Métodos que começam com use* indicam que é uma função da API de Composição Vue 3 ("Composable") que só pode ser usada dentro de setup() ou <script setup>.

useData composable

Retorna dados específicos da página. O objeto retornado possui o seguinte tipo:

interface VitePressData<T = any> {
  /**
   * Metadados do nível do site
   */
  site: Ref<SiteData<T>>
  /**
   * themeConfig de .vitepress/config.js
   */
  theme: Ref<T>
  /**
   * Metadados do nível da página
   */
  page: Ref<PageData>
  /**
   * Frontmatter da página
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * Parâmetros dinâmicos da rota
   */
  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
}

Exemplo:

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

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

<template>
  <h1>{{ theme.footer.copyright }}</h1>
</template>

useRoute composable

Retorna o objeto de rota atual com o seguinte tipo:

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

useRouter composable

Retorna a instância do roteador VitePress para que você possa navegar programaticamente para outra página.

interface Router {
  /**
   * Rota atual.
   */
  route: Route
  /**
   * Navegar para uma nova URL.
   */
  go: (to?: string) => Promise<void>
  /**
   * Chamado antes da mudança de rota. Retorne `false` para cancelar a navegação.
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * Chamado antes do carregamento do componente da página (depois que o estado do histórico é
   * atualizado). Retorne `false` para cancelar a navegação.
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * Chamado após a mudança de rota.
   */
  onAfterRouteChanged?: (to: string) => Awaitable<void>
}

withBase helper

• Tipo: (path: string) => string

Anexa o base configurado a um caminho de URL fornecido. Veja também Base URL.

<Content /> component

O componente <Content /> exibe o conteúdo markdown renderizado. Útil ao criar seu próprio tema.

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

<ClientOnly /> component

O componente <ClientOnly /> revela seu slot apenas no lado do cliente.

Como as aplicações VitePress são interpretadas no lado do servidor em Node.js ao gerar builds estáticos, qualquer uso do Vue deve seguir os requisitos de código universal. Em resumo, certifique-se de acessar apenas APIs do Navegador / DOM em ganchos beforeMount ou mounted.

Se você estiver usando ou demonstrando componentes que não são compatíveis com SSR (por exemplo, contêm diretivas personalizadas), você pode envolvê-los dentro do componente ClientOnly.

<ClientOnly>
  <NonSSRFriendlyComponent />
</ClientOnly>

• Relacionado: Compatibilidade SSR

$frontmatter template global

Acesse diretamente os dados frontmatter da página atual em expressões Vue.

---
title: Olá
---

# {{ $frontmatter.title }}

$params template global

Acesse diretamente os parâmetros de rota dinâmica da página atual em expressões Vue.

- nome do pacote: {{ $params.pkg }}
- versão: {{ $params.version }}