docs(pt) i18n: Create and translate `docs/pt/reference/runtime-api.md`

docs/pt/reference/runtime-api.md

@@ -0,0 +1,165 @@
+# 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)](https://vuejs.org/guide/scaling-up/sfc.html).
+
+Métodos que começam com `use*` indicam que é uma função da [API de Composição Vue 3](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") que só pode ser usada dentro de `setup()` ou `<script setup>`.
+
+## `useData` <Badge type="info" text="composable" />
+
+Retorna dados específicos da página. O objeto retornado possui o seguinte tipo:
+
+```ts
+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:**
+
+```vue
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme } = useData()
+</script>
+
+<template>
+  <h1>{{ theme.footer.copyright }}</h1>
+</template>
+```
+
+## `useRoute` <Badge type="info" text="composable" />
+
+Retorna o objeto de rota atual com o seguinte tipo:
+
+```ts
+interface Route {
+  path: string
+  data: PageData
+  component: Component | null
+}
+```
+
+## `useRouter` <Badge type="info" text="composable" />
+
+Retorna a instância do roteador VitePress para que você possa navegar programaticamente para outra página.
+
+```ts
+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` <Badge type="info" text="helper" />
+
+- **Tipo**: `(path: string) => string`
+
+Anexa o [`base`](./site-config#base) configurado a um caminho de URL fornecido. Veja também [Base URL](../guide/asset-handling#base-url).
+
+## `<Content />` <Badge type="info" text="component" />
+
+O componente `<Content />` exibe o conteúdo markdown renderizado. Útil [ao criar seu próprio tema](../guide/custom-theme).
+
+```vue
+<template>
+  <h1>Layout Personalizado!</h1>
+  <Content />
+</template>
+```
+
+## `<ClientOnly />` <Badge type="info" text="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`.
+
+```vue-html
+<ClientOnly>
+  <NonSSRFriendlyComponent />
+</ClientOnly>
+```
+
+- Relacionado: [Compatibilidade SSR](../guide/ssr-compat)
+
+## `$frontmatter` <Badge type="info" text="template global" />
+
+Acesse diretamente os dados [frontmatter](../guide/frontmatter) da página atual em expressões Vue.
+
+```md
+---
+title: Olá
+---
+
+# {{ $frontmatter.title }}
+```
+
+## `$params` <Badge type="info" text="template global" />
+
+Acesse diretamente os [parâmetros de rota dinâmica](../guide/routing#dynamic-routes) da página atual em expressões Vue.
+
+```md
+- nome do pacote: {{ $params.pkg }}
+- versão: {{ $params.version }}
+```