import{_ as i}from"./chunks/appearance-toggle-transition.Dpv85PEn.js";import{_ as a,c as n,ag as e,o as t}from"./chunks/framework.C1C4sYC0.js";const c=JSON.parse('{"title":"Estendendo o Tema Padrão","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"pt/guide/extending-default-theme.md","filePath":"pt/guide/extending-default-theme.md","lastUpdated":1736187882000}'),l={name:"pt/guide/extending-default-theme.md"};function p(h,s,k,r,d,E){return t(),n("div",null,s[0]||(s[0]=[e(`

Estendendo o Tema Padrão ​

O tema padrão do VitePress é otimizado para documentação e pode ser personalizado. Consulte a Visão Geral de Configuração do Tema Padrão para uma lista abrangente de opções.

No entanto, há casos em que apenas a configuração não será suficiente. Por exemplo:

  1. É necessário ajustar a estilização CSS;
  2. É necessário modificar a instância da aplicação Vue, por exemplo para registrar componentes globais;
  3. É necessário injetar conteúdo personalizado no tema por meio de slots no layout.

Essas personalizações avançadas exigirão o uso de um tema personalizado que "estende" o tema padrão.

TIP

Antes de prosseguir, certifique-se de ler primeiro Usando um Tema Personalizado para entender como temas personalizados funcionam.

Personalizando o CSS ​

O CSS do tema padrão pode ser personalizado substituindo as variáveis CSS no nível raiz:

.vitepress/theme/index.js
js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme
css
/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
}

Veja as variáveis CSS do tema padrão que podem ser substituídas.

Usando Fontes Diferentes ​

VitePress usa Inter como fonte padrão e incluirá as fontes na saída de compilação. A fonte também é pré-carregada automaticamente em produção. No entanto, isso pode não ser desejável se você quiser usar uma fonte principal diferente.

Para evitar a inclusão de Inter na saída de compilação, importe o tema de vitepress/theme-without-fonts:

.vitepress/theme/index.js
js
import DefaultTheme from 'vitepress/theme-without-fonts'
import './my-fonts.css'

export default DefaultTheme
css
/* .vitepress/theme/my-fonts.css */
:root {
  --vp-font-family-base: /* fonte de texto normal */
  --vp-font-family-mono: /* fonte de código */
}

WARNING

Se estiver usando componentes opcionais como os componentes da Página da Equipe, certifique-se de também importá-los de vitepress/theme-without-fonts!

Se a sua fonte é um arquivo local referenciado via @font-face, ela será processada como um ativo e incluída em .vitepress/dist/assets com um nome de arquivo hash. Para pré-carregar esse arquivo, use o gancho de construção transformHead:

.vitepress/config.js
js
export default {
  transformHead({ assets }) {
    // ajuste o regex para corresponder à sua fonte
    const myFontFile = assets.find(file => /font-name\\.\\w+\\.woff2/)
    if (myFontFile) {
      return [
        [
          'link',
          {
            rel: 'preload',
            href: myFontFile,
            as: 'font',
            type: 'font/woff2',
            crossorigin: ''
          }
        ]
      ]
    }
  }
}

Registrando Componentes Globais ​

.vitepress/theme/index.js
js
import DefaultTheme from 'vitepress/theme'

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // registre seus componentes globais personalizados
    app.component('MyGlobalComponent' /* ... */)
  }
}

Se estiver usando TypeScript:

.vitepress/theme/index.ts
ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // registre seus componentes globais personalizados
    app.component('MyGlobalComponent' /* ... */)
  }
} satisfies Theme

Como estamos usando Vite, você também pode aproveitar a funcionalidade de importação glob do Vite para registrar automaticamente um diretório de componentes.

Slots no Layout ​

O componente <Layout/> do tema padrão possui alguns slots que podem ser usados para injetar conteúdo em locais específicos da página. Aqui está um exemplo de como injetar um componente antes do esquema :

.vitepress/theme/index.js
js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  extends: DefaultTheme,
  // substitua o Layout por um componente envolvente que
  // injeta os slots
  Layout: MyLayout
}
.vitepress/theme/MyLayout.vue
vue
<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #aside-outline-before>
      Meu conteúdo personalizado superior da barra lateral
    </template>
  </Layout>
</template>

Ou você também pode usar a função render.

.vitepress/theme/index.js
js
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'aside-outline-before': () => h(MyComponent)
    })
  }
}

Lista completa de slots disponíveis no layout do tema padrão:

Usando a API View Transitions ​

Na Alternância de Aparência ​

Você pode estender o tema padrão para fornecer uma transição personalizada quando o modo de cor é alternado. Um exemplo:

.vitepress/theme/Layout.vue
vue
<script setup lang="ts">
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { nextTick, provide } from 'vue'

const { isDark } = useData()

const enableTransitions = () =>
  'startViewTransition' in document &&
  window.matchMedia('(prefers-reduced-motion: no-preference)').matches

provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
  if (!enableTransitions()) {
    isDark.value = !isDark.value
    return
  }

  const clipPath = [
    \`circle(0px at \${x}px \${y}px)\`,
    \`circle(\${Math.hypot(
      Math.max(x, innerWidth - x),
      Math.max(y, innerHeight - y)
    )}px at \${x}px \${y}px)\`
  ]

  await document.startViewTransition(async () => {
    isDark.value = !isDark.value
    await nextTick()
  }).ready

  document.documentElement.animate(
    { clipPath: isDark.value ? clipPath.reverse() : clipPath },
    {
      duration: 300,
      easing: 'ease-in',
      pseudoElement: \`::view-transition-\${isDark.value ? 'old' : 'new'}(root)\`
    }
  )
})
</script>

<template>
  <DefaultTheme.Layout />
</template>

<style>
::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
}

::view-transition-old(root),
.dark::view-transition-new(root) {
  z-index: 1;
}

::view-transition-new(root),
.dark::view-transition-old(root) {
  z-index: 9999;
}

.VPSwitchAppearance {
  width: 22px !important;
}

.VPSwitchAppearance .check {
  transform: none !important;
}
</style>

Resultado (atenção!: cores piscantes, movimentos súbitos, luzes brilhantes):

Demo

Demo de Transição de Alternância de Aparência

Consulte Chrome Docs para mais detalhes sobre view transitions.

Na Mudança de Rota ​

Em breve.

Substituindo Componentes Internos ​

Você pode usar os aliases Vite para substituir os componentes do tema padrão pelos seus personalizados:

ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    resolve: {
      alias: [
        {
          find: /^.*\\/VPNavBar\\.vue$/,
          replacement: fileURLToPath(
            new URL('./components/CustomNavBar.vue', import.meta.url)
          )
        }
      ]
    }
  }
})

Para saber o nome exato do componente consulte nosso código fonte. Como os componentes são internos, há uma pequena chance de que o nome deles seja atualizado entre lançamentos secundários.

`,45)]))}const y=a(l,[["render",p]]);export{c as __pageData,y as default};