---
url: /api/sfc-script-setup.md
---
# `<script setup>` {#script-setup}

`<script setup>` é um açúcar sintático do tempo de compilação para o uso da API de Composições dentro dos Componentes de Ficheiro Único (isto é, `*.vue`). É a sintaxe recomendada se estivermos a usar ambos Componentes de Ficheiro Único e API de Composição. Ele fornece um número de vantagens sobre a sintaxe de `<script>` normal:

- Código mais sucinto com menos padrões
- Habilidade de declarar as propriedades e eventos emitidos usando TypeScript puro
- Melhor desempenho de tempo de execução (o modelo de marcação é compilado numa função de interpretação no mesmo âmbito de aplicação, sem uma delegação intermediária)
- Melhor desempenho de inferência de tipo do ambiente de desenvolvimento integrado (menos trabalho para o servidor de linguagem para extrair tipos a partir do código).

## Sintaxe Básica {#basic-syntax}

Para optar pela sintaxe, adicione o atributo `setup` ao bloco `<script>`:

```vue
<script setup>
console.log('hello script setup')
</script>
```

O código dentro é compilado como conteúdo da função `setup()` do componente. Isto significa que ao contrário do `<script>` normal, o qual é executado apenas uma vez quando o componente é importado primeiro, o código dentro de `<script setup>` **executará todas as vezes que uma instância do componente for criada**.

### Vínculos de Alto Nível são Expostos ao Modelo de Marcação {#top-level-bindings-are-exposed-to-template}

Quando usamos `<script setup>`, quaisquer vínculos de alto nível (incluindo variáveis, declarações de função e importações) declaradas dentro do `<script setup>` são diretamente usáveis no modelo de marcação:

```vue
<script setup>
// variável
const msg = 'Hello!'

// funções
function log() {
  console.log(msg)
}
</script>

<template>
  <button @click="log">{{ msg }}</button>
</template>
```

As importações são expostas da mesma maneira. Isto significa que podemos usar diretamente uma função auxiliar importada nas expressões do modelo de marcação sem ter de a expor através da opção `methods`:

```vue
<script setup>
import { capitalize } from './helpers'
</script>

<template>
  <div>{{ capitalize('hello') }}</div>
</template>
```

## Reatividade {#reactivity}

O estado reativo precisa de ser explicitamente criado usando as [APIs de Reatividade](./reactivity-core). Semelhante aos valores retornados a partir duma função `setup()`, as referências são automaticamente desembrulhadas quando referenciadas nos modelos de marcação:

```vue
<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>
```

## Usando Componentes {#using-components}

Os valores no âmbito de `<script setup>` também podem ser usados diretamente como nomes de marcador de componente personalizados:

```vue
<script setup>
import MyComponent from './MyComponent.vue'
</script>

<template>
  <MyComponent />
</template>
```

Pense de `MyComponent` como sendo referenciado como uma variável. Se usávamos JSX, neste contexto o modelo mental é semelhante. O `<my-component>` equivalente de caixa-espetada também funciona no modelo de marcação - no entanto os marcadores de componente de CaixaPascal são fortemente recomendados por fins de consistência. Também ajuda a diferenciar dos elementos personalizados nativos.

### Componentes Dinâmicos {#dynamic-components}

Uma vez que os componentes são referenciados como variáveis ao invés de registados sob chaves de sequência de caracteres, devemos usar o vínculo `:is` dinâmico quando usamos componentes dinâmicos dentro de `<script setup>`:

```vue
<script setup>
import Foo from './Foo.vue'
import Bar from './Bar.vue'
</script>

<template>
  <component :is="Foo" />
  <component :is="someCondition ? Foo : Bar" />
</template>
```

Nota como os componentes podem ser usados como variáveis numa expressão de ternário.

### Componentes Recursivos {#recursive-components}

Um componente de ficheiro único pode referir-se a si mesmo implicitamente através do nome de ficheiro. Por exemplo, um ficheiro nomeado `FooBar.vue` pode referir-se a si mesmo como `<FooBar/>` no seu modelo de marcação.

Nota que isto tem prioridade menor do que os componentes importados. Se tivermos uma importação nomeada que entra em conflito com o nome inferido do componente, podemos definir um pseudónimo para a importação:

```js
import { FooBar as FooBarChild } from './components'
```

### Componentes de Nomes Espaçados {#namespaced-components}

Nós podemos usar marcadores de componente com pontos tal como `<Foo.Bar>` para referir-se aos componentes encaixados sob propriedades de objeto. Isto é útil quando importamos vários componentes a partir dum único ficheiro:

```vue
<script setup>
import * as Form from './form-components'
</script>

<template>
  <Form.Input>
    <Form.Label>label</Form.Label>
  </Form.Input>
</template>
```

## Usando Diretivas Personalizadas {#using-custom-directives}

As diretivas personalizadas registadas globalmente funcionam exatamente como esperado. As diretivas personalizadas locais não precisam de ser explicitamente registadas com o `<script setup>`, mas devem seguir o esquema de nomeação `vNameOfDirective`:

```vue
<script setup>
const vMyDirective = {
  beforeMount: (el) => {
    // fazer algo com o elemento
  }
}
</script>
<template>
  <h1 v-my-directive>This is a Heading</h1>
</template>
```

Se estivermos a importar uma diretiva a partir doutro lugar, pode ser renomeada para ajustar-se ao esquema de nomeação exigido:

```vue
<script setup>
import { myDirective as vMyDirective } from './MyDirective.js'
</script>
```

## `defineProps()` e `defineEmits()` {#defineprops-defineemits}

Para declarar opções tais como `props` e `emits` com o suporte total a inferência de tipo, podemos usar as APIs `defineProps` e `defineEmits`, as quais estão automaticamente disponíveis dentro do `<script setup>`:

```vue
<script setup>
const props = defineProps({
  foo: String
})

const emit = defineEmits(['change', 'delete'])
// código de configuração
</script>
```

- `defineProps` e `defineEmits` são **macros de compilador** utilizáveis apenas dentro de `<script setup>`. Eles não precisam de ser importados, e são compilados quando `<script setup>` é processado.

- `defineProps` aceita o mesmo valor que a opção `props`, enquanto `defineEmits` aceita o mesmo valor que a opção `emits`.

- `defineProps` e `defineEmits`  fornecem inferência de tipo adequada baseada nas opções passadas.

- As opções passadas às `defineProps` e `defineEmits` serão içadas para fora da configuração no âmbito do módulo. Portanto, as opções não podem referenciar as variáveis locais declaradas no âmbito de configuração. Fazer isto resultará num erro de compilação. No entanto, _pode_ referenciar vínculos importados uma vez que também estão no âmbito do módulo.

### Declarações de Propriedades ou Emissões de Tipo Exclusivo <sup class="vt-badge ts" data-text="typescript" /> {#type-only-props-emit-declarations}

As propriedades e emissões também podem ser declaradas usando a sintaxe de tipo pura passando um argumento de tipo literal à `defineProps` ou `defineEmits`:

```ts
const props = defineProps<{
  foo: string,
  bar?: number
}>()

const emit = defineEmits<{
  (e: 'change', id: number): void,
  (e: 'update', value: string): void
}>

// 3.3+: alternativa, sintaxe mais sucinta
const emit = defineEmits<{
  change: [id: number] // sintaxe de tupla nomeada
  update: [value: string]
}>
```

- `defineProps` ou `defineEmits` apenas pode usar ou a declaração de tempo de execução OU a declaração de tipo. Usar ambas ao mesmo tempo resultará num erro de compilação.

- Quando usamos a declaração de tipo, a declaração de tempo de execução equivalente é automaticamente gerada a partir da analise estática para remover a necessidade de dupla declaração e continuar a garantir comportamento de tempo de execução correto.

  - No modo de desenvolvimento, o compilador tentará inferir a validação de tempo de execução correspondente a partir dos tipos. Por exemplo `foo: String` é inferido a partir do tipo de `foo: string`. Se o tipo for uma referência à um tipo importado, o resultado inferido será `foo: null` (igual ao tipo `any`) uma vez que o compilador não tem a informação dos ficheiros externos.

  - No modo de produção, o compilador gerará o declaração de formato de vetor para reduzir o tamanho do pacote (as propriedades serão compiladas para `['foo', 'bar']`)

- Na versão 3.2 e para baixo, o parâmetro de tipo genérico para `defineProps()` estava limitado à um literal de tipo ou uma referência à uma interface local.

  Esta limitação tinha sido resolvida na 3.3. A versão mais recente da Vue suporta referência importada e um conjunto limitado de tipos complexos na posição do parâmetro de tipo. No entanto, uma vez que o tipo para a conversão de tempo de execução ainda é baseado na árvore de sintaxe abstrata, alguns tipos complexos que exigem de fato a analise de tipo, por exemplo tipos condicionais, não são suportados. Nós podemos usar os tipos condicionais para o tipo duma única propriedade, mas não para o objeto de propriedades inteiro.

### Valores de Propriedades Padrão Quando Usamos Declaração de Tipo {#default-props-values-when-using-type-declaration}

Uma desvantagem da declaração de `defineProps` de tipo exclusivo é que não tem uma maneira de fornecer valores padrão para as propriedades. Para resolver este problema, uma macro do compilador `withDefaults` também é fornecida:

```ts
export interface Props {
  msg?: string
  labels?: string[]
}

const props = withDefaults(defineProps<Props>(), {
  msg: 'Hello',
  labels: () => ['one', 'two']
})
```

Isto será compilado às opções `default` de propriedades de tempo de execução equivalentes. Além disto, a auxiliar `withDefaults` fornece verificações de tipo para os valores padrão, e garante que o tipo de `props` retornado tenha as opções opcionais removidas para as propriedades que têm os valores padrão declarados.

## `defineModel()` <sup class="vt-badge" data-text="3.4+" /> {#definemodel}

Esta macro pode ser usada para declarar uma propriedade de vínculo bi-direcional que pode ser consumida através da `v-model` a partir do componente pai. O uso do exemplo também é discutido no guia [Componente `v-model`](/guide/components/v-model).

Nos bastidores, esta macro declara uma propriedade modelo e um evento de atualização do valor correspondente. Se o primeiro argumento for uma sequência de caracteres literal, esta será usada como nome da propriedade; De outro modo o nome da propriedade predefinirá ao `"modelValue"`. Em ambos casos, também podes passar um objeto adicional que pode incluir as opções da propriedade e as opções de transformação do valor da referência.

```js
// declara a propriedade "modelValue",
// consumida pelo pai através da `v-model`
const model = defineModel()
// OU: declara a propriedade "modelValue" com as opções
const model = defineModel({ type: String })

// emite "update:modelValue" quando alterada
model.value = 'hello'

// declara a propriedade "count",
// consumida pelo pai através da `v-model:count`
const count = defineModel('count')
// OU: declara a propriedade "count" com opções
const count = defineModel('count', { type: Number, default: 0 })

function inc() {
  // emite "update:count" quando alterada
  count.value++
}
```

:::warning AVISO
Se tivermos um valor `default` para a propriedade de `defineModel` e não fornecermos nenhum valor a esta propriedade do componente pai, isso pode causar uma dessincronização entre os componentes pai e filho. No exemplo abaixo, a `myRef` do componente pai é indefinida, mas o `model` do componente filho é `1`:

```js
// componente filho
const model = defineModel({ default: 1 })

// componente pai
const myRef = ref()
```

```html
<child v-model="myRef"></child>
```

:::

### Modificadores e Transformadores {#modifiers-and-transformers}

Para acessar os modificadores usados com a diretiva `v-model`, podemos desestruturar o valor de retorno da `defineModel()` como este:

```js
const [modelValue, modelModifiers] = defineModel()

// corresponde a `v-model.trim`
if (modelModifiers.trim) {
  // ...
}
```

Quando um modificador estiver presente, provavelmente precisaremos transformar o valor quando o lemos ou sincronizamos de volta ao pai. Nós podemos alcançar isto usando as opções `get` e `set` do transformador:

```js
const [modelValue, modelModifiers] = defineModel({
  // `get()` omitido porque não é necessário neste exemplo
  set(value) {
    // se o modificador `.trim` for usado,
    // retorna o valor aparado
    if (modelModifiers.trim) {
      return value.trim()
    }
    // de outro modo, retorna o valor como está
    return value
  }
})
```

### Uso com a TypeScript <sup class="vt-badge ts" data="typescript" /> {#usage-with-typescript}

Tal como a `defineProps` e a `defineEmits`, a `defineModel` também pode receber argumentos de tipo para especificar os tipos do valor do modelo e dos modificadores:

```ts
const modelValue = defineModel<string>()
//    ^? Ref<string | undefined>

// predefinir modelo com opções,
// `required` remove possíveis valores indefinidos
const modelValue = defineModel<string>({ required: true })
//    ^? Ref<string>

const [modelValue, modifiers] = defineModel<string, 'trim' | 'uppercase'>()
//                 ^? Record<'trim' | 'uppercase', true | undefined>
```

## `defineExpose()` {#defineexpose}

Os componentes usando `<script setup>` estão **fechados por padrão** - isto quer dizer que, a instância pública do componente, a qual é recuperada através das referências do modelo de marcação ou cadeias de `$parent`, **não** exporão quaisquer vínculos declarados dentro do `<script setup>`.

Para expor explicitamente as propriedades num componente de `<script setup>`, usamos a macro do compilador `defineExpose`:

```vue
<script setup>
import { ref } from 'vue'

const a = 1
const b = ref(2)

defineExpose({
  a,
  b
})
</script>
```

Quando um pai recebe uma instância deste componente através das referências do componente, a instância recuperada será da forma `{ a: number, b: number }` (as referências são automaticamente desembrulhadas tal como nas instâncias normais).

## `defineOptions()` <sup class="vt-badge" data-text="3.3+" /> {#defineoptions}

Esta macro pode ser usada para declarar opções de componente diretamente de dentro do `<script setup>` sem ter de usar um bloco `<script>` separado:

```vue
<script setup>
defineOptions({
  inheritAttrs: false,
  customOptions: {
    /* ... */
  }
})
</script>
```

- Suportada apenas na 3.3+
- Isto é uma macro, As opções serão içadas para o âmbito de módulo e não podem acessar variáveis locais no `<script setup>` que não são constantes literais.

## `defineSlots()` <sup class="vt-badge ts" data-text="typescript" /> {#defineslots}

Esta macro pode ser usada para fornecer sugestões de tipo aos ambientes de desenvolvimento integrado para nome de ranhura e verificação de tipo de propriedades.

`defineSlots()` apenas aceita um parâmetro de tipo e nenhum argumento de tempo de execução. O parâmetro de tipo deve ser um literal de tipo onde a chave da propriedade é o nome da ranhura, e o tipo de valor é a função da ranhura. O primeiro argumento da função é o objeto de propriedades que a ranhura espera receber, e o seu tipo será usado para as propriedades da ranhura no modelo de marcação. O tipo de retorno é atualmente ignorado e pode ser `any`, mas podemos influenciá-lo para verificação do conteúdo da ranhura no futuro.

Esta também retorna o objeto `slots`, o qual é equivalente ao objeto `slots` exposto sobre o contexto de configuração ou retornado pela `useSlots()`:

```vue
<script setup>
const slots = defineSlots<{
  default(props: { msg: string }): any
}>()
</script>
```

- Suportada apenas na 3.3+

## `useSlots()` e `useAttrs()` {#useslots-useattrs}

O uso de `slots` e `attrs` dentro do `<script setup>` deve ser relativamente raro, uma vez que podemos acessá-los diretamente como `$slots` e `$attrs` no modelo de marcação. No caso raro onde de fato precisamos deles, usamos as auxiliares `useSlots` e `useAttrs` respetivamente:

```vue
<script setup>
import { useSlots, useAttrs } from 'vue'

const slots = useSlots()
const attrs = useAttrs()
</script>
```

`useSlots` e `useAttrs` são de fato funções de tempo de execução que retornam o equivalente de `setupContext.slots` e `setupContext.attrs`. Elas também podem ser usadas nas funções da API de composição normais.

## Uso ao Lado do `<script>` Normal {#usage-alongside-normal-script}

`<script setup>` pode ser usado ao lado do `<script>` normal. Um `<script>` normal pode ser necessário nos casos onde precisamos de:

- Declarar opções que não podem ser expressadas no `<script setup>`, por exemplo `inheritAttrs` ou opções personalizadas ativadas através de extensões (Pode ser substituído pela [`defineOptions`](/api/sfc-script-setup#defineoptions) na 3.3+).
- Declarar exportações nomeadas
- Executar efeitos colaterais ou criar objetos que apenas devem executar uma vez.

```vue
<script>
// <script> normal, executado no âmbito de módulo (apenas uma vez)
runSideEffectsOnce()

// declarar opções adicionais
export default {
  inheritAttrs: false,
  customOptions: {}
}
</script>

<script setup>
// executado no âmbito da `setup()` (para cada instância)
</script>
```

O suporte para combinação de `<script setup>` e `<script>` no mesmo componente está limitado aos cenários descritos acima. Especificamente:

- **NÃO** usar uma seção `<script>` separada para opções que já podem ser definidas usando `<script setup>`, tais como `props` e `emits`.
- As variáveis criadas dentro do `<script setup>` não são adicionadas como propriedades à instância do componente, tornando-as inacessíveis a partir da API de Opções. Misturar APIs desta maneira é fortemente desencorajado.

Se encontramos-nos em um dos cenários que não é suportado devemos considerar mudar para uma função [`setup()`](/api/composition-api-setup) explícita, ao invés de usar `<script setup>`.

## Espera de Alto Nível {#top-level-await}

A `await` de alto nível pode ser usada dentro do `<script setup>`. O código resultante será compilado tal como `async setup()`:

```vue
<script setup>
const post = await fetch(`/api/post/1`).then((r) => r.json())
</script>
```

Além disto, a expressão esperada será automaticamente compilada num formato que preserva o contexto da instância do componente atual depois de `await`.

:::warning NOTA
`async setup()` deve ser usado em conjunto com o `Suspense`, o qual atualmente ainda é uma funcionalidade experimental. Nós planeamos finalizar e documentá-lo num futuro lançamento - mas se agora estivermos curiosos, podemos consultar os seus [testes](https://github.com/vuejs/core/blob/main/packages/runtime-core/__tests__/components/Suspense.spec.ts) para sabermos como funciona.
:::

## Genéricos <sup class="vt-badge ts" data-text="typescript" /> {#generics}

Os parâmetros de tipo genérico podem ser declarados usando o atributo `generic` sobre o marcador `<script>`:

```vue
<script setup lang="ts" generic="T">
defineProps<{
  items: T[]
  selected: T
}>()
</script>
```

O valor de `generic` funciona exatamente como a lista de parâmetro entre `<...>` na TypeScript. Por exemplo, podemos usar vários parâmetros, restrições de `extends`, tipos padrão, e referenciar tipos importados:

```vue
<script
  setup
  lang="ts"
  generic="T extends string | number, U extends Item"
>
import type { Item } from './types'
defineProps<{
  id: T
  list: U[]
}>()
</script>
```

## Restrições {#restrictions}

- Por causa da diferença na semântica da execução do módulo, o código dentro do `<script setup>` depende do contexto dum componente de ficheiro único. Quando movido aos ficheiros `.js` ou `.ts` externos, este pode confundir ambos programadores e ferramentas. Portanto, **`<script setup>`** não pode ser usado com o atributo `src`.
- `<script setup>` não suporta o Modelo de Marcação de Componente de Raiz Embutido no DOM. ([Discussão Relacionada](https://github.com/vuejs/core/issues/8391)).

---

---
url: /guide/best-practices/accessibility.md
---
# Acessibilidade {#accessibility}

A acessibilidade da web (também conhecida como a11y) refere-se a prática de criar páginas e aplicações de web que podem ser usadas por qualquer um — seja essa uma pessoa com uma deficiência, uma conexão lenta, hardware destroçado ou desatualizado ou simplesmente alguém em um ambiente desfavorável. Por exemplo, adicionar legendas à um vídeo ajuda tanto os teus utilizadores surdos e com dificuldades de audição quanto os teus utilizadores que estão em um ambiente ruidoso e que não podem ouvir seus telemóveis. Similarmente, certificar-te que o teu texto não é de muito contraste muito baixo ajudará tanto os teus utilizadores de visão fraca quanto os teus utilizadores que estão a tentar usar os seus telemóveis na luz do sol forte.

Pronto para começar mas não sem a certeza de por onde?

Consulte o [guia de planeamento e gerência da acessibilidade da web](https://www.w3.org/WAI/planning-and-managing/) fornecido pelo [Consórcio da World Wide Web (W3C)](https://www.w3.org/)

## Ligação de Salto {#skip-link}

Tu deves adicionar uma ligação no topo de cada página que vai diretamente para a área do conteúdo principal assim os utilizadores podem salter o conteúdo que é repetido em várias páginas de Web.

Normalmente, isto é feito no topo de `App.vue` visto que será o primeiro elemento concentrável em todas as tuas páginas:

```vue-html
<ul class="skip-links">
  <li>
    <a href="#main" ref="skipLink" class="skip-link">Skip to main content</a>
  </li>
</ul>
```

Para esconder a ligação se não ela é focada, podes adicionar o seguinte estilo:

```css
.skip-link {
  white-space: nowrap;
  margin: 1em auto;
  top: 0;
  position: fixed;
  left: 50%;
  margin-left: -72px;
  opacity: 0;
}
.skip-link:focus {
  opacity: 1;
  background-color: white;
  padding: 0.5em;
  border: 1px solid black;
}
```

Uma vez que o utilizador mudar a rota, traga o foco de volta para a ligação saltar. Isto pode ser alcançado chamando o foco na referência do modelo de marcação da ligação saltar (assumindo o uso da `vue-router`):

<div class="options-api">

```vue
<script>
export default {
  watch: {
    $route() {
      this.$refs.skipLink.focus()
    }
  }
}
</script>
```

</div>
<div class="composition-api">

```vue
<script setup>
import { ref, watch } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()
const skipLink = ref()

watch(
  () => route.path,
  () => {
    skipLink.value.focus()
  }
)
</script>
```

</div>

[Leia a documentação sobre a ligação "saltar para o conteúdo principal"](https://www.w3.org/WAI/WCAG21/Techniques/general/G1.html)

## Estrutura de Conteúdo {#content-structure}

Um dos pedaços mais importantes da acessibilidade é garantir que o desenho possa suportar a implementação acessível. O desenho deve considerar não apenas o contraste de cor, seleção de fonte, tamanho de texto, e linguagem mas também como o conteúdo é estruturado na aplicação.

### Cabeçalhos {#headings}

Os utilizadores podem navegar em uma aplicação através dos cabeçalhos. Ter cabeçalhos descritivos para cada seção da tua aplicação torna mais fácil para os utilizadores prever o conteúdo de cada seção. Quando falamos de cabeçalhos, existem algumas práticas de acessibilidade recomendadas:

- Encaixar cabeçalhos nas suas ordem de classificação: `<h1>` - `<h6>`
- Não saltar cabeçalhos dentro de uma seção
- Usar marcadores de cabeçalho verdadeiros ao invés da estilização de texto para dar a aparência visual dos cabeçalhos

[Leia mais sobre cabeçalhos](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-descriptive.html):

```vue-html
<main role="main" aria-labelledby="main-title">
  <h1 id="main-title">Main title</h1>
  <section aria-labelledby="section-title">
    <h2 id="section-title"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Content -->
  </section>
  <section aria-labelledby="section-title">
    <h2 id="section-title"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Content -->
    <h3>Section Subtitle</h3>
    <!-- Content -->
  </section>
</main>
```

### Marcos {#landmarks}

Os [marcos](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) fornecem acesso programático às seções dentro de uma aplicação. Os utilizadores que dependem de tecnologia ajustantes podem navegar para cada seção da aplicação e saltar sobre o conteúdo. Tu podes usar os [papeis de ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) para ajudar-te a alcançar isto.

| HTML            | Papeis de ARIA            | Propósito do Marco                                                                                                |
| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| header          | role="banner"        | Cabeçalho principal: título da página.                                                                                 |
| nav             | role="navigation"    | Coleção de ligações adequadas para uso quando estiveres a navegar pelo documento ou documentos relacionados.                          |
| main            | role="main"          | O conteúdo principal ou central do documento.                                                                    |
| footer          | role="contentinfo"   | Informação sobre o documento pai: notas de rodapé ou direitos de autor ou ligações para o relatório de privacidade.                         |
| aside           | role="complementary" | Sustenta o conteúdo principal, mais é separado e significativo em seu próprio conteúdo.                                 |
| search | role="search"        | Esta seção contém a funcionalidade de pesquisa para a aplicação.                                            |
| form            | role="form"          | Coleção de elementos associados ao formulário.                                                                         |
| section         | role="region"        | O conteúdo que é relevante e para o qual os utilizadores provavelmente quererão navegar. O rótulo deve ser fornecido para este elemento.|

:::tip DICA:
É recomendado usar os elementos de HTML de marco com atributos do papel do marco redundante para maximizar a compatibilidade com [navegadores antigos que não suportam os elementos semânticos da HTML5](https://caniuse.com/#feat=html5semantic).
:::

[Leia mais sobre os marcos](https://www.w3.org/TR/wai-aria-1.2/#landmark_roles)

## Formulários Semânticos {#semantic-forms}

Quando criares um formulário, podes usar os seguintes elementos: `<form>`, `<label>`, `<input>`, `<textarea>`, e `<button>`.

Os rótulos são normalmente colocados no princípio ou a esquerda dos campos do formulário:

```vue-html
<form action="/dataCollectionLocation" method="post" autocomplete="on">
  <div v-for="item in formItems" :key="item.id" class="form-item">
    <label :for="item.id">{{ item.label }}: </label>
    <input
      :type="item.type"
      :id="item.id"
      :name="item.id"
      v-model="item.value"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

<!-- <common-codepen-snippet title="Simple Form" slug="dyNzzWZ" :height="368" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

Nota como podes incluir `autocomplete='on'` no elemento de formulário e aplicar-se-á à todas entradas no teu formulário. Tu podes também definir [valores diferentes para o atributo `autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) para cada entrada.

### Rótulos {#labels}

Forneça rótulos para descrever o propósito de todos os mecanismo de controlo do formulário: ligando `for` e `id`:

```vue-html
<label for="name">Name</label>
<input type="text" name="name" id="name" v-model="name" />
```

<!-- <common-codepen-snippet title="Form Label" slug="XWpaaaj" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

Se inspecionares este elemento nas ferramentas de programação do teu navegador Google Chrome e abrires a aba de Acessibilidade dentro da aba de Elementos, verás como a entrada recebe o seu nome a partir do rótulo:

![Ferramentas de Programação do Chrome exibindo o nome acessível da entrada do rótulo](./images/AccessibleLabelChromeDevTools.png)

:::warning Aviso:
Embora tenhas visto rótulos envolvendo os campos de entrada como este:

```vue-html
<label>
  Name:
  <input type="text" name="name" id="name" v-model="name" />
</label>
```

A definição explícita dos rótulos com um identificador correspondente é melhor suportado pela tecnologia ajudante.
:::

#### `aria-label` {#aria-label}

Tu podes também atribuir a entrada um nome acessível com o [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label):

```vue-html
<label for="name">Name</label>
<input
  type="text"
  name="name"
  id="name"
  v-model="name"
  :aria-label="nameLabel"
/>
```

<!-- <common-codepen-snippet title="Form ARIA label" slug="NWdvvYQ" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

Esteja a vontade para inspecionar este elemento nas Ferramentas de Programação do Chrome para veres como o nome acessível tem mudado:

![Ferramentas de Programação do Chrome exibindo o nome acessível da entrada do `aria-label`](./images/AccessibleARIAlabelDevTools.png)

#### `aria-labelledby` {#aria-labelledby}

O uso de [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) é parecido com o `aria-label` exceto que é usado se o texto do rótulo estiver visível na tela. É emparelhado com os outros elementos pelo seu `id` e podes ligar vários `id`:

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Name:</label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

<!-- <common-codepen-snippet title="Form ARIA labelledby" slug="MWJvvBe" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

![Ferramentas de Programação do Chrome exibindo o nome acessível da entrada do `aria-labelledby`](./images/AccessibleARIAlabelledbyDevTools.png)

#### `aria-describedby` {#aria-describedby}

O [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) é usado da mesma maneira que o `aria-labelledby` exceto que fornece uma descrição com informação adicional que o utilizador possa precisar. Isto pode ser usado para descrever o critério para qualquer entrada:

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Full Name:</label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
      aria-describedby="nameDescription"
    />
    <p id="nameDescription">Please provide first and last name.</p>
  </div>
  <button type="submit">Submit</button>
</form>
```

<!-- <common-codepen-snippet title="Form ARIA describedby" slug="gOgxxQE" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

Tu podes ver a descrição inspecionando as Ferramentas de Programação do Chrome:

![Ferramentas de Programação do Chrome exibindo o nome acessível da entrada do `aria-labelledby` e a descrição com o `aria-describedby`](./images/AccessibleARIAdescribedby.png)

### Espaço Reservado {#placeholder}

Evite usar espaços reservados visto que podem confundir muitos utilizadores.

Um dos problemas com os espaços reservados é que não cumprem com o [critério de contraste de cor](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) por padrão; corrigir o contraste de cor faz o espaço reservado parecer como dados pré-povoado nos campos de entrada. Olhando no seguinte exemplo, podes ver que o espaço reservado do Último Nome o qual cumpre com o critério de contraste de cor parece-se com dado pré-povoado:

![Espaço reservado acessível](./images/AccessiblePlaceholder.png)

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <div v-for="item in formItems" :key="item.id" class="form-item">
    <label :for="item.id">{{ item.label }}: </label>
    <input
      type="text"
      :id="item.id"
      :name="item.id"
      v-model="item.value"
      :placeholder="item.placeholder"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

```css
/* https://www.w3schools.com/howto/howto_css_placeholder.asp */

#lastName::placeholder {
  /* Chrome, Firefox, Opera, Safari 10.1+ */
  color: black;
  opacity: 1; /* Firefox */
}

#lastName:-ms-input-placeholder {
  /* Internet Explorer 10-11 */
  color: black;
}

#lastName::-ms-input-placeholder {
  /* Microsoft Edge */
  color: black;
}
```

É melhor fornecer todas as informações que o utilizador precisa para preencher os formulários fora de quaisquer entradas.

### Instruções {#instructions}

Quando estiveres a adicionar as instruções para os teus campos de entrada, certifica-te de ligá-lo corretamente ao campo de entrada. Tu podes fornecer instruções adicionais e vincule vários identificadores dentro de um [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). Isto permite um desenho mais flexível:

```vue-html
<fieldset>
  <legend>Using aria-labelledby</legend>
  <label id="date-label" for="date">Current Date:</label>
  <input
    type="date"
    name="date"
    id="date"
    aria-labelledby="date-label date-instructions"
  />
  <p id="date-instructions">MM/DD/YYYY</p>
</fieldset>
```

Alternativamente, podes atribuir as instruções ao campo de entrada com o [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby):

```vue-html
<fieldset>
  <legend>Using aria-describedby</legend>
  <label id="dob" for="dob">Date of Birth:</label>
  <input type="date" name="dob" id="dob" aria-describedby="dob-instructions" />
  <p id="dob-instructions">MM/DD/YYYY</p>
</fieldset>
```

<!-- <common-codepen-snippet title="Form Instructions" slug="WNREEqv" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

### Escondendo Conteúdo {#hiding-content}

Normalmente não é recomendado esconder visualmente os rótulos, mesmo se a entrada tiver um nome acessível. No entanto, se a funcionalidade da entrada pode ser entendida com o conteúdo circundante, então podemos esconder o rótulo visual.

Observemos este campo de pesquisa:

```vue-html
<form role="search">
  <label for="search" class="hidden-visually">Search: </label>
  <input type="text" name="search" id="search" v-model="search" />
  <button type="submit">Search</button>
</form>
```

Nós podemos fazer isto porque o botão de pesquisa ajudará os utilizadores visuais a identificarem o propósito do campo de entrada.

Nós podemos usar a CSS para esconder visualmente os elementos mas mantê-los disponíveis para a tecnologia assistiva:

```css
.hidden-visually {
  position: absolute;
  overflow: hidden;
  white-space: nowrap;
  margin: 0;
  padding: 0;
  height: 1px;
  width: 1px;
  clip: rect(0 0 0 0);
  clip-path: inset(100%);
}
```

<!-- <common-codepen-snippet title="Form Search" slug="QWdMqWy" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

#### `aria-hidden="true"` {#aria-hidden-true}

Adding `aria-hidden="true"` will hide the element from assistive technology but leave it visually available for other users. Do not use it on focusable elements, purely on decorative, duplicated or offscreen content.

```vue-html
<p>This is not hidden from screen readers.</p>
<p aria-hidden="true">This is hidden from screen readers.</p>
```

### Botões {#buttons}

Quando estiveres a usar os botões dentro de um formulário, deves definir o tipo para evitar a submissão do formulário. Tu podes também usar uma entrada para criar os botões:

```vue-html
<form action="/dataCollectionLocation" method="post" autocomplete="on">
  <!-- Botões -->
  <button type="button">Cancel</button>
  <button type="submit">Submit</button>

  <!-- Botões de entrada -->
  <input type="button" value="Cancel" />
  <input type="submit" value="Submit" />
</form>
```

<!-- <common-codepen-snippet title="Form Buttons" slug="JjEyrYZ" :height="467" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

### Imagens Funcionais {#functional-images}

Tu podes usar esta técnica para criar imagens funcionais.

- Campos de entrada

  - Estas imagens agirão como um botão de tipo submissão em formulários

  ```vue-html
  <form role="search">
    <label for="search" class="hidden-visually">Search: </label>
    <input type="text" name="search" id="search" v-model="search" />
    <input
      type="image"
      class="btnImg"
      src="https://img.icons8.com/search"
      alt="Search"
    />
  </form>
  ```

- Ícones

```vue-html
<form role="search">
  <label for="searchIcon" class="hidden-visually">Search: </label>
  <input type="text" name="searchIcon" id="searchIcon" v-model="searchIcon" />
  <button type="submit">
    <i class="fas fa-search" aria-hidden="true"></i>
    <span class="hidden-visually">Search</span>
  </button>
</form>
```

<!-- <common-codepen-snippet title="Functional Images" slug="jOyLGqM" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->

## Padrões {#standards}

A Iniciativa de Acessibilidade da Web (WAI, sigla em Inglês) do Consórcio da World Wide Web (W3C, sigla em Inglês) desenvolve os padrões de acessibilidade da web para os diferentes componentes:

- [Diretrizes de Acessibilidade do Agente do Utilizador (UAAG, sigla em Inglês)](https://www.w3.org/WAI/standards-guidelines/uaag/)
  - Os navegadores da web e leitores de media, incluindo alguns aspetos de tecnologias assistivas.
- [Diretrizes de Acessibilidade de Ferramenta de Autoria (ATAG, sigla em Inglês)](https://www.w3.org/WAI/standards-guidelines/atag/)
  - As ferramentas de autoria
- [Diretrizes de Acessibilidade do Conteúdo da Web (WCAG, sigla em Inglês)](https://www.w3.org/WAI/standards-guidelines/wcag/)
  - O conteúdo da web - usado por programadores, ferramentas de autoria, e ferramentas de avaliação da acessibilidade.

### Diretrizes de Acessibilidade do Conteúdo da Web (WCAG) {#web-content-accessibility-guidelines-wcag}

A [WCAG 2.1](https://www.w3.org/TR/WCAG21/) estende o [WCAG 2.0](https://www.w3.org/TR/WCAG20/) e permite a implementação de novas tecnologias endereçando as mudanças para a web. O W3C encoraja o uso da versão mais atual de WCAG quando estiveres a desenvolver ou a atualizar as políticas de acessibilidade da Web.

#### WCAG 2.1 Quatro Princípios Orientadores Principais (abreviado como POUR, em Inglês): {#wcag-2-1-four-main-guiding-principles-abbreviated-as-pour}

- [Percebível](https://www.w3.org/TR/WCAG21/#perceivable)
  - Os utilizadores devem ser capazes de perceber a informação sendo apresentada
- [Operável](https://www.w3.org/TR/WCAG21/#operable)
  - Formulários de interface, controlos, e navegação são operáveis
- [Compreensível](https://www.w3.org/TR/WCAG21/#understandable)
  - A informação e a operação da interface de utilizador devem ser compreensíveis para todos utilizadores.
- [Robusta](https://www.w3.org/TR/WCAG21/#robust)
  - Os utilizadores devem ser capazes de acessar o conteúdo conforme o avanço das tecnologias

#### Iniciativa de Acessibilidade da Web - Aplicações de Internet Ricas em Acessibilidade (WAI-ARIA) {#web-accessibility-initiative-–-accessible-rich-internet-applications-wai-aria}

A WAI-ARIA do W3C fornece orientação sobre como construir conteúdo dinâmico e controlos de interface de utilizador avançados:

- [Aplicações de Internet Ricas em Acessibilidade (WAI-ARIA, sigla em Inglês) 1.2](https://www.w3.org/TR/wai-aria-1.2/)
- [Práticas de Autoria da WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-practices-1.2/)

## Recursos {#resources}

### Documentação {#documentation}

- [WCAG 2.0](https://www.w3.org/TR/WCAG20/)
- [WCAG 2.1](https://www.w3.org/TR/WCAG21/)
- [Aplicações de Internet Ricas em Acessibilidade (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/)
- [Práticas de Autoria da WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-practices-1.2/)

### Tecnologias Assistivas {#assistive-technologies}

- Leitores de Ecrã
  - [NVDA](https://www.nvaccess.org/download/)
  - [VoiceOver](https://www.apple.com/accessibility/mac/vision/)
  - [JAWS](https://www.freedomscientific.com/products/software/jaws/?utm_term=jaws%20screen%20reader&utm_source=adwords&utm_campaign=All+Products&utm_medium=ppc&hsa_tgt=kwd-394361346638&hsa_cam=200218713&hsa_ad=296201131673&hsa_kw=jaws%20screen%20reader&hsa_grp=52663682111&hsa_net=adwords&hsa_mt=e&hsa_src=g&hsa_acc=1684996396&hsa_ver=3&gclid=Cj0KCQjwnv71BRCOARIsAIkxW9HXKQ6kKNQD0q8a_1TXSJXnIuUyb65KJeTWmtS6BH96-5he9dsNq6oaAh6UEALw_wcB)
  - [ChromeVox](https://chrome.google.com/webstore/detail/chromevox-classic-extensi/kgejglhpjiefppelpmljglcjbhoiplfn?hl=en)
- Ferramentas de Ampliação de Conteúdo
  - [MAGic](https://www.freedomscientific.com/products/software/magic/)
  - [ZoomText](https://www.zoomtext.com/)
  - [Magnifier](https://support.microsoft.com/en-us/help/11542/windows-use-magnifier-to-make-things-easier-to-see)

### Testagem {#testing}

- Ferramentas Automatizadas
  - [Lighthouse](https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk)
  - [WAVE](https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh)
  - [ARC Toolkit](https://chrome.google.com/webstore/detail/arc-toolkit/chdkkkccnlfncngelccgbgfmjebmkmce?hl=en-US)
- Ferramentas de Cores
  - [WebAim Color Contrast](https://webaim.org/resources/contrastchecker/)
  - [WebAim Link Color Contrast](https://webaim.org/resources/linkcontrastchecker)
- Outras Ferramentas Úteis
  - [HeadingMap](https://chrome.google.com/webstore/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi?hl=en…)
  - [Color Oracle](https://colororacle.org)
  - [Focus Indicator](https://chrome.google.com/webstore/detail/focus-indicator/heeoeadndnhebmfebjccbhmccmaoedlf?hl=en-US…)
  - [NerdeFocus](https://chrome.google.com/webstore/detail/nerdefocus/lpfiljldhgjecfepfljnbjnbjfhennpd?hl=en-US…)
  - [Visual Aria](https://chrome.google.com/webstore/detail/visual-aria/lhbmajchkkmakajkjenkchhnhbadmhmk?hl=en-US)
  - [Silktide Website Accessibility Simulator](https://chrome.google.com/webstore/detail/silktide-website-accessib/okcpiimdfkpkjcbihbmhppldhiebhhaf?hl=en-US)

### Utilizadores {#users}

A Organização Mundial da Saúde estima que 15% da população mundial tem alguma forma de deficiência, 2-4% deles com severidade. Isto é estimado em 1 bilhão de pessoas mundialmente; tornando as pessoas com deficiências o maior grupo minoritário no mundo.

Existem uma grande gama de deficiência, que podem ser divididas aproximadamente em quatro categorias:

- _[Visual](https://webaim.org/articles/visual/)_ - Estes utilizadores podem beneficiarem-se do uso de leitores de ecrã, ampliação de ecrã, controlo de contraste de ecrã, ou exibição de braille.
- _[Auditiva](https://webaim.org/articles/auditory/)_ - Estes utilizadores podem beneficiarem-se do legendamento, transcrições ou vídeo de linguagem gestual.
- _[Motora](https://webaim.org/articles/motor/)_ - Estes utilizadores podem beneficiarem-se de uma gama de [tecnologias assistivas para deficiências motoras](https://webaim.org/articles/motor/assistive): software de reconhecimento de voz, acompanhamento do olho, acesso de interruptor único, vara de mão, teclado adaptável ou outras tecnologias assistivas.
- _[Cognitiva](https://webaim.org/articles/cognitive/)_ - Estes utilizadores podem beneficiarem-se de media complementar, organização estrutural do conteúdo, escrita clara e simples.

Consulte as seguintes ligações da WebAim para entenderes as necessidades dos utilizadores:

- [Perspetivas da Acessibilidade da Web: Explorar o Impacto e Benefícios para Todos](https://www.w3.org/WAI/perspective-videos/)
- [As Histórias dos Utilizadores da Web](https://www.w3.org/WAI/people-use-web/user-stories/)

---

---
url: /api/application.md
---
# API da Aplicação {#application-api}

## `createApp()` {#createapp}

Cria uma instância da aplicação.

- **Tipo**

  ```ts
  function createApp(rootComponent: Component, rootProps?: object): App
  ```

- **Detalhes**

  O primeiro argumento é o componente raiz. O segundo argumento são propriedades opcionais a serem passadas ao componente raiz.

- **Exemplo**

  Com o componente raiz em linha:

  ```js
  import { createApp } from 'vue'

  const app = createApp({
    /* opções do componente raiz */
  })
  ```

  Com o componente importado:

  ```js
  import { createApp } from 'vue'
  import App from './App.vue'

  const app = createApp(App)
  ```

- **Consulte também:** [Guia - Criando uma Aplicação de Vue](/guide/essentials/application)

## `createSSRApp()` {#createssrapp}

Cria uma instância da aplicação no modo de [Hidratação SSR](/guide/scaling-up/ssr#client-hydration). A forma de uso é exatamente igual à `createApp()`.

## `app.mount()` {#app-mount}

Monta a instância da aplicação em um elemento contentor.

- **Tipo**

  ```ts
  interface App {
    mount(rootContainer: Element | string): ComponentPublicInstance
  }
  ```

- **Detalhes**

  O argumento pode ser tanto o elemento real do DOM ou um seletor CSS (o primeiro elemento compatível será usado). Retorna a instância do componente raiz.

  Se o componente tem um modelo de marcação ou uma função de interpretação definida, ele substituirá qualquer nódulo do DOM existente dentro do contentor. Caso contrário, se o compilador de tempo de execução estiver disponível, a `innerHTML` do contentor será usado como modelo.

  No modo de hidratação de SSR, ele hidratará os nódulos DOM existentes dentro do contentor. Se houverem [disparidades](/guide/scaling-up/ssr#hydration-mismatch), os nódulos DOM existentes serão transformados para corresponder ao resultado esperado.

  O `mount()` poderá ser chamado apenas uma vez para cada instância da aplicação.

- **Exemplo**

  ```js
  import { createApp } from 'vue'
  const app = createApp(/* ... */)

  app.mount('#app')
  ```

  Também se pode montar em um elemento DOM real:

  ```js
  app.mount(document.body.firstChild)
  ```

## `app.unmount()` {#app-unmount}

Desmonta uma instância de aplicação montada, disparando os gatilhos do ciclo de vida para todos os componentes na árvore de componentes da aplicação.

- **Tipo**

  ```ts
  interface App {
    unmount(): void
  }
  ```

## `app.component()` {#app-component}

Regista um componente global ao passar um nome como string e uma definição de componente, ou busca um componente já registado se apenas o nome é passado.

- **Tipo**

  ```ts
  interface App {
    component(name: string): Component | undefined
    component(name: string, component: Component): this
  }
  ```

- **Exemplo**

  ```js
  import { createApp } from 'vue'

  const app = createApp({})

  // regista um objeto com opções
  app.component('my-component', {
    /* ... */
  })

  // busca um componente registado
  const MyComponent = app.component('my-component')
  ```

- **Consulte também:** [Registo de Componente](/guide/components/registration)

## `app.directive()` {#app-directive}

Regista uma diretiva global personalizada se passar uma sequência de caracteres de nome e uma definição de diretiva, ou buscar uma já registada se apenas o nome for passado.

- **Tipo**

  ```ts
  interface App {
    directive(name: string): Directive | undefined
    directive(name: string, directive: Directive): this
  }
  ```

- **Exemplo**

  ```js
  import { createApp } from 'vue'

  const app = createApp({
    /* ... */
  })

  // registar (objeto da diretiva)
  app.directive('my-directive', {
    /* gatilhos personalizados da diretiva */
  })

  // registar (atalho da função diretiva)
  app.directive('my-directive', () => {
    /* ... */
  })

  // busca uma diretiva registada
  const myDirective = app.directive('my-directive')
  ```

- **Consulte também:** [Diretivas Personalizadas](/guide/reusability/custom-directives)

## `app.use()` {#app-use}

Instala uma [extensão](/guide/reusability/plugins).

- **Tipo**

  ```ts
  interface App {
    use(plugin: Plugin, ...options: any[]): this
  }
  ```

- **Detalhes**

  Exige a extensão como primeiro argumento, e opcionalmente configurações da extensão como segundo argumento.

  A extensão pode tanto ser um objeto com um método `install()`, ou apenas uma função que será usada como o método `install()`. As opções (segundo argumento do `app.use()`) serão passadas através do método `install()` da extensão.

  Quando `app.use()` for chamado com a mesma extensão múltiplas vezes, a extensão será instalada apenas uma vez.

- **Exemplo**

  ```js
  import { createApp } from 'vue'
  import MyPlugin from './plugins/MyPlugin'

  const app = createApp({
    /* ... */
  })

  app.use(MyPlugin)
  ```

- **Consulte também:** [Extensões](/guide/reusability/plugins)

## `app.mixin()` {#app-mixin}

Aplica uma mistura global (isolada à aplicação). Uma mistura global aplica suas opções incluídas à toda instância de componente na aplicação.

:::warning Não Recomendado
Misturas são suportadas na Vue 3 principalmente para compatibilidade retroativa, devido ao seu uso difundido nas bibliotecas do ecossistema. O uso de misturas, especialmente misturas globais, deve ser evitado no código da aplicação.

Para reutilização de lógica, prefira as [Funções de Composição](/guide/reusability/composables).
:::

- **Tipo**

  ```ts
  interface App {
    mixin(mixin: ComponentOptions): this
  }
  ```

## `app.provide()` {#app-provide}

Fornece um valor que pode ser injetado em todos os componentes descendentes dentro da aplicação.

- **Tipo**

  ```ts
  interface App {
    provide<T>(key: InjectionKey<T> | symbol | string, value: T): this
  }
  ```

- **Detalhes**

  Exige a chave de injeção como primeiro argumento, e o valor fornecido como o segundo. Retorna a própria instância da aplicação.

- **Exemplo**

  ```js
  import { createApp } from 'vue'

  const app = createApp(/* ... */)

  app.provide('message', 'olá')
  ```

  Dentro de um componente na aplicação:

  <div class="composition-api">

  ```js
  import { inject } from 'vue'

  export default {
    setup() {
      console.log(inject('message')) // 'olá'
    }
  }
  ```

  </div>
  <div class="options-api">

  ```js
  export default {
    inject: ['message'],
    created() {
      console.log(this.message) // 'olá'
    }
  }
  ```

  </div>

- **Consulte também:**
  - [Fornecer / Injetar](/guide/components/provide-inject)
  - [Fornecimento a Nível de Aplicação](/guide/components/provide-inject#app-level-provide)
  - [`app.runWithContext()`](#app-runwithcontext)

## `app.runWithContext()`<sup class="vt-badge" data-text="3.3+" /> {#app-runwithcontext}

Executa uma função de resposta com a aplicação atual como contexto de injeção.

- **Tipo**

  ```ts
  interface App {
    runWithContext<T>(fn: () => T): T
  }
  ```

- **Detalhes**
  
  Espera uma função de resposta e executa a função de resposta imediatamente. Durante a chamada síncrona da função de resposta, as chamadas de `inject()` são capazes de procurar as injeções a partir dos valores fornecidos pela aplicação atual, mesmo quando não existir nenhuma instância de componente ativa atualmente. O valor de retorno da função de resposta também será retornado.

- **Exemplo**

  ```js
  import { inject } from 'vue'

  app.provide('id', 1)

  const injected = app.runWithContext(() => {
    return inject('id')
  })

  console.log(injected) // 1
  ```

## `app.version` {#app-version}

Fornece a versão da Vue com que a aplicação foi criada. Isto é útil dentro de [extensões](/guide/reusability/plugins), onde podemos precisar de lógica condicional baseada em diferentes versões da Vue.

- **Tipo**

  ```ts
  interface App {
    version: string
  }
  ```

- **Exemplo**

  Realizando uma verificação da versão dentro de uma extensão:

  ```js
  export default {
    install(app) {
      const version = Number(app.version.split('.')[0])
      if (version < 3) {
        console.warn('Esta extensão exige a Vue 3')
      }
    }
  }
  ```

- **Consulte também:** [API Global - versão](/api/general#version)

## `app.config` {#app-config}

Toda instância da aplicação expõe um objeto `config` que contém as definições de configuração para aquela aplicação. Nós podemos modificar estas propriedades (documentadas abaixo) antes de montar a nossa aplicação.

```js
import { createApp } from 'vue'

const app = createApp(/* ... */)

console.log(app.config)
```

## `app.config.errorHandler` {#app-config-errorhandler}

Atribui um manipulador global para erros não capturados que se propagam a partir de dentro da aplicação.

- **Tipo**

  ```ts
  interface AppConfig {
    errorHandler?: (
      err: unknown,
      instance: ComponentPublicInstance | null,
      // `info` é uma informação de erro específica da Vue,
      // e.g. em qual gatilho do ciclo de vida o erro foi lançado
      info: string
    ) => void
  }
  ```

- **Detalhes**

  O manipulador do erro recebe três argumentos: o erro, a instância do componente que disparou o erro, e uma sequência de caracteres de informação especificando o tipo da fonte do erro.

  Ele pode capturar erros das seguintes fontes:

  - Interpretação de componente
  - Manipuladores de evento
  - Gatilhos de Ciclo de Vida
  - Função `setup()`
  - Observadores
  - Gatilhos personalizados de diretiva
  - Gatilhos de transição

  :::tip DICA
  Em produção, o terceiro argumento (`info`) será um código encurtado ao invés da sequência de caracteres da informação completa. Nós podemos encontrar o código ao mapeamento da sequência de caracteres na [Referência do Código de Erro de Produção](/error-reference/#runtime-errors).
  :::

- **Exemplo**

  ```js
  app.config.errorHandler = (err, instance, info) => {
    // manipular o erro, por exemplo, informar para um serviço
  }
  ```

## `app.config.warnHandler` {#app-config-warnhandler}

Atribui um manipulador personalizado para avisos de tempo de execução da Vue.

- **Tipo**

  ```ts
  interface AppConfig {
    warnHandler?: (
      msg: string,
      instance: ComponentPublicInstance | null,
      trace: string
    ) => void
  }
  ```

- **Detalhes**

  O manipulador de avisos recebe uma mensagem de aviso como primeiro argumento, a instância do componente fonte como segundo argumento, e uma string de rastro de componentes como terceiro.

  Pode ser usado para filtrar avisos específicos a fim de reduzir a verbosidade no _console_. Todos os avisos da Vue devem ser abordados durante o desenvolvimento, então isto é recomendado apenas durante sessões de depuração para focar em avisos específicos entre muitos, e deve ser removido uma vez que a depuração tenha sido finalizada.

  :::tip DICA
  Avisos funcionam apenas durante o desenvolvimento, então esta configuração é ignorada no modo de produção.
  :::

- **Exemplo**

  ```js
  app.config.warnHandler = (msg, instance, trace) => {
    // `trace` é o rastro da hierarquia de componentes
  }
  ```

## `app.config.performance` {#app-config-performance}

Defina isto para `true` para ativar o rastreio do desempenho do remendo, desenho, compilação e inicialização do componente no painel de desempenho ou linha do tempo da ferramenta de programação do navegador. Funciona apenas no modo de desenvolvimento e em navegadores que suportam a API [`performance.mark`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark).

- **Tipo**: `boolean`

- **Consulte também**: [Guia - Desempenho](/guide/best-practices/performance)

## `app.config.compilerOptions` {#app-config-compileroptions}

Configura opções do compilador de tempo de execução. Os valores definidos neste objeto serão passados para o compilador de modelos de marcação no navegador e afetarão todo componente na aplicação configurada. Observe que podemos sobrepor estas opções com base num componente usando a [opção `compilerOptions`](/api/options-rendering#compileroptions).

:::warning IMPORTANTE
Esta opção da configuração é respeitada apenas quando usasse a construção completa (por exemplo, o `vue.js` autónomo que pode compilar modelos de marcação no navegador). Se estivermos usando uma construção que executa apenas no tempo de execução com uma configuração de construção, as opções do compilador devem ser passadas para o `@vue/compiler-dom` através das configurações da ferramenta de construção.

- Para `vue-loader`: [passamos através da opção do carregador `compilerOptions`](https://vue-loader.vuejs.org/options#compileroptions). Consulte também [como configurá-lo na `vue-cli`](https://cli.vuejs.org/guide/webpack#modifying-options-of-a-loader).

- Para `vite`: [passamos através das opções `@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options).
  :::

### `app.config.compilerOptions.isCustomElement` {#app-config-compileroptions-iscustomelement}

Especifica um método de verificação para reconhecer elementos personalizados nativos.

- **Tipo:** `(tag: string) => boolean`

- **Detalhes**

  Deve retornar `true` se o marcador deve ser tratado como elemento personalizado nativo. Para um marcador correspondente, a Vue interpretará como um elemento nativo ao invés de tentar resolvê-lo como um componente de Vue.

  Os marcadores de HTML e SVG nativos não precisam ser correspondidos nesta função - o analisador da Vue reconhece-os automaticamente.

- **Exemplo**

  ```js
  // tratar todos marcadores começando com
  // 'ion-' como elementos personalizados
  app.config.compilerOptions.isCustomElement = (tag) => {
    return tag.startsWith('ion-')
  }
  ```

- **Consulte também**: [Vue e os Componentes da Web](/guide/extras/web-components.html)

### `app.config.compilerOptions.whitespace` {#app-config-compileroptions-whitespace}

Ajusta o tratamento de espaço em branco do modelo de marcação.

- **Tipo:** `'condense' | 'preserve'`

- **Padrão:** `'condense'`

- **Detalhes**

  A Vue remove ou condensa os caracteres de espaço em branco nos modelos de marcação para produzir uma saída compilada mais eficiente. A estratégia padrão é "condensar", com o seguinte comportamento:

  1. Caracteres de espaço em branco iniciais ou finais dentro de um elemento são condensados em um único espaço.
  2. Caracteres de espaço em branco entre elementos que contêm novas linhas são removidos.
  3. Caracteres de espaço em branco consecutivos em nódulos de texto são condensados em um único espaço.

  A definição desta opção para `'preserve'` desativará os itens (2) e (3) acima.

- **Exemplo**

  ```js
  app.config.compilerOptions.whitespace = 'preserve'
  ```

### `app.config.compilerOptions.delimiters` {#app-config-compileroptions-delimiters}

Ajusta os delimitadores usados para a interpolação de texto dentro do modelo de marcação.

- **Tipo:** `[string, string]`

- **Padrão:** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`

- **Detalhes**

  Isto é normalmente usado para evitar conflitos com abstrações do lado do servidor que também podem usar a sintaxe de bigodes ou chavetas.

- **Exemplo**

  ```js
  // Delimitadores modificados para o 
  // estilo de sequência de caracteres de modelo da ES6
  app.config.compilerOptions.delimiters = ['${', '}']
  ```

### `app.config.compilerOptions.comments` {#app-config-compileroptions-comments}

Ajusta o tratamento de comentários HTML nos modelos de marcação.

- **Tipo:** `boolean`

- **Padrão:** `false`

- **Detalhes**

  Por padrão, a Vue removerá todos os comentários em produção. A definição desta opção para `true` forçará a Vue a preservar os comentários até em produção. Os comentários são sempre preservados durante o desenvolvimento. Esta opção é normalmente usada para quando a Vue for usada com outras bibliotecas que dependem de comentários de HTML.

- **Exemplo**

  ```js
  app.config.compilerOptions.comments = true
  ```

## `app.config.globalProperties` {#app-config-globalproperties}

Um objeto pode ser usado para registar propriedades globais que podem ser acessadas em qualquer instância de componente dentro da aplicação.

- **Tipo**

  ```ts
  interface AppConfig {
    globalProperties: Record<string, any>
  }
  ```

- **Detalhes**

  Isto é uma substituição da `Vue.prototype` da Vue 2, que não está mais presente na Vue 3. Como qualquer outra coisa global, isto deve ser usado com moderação.

  Se uma propriedade global entrar em conflito com uma propriedade de um componente, a propriedade do componente terá maior prioridade.

- **Uso**

  ```js
  app.config.globalProperties.msg = 'olá'
  ```

  Isto torna `msg` disponível dentro de qualquer modelo de marcação do componente na aplicação, e também no `this` de qualquer instância de componente:

  ```js
  export default {
    mounted() {
      console.log(this.msg) // 'olá'
    }
  }
  ```

- **Consulte também** [Guia - Aumentando as Propriedades Globais](/guide/typescript/options-api#augmenting-global-properties) <sup class="vt-badge ts" />

## `app.config.optionMergeStrategies` {#app-config-optionmergestrategies}

Um objeto para definir estratégias de fusão para opções de componente personalizadas.

- **Tipo**

  ```ts
  interface AppConfig {
    optionMergeStrategies: Record<string, OptionMergeFunction>
  }

  type OptionMergeFunction = (to: unknown, from: unknown) => any
  ```

- **Detalhes**

  Algumas extensões ou bibliotecas adicionam suporte para opções de componente personalizas (injetando misturas globais). Essas opções podem exigir uma lógica de fusão especial quando a mesma opção precisa ser "combinada" de múltiplas fontes (por exemplo, misturas ou herança de componente).

  Uma função de estratégia de fusão pode ser registada por uma opção personalizada ao atribuí-la ao objeto `app.config.optionMergeStrategies` usando o nome da opção como chave.

  A estratégia de fusão recebe o valor da opção definida nas instâncias pai e filho como primeiro e segundo argumentos, respetivamente.

- **Exemplo**

  ```js
  const app = createApp({
    // opção própria
    msg: 'Vue',
    // opção de uma mistura
    mixins: [
      {
        msg: 'Olá '
      }
    ],
    mounted() {
      // opções combinadas expostas na this.$options
      console.log(this.$options.msg)
    }
  })

  // definir uma estratégia de fusão personalizada para `msg`
  app.config.optionMergeStrategies.msg = (parent, child) => {
    return (parent || '') + (child || '')
  }

  app.mount('#app')
  // mostra 'Olá Vue'
  ```

- **Consulte também**: [Instância do Componente - `$options`](/api/component-instance#options)

---

---
url: /api/ssr.md
---
# API da Interpretação do Lado do Servidor {#server-side-rendering-api}

## `renderToString()` {#rendertostring}

- **Exportada a partir do `vue/server-renderer`**

- **Tipo**

  ```ts
  function renderToString(
    input: App | VNode,
    context?: SSRContext
  ): Promise<string>
  ```

- **Exemplo**

  ```js
  import { createSSRApp } from 'vue'
  import { renderToString } from 'vue/server-renderer'

  const app = createSSRApp({
    data: () => ({ msg: 'hello' }),
    template: `<div>{{ msg }}</div>`
  })

  ;(async () => {
    const html = await renderToString(app)
    console.log(html)
  })()
  ```

  ### Contexto da Interpretação no Lado do Servidor {#ssr-context}

  Nós podemos passar um objeto de contexto opcional, o qual pode ser usado para gravar dados adicionais durante a interpretação, por exemplo [acessando o conteúdo dos teletransportes](/guide/scaling-up/ssr#teleports):

  ```js
  const ctx = {}
  const html = await renderToString(app, ctx)

  console.log(ctx.teleports) // { '#teleported': 'teleported content' }
  ```

  A maioria das outras APIs da Interpretação do Lado do Servidor nesta página também aceitam opcionalmente um objeto de contexto. O objeto de contexto pode ser acessado no código do componente através da auxiliar [`useSSRContext`](#usessrcontext).

- **Consulte também** [Guia - Interpretação do Lado do Servidor](/guide/scaling-up/ssr)

## `renderToNodeStream()` {#rendertonodestream}

Interpreta a entrada como uma [corrente legível da Node.js](https://nodejs.org/api/stream.html#stream_class_stream_readable).

- **Exportada a partir do `vue/server-renderer`**

- **Tipo**

  ```ts
  function renderToNodeStream(
    input: App | VNode,
    context?: SSRContext
  ): Readable
  ```

- **Exemplo**

  ```js
  // dentro dum manipulador de HTTP da Node.js
  renderToNodeStream(app).pipe(res)
  ```

  :::tip NOTA
  Este método não suportado na construção de módulo de ECMAScript do `vue/server-renderer`, que é separado dos ambientes da Node.js. No lugar disto, usamos a [`pipeToNodeWritable`](#pipetonodewritable).
  :::

## `pipeToNodeWritable()` {#pipetonodewritable}

Interpreta e canaliza à uma instância de [corrente gravável da Node.js](https://nodejs.org/api/stream.html#stream_writable_streams) existente.

- **Exportada a partir do `vue/server-renderer`**

- **Tipo**

  ```ts
  function pipeToNodeWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: Writable
  ): void
  ```

- **Exemplo**

  ```js
  // dentro dum manipulador de http da Node.js
  pipeToNodeWritable(app, {}, res)
  ```

## `renderToWebStream()` {#rendertowebstream}

Interpreta a entrada como uma [corrente legível de Web](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).

- **Exportada a partir do `vue/server-renderer`**

- **Tipo**

  ```ts
  function renderToWebStream(
    input: App | VNode,
    context?: SSRContext
  ): ReadableStream
  ```

- **Exemplo**

  ```js
  // dentro dum ambiente com suporte de `ReadableStream`
  return new Response(renderToWebStream(app))
  ```

  :::tip NOTA
  Nos ambientes que não expõem o construtor `ReadableStream` no âmbito global, [`pipeToWebWritable()`](#pipetowebwritable) deve ser usado.
  :::

## `pipeToWebWritable()` {#pipetowebwritable}

Interpreta e canaliza à uma instância de [conduta gravável de Web](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) existente.

- **Exportada a partir do `vue/server-renderer`**

- **Tipo**

  ```ts
  function pipeToWebWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: WritableStream
  ): void
  ```

- **Exemplo**

  Isso é normalmente usado em combinação com [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream):

  ```js
  // `TransformStream` é disponível em ambientes como operários da
  // CloudFlare. Na Node.js, `TransformStream` precisa ser
  // importado explicitamente a partir de 'stream/web'
  const { readable, writable } = new TransformStream()
  pipeToWebWritable(app, {}, writable)

  return new Response(readable)
  ```

## `renderToSimpleStream()` {#rendertosimplestream}

Interpreta a entrada no modo de corrente usando uma simples interface legível.

- **Exportado de `vue/server-renderer`**

- **Tipo**

  ```ts
  function renderToSimpleStream(
    input: App | VNode,
    context: SSRContext,
    options: SimpleReadable
  ): SimpleReadable

  interface SimpleReadable {
    push(content: string | null): void
    destroy(err: any): void
  }
  ```

- **Exemplo**

  ```js
  let res = ''

  renderToSimpleStream(
    app,
    {},
    {
      push(chunk) {
        if (chunk === null) {
          // feito
          console(`render complete: ${res}`)
        } else {
          res += chunk
        }
      },
      destroy(err) {
        // erro encontrado
      }
    }
  )
  ```

## `useSSRContext()` {#usessrcontext}

Uma API de tempo de execução para recuperar o objeto do contexto passado à `renderToString()` ou outras APIs interpretação do servidor.


- **Tipo**

  ```ts
  function useSSRContext<T = Record<string, any>>(): T | undefined
  ```

- **Exemplo**

  O contexto recuperado pode ser usado para anexar informação que for necessária para produzir o HTML final (por exemplo, metadados de cabeçalho).

  ```vue
  <script setup>
  import { useSSRContext } from 'vue'

  // Temos apenas de certificar-nos de chamá-la durante a
  // interpretação do lado do servidor
  // https://pt.vitejs.dev/guide/ssr#conditional-logic
  if (import.meta.env.SSR) {
    const ctx = useSSRContext()
    // ...anexar propriedades ao contexto
  }
  </script>
  ```

---

---
url: /api/composition-api-setup.md
---
# API de Composição: `setup()` {#composition-api-setup}

## Uso Básico {#basic-usage}

O gancho `setup()` serve como o ponto de entrada para o uso da API de Composição nos componentes nos seguintes casos:

1. Uso da API de Composição sem uma etapa de construção;
2. Integração do código baseado na API de Composição num componente de API de Opções.

:::info Nota
Se estivermos a usar a API de Composição com Componentes de Ficheiro Único, [`<script setup>`](/api/sfc-script-setup) é fortemente recomendado para uma sintaxe mais sucinta e ergonómica.
:::

Nós podemos declarar estado reativo usando as [APIs de Reatividade](./reactivity-core) e expo-las ao modelo de marcação retornando um objeto a partir da `setup()`. As propriedades do objeto retornado também serão disponibilizadas na instância do componente (se outras opções forem usadas):

```vue
<script>
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    // expor ao modelo de marcação e
    // a outros ganchos da API de opções
    return {
      count
    }
  },

  mounted() {
    console.log(this.count) // 0
  }
}
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>
```

As [referências](/api/reactivity-core#ref) retornadas a partir de `setup` são [desembrulhadas superficialmente de maneira automática](/guide/essentials/reactivity-fundamentals#deep-reactivity) quando acessadas no modelo para que não precisemos de chamar `.value` quando as acessamos. Elas também são desembrulhadas da mesma forma quando acessadas pelo `this`.

`setup()` em si não possui qualquer acesso à instância do componente - `this` terá um valor de `undefined` dentro de `setup()`. Nós podemos acessar os valores expostos pela API de Composição através da API de Opções, mas não o contrário.

`setup()` deve retornar um objeto de maneira síncrona. O único caso em que `async setup()` pode ser usado é quando o componente é descendente dum componente [Suspense](../guide/built-ins/suspense).

## Acessando Propriedades {#accessing-props}

O primeiro argumento na função `setup` é o argumento `props`. Tal como esperaríamos num componente padrão, `props` dentro da função `setup` são reativas e serão atualizadas quando novas propriedades forem passadas.

```js
export default {
  props: {
    title: String
  },
  setup(props) {
    console.log(props.title)
  }
}
```

Note que se desestruturarmos o objeto `props`, as variáveis desestruturadas perderão a reatividade. É portanto recomendado sempre acessá-las na forma de `props.xxx`.

Se realmente precisarmos de desestruturar as propriedades, ou precisarmos passar uma propriedade à uma função externa enquanto preserva-se a reatividade, podemos fazer isto com as APIs utilitárias [toRefs()](./reactivity-utilities#torefs) e [toRef()](/api/reactivity-utilities#toref):

```js
import { toRefs, toRef } from 'vue'

export default {
  setup(props) {
    // tornar `props` num objeto de referências, então desestruturar
    const { title } = toRefs(props)
    // `title` é uma referência que monitoriza `props.title`
    console.log(title.value)

    // OU, tornar uma única propriedade em `props` numa referência
    const title = toRef(props, 'title')
  }
}
```

## Contexto de Configuração {#setup-context}

O segundo argumento passado à função `setup` é um objeto **Contexto de Configuração**. O objeto de contexto expõe outros valores que podem ser úteis dentro de `setup`:

```js
export default {
  setup(props, context) {
    // Atributos (Objeto não reativo, equivalente a $attrs)
    console.log(context.attrs)

    // Ranhuras (Objeto não reativo, equivalente a $slots)
    console.log(context.slots)

    // Emite eventos (Função, equivalente a $emit)
    console.log(context.emit)

    // Expõe propriedades públicas (Função)
    console.log(context.expose)
  }
}
```

O objeto de contexto não é reativo e pode ser seguramente desestruturado:

```js
export default {
  setup(props, { attrs, slots, emit, expose }) {
    ...
  }
}
```

`attrs` e `slots` são objetos com estado que sempre são atualizados quando o próprio componente é atualizado. Isso significa que você deve evitar desestruturá-los e sempre referenciar propriedades como `attrs.x` ou `slots.x`. Também perceba que ao contrário de `props`, as propriedades `attrs` e `slots` **não** são reativas. Se você pretende aplicar efeitos colaterais com base em mudanças em `attrs` ou `slots`, você deve fazer dentro do gatilho de ciclo de vida `onBeforeUpdate`.

### Expondo Propriedades Públicas {#exposing-public-properties}

`expose` é uma função que pode ser usada para limitar explicitamente as propriedades expostas quando a instância do componente é acessada por um componente pai através de [referências do modelo](/guide/essentials/template-refs#ref-on-component):

```js{5,10}
export default {
  setup(props, { expose }) {
    // tornar a instância "fechada" -
    // por exemplo, não expõe qualquer coisa ao pai
    expose()

    const publicCount = ref(0)
    const privateCount = ref(0)
    // expõe o estado local seletivamente
    expose({ count: publicCount })
  }
}
```

## Uso com Funções de Interpretação {#usage-with-render-functions}

`setup` também pode retornar uma [função de interpretação](/guide/extras/render-function) que pode fazer uso diretamente do estado reativo declarado no mesmo âmbito:

```js{6}
import { h, ref } from 'vue'

export default {
  setup() {
    const count = ref(0)
    return () => h('div', count.value)
  }
}
```

Retornar uma função de interpretação guarda-nos de retornar qualquer outra coisa. Internamente isto não deveria ser um problema, mas pode ser problemático se quisermos expor métodos deste componente para o componente pai através de referências de modelo de marcação.

Nós podemos resolver esse problema chamando [`expose()`](#exposing-public-properties):

```js{8-10}
import { h, ref } from 'vue'

export default {
  setup(props, { expose }) {
    const count = ref(0)
    const increment = () => ++count.value

    expose({
      increment
    })

    return () => h('div', count.value)
  }
}
```

O método `increment` estaria então disponível no componente pai através duma referência de modelo de marcação.

---

---
url: /api/composition-api-dependency-injection.md
---
# API de Composição: <br>Injeção de Dependência {#composition-api-dependency-injection}

## `provide()` {#provide}

Fornece um valor que pode ser injetado pelos componentes descendentes.

- **Tipo**

  ```ts
  function provide<T>(key: InjectionKey<T> | string, value: T): void
  ```

- **Detalhes**

  `provide()` recebe dois argumentos: a chave, que pode ser uma sequência de caracteres ou um símbolo, e o valor a ser injetado.

  Quando usamos a TypeScript, a chave pode ser um símbolo moldado como `InjectionKey` - um tipo de utilitário fornecido pela Vue que estende o `Symbol`, que pode ser usado para sincronizar o tipo de valor entre `provide()` e `inject()`.

  Semelhante às APIs de registo de gatilho de ciclo de vida, `provide()` deve ser chamada de maneira síncrona durante a fase `setup()` dum componente.

- **Exemplo**

  ```vue
  <script setup>
  import { ref, provide } from 'vue'
  import { fooSymbol } from './injectionSymbols'

  // fornecer valor estático
  provide('foo', 'bar')

  // fornecer valor reativo
  const count = ref(0)
  provide('count', count)

  // fornecer com chaves de símbolo
  provide(fooSymbol, count)
  </script>
  ```

- **Consultar também**:
  - [Guia - Fornecer ou Injetar](/guide/components/provide-inject)
  - [Guia - Tipificação de `provide()` / `inject()`](/guide/typescript/composition-api#typing-provide-inject) <sup class="vt-badge ts" data-text="typescript" />

## `inject()` {#inject}

Injeta um valor fornecido por um componente ancestral ou pela aplicação (através de `app.provide()`).

- **Tipo**

  ```ts
  // sem valor padrão
  function inject<T>(key: InjectionKey<T> | string): T | undefined

  // com valor padrão
  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T

  // com fábrica
  function inject<T>(
    key: InjectionKey<T> | string,
    defaultValue: () => T,
    treatDefaultAsFactory: true
  ): T
  ```

- **Detalhes**

  O primeiro argumento é a chave de injeção. A Vue percorrerá a cadeia dos pais para localizar um valor fornecido com uma chave correspondente. Se vários componentes na cadeia dos pais fornecerem a mesma chave, o componente mais próximo do componente injetor "sombreará" os componentes mais acima na cadeia. Se nenhum valor com a chave correspondente for encontrado, `inject()` retorna `undefined` a menos que um valor padrão seja fornecido.

  O segundo argumento é opcional e é o valor padrão a ser usado quando nenhum valor correspondente foi encontrado.

  O segundo argumento também pode ser uma função de fábrica que retorna valores cuja criação é dispendiosa. Neste caso, `true` deve ser passado como terceiro argumento para indicar que a função deveria ser usada como uma fábrica ao invés do próprio valor.

  Semelhante às APIs de registo de gatilho de ciclo de vida, `inject()` deve ser chamada de maneira síncrona durante a fase `setup()` dum componente.

  Quando usamos a TypeScript, a chave pode ser do tipo de `InjectionKey` - um tipo de utilitário fornecido pela Vue que estende o `Symbol`, que pode ser usado para sincronizar o tipo de valor entre `provide()` e `inject()`.

- **Exemplo**

  Assumindo que um componente pai forneceu valores como mostrado no exemplo anterior de `provide()`:

  ```vue
  <script setup>
  import { inject } from 'vue'
  import { fooSymbol } from './injectionSymbols'

  // injetar valor estático sem padrão
  const foo = inject('foo')

  // injetar valor reativo
  const count = inject('count')

  // injetar com chaves de símbolo
  const foo2 = inject(fooSymbol)

  // injetar com valor padrão
  const bar = inject('foo', 'default value')

  // injetar com valor padrão de função
  const fn = inject('function', () => {})

  // injetar com fábrica de valor padrão
  const baz = inject('factory', () => new ExpensiveObject(), true)
  </script>
  ```

- **Consultar também**:
  - [Guia - Fornecer ou Injetar](/guide/components/provide-inject)
  - [Guia - Tipificação de `provide()` e `inject()`](/guide/typescript/composition-api#typing-provide-inject) <sup class="vt-badge ts" data-text="typescript" />

## hasInjectionContext() <sup class="vt-badge" data-text="3.3+" /> {#has-injection-context}

Retorna verdadeiro se [`inject()`](#inject) puder ser usada sem aviso por ter sido chamada no lugar errado (por exemplo, fora de `setup()`). Este método foi concebido para ser usado por bibliotecas que querem usar `inject()` internamente sem disparar um aviso ao utilizador final.

- **Tipo**

  ```ts
  function hasInjectionContext(): boolean
  ```

---

---
url: /api/composition-api-lifecycle.md
---
# API de Composição: Gatilhos do Ciclo de Vida {#composition-api-lifecycle-hooks}

:::info Nota de Uso
Todas as APIs listadas nesta página devem ser chamadas de maneira síncrona durante a fase `setup()` do componente. Consulte o [Guia - Gatilhos do Ciclo de Vida](/guide/essentials/lifecycle) por mais detalhes.
:::

## `onMounted()` {#onmounted}

Regista uma função de resposta a ser chamada depois do componente ter sido montado.

- **Tipo**

  ```ts
  function onMounted(callback: () => void): void
  ```

- **Detalhes**

  Um componente é considerado montado depois que:

  - Todos os seus componentes filho síncronos terem sido montados (isto não inclui componentes assíncronos ou componentes dentro de árvores de `<Suspense>`).

  - Sua própria árvore de DOM ter sido criada e inserida no contentor pai. Nota que isto apenas garante que a árvore de DOM do componente está no documento se o contentor raiz da aplicação também estiver no documento.

  Este gatilho é tipicamente usado para realizar efeitos colaterais que precisam de acesso ao DOM interpretado do componente, ou para limitar o código relacionado ao DOM para o cliente numa [aplicação interpretada no servidor](/guide/scaling-up/ssr).

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Exemplo**

  Acessar um elemento através de referências do modelo de marcação:

  ```vue
  <script setup>
  import { ref, onMounted } from 'vue'

  const el = ref()

  onMounted(() => {
    el.value // <div>
  })
  </script>

  <template>
    <div ref="el"></div>
  </template>
  ```

## `onUpdated()` {#onupdated}

Regista uma função de resposta a ser chamada depois do componente tiver atualizado a sua árvore de DOM devido a uma mudança de estado reativa.

- **Tipo**

  ```ts
  function onUpdated(callback: () => void): void
  ```

- **Detalhes**

  O gatilho de atualização dum componente pai é chamado apenas depois do gatilho dos seus componentes.

  Este gatilho é chamado depois de qualquer atualização de DOM do componente, que pode ser causada por mudanças de estado diferente. Se precisarmos acessar o DOM atualizado depois duma mudança de estado específica, devemos usar [`nextTick()`](/api/general#nexttick).

  **Este gatilho não é chamado durante a interpretação do lado do servidor.**

  :::warning AVISO
  Não altere o estado do componente no gatilho `updated` - isto provavelmente conduzirá à um laço de atualização infinita!
  :::

- **Exemplo**

  Acessando o DOM atualizado:

  ```vue
  <script setup>
  import { ref, onUpdated } from 'vue'

  const count = ref(0)

  onUpdated(() => {
    // o conteúdo de texto deve ser o mesmo que o `count.value` atual
    console.log(document.getElementById('count').textContent)
  })
  </script>

  <template>
    <button id="count" @click="count++">{{ count }}</button>
  </template>
  ```

## `onUnmounted()` {#onunmounted}

Regista uma função de resposta a ser chamada depois do componente tiver sido desmontado.

- **Tipo**

  ```ts
  function onUnmounted(callback: () => void): void
  ```

- **Detalhes**

  Um componente é considerado desmontado depois que:

  - Todos os seus componentes filho foram desmontados.

  - Todos os seus efeitos reativos associados (efeitos de interpretação e valores computados ou observadores criados durante `setup()`) foram interrompidos.

  Use este gatilho para limpar manualmente efeitos colaterais como temporizadores, ouvintes de evento de DOM, ou conexões de servidor.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Exemplo**

  ```vue
  <script setup>
  import { onMounted, onUnmounted } from 'vue'

  let intervalId
  onMounted(() => {
    intervalId = setInterval(() => {
      // ...
    })
  })

  onUnmounted(() => clearInterval(intervalId))
  </script>
  ```

## `onBeforeMount()` {#onbeforemount}

Regista um gatilho a ser chamado imediatamente antes do componente ser montado.

- **Tipo**

  ```ts
  function onBeforeMount(callback: () => void): void
  ```

- **Detalhes**

  Quando este gatilho é chamado, o componente terminou de configurar seu estado reativo, mas nenhum nós de DOM foi criado ainda. Está prestes a executar o seu efeito de interpretação de DOM pela primeira vez.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `onBeforeUpdate()` {#onbeforeupdate}

Regista um gatilho a ser chamado imediatamente antes do componente estar prestes a atualizar sua árvore de DOM devido a uma mudança de estado reativo.

- **Tipo**

  ```ts
  function onBeforeUpdate(callback: () => void): void
  ```

- **Detalhes**

  Este gatilho pode ser usado para acessar o estado do DOM imediatamente antes da Vue atualizar o DOM. Também é seguro modificar o estado do componente dentro deste gatilho.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `onBeforeUnmount()` {#onbeforeunmount}

Regista um gatilho a ser chamado imediatamente antes da instância do componente ser desmontada.

- **Tipo**

  ```ts
  function onBeforeUnmount(callback: () => void): void
  ```

- **Detalhes**

  Quando este gatilho é chamado, a instância do componente ainda está completamente funcional.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `onErrorCaptured()` {#onerrorcaptured}

Regista um gatilho a ser chamado quando um erro que se propaga a partir dum componente descendente tiver sido capturado.

- **Tipo**

  ```ts
  function onErrorCaptured(callback: ErrorCapturedHook): void

  type ErrorCapturedHook = (
    err: unknown,
    instance: ComponentPublicInstance | null,
    info: string
  ) => boolean | void
  ```

- **Detalhes**

  Erros podem ser capturados a partir das seguintes fontes:

  - Interpretações de componente
  - Manipuladores de evento
  - Gatilhos do ciclo de vida
  - Função `setup()`
  - Observadores
  - Gatilhos de diretiva personalizada
  - Gatilhos de transição

  O gatilho recebe três argumentos: o erro, a instância do componente que disparou o erro, e uma sequência de caracteres de informação especificando o tipo de erro da fonte.

  :::tip DICA
  Em produção, o terceiro argumento (`info`) será um código encurtado ao invés da sequência de caracteres da informação completa. Nós podemos encontrar o código ao mapeamento da sequência de caracteres na [Referência do Código de Erro de Produção](/error-reference/#runtime-errors).
  :::

  Nós podemos modificar o estado do componente em `errorCaptured()` para mostrar um estado de erro ao utilizador. No entanto, é importante que o estado de erro não desenhe o conteúdo original que causou o erro; de outro modo o componente será lançado num laço de interpretação infinita.

  O gatilho pode retornar `false` para impedir que o erro continue a propagar-se. Consulte os detalhes de propagação de erro abaixo.

  **Regras de Propagação de Erro**

  - Por padrão, todos os erros ainda serão enviados para o nível de aplicação [`app.config.errorHandler`](/api/application#app-config-errorhandler) se for definido, para que estes erros possam ser relatados à um serviço de análises num único lugar.

  - Se vários gatilhos de `errorCaptured` existirem numa cadeia de herança de componentes ou em uma cadeia de pais, todos serão invocados com o mesmo erro, na ordem de baixo para cima. Isto é semelhante ao mecanismo borbulhante de eventos de DOM nativos.

  - Se o próprio gatilho `errorCaptured` lançar um erro, tanto este erro quanto o erro original capturado serão enviados à `app.config.errorHandler`.

  - Um gatilho `errorCaptured` pode retornar `false` para evitar que o erro continue a propagar-se. Isto significa essencialmente que "este erro já foi manipulado e deve ser ignorado". Ele evitará quaisquer gatilhos `errorCaptured` adicionais ou `app.config.errorHandler` de serem invocados por este erro.

## `onRenderTracked()` <sup class="vt-badge dev-only" data-text="desenvolvimento" /> {#onrendertracked}

Regista um gatilho de depuração a ser chamado quando uma dependência reativa tiver sido rastreada pelo efeito da interpretação do componente.

**Este gatilho é apenas para o modo de desenvolvimento e não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  function onRenderTracked(callback: DebuggerHook): void

  type DebuggerHook = (e: DebuggerEvent) => void

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TrackOpTypes /* 'get' | 'has' | 'iterate' */
    key: any
  }
  ```

- **Consulte também:** [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## `onRenderTriggered()` <sup class="vt-badge dev-only" data-text="desenvolvimento" /> {#onrendertriggered}

Regista um gatilho de depuração a ser chamado quando uma dependência reativa aciona o efeito de interpretação do componente a ser executado novamente.

**Este gatilho é apenas para o modo de desenvolvimento e não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  function onRenderTriggered(callback: DebuggerHook): void

  type DebuggerHook = (e: DebuggerEvent) => void

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
    key: any
    newValue?: any
    oldValue?: any
    oldTarget?: Map<any, any> | Set<any>
  }
  ```

- **Consulte também:** [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## `onActivated()` {#onactivated}

Regista uma função de resposta a ser chamada depois da instância do componente for inserida no DOM como parte duma árvore armazenada para consulta imediata pelo [`<KeepAlive>`](/api/built-in-components#keepalive).

**Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  function onActivated(callback: () => void): void
  ```

- **Consulte também:** [Guia - Ciclo de Vida da Instância Armazenada para Consulta Imediata](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## `onDeactivated()` {#ondeactivated}

Regista uma função de resposta a ser chamada depois da instância do componente ser removida do DOM como parte duma árvore armazenada para consulta imediata pelo [`<KeepAlive>`](/api/built-in-components#keepalive).

**Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  function onDeactivated(callback: () => void): void
  ```

- **Consulte também:** [Guia - Ciclo de Vida da Instância Armazenada para Consulta Imediata](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## `onServerPrefetch()` <sup class="vt-badge" data-text="servidor" /> {#onserverprefetch}

Regista uma função assíncrona a ser resolvida antes da instância do componente estiver à ser interpretada no servidor.

- **Tipo**

  ```ts
  function onServerPrefetch(callback: () => Promise<any>): void
  ```

- **Detalhes**

  Se a função de resposta retornar uma promessa, o interpretador do servidor aguardará até a promessa ser resolvida antes de desenhar o componente.

  Este gatilho é chamado apenas durante a interpretação no lado do servidor, pode ser usada para realizar requisição de dados apenas no servidor.

- **Exemplo**

  ```vue
  <script setup>
  import { ref, onServerPrefetch, onMounted } from 'vue'

  const data = ref(null)

  onServerPrefetch(async () => {
    // componente é interpretado como parte da requisição inicial
    // pré-requisita dados no servidor pois é mais rápido do que no cliente
    data.value = await fetchOnServer(/* ... */)
  })

  onMounted(async () => {
    if (!data.value) {
      // se data for null ao montar, significa que o componente
      // é interpretado dinamicamente no cliente.
      // Realizar uma requisição no lado do cliente.
      data.value = await fetchOnClient(/* ... */)
    }
  })
  </script>
  ```

- **Consulte também:** [Interpretação no Lado do Servidor](/guide/scaling-up/ssr)

---

---
url: /api/custom-renderer.md
---
# API de Interpretação Personalizada {#custom-renderer-api}

## `createRenderer()` {#createrenderer}

Cria um interpretador personalizado. Ao fornecer criação de nó específico de plataforma e APIs de manipulação, podemos influenciar o tempo de execução do núcleo da Vue para atingir ambientes que não tem DOM.

- **Tipo**

  ```ts
  function createRenderer<HostNode, HostElement>(
    options: RendererOptions<HostNode, HostElement>
  ): Renderer<HostElement>

  interface Renderer<HostElement> {
    render: RootRenderFunction<HostElement>
    createApp: CreateAppFunction<HostElement>
  }

  interface RendererOptions<HostNode, HostElement> {
    patchProp(
      el: HostElement,
      key: string,
      prevValue: any,
      nextValue: any,
      // o resto não é usado pela maioria dos
      // interpretadores personalizados
      isSVG?: boolean,
      prevChildren?: VNode<HostNode, HostElement>[],
      parentComponent?: ComponentInternalInstance | null,
      parentSuspense?: SuspenseBoundary | null,
      unmountChildren?: UnmountChildrenFn
    ): void
    insert(
      el: HostNode,
      parent: HostElement,
      anchor?: HostNode | null
    ): void
    remove(el: HostNode): void
    createElement(
      type: string,
      isSVG?: boolean,
      isCustomizedBuiltIn?: string,
      vnodeProps?: (VNodeProps & { [key: string]: any }) | null
    ): HostElement
    createText(text: string): HostNode
    createComment(text: string): HostNode
    setText(node: HostNode, text: string): void
    setElementText(node: HostElement, text: string): void
    parentNode(node: HostNode): HostElement | null
    nextSibling(node: HostNode): HostNode | null

    // opcional, específico de DOM
    querySelector?(selector: string): HostElement | null
    setScopeId?(el: HostElement, id: string): void
    cloneNode?(node: HostNode): HostNode
    insertStaticContent?(
      content: string,
      parent: HostElement,
      anchor: HostNode | null,
      isSVG: boolean
    ): [HostNode, HostNode]
  }
  ```

- **Exemplo**

  ```js
  import { createRenderer } from '@vue/runtime-core'

  const { render, createApp } = createRenderer({
    patchProp,
    insert,
    remove,
    createElement
    // ...
  })

  // `render` é a API de baixo nível
  // `createApp` retorna uma instância da aplicação
  export { render, createApp }

  // re-exportar as APIs do núcleo da Vue
  export * from '@vue/runtime-core'
  ```

  O `@vue/runtime-dom` da própria Vue é [implementado usando a mesma API](https://github.com/vuejs/core/blob/main/packages/runtime-dom/src/index.ts). Para uma implementação mais simples, consulte o [`@vue/runtime-test`](https://github.com/vuejs/core/blob/main/packages/runtime-test/src/index.ts) que é um pacote privado para testes unitários da própria Vue.

---

---
url: /api/reactivity-advanced.md
---
# API de Reatividade: Avançado {#reactivity-api-advanced}

## `shallowRef()` {#shallowref}

Versão superficial de [`ref()`](./reactivity-core#ref).

- **Tipo**

  ```ts
  function shallowRef<T>(value: T): ShallowRef<T>

  interface ShallowRef<T> {
    value: T
  }
  ```

- **Detalhes**

  Ao contrário de `ref()`, o valor interno duma referência superficial é armazenado e exposto como é, e não será profundamente reativa. Apenas o acesso de `.value` é reativo.

  `shallowRef()` é normalmente usado para otimizações de desempenho de grandes estruturas de dados ou integração com sistemas externos de gestão de estado.

- **Exemplo**

  ```js
  const state = shallowRef({ count: 1 })

  // NÃO aciona mudança
  state.value.count = 2

  // aciona mudança
  state.value = { count: 2 }
  ```

- **Consulte também:**
  - [Guia - Reduzir Custos de Reatividade para Grandes Estruturas Imutáveis](/guide/best-practices/performance#reduce-reactivity-overhead-for-large-immutable-structures)
  - [Guia - Integração com Sistemas de Estado Externos](/guide/extras/reactivity-in-depth#integration-with-external-state-systems)

## `triggerRef()` {#triggerref}

Força o acionamento de efeitos que dependem duma [referência superficial](#shallowref). Isso é normalmente usado depois de fazer-se mutações profundas no valor interno duma referência superficial.

- **Tipo**

  ```ts
  function triggerRef(ref: ShallowRef): void
  ```

- **Exemplo**

  ```js
  const shallow = shallowRef({
    greet: 'Hello, world'
  })

  // Regista "Hello, world" uma vez para o primeiro ensaio
  watchEffect(() => {
    console.log(shallow.value.greet)
  })

  // Isto não acionará o efeito porque a referência é superficial
  shallow.value.greet = 'Hello, universe'

  // Regista "Hello, universe"
  triggerRef(shallow)
  ```

## `customRef()` {#customref}

Cria uma referência personalizada com controlo explícito sobre o rastreio de dependência e acionamento de atualizações.

- **Tipo**

  ```ts
  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>

  type CustomRefFactory<T> = (
    track: () => void,
    trigger: () => void
  ) => {
    get: () => T
    set: (value: T) => void
  }
  ```

- **Detalhes**

  `customRef()` espera uma função de fábrica, que recebe as funções `track` e `trigger` como argumentos e deve retornar um objeto com os métodos `get` e `set`.

  Em geral, `track()` deve ser chamado dentro de `get()`, e `trigger()` deve ser chamado dentro de `set()`. No entanto, temos controlo total sobre quando devem ser chamados ou se devem ser chamados.

- **Exemplo**

  Criação duma referência de velocidade reduzida que apenas atualiza o valor após uma certa pausa após a última chamada definida:

  ```js
  import { customRef } from 'vue'
  
  export function useDebouncedRef(value, delay = 200) {
    let timeout
    return customRef((track, trigger) => {
      return {
        get() {
          track()
          return value
        },
        set(newValue) {
          clearTimeout(timeout)
          timeout = setTimeout(() => {
            value = newValue
            trigger()
          }, delay)
        }
      }
    })
  }
  ```

  Uso no componente:

  ```vue
  <script setup>
  import { useDebouncedRef } from './debouncedRef'
  const text = useDebouncedRef('hello')
  </script>

  <template>
    <input v-model="text" />
  </template>
  ```

  [Experimentar na Zona de Testes](https://play.vuejs.org/#eNplUkFugzAQ/MqKC1SiIekxIpEq9QVV1BMXCguhBdsyaxqE/PcuGAhNfYGd3Z0ZDwzeq1K7zqB39OI205UiaJGMOieiapTUBAOYFt/wUxqRYf6OBVgotGzA30X5Bt59tX4iMilaAsIbwelxMfCvWNfSD+Gw3++fEhFHTpLFuCBsVJ0ScgUQjw6Az+VatY5PiroHo3IeaeHANlkrh7Qg1NBL43cILUmlMAfqVSXK40QUOSYmHAZHZO0KVkIZgu65kTnWp8Qb+4kHEXfjaDXkhd7DTTmuNZ7MsGyzDYbz5CgSgbdppOBFqqT4l0eX1gZDYOm057heOBQYRl81coZVg9LQWGr+IlrchYKAdJp9h0C6KkvUT3A6u8V1dq4ASqRgZnVnWg04/QWYNyYzC2rD5Y3/hkDgz8fY/cOT1ZjqizMZzGY3rDPC12KGZYyd3J26M8ny1KKx7c3X25q1c1wrZN3L9LCMWs/+AmeG6xI=)

## `shallowReactive()` {#shallowreactive}

Versão superficial de [`reactive()`](./reactivity-core#reactive).

- **Tipo**

  ```ts
  function shallowReactive<T extends object>(target: T): T
  ```

- **Detalhes**

  Ao contrário de `reactive()`, não existe conversão profunda: apenas as propriedades de nível raiz são reativas para um objeto reativo superficial. Os valores de propriedade são armazenados e expostos como são - isto também significa que as propriedades com valores de referência **não** serão desembrulhados automaticamente.

  :::warning Use com Cautela
  Estruturas de dados superficiais devem ser usadas apenas para o estado de nível de raiz num componente. Evite encaixá-lo dentro dum objeto reativo profundo, visto que cria uma árvore com comportamento de reatividade inconsistente que pode ser difícil de entender e depurar.
  :::

- **Exemplo**

  ```js
  const state = shallowReactive({
    foo: 1,
    nested: {
      bar: 2
    }
  })

  // a mutação das propriedades do próprio estado é reativa
  state.foo++

  // ...mas não converte objetos encaixados
  isReactive(state.nested) // false

  // NÃO é reativo
  state.nested.bar++
  ```

## `shallowReadonly()` {#shallowreadonly}

Versão superficial de [`readonly()`](./reactivity-core#readonly).

- **Tipo**

  ```ts
  function shallowReadonly<T extends object>(target: T): Readonly<T>
  ```

- **Detalhes**

  Ao contrário de `readonly()`, não existe conversão profunda: apenas propriedades de nível de raiz são tornadas de somente leitura. Os valores de propriedade são armazenados e expostos como são - isto também significa que as propriedades com valores de referência **não** serão desembrulhados automaticamente.

  :::warning Use com Cautela
  Estruturas de dados rasas devem ser usadas apenas para o estado de nível de raiz num componente. Evite encaixá-lo dentro dum objeto reativo profundo, visto que cria uma árvore com comportamento de reatividade inconsistente que pode ser difícil de entender e depurar.
  :::

- **Exemplo**

  ```js
  const state = shallowReadonly({
    foo: 1,
    nested: {
      bar: 2
    }
  })

  // a mutação das propriedades do próprio estado falhará
  state.foo++

  // ...mas funciona sobre objetos encaixados
  isReadonly(state.nested) // false

  // funciona
  state.nested.bar++
  ```

## `toRaw()` {#toraw}

Retorna o puro, objeto original duma delegação criada pela Vue.

- **Tipo**

  ```ts
  function toRaw<T>(proxy: T): T
  ```

- **Detalhes**

  `toRaw()` pode retornar o objeto original a partir das delegações criadas por [`reactive()`](./reactivity-core#reactive), [`readonly()`](./reactivity-core#readonly ), [`shallowReactive()`](#shallowreactive) ou [`shallowReadonly()`](#shallowreadonly).

  Isto é uma escotilha de fuga que pode ser usada para ler temporariamente sem ficar sujeito ao acesso da delegação ou custos de rastreio ou escrever sem acionar mudanças. **Não** é recomendado segurar uma referência persistente ao objeto original. Use com cautela.

- **Exemplo**

  ```js
  const foo = {}
  const reactiveFoo = reactive(foo)

  console.log(toRaw(reactiveFoo) === foo) // true
  ```

## `markRaw()` {#markraw}

Marca um objeto para nunca ser convertido à uma delegação. Retorna o próprio objeto.

- **Tipo**

  ```ts
  function markRaw<T extends object>(value: T): T
  ```

- **Exemplo**

  ```js
  const foo = markRaw({})
  console.log(isReactive(reactive(foo))) // false

  // também funciona quando encaixado dentro dos outros objetos reativos
  const bar = reactive({ foo })
  console.log(isReactive(bar.foo)) // false
  ```

  :::warning Use com Cautela
  `markRaw()` e as APIs superficiais tais como `shallowReactive()` permitem-nos abandonar seletivamente a conversão profunda reativa ou de somente leitura padrão e fixar objetos brutos não delegados no nosso grafo de estado. Eles podem ser usados ​​por várias razões:

  - Alguns valores simplesmente não deveriam ser reativos, por exemplo, uma instância de classe de terceiros complexa ou um objeto de componente Vue.

  - Ignorar a conversão de delegação pode fornecer melhorias de desempenho quando interpretamos grandes listas com fontes de dados imutáveis.

  Eles são considerados avançados porque o puro abandono é apenas ao nível de raiz, então se definirmos um objeto puro não marcado encaixado num objeto reativo e então acessá-lo novamente, recebemos de volta a versão delegada. Isto pode conduzir à **riscos de identidade** - por exemplo, executar uma operação que depende da identidade do objeto porém usando ambas a pura e versão delegada do mesmo objeto:


  ```js
  const foo = markRaw({
    nested: {}
  })

  const bar = reactive({
    // apesar de `foo` ser marcada como pura, `foo.nested` não é.
    nested: foo.nested
  })

  console.log(foo.nested === bar.nested) // false
  ```

  Os riscos de identidade são em geral raros. No entanto, para usar adequadamente estas APIs enquanto evitar-se riscos de identidade com segurança exige um conhecimento sólido de como o sistema de reatividade funciona.

  :::

## `effectScope()` {#effectscope}

Cria um objeto de âmbito de efeito que pode capturar os efeitos reativos (por exemplo, propriedades computadas e observadores) criados dentro dela para que estes efeitos possam ser colocados juntos. Para casos de uso detalhados desta API, consulte seu [RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0041-reactivity-effect-scope.md) correspondente.

- **Tipo**

  ```ts
  function effectScope(detached?: boolean): EffectScope

  interface EffectScope {
    run<T>(fn: () => T): T | undefined // `undefined` se o âmbito estiver inativo
    stop(): void
  }
  ```

- **Exemplo**

  ```js
  const scope = effectScope()

  scope.run(() => {
    const doubled = computed(() => counter.value * 2)

    watch(doubled, () => console.log(doubled.value))

    watchEffect(() => console.log('Count: ', doubled.value))
  })

  // colocar todos efeitos no âmbito
  scope.stop()
  ```

## `getCurrentScope()` {#getcurrentscope}

Retorna o [âmbito de efeito](#effectscope) ativo atual, se existir um.

- **Tipo**

  ```ts
  function getCurrentScope(): EffectScope | undefined
  ```

## `onScopeDispose()` {#onscopedispose}

Regista uma função de resposta de despacho no [âmbito de efeito](#effectscope) ativo atual. A função de resposta será invocada quando o âmbito de efeito associado for parado.

Este método pode ser usado como uma substituição não associada ao componente de `onUnmounted` nas funções de composição reutilizáveis, uma vez que a função `setup()` de cada componente da Vue também é invocada num âmbito de efeito.

- **Tipo**

  ```ts
  function onScopeDispose(fn: () => void): void
  ```

---

---
url: /api/reactivity-core.md
---
# API de Reatividade: Núcleo {#reactivity-api-core}

:::info Consultar Também
Para entender melhor as APIs de Reatividade, é recomendado a leitura dos seguintes capítulos no guia:

- [Fundamentos da Reatividade](/guide/essentials/reactivity-fundamentals) (com a preferência de API definida para API de Composição)
- [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)
:::

## `ref()` {#ref}

Recebe um valor interno e retorna um objeto de referência reativa e mutável, que possui uma única propriedade `.value` que aponta para o valor interno.

- **Tipo**

  ```ts
  function ref<T>(value: T): Ref<UnwrapRef<T>>

  interface Ref<T> {
    value: T
  }
  ```

- **Detalhes**

  O objeto de referência é mutável - por exemplo, podemos atribuir novos valores à `.value`. Também é reativo, o que significa que quaisquer operações de leitura à `.value` serão rastreadas, e operações de escrita acionarão os efeitos associados.

  Se um objeto for atribuído como valor duma referência, este objeto torna-se profundamente reativo com a [`reactive()`](#reactive). Isto também significa que se o objeto contiver referências encaixadas, serão profundamente desembrulhadas.

  Para evitar a conversão profunda, use [`shallowRef()`](./reactivity-advanced#shallowref).

- **Exemplo**

  ```js
  const count = ref(0)
  console.log(count.value) // 0

  count.value = 1
  console.log(count.value) // 1
  ```

- **Consultar também:**
  - [Guia - Variáveis Reativas com `ref()`](/guide/essentials/reactivity-fundamentals#reactive-variables-with-ref)
  - [Guia - Tipificando a `ref()`](/guide/typescript/composition-api#typing-ref) <sup class="vt-badge ts" data-text="typescript" />

## `computed()` {#computed}

Recebe uma função recuperadora e retorna um objeto de [referência](#ref) de somente leitura para o valor retornado a partir do recuperador. Também pode receber um objeto com funções `get` e `set`  para criar um objeto de referência gravável.

- **Tipo**

  ```ts
  // somente leitura
  function computed<T>(
    getter: (oldValue: T | undefined) => T,
    // consulte a ligação "Depuração de Propriedades Computadas" abaixo
    debuggerOptions?: DebuggerOptions
  ): Readonly<Ref<Readonly<T>>>

  // gravável
  function computed<T>(
    options: {
      get: (oldValue: T | undefined) => T
      set: (value: T) => void
    },
    debuggerOptions?: DebuggerOptions
  ): Ref<T>
  ```

- **Exemplo**

  Criando uma referência computada de somente leitura:

  ```js
  const count = ref(1)
  const plusOne = computed(() => count.value + 1)

  console.log(plusOne.value) // 2

  plusOne.value++ // erro
  ```

  Criando uma referência computada gravável:

  ```js
  const count = ref(1)
  const plusOne = computed({
    get: () => count.value + 1,
    set: (val) => {
      count.value = val - 1
    }
  })

  plusOne.value = 1
  console.log(count.value) // 0
  ```

  Depuração:

  ```js
  const plusOne = computed(() => count.value + 1, {
    onTrack(e) {
      debugger
    },
    onTrigger(e) {
      debugger
    }
  })
  ```

- **Consultar também:**
  - [Guia - Propriedades Computadas](/guide/essentials/computed)
  - [Guia - Depuração de Propriedades Computadas](/guide/extras/reactivity-in-depth#computed-debugging)
  - [Guia - Tipificando a `computed()`](/guide/typescript/composition-api#typing-computed) <sup class="vt-badge ts" data-text="typescript" />
  - [Guia - Desempenho - Estabilidade Computada](/guide/best-practices/performance#computed-stability) <sup class="vt-badge" data-text="3.4+" />

## `reactive()` {#reactive}

Retorna uma delegação reativa do objeto.

- **Tipo**

  ```ts
  function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
  ```

- **Detalhes**

  A conversão reativa é "profunda": ela afeta todas as propriedades encaixadas. Um objeto reativo também desembrulha quaisquer propriedades que são [referências](#ref) embora preserve a reatividade.

  Deve-se notar que não existe desembrulho de referência realizado quando a referência é acessada como um elemento dum vetor reativo ou tipo de coleção nativo como `Map`.

  Para evitar esta conversão profunda e somente reter reatividade no nível da raiz, use [`shallowReactive()`](./reactivity-advanced#shallowreactive).

  O objeto retornado e seus objetos encaixados são embrulhados com a [Delegação da ECMAScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) e **não** são iguais ao objeto original. É recomendado trabalhar somente com a delegação reativa e evitar depender do objeto original.

- **Exemplo**

  Criando um objeto reativo:

  ```js
  const obj = reactive({ count: 0 })
  obj.count++
  ```

  Desembrulhando uma referência:

  ```ts
  const count = ref(1)
  const obj = reactive({ count })

  // a referência será desembrulhado
  console.log(obj.count === count.value) // true

  // atualizará `obj.count`
  count.value++
  console.log(count.value) // 2
  console.log(obj.count) // 2

  // `count` será atualizado também
  obj.count++
  console.log(obj.count) // 3
  console.log(count.value) // 3
  ```
  Note que as referências **não** são desembrulhadas quando acessadas como vetor ou elementos de coleções:

  ```js
  const books = reactive([ref('Vue 3 Guide')])
  // precisa de `.value` aqui
  console.log(books[0].value)

  const map = reactive(new Map([['count', ref(0)]]))
  // precisa de `.value` aqui
  console.log(map.get('count').value)
  ```
  Quando atribuímos uma [referência](#ref) à uma propriedade `reactive`, essa referência também será desembrulhada automaticamente. 

  ```ts
  const count = ref(1)
  const obj = reactive({})

  obj.count = count

  console.log(obj.count) // 1
  console.log(obj.count === count.value) // true
  ```

- **Consultar também:**
  - [Guia - Fundamentos de Reatividade](/guide/essentials/reactivity-fundamentals)
  - [Guia - Tipificando a `reactive()`](/guide/typescript/composition-api#typing-reactive) <sup class="vt-badge ts" />

## `readonly()` {#readonly}

Recebe um objeto (reativo ou simples) ou uma [referência](#ref) e retorna uma delegação de somente leitura ao original.

- **Tipo**

  ```ts
  function readonly<T extends object>(
    target: T
  ): DeepReadonly<UnwrapNestedRefs<T>>
  ```

- **Detalhes**

  Uma delegação de somente leitura é profunda: qualquer propriedade encaixada acessada serão de somente leitura também. Ela possui o mesmo mecanismo de desembrulho de referências que a `reactive()`, exceto que valores desembrulhados também serão de somente leitura.

  Para evitar a conversão profunda, use [shallowReadonly()](./reactivity-advanced#shallowreadonly).

- **Exemplo**

  ```js
  const original = reactive({ count: 0 })

  const copy = readonly(original)

  watchEffect(() => {
    // funciona para o rastreio da reatividade
    console.log(copy.count)
  })

  // modificar o objeto original disparará observadores que dependem da cópia
  original.count++

  // modificações na cópia falharão e resultarão num aviso
  copy.count++ // aviso!
  ```

## `watchEffect()` {#watcheffect}

Executa uma função imediatamente enquanto rastreia reativamente suas dependências, e as re-executa sempre que as dependências forem modificadas.

- **Tipo**

  ```ts
  function watchEffect(
    effect: (onCleanup: OnCleanup) => void,
    options?: WatchEffectOptions
  ): StopHandle

  type OnCleanup = (cleanupFn: () => void) => void

  interface WatchEffectOptions {
    flush?: 'pre' | 'post' | 'sync' // pré-definido como: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }

  type StopHandle = () => void
  ```

- **Detalhes**

  O primeiro argumento é a função de efeito a ser executada. A função de efeito recebe uma função que pode ser usada para registar uma função de resposta de limpeza. A função de resposta de limpeza será chamada bem antes duma função de efeito ser re-executada, e pode ser usada para limpar efeitos colaterais invalidados, por exemplo, uma requisição assíncrona pendente (consulte o exemplo abaixo).

  O segundo argumento é um objeto de configuração opcional que pode ser usado para ajustar o tempo de descarga ou depurar as dependências do efeito.

  Por padrão, observadores executarão apenas antes da interpretação do componente. Definir `flush: 'post'` adiará o observador até depois da interpretação do componente. Consulte [Tempo de Descarga da Função de Resposta](/guide/essentials/watchers#callback-flush-timing) por mais informações. Nos casos raros, pode ser necessário acionar um observador imediatamente quando as dependências mudam, por exemplo, para invalidar uma memória de consulta imediata. Isto pode ser alcançado usando `flush: 'sync'`. No entanto, esta configuração deve ser usada com cautela, visto que pode conduzir à problemas de desempenho e consistência de dados se várias propriedades estiverem sendo atualizadas ao mesmo tempo.

  O valor de retorno é uma função de manipulação que pode ser chamada para impedir o efeito de executar novamente.

- **Example**

  ```js
  const count = ref(0)

  watchEffect(() => console.log(count.value))
  // -> logs 0

  count.value++
  // -> logs 1
  ```

  Limpeza de efeitos colaterais:

  ```js
  watchEffect(async (onCleanup) => {
    const { response, cancel } = doAsyncWork(id.value)
    // `cancel` será chamada se `id` mudar
    // para que requisições pendentes anteriores sejam canceladas
    // se ainda não foram completadas

    onCleanup(cancel)
    data.value = await response
  })
  ```

  Parando o observador:

  ```js
  const stop = watchEffect(() => {})

  // quando o observador não for mais necessário:
  stop()
  ```

  Opções:

  ```js
  watchEffect(() => {}, {
    flush: 'post',
    onTrack(e) {
      debugger
    },
    onTrigger(e) {
      debugger
    }
  })
  ```

- **Consulte também**:
  - [Guia - Observadores](/guide/essentials/watchers#watcheffect)
  - [Guia - Depuração de Observadores](/guide/extras/reactivity-in-depth#watcher-debugging)

## `watchPostEffect()` {#watchposteffect}

Pseudónimo da [`watchEffect()`](#watcheffect) com a opção `flush: 'post'`.

## `watchSyncEffect()` {#watchsynceffect}

Pseudónimo da [`watchEffect()`](#watcheffect) com a opção `flush: 'sync'`.

## `watch()` {#watch}

Observa uma ou mais fontes de dados reativos e invoca uma função de resposta quando as
fontes mudam.

- **Tipo**

  ```ts
  // observando uma única fonte
  function watch<T>(
    source: WatchSource<T>,
    callback: WatchCallback<T>,
    options?: WatchOptions
  ): StopHandle

  // observando várias fontes
  function watch<T>(
    sources: WatchSource<T>[],
    callback: WatchCallback<T[]>,
    options?: WatchOptions
  ): StopHandle

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  type WatchSource<T> =
    | Ref<T> // referência
    | (() => T) // recuperador
    | T extends object
    ? T
    : never // objeto reativo

  interface WatchOptions extends WatchEffectOptions {
    immediate?: boolean // pré-definido como: false
    deep?: boolean // pré-definido como: false
    flush?: 'pre' | 'post' | 'sync' // pré-definido como: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
    once?: boolean // pré-definido como: false (3.4+)
  }
  ```

  > Os tipos foram simplificados para facilitar a leitura.

- **Detalhes**

  `watch()` é preguiçosa por padrão - por exemplo, a função de resposta é apenas chamada quando a fonte observada for mudada.

  O primeiro argumento é a **fonte** do observador. A fonte pode ser uma das seguintes:

  - Uma função recuperadora que retorna um valor
  - Uma referência
  - Um objeto reativo
  - ...ou um vetor de itens acima.

  O segundo argumento é a função de resposta que será chamada quando a fonte mudar. A função de resposta recebe três argumentos: o novo valor, o valor antigo e a função para registar uma função de resposta da limpeza de efeito colateral. A função de resposta da limpeza será chamada imediatamente antes da próxima vez do efeito ser re-executado, e pode ser usada para limpar efeitos colaterais invalidados, por exemplo, uma requisição assíncrona pendente.

  Quando observamos várias fontes, a função de resposta recebe dois vetores contendo novos ou antigos valores correspondendo ao vetor de fonte.

  O terceiro argumento opcional é um objeto de opções que suporta as seguintes opções:

  - **`immediate`**: aciona a função de resposta imediatamente depois da criação do observador. O valor antigo será `undefined` na primeira chamada.
  - **`deep`**: força travessia profunda da fonte se for um objeto, para que a função de resposta dispare sobre as mutações profundas. Consulte [Observadores Profundos](/guide/essentials/watchers#deep-watchers).
  - **`flush`**: ajusta o tempo de descarga da função de resposta. Consulte [Tempo de Descarga da Função de Resposta](/guide/essentials/watchers#callback-flush-timing) e [`watchEffect()`](/api/reactivity-core#watcheffect).
  - **`onTrack / onTrigger`**: depura as dependências do observador. Consulte [Depuração de Observadores](/guide/extras/reactivity-in-depth#watcher-debugging).
  - **`once`**: executa a função de resposta apenas uma vez. O observador é parado automaticamente depois da primeira execução da função de resposta. <sup class="vt-badge" data-text="3.4+" />

  Comparado ao [`watchEffect()`](#watcheffect), `watch()` permite-nos:

  - Executar os efeitos colaterais preguiçosamente;
  - Ser mais específico sobre qual estado deve acionar o observador à ser re-executar;
  - Acessar ambos o valor anterior e atual estado do estado observado.

- **Exemplo**

  Observando um recuperador:

  ```js
  const state = reactive({ count: 0 })
  watch(
    () => state.count,
    (count, prevCount) => {
      /* ... */
    }
  )
  ```

  Observando uma referência:

  ```js
  const count = ref(0)
  watch(count, (count, prevCount) => {
    /* ... */
  })
  ```

  Quando observamos várias fontes, a função de resposta recebe vetores contendo novos ou valores antigos correspondendo ao vetor de fonte:

  ```js
  watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
    /* ... */
  })
  ```
  Quando usamos a fonte dum recuperador, o observador apenas dispara se o valor de retorno do recuperador for mudado. Se quisermos que função de resposta dispara mesmo sobre mutações profundas, precisamos de explicitamente forçar o observador a entrar num modo profundo com `{ deep: true }`. Nota: no modo profundo, o novo valor e antigo serão o mesmo objeto se a função de resposta foi acionada por uma mutação profunda:

  ```js
  const state = reactive({ count: 0 })
  watch(
    () => state,
    (newValue, oldValue) => {
      // newValue === oldValue
    },
    { deep: true }
  )
  ```
  
  Quando observamos diretamente um objeto reativo, o observador está automaticamente no modo profundo:

  ```js
  const state = reactive({ count: 0 })
  watch(state, () => {
    /* aciona sobre a mutação profunda para o estado */
  })
  ```

  `watch()` partilha o mesmo tempo de descarga e opções de depuração com [`watchEffect()`](#watcheffect):

  ```js
  watch(source, callback, {
    flush: 'post',
    onTrack(e) {
      debugger
    },
    onTrigger(e) {
      debugger
    }
  })
  ```

  Parando o observador:

  ```js
  const stop = watch(source, callback)

  // quando o observador não for mais necessário:
  stop()
  ```

  Limpeza de efeitos colaterais:

  ```js
  watch(id, async (newId, oldId, onCleanup) => {
    const { response, cancel } = doAsyncWork(newId)
    // `cancel` será chamada se `id` mudar, cancelando
    // requisições anteriores se ainda não foram completadas
    onCleanup(cancel)
    data.value = await response
  })
  ```

- **Consulte também**:

  - [Guia - Observadores](/guide/essentials/watchers)
  - [Guia - Depuração de Observadores](/guide/extras/reactivity-in-depth#watcher-debugging)

---

---
url: /api/reactivity-utilities.md
---
# API de Reatividade: Utilitários {#reactivity-api-utilities}

## `isRef()` {#isref}

Verifica se um valor é um objeto de referência.

- **Tipo**

  ```ts
  function isRef<T>(r: Ref<T> | unknown): r is Ref<T>
  ```

  
  Nota que o tipo de retorno é um [predicado de tipo](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates), o que significa que `isRef` pode ser usado como um guarda de tipo:

  ```ts
  let foo: unknown
  if (isRef(foo)) {
    // tipo de foo é reduzido para Ref<unknown>
    foo.value
  }
  ```

## `unref()` {#unref}

Retorna o valor interno se o argumento for uma referência, de outro modo retorna o próprio argumento. Isto é uma função açucareira para `val = isRef(val) ? val.value : val`.

- **Tipo**

  ```ts
  function unref<T>(ref: T | Ref<T>): T
  ```

- **Exemplo**

  ```ts
  function useFoo(x: number | Ref<number>) {
    const unwrapped = unref(x)
    // `unwrapped` agora tem uma garantia de ser número
  }
  ```

## `toRef()` {#toref}

Pode ser usado para normalizar valores ou referências ou recuperadores para as referências (3.3+).

Também pode ser usado para criar uma referência para uma propriedade num objeto reativo de origem. A referência criada é sincronizada com sua propriedade de origem: a mutação da propriedade de origem atualizará a referência, e vice-versa.

- **Tipo**

  ```ts
  // assinatura da normalização (3.3+)
  function toRef<T>(
    value: T
  ): T extends () => infer R
    ? Readonly<Ref<R>>
    : T extends Ref
    ? T
    : Ref<UnwrapRef<T>>

  // assinatura da propriedade do objeto
  function toRef<T extends object, K extends keyof T>(
    object: T,
    key: K,
    defaultValue?: T[K]
  ): ToRef<T[K]>

  type ToRef<T> = T extends Ref ? T : Ref<T>
  ```

- **Exemplo**

  Assinatura da normalização (3.3+):

  ```js
  // retorna as referências existentes como são
  toRef(existingRef)

  // cria um referência de apenas leitura que chama
  // o recuperador sobre o acesso de `.value`
  toRef(() => props.foo)

  // cria referências normais a partir de valores 
  // que são funções equivalentes à `ref(1)`
  toRef(1)
  ```

  Assinatura da propriedade do objeto:

  ```js
  const state = reactive({
    foo: 1,
    bar: 2
  })

  // uma referência bidirecional que sincroniza com
  // a propriedade original
  const fooRef = toRef(state, 'foo')

  // mudanças na referência atualizam o original
  fooRef.value++
  console.log(state.foo) // 2

  // mudanças no original também atualizam a referência
  state.foo++
  console.log(fooRef.value) // 3
  ```

  Nota que isto é diferente de:

  ```js
  const fooRef = ref(state.foo)
  ```

  A referência acima **não** está sincronizada com `state.foo`, porque a `ref()` recebe um valor numérico simples.

  `toRef()` é útil quando queremos passar a referência duma propriedade à uma função de composição:

  ```vue
  <script setup>
  import { toRef } from 'vue'
  
  const props = defineProps(/* ... */)

  // converter `props.foo` numa referência, depois
  // passar à uma função de composição
  useSomeFeature(toRef(props, 'foo'))

  // sintaxe de recuperador - recomendado na 3.3+
  useSomeFeature(toRef(() => props.foo))
  </script>
  ```

  Quando `toRef` é usada com as propriedades dos componentes, as restrições habituais em torno da mutação de propriedades ainda aplicam-se. Tentar atribuir um novo valor à referência é equivalente a tentativa de modificar a propriedade diretamente e não é permitido. Neste cenário podemos considerar o uso de [`computed`](./reactivity-core#computed) com `get` e `set`. Consulte o guia [usando `v-model` com os componentes](/guide/components/v-model) por mais informações.

  Quando usamos a assinatura da propriedade do objeto, `toRef()` retornará uma referência usável mesmo se a propriedade de origem não existir atualmente. Isto torna possível trabalhar com propriedades opcionais, que não seriam escolhidas pelas [`toRefs`](#torefs).

## `toValue()` <sup class="vt-badge" data-text="3.3+" /> {#tovalue}

Normaliza valores ou referências ou recuperadores para valores. Isto é semelhante à [`unref()`](#unref), exceto que também normaliza recuperadores. Se o argumento for um recuperador, será invocado e seu valor de retorno será retornado.

Isto pode ser usado nas [Funções de Composição](/guide/reusability/composables) para normalizar um argumento que pode ser ou um valor, uma referência, ou um recuperador.

- **Tipo**

  ```ts
  function toValue<T>(source: T | Ref<T> | (() => T)): T
  ```

- **Exemplo**

  ```js
  toValue(1) //        --> 1
  toValue(ref(1)) //   --> 1
  toValue(() => 1) //  --> 1
  ```

  Normalização de argumentos nas funções de composição:

  ```ts
  import type { MaybeRefOrGetter } from 'vue'

  function useFeature(id: MaybeRefOrGetter<number>) {
    watch(() => toValue(id), id => {
      // reagir às mudanças do `id`
    })
  }

  // esta função de composição suporta alguma das seguintes:
  useFeature(1)
  useFeature(ref(1))
  useFeature(() => 1)
  ```

## `toRefs()` {#torefs}

Converte um objeto reativo num objeto simples onde cada propriedade do objeto resultante é uma referência apontando para a propriedade correspondente do objeto original. Cada referência individual é criada usando [`toRef()`](#toref).

- **Tipo**

  ```ts
  function toRefs<T extends object>(
    object: T
  ): {
    [K in keyof T]: ToRef<T[K]>
  }

  type ToRef = T extends Ref ? T : Ref<T>
  ```

- **Exemplo**

  ```js
  const state = reactive({
    foo: 1,
    bar: 2
  })

  const stateAsRefs = toRefs(state)
  /*
  Type de stateAsRefs: {
    foo: Ref<number>,
    bar: Ref<number>
  }
  */

  // A referência e a propriedade original estão "vinculadas"
  state.foo++
  console.log(stateAsRefs.foo.value) // 2

  stateAsRefs.foo.value++
  console.log(state.foo) // 3
  ```

  `toRefs` é útil quando retornamos um objeto reativo a partir duma função de composição para que o componente consumidor possa desestruturar ou propagar o objeto retornado sem perder a reatividade:

  ```js
  function useFeatureX() {
    const state = reactive({
      foo: 1,
      bar: 2
    })

    // ...lógica operando no estado

    // converter às referências quando retornar
    return toRefs(state)
  }

  // pode desestruturar sem perder a reatividade
  const { foo, bar } = useFeatureX()
  ```

  `toRefs` apenas gerará referências para propriedades que são enumeráveis ​​no objeto de origem no momento da chamada. Para criar uma referência para uma propriedade que talvez ainda não exista, use [`toRef`](#toref).

## `isProxy()` {#isproxy}

Verifica se um objeto é uma delegação criada por [`reactive()`](./reactivity-core.html#reactive), [`readonly()`](./reactivity-core#readonly), [`shallowReactive()`](./reactivity-advanced#shallowreactive) ou [`shallowReadonly()`](./reactivity-advanced#shallowreadonly).

- **Tipo**

  ```ts
  function isProxy(value: unknown): boolean
  ```

## `isReactive()` {#isreactive}

Verifica se um objeto é uma delegação criada por [`reactive()`](./reactivity-core#reactive) ou [`shallowReactive()`](./reactivity-advanced#shallowreactive).

- **Tipo**

  ```ts
  function isReactive(value: unknown): boolean
  ```

## `isReadonly()` {#isreadonly}

Verifica se o valor passado é um objeto de somente leitura. As propriedades dum objeto de somente leitura podem mudar, mas não podem ser atribuídas diretamente através do objeto passado.

As delegações criadas por [`readonly()`](./reactivity-core#readonly) e [`shallowReadonly()`](./reactivity-advanced#shallowreadonly) são ambas consideradas de somente leitura, visto que são uma referência [`computed()`](./reactivity-core#computed) sem uma função `set`.

- **Tipo**

  ```ts
  function isReadonly(value: unknown): boolean
  ```

---

---
url: /api/general.md
---
# API Global: Geral {#global-api-general}

## `version` {#version}

Expõe a versão atual da Vue.

- **Tipo:** `string`

- **Exemplo**

  ```js
  import { version } from 'vue'

  console.log(version)
  ```

## `nextTick()` {#nexttick}

Um utilitário para esperar o próximo fluxo de atualização do DOM.

- **Tipo**

  ```ts
  function nextTick(callback?: () => void): Promise<void>
  ```

- **Detalhes**

  Quando mudamos o estado reativo na Vue, as atualizações do DOM resultantes não são aplicadas de maneira síncrona. Em vez disso, a Vue amortece-as até o "próximo tiquetaque" para garantir que cada componente atualize apenas uma vez, não importa quantas mudanças de estado tenhamos realizado.

  `nextTick()` pode ser usado imediatamente depois de uma mudança de estado para esperar as atualizações do DOM concluírem. Nós podemos ou passar uma função de resposta como argumento, ou aguardar pela promessa retornada.

- **Exemplo**

  <div class="composition-api">

  ```vue
  <script setup>
  import { ref, nextTick } from 'vue'

  const count = ref(0)

  async function increment() {
    count.value++

    // DOM ainda não foi atualizado
    console.log(document.getElementById('counter').textContent) // 0

    await nextTick()
    // DOM agora está atualizado
    console.log(document.getElementById('counter').textContent) // 1
  }
  </script>

  <template>
    <button id="counter" @click="increment">{{ count }}</button>
  </template>
  ```

  </div>
  <div class="options-api">

  ```vue
  <script>
  import { nextTick } from 'vue'

  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      async increment() {
        this.count++

        // DOM ainda não foi atualizado
        console.log(document.getElementById('counter').textContent) // 0

        await nextTick()
        // DOM agora está atualizado
        console.log(document.getElementById('counter').textContent) // 1
      }
    }
  }
  </script>

  <template>
    <button id="counter" @click="increment">{{ count }}</button>
  </template>
  ```

  </div>

- **Consulte também:** [`this.$nextTick()`](/api/component-instance#nexttick)

## `defineComponent()` {#definecomponent}

Um auxiliar de tipo para definir um componente de Vue com inferência de tipos.

- **Tipo**

  ```ts
  function defineComponent(
    component: ComponentOptions | ComponentOptions['setup']
  ): ComponentConstructor
  ```

  > O tipo está simplificado por legibilidade.

- **Detalhes**

  O primeiro argumento espera um objeto de opções de componente. O valor retornado será o mesmo objeto de opções, uma vez que a função é essencialmente um tempo de execução sem operações com o único propósito de inferir o tipo.

  Perceba que o tipo de retorno é um pouco especial: ele será um construtor de tipo do qual a instância de tipo é a instância do componente inferido baseada nas opções. Isso é usado para inferir o tipo quando o tipo retornado é usado como um marcador em TSX.

  Nós podemos extrair o tipo de instância do componente (equivalente ao tipo do `this` em suas opções) do tipo de retorno do `defineComponent()` desta forma:

  ```ts
  const Foo = defineComponent(/* ... */)

  type FooInstance = InstanceType<typeof Foo>
  ```

  ### Assinatura da Função <sup class="vt-badge" data-text="3.3+" /> {#function-signature}

  `defineComponent()` também tem uma assinatura alternativa que está destinada à ser usada com a API de Composição e as [funções de interpretação ou JSX](/guide/extras/render-function).

  Ao invés da passagem dum objeto de opções, uma função é esperada. Esta função funciona da mesma maneira que a função [`setup()`](/api/composition-api-setup#composition-api-setup) da API de Composição: ela recebe as propriedades e o contexto de configuração. O valor de retorno deve ser uma função de interpretação - ambos `h()` e JSX são suportados:

  ```js
  import { ref, h } from 'vue'

  const Comp = defineComponent(
    (props) => {
      // usar a API de Composição como no <script setup>
      const count = ref(0)

      return () => {
        // função de interpretação ou JSX
        return h('div', count.value)
      }
    },
    // opções adicionais, por exemplo, declarar propriedades e emissões
    {
      props: {
        /* ... */
      }
    }
  )
  ```

  O caso de uso principal para esta assinatura é com a TypeScript (e em especial com a TSX), visto que suporta genéricos:

  ```tsx
  const Comp = defineComponent(
    <T extends string | number>(props: { msg: T; list: T[] }) => {
      // usar a API de Composição como no <script setup>
      const count = ref(0)

      return () => {
        // função de interpretação ou JSX
        return <div>{count.value}</div>
      }
    },
    // declaração de propriedades de tempo de execução manual
    // atualmente ainda é necessária.
    {
      props: ['msg', 'list']
    }
  )
  ```

  No futuro, planeamos fornecer uma extensão de Babel que infere e injeta automaticamente as propriedades de tempo de execução (como para `defineProps` nos componentes de ficheiro único) para que a declaração de propriedades de tempo de execução possam ser emitidas.

  ### Nota sobre a agitação de árvores da Webpack {#note-on-webpack-treeshaking}

  Uma vez que `defineComponent()` é uma chamada de função, poderia parecer que produziria efeitos colaterais para algumas ferramentas de construção, por exemplo, Webpack. Isto prevenirá o componente de ter a árvore agitada mesmo quando o componente nunca for usado.

  Para dizer à Webpack que esta chamada de função está segura para ter a árvore agitada, podes adicionar uma notação de comentário `/*#__PURE__*/` antes da chamada da função:

  ```js
  export default /*#__PURE__*/ defineComponent(/* ... */)
  ```

  Nota que isto não é necessário se estivermos a usar a Vite, porque a Rollup (o empacotador de produção subjacente usado pela Vite) é inteligente o suficiente para determinar que `defineComponent` está de fato livre de efeito colateral sem a necessidade de notações manuais.

- **Consulte também:** [Guia - Usar a Vue com a TypeScript](/guide/typescript/overview#general-usage-notes)

## `defineAsyncComponent()` {#defineasynccomponent}

Define um componente assíncrono que é carregado preguiçosamente apenas quando é interpretado. O argumento pode ser ou uma função carregadora, ou um objeto de opções para controlo mais avançado do comportamento de carregamento.

- **Tipo**

  ```ts
  function defineAsyncComponent(
    source: AsyncComponentLoader | AsyncComponentOptions
  ): Component

  type AsyncComponentLoader = () => Promise<Component>

  interface AsyncComponentOptions {
    loader: AsyncComponentLoader
    loadingComponent?: Component
    errorComponent?: Component
    delay?: number
    timeout?: number
    suspensible?: boolean
    onError?: (
      error: Error,
      retry: () => void,
      fail: () => void,
      attempts: number
    ) => any
  }
  ```

- **Consulte também:** [Guia - Componentes Assíncronos](/guide/components/async)

## `defineCustomElement()` {#definecustomelement}

Este método aceita o mesmo argumento que [`defineComponent`](#definecomponent), porém este retorna um construtor de classe de [Elemento Personalizado](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) nativo.

- **Tipo**

  ```ts
  function defineCustomElement(
    component:
      | (ComponentOptions & { styles?: string[] })
      | ComponentOptions['setup']
  ): {
    new (props?: object): HTMLElement
  }
  ```

  > Tipo está simplificado para legibilidade.

- **Detalhes**

  Além das opções normais de componente, o `defineCustomElement()` também suporta uma opção especial `styles`, que deve ser um _array_ de strings CSS alinhadas, para fornecer CSS que será injetado na _shadow root_ do elemento.
  Além das opções normais do componente, a `defineCustomElement()` também suporta uma opção especial `styles`, que deve ser um vetor de sequências de caracteres sublinhadas, para fornecer CSS que deve ser injetado na raiz da sombra do elemento.

  O valor de retorno é um construtor de elemento personalizado que pode ser registado usando [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).

- **Exemplo**

  ```js
  import { defineCustomElement } from 'vue'

  const MyVueElement = defineCustomElement({
    /* opções do componente */
  })

  // Registar o elemento personalizado.
  customElements.define('my-vue-element', MyVueElement)
  ```

- **Consulte também:**

  - [Guia - Construindo Elementos Personalizados com Vue](/guide/extras/web-components#building-custom-elements-with-vue)

  - Note também que `defineCustomElement()` exige uma [configuração especial](/guide/extras/web-components#sfc-as-custom-element) ao ser usado com Componentes de Ficheiro Único.

---

---
url: /api/render-function.md
---
# APIs da Função de Interpretação {#render-function-apis}

## `h()` {#h}

Cria nós do DOM virtual (vnodes).

- **Tipo**

  ```ts
  // assinatura completa
  function h(
    type: string | Component,
    props?: object | null,
    children?: Children | Slot | Slots
  ): VNode

  // omitindo propriedades
  function h(type: string | Component, children?: Children | Slot): VNode

  type Children = string | number | boolean | VNode | null | Children[]

  type Slot = () => Children

  type Slots = { [name: string]: Slot }
  ```

  > Os tipos foram simplificados para fins de legibilidade.

- **Detalhes**

  O primeiro argumento pode ser ou uma sequência de caracteres (para os elementos nativos) ou uma definição de componente da Vue. O segundo argumento são as propriedades à serem passadas, e o terceiro são os filhos.

  Quando criamos um nó virtual de componente, os filhos devem ser passados como funções de ranhura. Uma única função de ranhura pode ser passada se o componente esperar apenas a ranhura padrão. De outro modo, as ranhuras devem ser passadas como um objeto de funções de ranhura.

  Por conveniência, o argumento de propriedades pode ser omitido quando os filhos não forem um objeto de ranhuras.

- **Exemplo**

  Criando elementos nativos:

  ```js
  import { h } from 'vue'

  // todos os argumentos exceto o tipo são opcionais
  h('div')
  h('div', { id: 'foo' })

  // ambos atributos e propriedades podem ser usados ​​em propriedades
  // a Vue escolhe automaticamente a maneira correta de atribuí-los
  h('div', { class: 'bar', innerHTML: 'hello' })

  // `class` e `style` têm o mesmo objeto ou vetor
  // suporte de valor tal como nos modelos de marcação
  h('div', { class: [foo, { bar }], style: { color: 'red' } })

  // os ouvintes de evento devem ser passados como `onXxx`
  h('div', { onClick: () => {} })

  // os filhos podem ser uma sequência de caracteres
  h('div', { id: 'foo' }, 'hello')

  // as propriedades podem ser omitidas quando não existirem propriedades
  h('div', 'hello')
  h('div', [h('span', 'hello')])

  // o vetor de filhos pode conter nós virtuais e
  // sequências de caracteres misturados
  h('div', ['hello', h('span', 'hello')])
  ```

  Criando componentes:

  ```js
  import Foo from './Foo.vue'

  // passando propriedades
  h(Foo, {
    // equivalente de `some-prop="hello"`
    someProp: 'hello',
    // equivalente de `@update="() => {}"`
    onUpdate: () => {}
  })

  // passando a única ranhura padrão
  h(Foo, () => 'default slot')

  // passando ranhuras nomeadas
  // repara que o `null` é obrigatório para evitar
  // que o objeto de ranhuras seja tratado como propriedades
  h(MyComponent, null, {
    default: () => 'default slot',
    foo: () => h('div', 'foo'),
    bar: () => [h('span', 'one'), h('span', 'two')]
  })
  ```

- **Consulte também** [Guia - Funções de Interpretação - Criando Nós Virtuais](/guide/extras/render-function#creating-vnodes)

## `mergeProps()` {#mergeprops}

Combina vários objetos de propriedades com tratamento especial para certas propriedades.

- **Tipo**

  ```ts
  function mergeProps(...args: object[]): object
  ```

- **Detalhes**

  `mergeProps()` suporta a fusão de vários objetos de propriedades com tratamento especial para as seguintes propriedades:

  - `class`
  - `style`
  - Ouvintes de evento `onXxx` - vários ouvintes com o mesmo nome serão combinados num vetor.

  Se não precisarmos do comportamento de combinação e quisermos substituições simples, q propagação de objeto nativo pode ser usada.

- **Exemplo**

  ```js
  import { mergeProps } from 'vue'

  const one = {
    class: 'foo',
    onClick: handlerA
  }

  const two = {
    class: { bar: true },
    onClick: handlerB
  }

  const merged = mergeProps(one, two)
  /**
   {
     class: 'foo bar',
     onClick: [handlerA, handlerB]
   }
   */
  ```

## `cloneVNode()` {#clonevnode}

Clona um nó virtual.

- **Tipo**

  ```ts
  function cloneVNode(vnode: VNode, extraProps?: object): VNode
  ```

- **Detalhes**

  Retorna um nó virtual clonado, opcionalmente com propriedades adicionais para combinar com o original.

  Uma vez criados os nós virtuais devem ser considerados imutáveis e não devemos mudar as propriedades dum nó virtual existente. Ao invés disto, o clonamos com propriedades diferentes ou adicionais.

  Os nós virtuais têm propriedades internas especiais, então cloná-los não tão simples quando uma propagação de objeto. `cloneVNode()` manipula a maioria da lógica interna.

- **Exemplo**

  ```js
  import { h, cloneVNode } from 'vue'

  const original = h('div')
  const cloned = cloneVNode(original, { id: 'foo' })
  ```

## `isVNode()` {#isvnode}

Verifica se um valor é um nó virtual.

- **Tipo**

  ```ts
  function isVNode(value: unknown): boolean
  ```

## `resolveComponent()` {#resolvecomponent}

Para resolver manualmente um componente registado por nome.

- **Tipo**

  ```ts
  function resolveComponent(name: string): Component | string
  ```

- **Detalhes**

  **Nota: não precisamos disto se pudermos importar o componente diretamente.**

  `resolveComponent()` deve ser chamada dentro <span class="composition-api">da `setup()` ou</span> da função de interpretação no sentido de resolver a partir do contexto do componente correto.

  Se o componente não for encontrado, um aviso de execução será emitido, e a sequência de caracteres do nome é retornada.

- **Exemplo**

  <div class="composition-api">

  ```js
  import { h, resolveComponent } from 'vue'

  export default {
    setup() {
      const ButtonCounter = resolveComponent('ButtonCounter')

      return () => {
        return h(ButtonCounter)
      }
    }
  }
  ```

  </div>
  <div class="options-api">

  ```js
  import { h, resolveComponent } from 'vue'

  export default {
    render() {
      const ButtonCounter = resolveComponent('ButtonCounter')
      return h(ButtonCounter)
    }
  }
  ```

  </div>

- **Consulte também** [Guia - Funções de Interpretação - Componentes](/guide/extras/render-function#components)

## `resolveDirective()` {#resolvedirective}

Para resolver manualmente uma diretiva registada por nome.

- **Tipo**

  ```ts
  function resolveDirective(name: string): Directive | undefined
  ```

- **Detalhes**

  **Nota: não precisamos disto se pudermos importar a diretiva diretamente.**

  `resolveDirective()` dever chamada dentro <span class="composition-api">da `setup()` ou</span> da função de interpretação no sentido de resolver a partir do contexto do componente correto.

  Se a diretiva não for encontrada, um aviso de execução será emitido, e a função retorna `undefined`.

- **Consulte também** [Guia - Funções de Interpretação - Diretivas Personalizadas](/guide/extras/render-function#custom-directives)

## `withDirectives()` {#withdirectives}

Para adicionar diretivas personalizadas aos nós virtuais.

- **Tipo**

  ```ts
  function withDirectives(
    vnode: VNode,
    directives: DirectiveArguments
  ): VNode

  // [Directive, value, argument, modifiers]
  type DirectiveArguments = Array<
    | [Directive]
    | [Directive, any]
    | [Directive, any, string]
    | [Directive, any, string, DirectiveModifiers]
  >
  ```

- **Detalhes**

  Envolve um nó virtual existente com as diretivas personalizadas. O segundo argumento é um vetor de diretivas personalizadas. Cada diretiva personalizada é também representada como um vetor na forma de `[Directive, value, argument, modifiers]`. Os últimos elementos do vetor podem ser omitidos se não forem necessários.

- **Exemplo**

  ```js
  import { h, withDirectives } from 'vue'

  // uma diretiva personalizada
  const pin = {
    mounted() {
      /* ... */
    },
    updated() {
      /* ... */
    }
  }

  // <div v-pin:top.animate="200"></div>
  const vnode = withDirectives(h('div'), [
    [pin, 200, 'top', { animate: true }]
  ])
  ```

- **Consulte também** [Guia - Funções de Interpretação - Diretivas Personalizadas](/guide/extras/render-function#custom-directives)

## `withModifiers()` {#withmodifiers}

Para adicionar [modificadores de `v-on`](/guide/essentials/event-handling#event-modifiers) embutidos à uma função manipuladora de eventos.

- **Tipo**

  ```ts
  function withModifiers(fn: Function, modifiers: string[]): Function
  ```

- **Exemplo**

  ```js
  import { h, withModifiers } from 'vue'

  const vnode = h('button', {
    // equivalente de `v-on:click.stop.prevent`
    onClick: withModifiers(() => {
      // ...
    }, ['stop', 'prevent'])
  })
  ```

- **Consulte também** [Guia - Funções de Interpretação - Modificadores de Evento](/guide/extras/render-function#event-modifiers)

---

---
url: /guide/components/attrs.md
---

# Atributos de Passagem {#fallthrough-attributes}

> Neste material assume-se conhecimento dos [Fundamentos dos Componentes](/guide/essentials/component-basics). Precisamos entender o básico de componentes para acompanhar este material.

## Herança de Atributo {#attribute-inheritance}

Um "atributo de passagem" é um atributo ou ouvinte de evento de `v-on` que é passado a um componente, mas não é explicitamente declarado nas [propriedades](./props) ou [emissões](./events#declaring-emitted-events) do componente recetor. Os exemplos comuns disto incluem os atributos `class`, `style`, e `id`.

Quando um componente desenhar um único elemento de raiz, os atributos de passagem serão automaticamente adicionados aos atributos do elemento de raiz. Por exemplo, dado um componente `<MyButton>` com o seguinte modelo de marcação:

```vue-html
<!-- modelo de marcação do <MyButton> -->
<button>click me</button>
```

E um pai que utiliza este componente com:

```vue-html
<MyButton class="large" />
```

O modelo de objeto do documento (DOM) resultante seria:

```html
<button class="large">click me</button>
```

Neste exemplo, `<MyButton>` não declarou `class` como uma propriedade aceita. Portanto, `class` é tratado como um atributo de passagem e automaticamente adicionado ao elemento de raiz do `<MyButton>`.

### Fusão de `class` e `style` {#class-and-style-merging}

Se o elemento de raiz do componente filho já tiver atributos `class` ou `style` existentes, este será fundido com os valores de `class` e `style` que serão herdados do pai. Suponhamos que alteramos o modelo de marcação do `<MyButton>` no exemplo anterior para:

```vue-html
<!-- modelo de marcação do <MyButton> -->
<button class="btn">click me</button>
```

Então, o modelo de objeto do documento (DOM) resultante tornar-se-ia agora:

```html
<button class="btn large">click me</button>
```

### Herança de Ouvinte de `v-on` {#v-on-listener-inheritance}

A mesma regra se aplica aos ouvintes de eventos de `v-on`:

```vue-html
<MyButton @click="onClick" />
```

O ouvinte de `click` será adicionado ao elemento de raiz do `<MyButton>`, ou seja, o elemento nativo `<button>`. Quando o `<button>` nativo for clicado, acionará o método `onClick` do componente pai. Se o `<button>` nativo já tiver um ouvinte de `click` vinculado com `v-on`, então ambos os ouvintes serão acionados.

### Herança de Componente Encaixado {#nested-component-inheritance}

Se um componente desenhar outro componente como seu nó de raiz, por exemplo, nós refizemos `<MyButton>` para desenhar um `<BaseButton>` como sua raiz:

```vue-html
<!-- modelo de marcação do <MyButton/> que simplesmente desenha um outro componente -->
<BaseButton />
```

Então os atributos de passagem recebidos por `<MyButton>` serão automaticamente encaminhados ao `<BaseButton>`.

Nota que:

1. Os atributos encaminhados não incluem quaisquer atributos que são declarados como propriedades, ou ouvintes de `v-on` de eventos declarados por `<MyButton>` - em outras palavras, as propriedades e os ouvintes declarados foram "consumidos" por `<MyButton>`.

2. Os atributos encaminhados podem ser aceites como propriedades por `<BaseButton>`, se declarados por este.

## Desativação da Herança de Atributo {#disabling-attribute-inheritance}

Se **não** quisermos que um componente herde automaticamente os atributos, podemos definir `inheritAttrs: false` nas opções do componente.

<div class="composition-api">

Desde a versão 3.3 também podemos usar [`defineOptions`](/api/sfc-script-setup#defineoptions) diretamente em `<script setup>`:

```vue
<script setup>
defineOptions({
  inheritAttrs: false
})
// ...lógica de configuração
</script>
```

</div>

O cenário comum para desativar a herança de atributo é quando os atributos precisam ser aplicados a outros elementos além do nó de raiz. Ao definir a opção `inheritAttrs` como `false`, podemos ter total controlo sobre onde os atributos de passagem devem ser aplicados.

Estes atributos de passagem podem ser acessados diretamente em expressões de modelo de marcação como `$attrs`:

```vue-html
<span>Fallthrough attributes: {{ $attrs }}</span>
```

O objeto `$attrs` inclui todos os atributos que não são declarados pelas opções `props` ou `emits` do componente (por exemplo, `class`, `style`, ouvintes de `v-on`, etc.).

Algumas notas:

- Ao contrário das propriedades, os atributos de passagem preservam a sua caixa de texto original na JavaScript, por isto um atributo como `foo-bar` precisa de ser acessado como `$attrs['foo-bar']`.

- Um ouvinte de evento de `v-on` como `@click` será exposto sobre o objeto como uma função sob a `$attrs.onClick`.

Usando o nosso exemplo do componente `<MyButton>` da [secção anterior](#attribute-inheritance) — por vezes podemos precisar de envolver o verdadeiro elemento `<button>` com um `<div>` adicional para fins de estilização:

```vue-html
<div class="btn-wrapper">
  <button class="btn">click me</button>
</div>
```

Nós queremos que todos os atributos de passagem como `class` e ouvintes de `v-on` que sejam aplicados ao `<button>` interno, não ao `<div>` externo. Nós podemos alcançar isto com `inheritAttrs: false` e `v-bind="$attrs"`:

```vue-html{2}
<div class="btn-wrapper">
  <button class="btn" v-bind="$attrs">click me</button>
</div>
```

É preciso lembrar que [`v-bind` sem um argumento](/guide/essentials/template-syntax#dynamically-binding-multiple-attributes) vincula todas as propriedades dum objeto como atributos ao elemento de destino.

## Herança de Atributo sobre Vários Nós de Raiz {#attribute-inheritance-on-multiple-root-nodes}

Ao contrário dos componentes com um único nó de raiz, os componentes com vários nós de raiz não têm um comportamento automático de passagem de atributo. Se `$attrs` não estiver vinculado explicitamente, um aviso de execução será emitido:

```vue-html
<CustomLayout id="custom-layout" @click="changeValue" />
```

Se `<CustomLayout>` tiver o seguinte modelo de marcação com várias raízes, haverá um aviso porque a Vue não pode ter a certeza de onde aplicar os atributos de passagem:

```vue-html
<header>...</header>
<main>...</main>
<footer>...</footer>
```

O aviso será suprimido se `$attrs` for explicitamente vinculado:

```vue-html{2}
<header>...</header>
<main v-bind="$attrs">...</main>
<footer>...</footer>
```

## Acesso aos Atributos de Passagem na JavaScript {#accessing-fallthrough-attributes-in-javascript}

<div class="composition-api">

Se necessário, podemos acessar os atributos de passagem dum componente no `<script setup>` usando a interface de programação `useAttrs()`:

```vue
<script setup>
import { useAttrs } from 'vue'

const attrs = useAttrs()
</script>
```

Se não estivermos usando o `<script setup>`, `attrs` será exposta como uma propriedade de contexto de `setup()`:

```js
export default {
  setup(props, ctx) {
    // os atributos de passagem são
    // expostos como `ctx.attrs`
    console.log(ctx.attrs)
  }
}
```

Nota que, embora o objeto `attrs` reflita sempre os últimos atributos de passagem, não é reativo (por razões de desempenho). Nós podemos usar observadores para observar as suas alterações. Se precisamos de reatividade, usamos uma propriedade. Alternativamente, podemos usar `onUpdated()` para executar efeitos colaterais com as `attrs` mais recentes em cada atualização.

</div>

<div class="options-api">

Se necessário, podemos acessar os atributos de passagem dum componente através da propriedade de instância `$attrs`:

```js
export default {
  created() {
    console.log(this.$attrs)
  }
}
```

</div>

---

---
url: /api/built-in-special-attributes.md
---
# Atributos Especiais Embutidos {#built-in-special-attributes}

## `key` {#key}

O atributo especial `key` é primariamente usado como uma sugestão para o algoritmo do DOM virtual da Vue identificar os nós virtuais quando diferenciar a nova lista de nós contra a antiga lista.

- **Espera:** `number | string | symbol`

- **Detalhes**

  Sem chaves, a Vue usa um algoritmo que minimiza o movimento de elemento e tenta remendar ou reusar elementos do mesmo tipo no lugar o máximo possível. Com chaves, reorganizará os elementos baseado na mudança de ordem das chaves, e os elementos com chaves que não estão mais presentes sempre serão removidos ou destruídos.

  Os filhos do mesmo pai comum devem ter **chaves únicas**. As chaves duplicadas causarão erros de interpretação.

  O caso de uso mais comum é combinado com `v-for`:

  ```vue-html
  <ul>
    <li v-for="item in items" :key="item.id">...</li>
  </ul>
  ```

  Também pode ser usado para forçar a substituição dum elemento ou componente ao invés de reusá-lo. Isto pode ser útil quando queremos:

  - Acionar corretamente os gatilhos do ciclo de vida dum componente
  - Acionar transições

  Por exemplo:

  ```vue-html
  <transition>
    <span :key="text">{{ text }}</span>
  </transition>
  ```

  Quando `text` mudar, o `<span>` sempre será substituído ao invés de ser remendado, depois uma transição será acionada.

- **Consulte também** [Guia - Interpretação de Lista - Mantendo o Estado com `key`](/guide/essentials/list#maintaining-state-with-key)

## `ref` {#ref}

Denota uma [referência do modelo de marcação](/guide/essentials/template-refs).

- **Espera:** `string | Function`

- **Detalhes**

  `ref` é usado para registar uma referência à um elemento ou à um componente filho.

  Na API de Opções, a referência será registada sob o objeto `this.$refs` do componente:

  ```vue-html
  <!-- armazenado como this.$refs.p -->
  <p ref="p">hello</p>
  ```

  Na API de Composição, a referência será armazenada em uma `ref` com o nome correspondente:

  ```vue
  <script setup>
  import { ref } from 'vue'

  const p = ref()
  </script>

  <template>
    <p ref="p">hello</p>
  </template>
  ```

  Se usado sobre um elemento de DOM simples, a referência será este elemento; se usada sobre um componente filho, a referência será a instância do componente filho.

  Alternativamente, a `ref` pode aceitar um valor de função que fornece controlo total sobre onde armazenar a referência:

  ```vue-html
  <ChildComponent :ref="(el) => child = el" />
  ```

  Uma nota importante sobre o tempo de registo da referência: uma vez que as próprias referências são criadas como resultado da função de interpretação, devemos esperar até o componente ser montado antes de acessá-las.

  `this.$refs` também não é reativa, portanto não devemos tentar usá-la nos modelos de marcação para vínculo de dados.

- **Consulte também**
  - [Guia - Referências do Modelo de Marcação](/guide/essentials/template-refs)
  - [Guia - Tipos para Referências do Modelo de Marcação](/guide/typescript/composition-api#typing-template-refs) <sup class="vt-badge ts" data-text="typescript" />
  - [Guia - Tipos para Referências do Modelo de Marcação do Componente](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" data-text="typescript" />

## `is` {#is}

Usado para vincular os [componentes dinâmicos](/guide/essentials/component-basics#dynamic-components).

- **Espera:** `string | Component`

- **Uso sobre os elementos nativos** <sup class="vt-badge">3.1+</sup>

  Quando o atributo `is` for usado sobre um elemento de HTML nativo, será interpretado como um [elemento embutido personalizado](https://html.spec.whatwg.org/multipage/custom-elements#custom-elements-customized-builtin-example), que é uma funcionalidade da plataforma da Web nativa.

  Existe, no entanto, um caso de uso onde podemos precisar que a Vue substitua um elemento nativo por um elemento da Vue, como explicado nas [Advertências de Analise do Modelo de Marcação de DOM](/guide/essentials/component-basics#dom-template-parsing-caveats). Nós podemos prefixar o valor do atributo `is` com `vue:` assim a Vue interpretará o elemento como um componente de Vue:

  ```vue-html
  <table>
    <tr is="vue:my-row-component"></tr>
  </table>
  ```

- **Consulte também**

  - [Elementos Especiais Embutidos - `<component>`](/api/built-in-special-elements#component)
  - [Componentes Dinâmicos](/guide/essentials/component-basics#dynamic-components)

---

---
url: /ecosystem/newsletters.md
---
# Boletins Informativos da Comunidade {#community-newsletters}

Existem muitos boletins informativos ou blogues dedicados à Vue da comunidade que nos trazem as últimas notícias e acontecimentos no ecossistema da Vue. Eis uma lista não exaustiva dos que estão ativos que encontrámos:

- [Vue.js Feed](https://vuejsfeed.com/)
- [Michael Thiessen](https://michaelnthiessen.com/newsletter)
- [Jakub Andrzejewski](https://dev.to/jacobandrewsky)
- [Weekly Vue News](https://weekly-vue.news/)
- [Vue.js Developers Newsletter](https://vuejsdevelopers.com/newsletter/)

Se soubermos dum bom boletim informativo que ainda não esteja incluído, podemos enviar um pedido de atualização usando a ligação abaixo!

---

---
url: /guide/components/async.md
---
# Componentes Assíncronos {#async-components}

## Uso Básico {#basic-usage}

Em grandes aplicações, podemos precisar dividir a aplicação em partes menores e apenas carregar um componente do servidor quando for necessário. Para possibilitar isto, a Vue tem uma função [`defineAsyncComponent`](/api/general#defineasynccomponent):

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() => {
  return new Promise((resolve, reject) => {
    // ...carregar o componente do servidor
    resolve(/* componente carregado */)
  })
})
// ... usar `AsyncComp` como um componente normal
```

Como podemos ver, `defineAsyncComponent` aceita uma função carregadora que retorna uma promessa. A função de resposta `resolve` da promessa deve ser chamada quando tivermos recuperado a definição da nosso componente do servidor. Nós também podemos chamar `reject(reason)` para indicar que o carregamento falhou.

A [importação dinâmica do módulo da ECMAScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) também retorna uma promessa, então na maioria das vezes a usaremos em conjunto com a `defineAsyncComponent`. As empacotadoras como a Vite e Webpack também suportam a sintaxe (e a usarão como pontos de separação do pacote), assim podemos usá-la para importar os componentes de ficheiro único da Vue:

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
)
```

O `AsyncComp` resultante é um componente embrulhador que só chama a função carregadora quando estiver realmente desenhada na página. Além disto, este passará adiante quaisquer propriedades e ranhuras ao componente interno, assim podemos usar o embrulhador assíncrono para substituir perfeitamente o componente original enquanto realizamos o carregamento preguiçoso.

Tal como acontece com os componentes normais, os componentes assíncronos podem ser [registados globalmente](/guide/components/registration#global-registration) usando `app.component()`:

```js
app.component('MyComponent', defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
))
```

<div class="options-api">

Nós também podemos usar a `defineAsyncComponent` quando estivermos [registando um componente localmente](/guide/components/registration#local-registration):

```vue
<script>
import { defineAsyncComponent } from 'vue'

export default {
  components: {
    AdminPage: defineAsyncComponent(() =>
      import('./components/AdminPageComponent.vue')
    )
  }
}
</script>

<template>
  <AdminPage />
</template>
```

</div>

<div class="composition-api">

Estes também podem ser definidos diretamente dentro do seu componente pai:

```vue
<script setup>
import { defineAsyncComponent } from 'vue'

const AdminPage = defineAsyncComponent(() =>
  import('./components/AdminPageComponent.vue')
)
</script>

<template>
  <AdminPage />
</template>
```

</div>

## Estados de Carregamento e Erro {#loading-and-error-states}

As operações assíncronas envolvem inevitavelmente os estados de carregamento e erro — a `defineAsyncComponent()` suporta a manipulação destes estados através das opções avançadas:

```js
const AsyncComp = defineAsyncComponent({
  // a função carregadora
  loader: () => import('./Foo.vue'),

  // Um componente a usar enquanto o
  // componente assíncrono carrega
  loadingComponent: LoadingComponent,
  // Espera antes de exibir o componente de
  // carregamento. Predefinido como: 200ms
  delay: 200,

  // Um componente a usar se o carregamento falhar
  errorComponent: ErrorComponent,
  // O componente de erro será exibido se uma pausa for
  // fornecida e excedida Predefinida como: Infinity
  timeout: 3000
})
```

Se um componente de carregamento for fornecido, este será exibido primeiro enquanto o componente interno estiver sendo carregado. Existe um atraso de 200ms predefinido antes do componente de carregamento ser mostrado — isto porque nas redes rápidas, um estado de carregamento instantâneo pode ser substituído muito rápido e acabar por parecer-se como uma tremulação.

Se um componente de erro for fornecido, este será exibido quando a promessa retornada pela função carregadora for rejeitada. Nós também podemos especificar uma pausa para mostrar o componente de erro quando a requisição estiver a demorar muito.

## Usar com Suspense {#using-with-suspense}

Os componentes assíncronos podem ser usados com o componente embutido `<Suspense>`. A interação entre os componentes `<Suspense>` e assíncronos é documentada no [capítulo dedicado ao `<Suspense>`](/guide/built-ins/suspense).

---

---
url: /guide/scaling-up/sfc.md
---
# Componentes de Ficheiro Único {#single-file-components}

## Introdução {#introduction}

O Componente de Ficheiro Único de Vue (mais conhecido como ficheiros `*.vue`, abreviado como **SFC** na sua sigla em Inglês) é um formato de ficheiro especial que permite-nos encapsular o modelo de marcação, a lógica, **e** a estilização dum componente de Vue num único ficheiro. Eis um componente de ficheiro único de exemplo:

<div class="options-api">

```vue
<script>
export default {
  data() {
    return {
      greeting: 'Hello World!'
    }
  }
}
</script>

<template>
  <p class="greeting">{{ greeting }}</p>
</template>

<style>
.greeting {
  color: red;
  font-weight: bold;
}
</style>
```

</div>

<div class="composition-api">

```vue
<script setup>
import { ref } from 'vue'
const greeting = ref('Hello World!')
</script>

<template>
  <p class="greeting">{{ greeting }}</p>
</template>

<style>
.greeting {
  color: red;
  font-weight: bold;
}
</style>
```

</div>

Conforme podemos ver, o Componente de Ficheiro Único da Vue é uma extensão natural do trio clássico HTML, CSS e JavaScript. Os blocos `<template>`, `<script>`, e `<style>` encapsulam e colocam a visão, a lógica e a estilização dum componente no mesmo ficheiro. A sintaxe completa é definida na [Especificação da Sintaxe do Componente de Ficheiro Único](/api/sfc-spec).

## Por que Componente de Ficheiro Único? {#why-sfc}

Enquanto os Componentes de Ficheiro Único exigem uma etapa de construção, existem muitos benefícios em troca:

- Produzir componentes modularizados usando a sintaxe familiar de HTML, CSS e JavaScript
- [Colocação de interesses inerentemente associados](#what-about-separation-of-concerns)
- Modelos de marcação pré-compilados sem custo de compilação de execução
- [CSS isolado ao Componente](/api/sfc-css-features)
- [Sintaxe mais ergonómica quando trabalhamos com a API de Composição](/api/sfc-script-setup)
- Mais otimizações de compilação analisando de várias maneiras o modelo de marcação e o programa
- [Suporte de Ambiente de Desenvolvimento Integrado](/guide/scaling-up/tooling#ide-support) com a conclusão automática e verificação de tipo para as expressões do modelo de marcação
- Suporte de Substituição de Módulo Instantânea (HMR, sigla em Inglês) fora da caixa

O Componente de Ficheiro Único é uma funcionalidade determinante da Vue como uma abstração, e é a abordagem recomendada para usar a Vue nos seguintes cenários:

- Aplicações de Página Única (SPA, sigla em Inglês)
- Geração de Aplicação Estática (SSG, sigla em Inglês)
- Qualquer frontend que não for banal onde uma etapa de construção pode ser justificada para melhor experiência de programação (DX, sigla em Inglês).

Com isto dito, nos apercebemos de que existem cenários onde os Componentes de Ficheiro Único podem ser como um excesso. É por isto que a Vue pode continuar a ser usada através da JavaScript simples sem uma etapa de construção. Se estivermos apenas procurando melhorar em grande parte o HTML estático com interações leves, também podemos verificar a [`petite-vue`](https://github.com/vuejs/petite-vue), um subconjunto de 6kb da Vue otimizada para aprimoramento progressivo.

## Como Este Funciona? {#how-it-works}

O Componente de Ficheiro Único da Vue é um formato de ficheiro específico para a abstração e deve ser pré-compilado pela [`@vue/compiler-sfc`](https://github.com/vuejs/core/tree/main/packages/compiler-sfc) para JavaScript e CSS padrão. Um Componente de Ficheiro Único compilado é um módulo (ECMAScript) de JavaScript padrão - o que significa que com a configuração de construção correta podemos importar um Componente de Ficheiro Único como um módulo:

```js
import MyComponent from './MyComponent.vue'

export default {
  components: {
    MyComponent
  }
}
```

Os marcadores `<style>` dentro dos Componentes de Ficheiro Único são normalmente injetados como marcadores de `<style>` nativos durante o desenvolvimento para suportar as atualizações instantâneas. Para produção estes podem ser extraídos e combinados num único ficheiro de CSS.

Nós podemos brincar com os Componentes de Ficheiro Único e explorar como estes são compilados na [Zona de Testes de Componente de Ficheiro Único da Vue](https://play.vuejs.org/).

Nos projetos de verdade, normalmente integramos o compilador de SFC com uma ferramenta de construção tal como [Vite](https://vitejs.dev/) ou [Vue CLI](http://cli.vuejs.org/) (que é baseada sobre [Webpack](https://webpack.js.org/)), e a Vue fornece ferramentas de estruturação de projetos oficiais para começares com os SFCs o mais rápido possível. Consulte mais detalhes na secção [Ferramental de SFC](/guide/scaling-up/tooling)

## E Quanto a Separação de Interesses? {#what-about-separation-of-concerns}

Os utilizadores que vêm dum contexto do desenvolvimento da Web tradicional podem ter a preocupação que os Componentes de Ficheiro Único estão misturando interesses diferentes no mesmo lugar - que HTML/CSS/JS eram suposto estarem separados!

Para responder esta questão, é importante para nós concordar que a **separação de interesses não é igual a separação de tipos de ficheiro**. O objetivo final dos princípios de engenharia é melhorar a manutenção das bases de código. A separação de interesses, quando aplicada dogmaticamente como separação de tipos de ficheiro, não nos ajuda a alcançar este objetivo no contexto das aplicações de frontend crescentemente complexas.

No desenvolvimento de interface de aplicação moderna, descobrimos que ao invés de dividir a base de código em três enorme camadas que entrelaçam-se umas às outras, faz muito mais sentido dividi-las em componentes associados livremente e compo-los. Dentro dum componente, o seu modelo de marcação, lógica, e estilos estão inerentemente associados, e colocá-los realmente torna o componente mais coeso e sustentável.

Nota que mesmo se não gostarmos da ideia dos Componentes de Ficheiro Único, ainda podemos influenciar as suas funcionalidade de recarregamento instantâneo e pré-compilação separando o nosso JavaScript, e CSS em ficheiros separados usando [Importações de Recursos](/api/sfc-spec#src-imports).

---

---
url: /api/built-in-components.md
---

# Componentes Embutidos {#built-in-components}

:::info Registo e Uso
Os componentes embutidos podem ser usados diretamente em modelos sem a necessidade de registo. Eles também são passíveis de ter a sua árvore agitada: são apenas incluídos na construção quando forem usados.

Quando os usarmos nas [funções de interpretação](/guide/extras/render-function), precisam ser importados explicitamente. Por exemplo:

```js
import { h, Transition } from 'vue'

h(Transition, {
  /* propriedades */
})
```

:::

## `<Transition>` {#transition}

Fornece efeitos de transição animados para um **único** elemento ou componente.

- **Propriedades**

  ```ts
  interface TransitionProps {
    /**
     * Usado para gerar automaticamente nomes de classes CSS de transição.
     * exemplo `name: 'fade'` expandirá automaticamente para `.fade-enter`,
     * `.fade-enter-active`, etc.
     */
    name?: string
    /**
     * Decide aplicar classes CSS de transição.
     * Padrão: true
     */
    css?: boolean
    /**
     * Especifica o tipo de eventos de transição à aguardar
     * para determinar a transição e o tempo.
     * O comportamento padrão é detetar automaticamente o tipo
     * que tiver a maior duração.
     */
    type?: 'transition' | 'animation'
    /**
     * Especifica durações explícitas para as transições.
     * O comportamento padrão é esperar pelo primeiro evento `transitionend`
     * ou `animationend` no elemento de transição raiz.
     */
    duration?: number | { enter: number; leave: number }
    /**
     * Controla a sequência de tempo das transições que entram ou saem.
     * O comportamento padrão é simultâneo.
     */
    mode?: 'in-out' | 'out-in' | 'default'
    /**
     * Define aplicar a transição na interpretação inicial.
     * Padrão: false
     */
    appear?: boolean

    /**
     * Propriedades para personalizar as classes de transição.
     * Use kebab-case nos modelos de marcação, exemplo enter-from-class="xxx"
     */
    enterFromClass?: string
    enterActiveClass?: string
    enterToClass?: string
    appearFromClass?: string
    appearActiveClass?: string
    appearToClass?: string
    leaveFromClass?: string
    leaveActiveClass?: string
    leaveToClass?: string
  }
  ```

- **Eventos**

  - `@before-enter`
  - `@before-leave`
  - `@enter`
  - `@leave`
  - `@appear`
  - `@after-enter`
  - `@after-leave`
  - `@after-appear`
  - `@enter-cancelled`
  - `@leave-cancelled` (apenas `v-show`)
  - `@appear-cancelled`

- **Exemplo**

  Elemento simples:

  ```vue-html
  <Transition>
    <div v-if="ok">conteúdo alternado</div>
  </Transition>
  ```

  Forçar uma transição mudando o atributo `key`:

  ```vue-html
  <Transition>
    <div :key="text">{{ text }}</div>
  </Transition>
  ```

  Componente dinâmico, com o modo de transição + animação ao aparecer:

  ```vue-html
  <Transition name="fade" mode="out-in" appear>
    <component :is="view"></component>
  </Transition>
  ```

  Ouvir eventos de transição:

  ```vue-html
  <Transition @after-enter="onTransitionComplete">
    <div v-show="ok">conteúdo ativado</div>
  </Transition>
  ```

- **Consultar também:** [Guia - Transição](/guide/built-ins/transition)

## `<TransitionGroup>` {#transitiongroup}

Fornece efeitos de transição para **múltiplos** elementos ou componentes numa lista.

- **Propriedades**

  `<TransitionGroup>` aceita as mesmas propriedades que o `<Transition>` exceto `mode`, e mais duas propriedades adicionais:

  ```ts
  interface TransitionGroupProps extends Omit<TransitionProps, 'mode'> {
    /**
     * Se não definido, desenha um fragmento.
     */
    tag?: string
    /**
     * Para personalizar as classes CSS aplicadas durante as transições de movimento.
     * Use kebab-case em modelos de marcação, exemplo move-class="xxx"
     */
    moveClass?: string
  }
  ```

- **Eventos**

  `<TransitionGroup>` emite os mesmos eventos que `<Transition>`.

- **Detalhes**

  Por padrão, `<TransitionGroup>` não desenha um elemento de DOM que envolve, mas pode ser definido através da propriedade `tag`.

  Note que todo filho num `<transition-group>` deve ser [**identificado unicamente**](/guide/essentials/list#maintaining-state-with-key) para que as animações funcionem apropriadamente.

  `<TransitionGroup>` suporta transições de movimento através de transformações de CSS. Quando a posição dum filho na tela é mudada após uma atualização, será aplicada uma classe de movimento CSS (gerada automaticamente pelo atributo `name` ou configurada pela propriedade `move-class`). Se a propriedade de CSS `transform` é passível de transição quando a classe de movimento é aplicada, o elemento será suavemente animado até o seu destino usando a [técnica FLIP](https://aerotwist.com/blog/flip-your-animations/).

- **Exemplo**

  ```vue-html
  <TransitionGroup tag="ul" name="slide">
    <li v-for="item in items" :key="item.id">
      {{ item.text }}
    </li>
  </TransitionGroup>
  ```

- **Consultar também:** [Guia - `TransitionGroup`](/guide/built-ins/transition-group)

## `<KeepAlive>` {#keepalive}

Armazena para consulta imediata os componentes alternados dinamicamente envolvidos dentro.

- **Propriedades**

  ```ts
  interface KeepAliveProps {
    /**
     * Se especificado, apenas componentes com nomes correspondidos
     * pelo `include` estarão na memória de consulta imediata.
     */
    include?: MatchPattern
    /**
     * Qualquer componente com um nome correspondidos pelo `exclude`
     * não estarão na memória de consulta imediata.
     */
    exclude?: MatchPattern
    /**
     * O número máximo de instâncias de componente à armazenar
     * na memória de consulta imediata.
     */
    max?: number | string
  }

  type MatchPattern = string | RegExp | (string | RegExp)[]
  ```

- **Detalhes**

  Quando envolvido em torno dum componente dinâmico, `<KeepAlive>` armazena para consulta imediata as instâncias de componente inativo sem destruí-las.

  Só pode existir uma instância de componente como filho direto de `<KeepAlive>` em qualquer momento.

  Quando um componente é alternado dentro de `<KeepAlive>`, seus gatilhos de ciclo de vida `activated` e `deactivated` são invocados de acordo, fornecendo uma alternativa ao `mounted` e `unmounted`, que não são chamados. Isto aplica-se ao filho direto de `<KeepAlive>` e também a todos os seus descendentes.

- **Exemplo**

  Uso básico:

  ```vue-html
  <KeepAlive>
    <component :is="view"></component>
  </KeepAlive>
  ```

  Quando usado com os ramos `v-if` / `v-else`, só deve existir um componente desenhado de cada vez:

  ```vue-html
  <KeepAlive>
    <comp-a v-if="a > 1"></comp-a>
    <comp-b v-else></comp-b>
  </KeepAlive>
  ```

  Usado em conjunto com `<Transition>`:

  ```vue-html
  <Transition>
    <KeepAlive>
      <component :is="view"></component>
    </KeepAlive>
  </Transition>
  ```

  Usando `include` / `exclude`:

  ```vue-html
  <!-- sequência de caracteres delimitada por vírgula -->
  <KeepAlive include="a,b">
    <component :is="view"></component>
  </KeepAlive>

  <!-- regex (use `v-bind`) -->
  <KeepAlive :include="/a|b/">
    <component :is="view"></component>
  </KeepAlive>

  <!-- vetor (use `v-bind`) -->
  <KeepAlive :include="['a', 'b']">
    <component :is="view"></component>
  </KeepAlive>
  ```

  Uso com `max`:

  ```vue-html
  <KeepAlive :max="10">
    <component :is="view"></component>
  </KeepAlive>
  ```

- **Consultar também:** [Guia - `KeepAlive`](/guide/built-ins/keep-alive)

## `<Teleport>` {#teleport}

Desenha o conteúdo da sua ranhura numa outra parte do DOM.

- **Propriedades**

  ```ts
  interface TeleportProps {
    /**
     * Obrigatório. Específica o contentor alvo.
     * Pode ser ou um seletor ou um elemento verdadeiro.
     */
    to: string | HTMLElement
    /**
     * Quando `true`, o conteúdo continuará na sua localização
     * original ao invés de ser movido para o contentor alvo.
     * Pode ser mudado dinamicamente.
     */
    disabled?: boolean
  }
  ```

- **Exemplo**

  Especificando o contentor alvo:

  ```vue-html
  <teleport to="#some-id" />
  <teleport to=".some-class" />
  <teleport to="[data-teleport]" />
  ```

  Desativar condicionalmente:

  ```vue-html
  <teleport to="#popup" :disabled="displayVideoInline">
    <video src="./my-movie.mp4">
  </teleport>
  ```

- **Consultar também:** [Guia - `Teleport`](/guide/built-ins/teleport.html)

## `<Suspense>` <sup class="vt-badge experimental" /> {#suspense}

Usado para orquestrar dependências assíncronas encaixadas numa árvore de componente.

- **Propriedades**

  ```ts
  interface SuspenseProps {
    timeout?: string | number
  }
  ```

- **Eventos**

  - `@resolve`
  - `@pending`
  - `@fallback`

- **Detalhes**

  `<Suspense>` aceita duas ranhuras: a ranhura `#default` e a ranhura `#fallback`. Ele exibirá o conteúdo da ranhura de retorno (`#fallback`) enquanto desenha a ranhura padrão (`#default`) na memória.

  Se encontrar dependências assíncronas ([Componentes Assíncronos](/guide/components/async) e componentes com [`async setup()`](/guide/built-ins/suspense#async-setup)) enquanto desenha a ranhura padrão, aguardará até todos serem resolvidos antes de exibir a ranhura padrão.

- **Consultar também:** [Guia - `Suspense`](/guide/built-ins/suspense)

---

---
url: /guide/essentials/application.md
---
# Criando uma Aplicação de Vue {#creating-a-vue-application}

## A Instância da Aplicação {#the-application-instance}

Todas as aplicações de Vue começam com a criação duma nova **instância de aplicação** com a função [`createApp`](/api/application#createapp):

```js
import { createApp } from 'vue'

const app = createApp({
  /* opções do componente de raiz */
})
```

## O Componente de Raiz {#the-root-component}

O objeto que passamos à `createApp` é na realidade um componente. Todas as aplicações exigem um "componente de raiz" que pode conter outros componentes como seus filhos.

Se estivermos a usar os componentes de ficheiro único, normalmente importamos o componente de raiz a partir dum outro ficheiro:

```js
import { createApp } from 'vue'
// importar o componente de raiz `App`
// a partir dum componente de ficheiro único.
import App from './App.vue'

const app = createApp(App)
```

Embora muitos dos exemplos neste guia apenas precisam dum único componente, a maioria das aplicações reias são organizadas numa árvore de componentes reutilizáveis e encaixados. Por exemplo, a árvore de componente duma aplicação de afazeres pode parecer-se com isto:

```
App (componente de raiz)
├─ TodoList
│  └─ TodoItem
│     ├─ TodoDeleteButton
│     └─ TodoEditButton
└─ TodoFooter
   ├─ TodoClearButton
   └─ TodoStatistics
```

Nas seções posteriores do guia, discutiremos como definir e compor vários componentes. Antes disto, nos concentraremos no que acontece dentro dum único componente.

## Montando a Aplicação {#mounting-the-app}

Uma instância de aplicação não interpretará nada até o seu método `mount()` ser chamado. Esta espera um argumento "contentor", que pode ser ou elemento do DOM verdadeiro ou uma sequência de caracteres de seletor:

```html
<div id="app"></div>
```

```js
app.mount('#app')
```

O conteúdo do componente de raiz da aplicação será desenhado dentro do elemento contentor. O elemento contentor por si só não é considerado parte da aplicação.

O método `.mount()` sempre deve ser chamado depois de todas as configurações e registos de recurso da aplicação serem feitas. Também nota que o seu valor de retorno, ao contrário dos métodos de registo de recurso, é a instância do componente de raiz ao invés da instância da aplicação.

### Modelo de Marcação do Componente de Raiz no DOM {#in-dom-root-component-template}

O modelo de marcação para o componente de raiz é normalmente parte do próprio componente, mas também é possível fornecer o modelo de marcação separadamente escrevendo-o diretamente dentro do contentor de montagem:

```html
<div id="app">
  <button @click="count++">{{ count }}</button>
</div>
```

```js
import { createApp } from 'vue'

const app = createApp({
  data() {
    return {
      count: 0
    }
  }
})

app.mount('#app')
```

A Vue usará automaticamente a `innerHTML` do contentor como modelo de marcação se o componente de raiz já não tiver uma opção `template`.

Os modelos de marcação no DOM são frequentemente usados nas aplicações que [usam a Vue sem uma etapa de construção](/guide/quick-start#using-vue-from-cdn). Eles também podem ser usados em conjunto com abstrações do lado do servidor, onde a modelo de marcação de raiz pode ser gerado dinamicamente pelo servidor.

## Configurações da Aplicação {#app-configurations}

A instância da aplicação expõe um objeto `.config` que permite-nos configurar algumas opções de nível de aplicação, por exemplo, definindo um manipulador de erro de nível de aplicação que captura os erros a partir de todos componentes descendentes:

```js
app.config.errorHandler = (err) => {
  /* manipular o erro */
}
```

A instância da aplicação também fornece alguns métodos para o registo de recursos isolados em âmbitos da aplicação. Por exemplo, registando um componente:

```js
app.component('TodoDeleteButton', TodoDeleteButton)
```

Isto torna o `TodoDeleteButton` disponível para uso em qualquer parte da nossa aplicação. Nós discutiremos o registo de componentes e outros tipos de recursos sem seções posteriores do guia. Nós também podemos pesquisar a lista completa das APIs da instância da aplicação na sua [referência de API](/api/application).

Certifica-te de aplicar todas as configurações da aplicação antes da montagem da aplicação!

## Várias Instâncias de Aplicação {#multiple-application-instances}

Nós não estamos restritos à uma única instância de aplicação na mesma página. A API da `createApp` permite que várias aplicações de Vue coexistam na mesma página, cada uma com o seu próprio âmbito de aplicação para configuração e recursos globais:

```js
const app1 = createApp({
  /* ... */
})
app1.mount('#container-1')

const app2 = createApp({
  /* ... */
})
app2.mount('#container-2')
```

Se estivermos a usar a Vue para melhorar o HTML gerado pelo servidor e apenas precisamos da Vue para controlar partes específicas duma página grande, devemos evitar montar uma única instância de aplicação de Vue sobre a página inteira. No lugar disto, devemos criar várias instâncias de aplicação pequenas e montá-las sobre os elementos de que são responsáveis.

---

---
url: /guide/best-practices/performance.md
---

# Desempenho {#performance}

## Visão Geral {#overview}

A Vue é desenhada para ser otimizada para a maior parte dos casos de uso comuns sem muita necessidade de otimizações manuais. No entanto, existe sempre cenários desafiadores onde afinamento adicional é necessário. Nesta seção, discutiremos o que deverias prestar atenção quando toca o desempenho em uma aplicação de Vue.

Primeiro, vamos discutir dois aspetos principais de desempenho da web:

- **Desempenho do Carregamento da Página**: quão rápido a aplicação mostra o conteúdo e torna-se interativa na visita inicial. Isto é usualmente medido usando métricas vitais da web como [Pintura Alargada do Conteúdo (LCP)](https://web.dev/lcp/) e [Primeiro Atraso da Entrada (FID)](https://web.dev/fid/).

- **Desempenho da Atualização**: quão rápido a aplicação atualiza-se em resposta a entrada do utilizador. Por exemplo, quão rápido uma lista atualiza quando o utilizador digita em uma caixa de pesquisa, ou quão rápido a página alterna quando o utilizador clica em uma ligação de navegação em uma Aplicação de Página Única (SPA).

Enquanto seria ideal maximizar ambos, diferentes arquiteturas de frontend tendem a afetar o quão fácil é alcançar o desempenho desejado nestes aspetos. Além disto, o tipo de aplicação que estás a construir influencia grandemente no que deves priorizar em termos de desempenho. Portanto, o primeiro passo de garantir o desempenho ideal está em escolher a arquitetura correta para o tipo de aplicação que estás a construir:

- Consulte a [Maneiras de Usar a Vue](/guide/extras/ways-of-using-vue) para veres como podes influenciar a Vue de maneiras diferentes.

- O programador Jason Miller discute os tipos de aplicações de web e suas respetivas implementações ou entregas ideais nos [Holótipos de Aplicação](https://jasonformat.com/application-holotypes/).

## Opções de Perfilamento {#profiling-options}

Para melhorar o desempenho, precisamos de primeiro saber como medi-lo. Existem um número de excelentes ferramentas que podem ajudar neste aspeto:

Para o perfilamento do desempenho do carregamento das implementações de produção:

- [Entendimentos da PageSpeed](https://pagespeed.web.dev/)
- [WebPageTest](https://www.webpagetest.org/)

Para perfilamento do desempenho durante o desenvolvimento local:

- [Painel de Desempenho das Ferramentas de Programação do Chrome](https://developer.chrome.com/docs/devtools/evaluate-performance/)
  - [`app.config.performance`](/api/application.html#app-config-performance) ativa marcadores de desempenho específicas da Vue na linha do tempo do desempenho das Ferramentas de Programação do Chrome.
- [Extensão de Ferramentas de Programação de Vue](/guide/scaling-up/tooling#browser-devtools) também fornece uma funcionalidade de perfilamento do desempenho.

## Otimizações do Carregamento da Página {#page-load-optimizations}

Existem muitas aspetos agnósticos de abstração para otimização do desempenho do carregamento da página - consulte [este guia da web.dev](https://web.dev/fast/) para um arredondamento para cima compreensivo. Nesta seção, iremos primeiramente concentrar-nos nas técnicas que são específicas para Vue.

### Escolhendo a Arquitetura Correta {#choosing-the-right-architecture}

Se o teu caso de uso for sensível ao desempenho do carregamento da página, evite entregá-lo como uma Aplicação de Página Única (SPA) pura no lado do cliente. Tu queres que o teu servidor esteja enviando diretamente o HTML contendo o conteúdo que os utilizadores querem ver. A apresentação pura do lado do cliente sofre de lentidão de tempo para o conteúdo. Isto pode ser mitigado com a [Interpretação no Lado do Servidor (SSR, sigle em Inglês)](/guide/extras/ways-of-using-vue#fullstack-ssr) ou [Geração de Página Estática](/guide/extras/ways-of-using-vue#jamstack-ssg). Consulte o [Guia de SSR](/guide/scaling-up/ssr) para aprender a respeito de como realizar a Interpretação no Lado do Servidor com a Vue. Se a tua aplicação não tiver requisitos ricos de interatividade, também podes usar um servidor de backend tradicional para produzir o HTML e melhorá-lo com a Vue no cliente.

Se a tua aplicação principal tiver que ser uma Aplicação de Página Única, mas tem páginas de publicidade (chegada (landing, em Inglês), sobre, blogue), entregue-as separadamente! A tuas páginas de publicidade devem idealmente ser implementadas em produção como HTML estático com o mínimo de JavaScript, usando Geração de Página Estática (SSG).

### Tamanho do Pacote e Sacudidura de Árvore {#bundle-size-and-tree-shaking}

Uma das maneiras mais efetivas de melhorar o desempenho do carregamento da página é entregando pacotes de JavaScript mais pequenos. Listamos abaixo algumas maneiras de reduzir o tamanho do pacote quando estiveres a usar a Vue:

- Utilize uma etapa de construção se possível

  - Muitas das APIs da Vue são ["passíveis de sacudidura"](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) se empacotadas através de uma ferramenta de construção moderna. Por exemplo, se não usas o componente embutido `<Transition>`, não será incluído no pacote de produção final. A sacudidura de árvore também pode remover outros módulos que não são usados no teu código-fonte.

  - Quando estiveres a usar uma etapa de construção, os modelos de marcação são pré-compilados assim não precisamos de entregar o compilador da Vue para o navegador. Isto economiza **14kb** de JavaScript gzipado minificado e evita o custo de compilação de tempo de execução.

- Seja prudente quanto o tamanho quando estiveres introduzindo novas dependências! Em aplicações do mundo real, os pacotes inchados são mais frequentemente um resultado da introdução de dependências pesadas sem aperceber-se dele:

  - Se estiveres a usar uma etapa de construção, prefira dependências que oferecem formatos de módulos de ECMAScript e são amigáveis a sacudidura de árvore. Por exemplo, prefira `lodash-es` acima do `lodash`.

  - Consulte o tamanho de uma dependência e avaliar se a funcionalidade que fornece é digna. Nota se a dependência é amigável a sacudidura de árvore, o aumento do tamanho real dependerá das APIs que realmente estiveres a importar a partir dela. Ferramentas como [bundlejs.com](https://bundlejs.com/) podem ser usadas para verificações rápidas, mas medir com a tua configuração de construção real sempre será o mais preciso.

- Se estiveres a usar a Vue primariamente para otimização progressiva e preferes evitar uma etapa de construção, considere então usar a [petite-vue](https://github.com/vuejs/petite-vue) (apenas **6kb**).

### Separação de Código {#code-splitting}

A separação de código é onde uma ferramenta de construção separa o pacote da aplicação em vários pedaços mais pequenos, os quais podem então ser carregados sobre demanda ou em simultâneo. Com a separação de código apropriada, as funcionalidades exigidas no carregamento da página podem ser descarregados imediatamente, com pedaços adicionais sendo carregados preguiçosamente apenas quando necessário, assim melhorando o desempenho.

Os empacotadores como o Rollup (que é sobre o qual a Vite é baseada) ou Webpack podem criar automaticamente pedaços separados detetando a sintaxe de importação dinâmica de Módulo de ECMAScript:

```js
// lazy.js e suas dependências serão separadas em um pedaço separado
// e apenas carregadas quando `loadLazy()` for chamada.
function loadLazy() {
  return import('./lazy.js')
}
```

O carregamento preguiçoso é melhor usado em funcionalidades que não são imediatamente necessárias depois do carregamento da página. Em aplicações de Vue, isto pode ser usado em conjunto com a funcionalidade de [Componente Assíncrono](/guide/components/async) da Vue para criar pedaços separados para as árvores de componente:

```js
import { defineAsyncComponent } from 'vue'

// um pedaço separado é criado para `Foo.vue` e suas dependências.
// ele é apenas buscado sobre demanda quando o componente assíncrono for
// apresentado na página.
const Foo = defineAsyncComponent(() => import('./Foo.vue'))
```

Para as aplicações usando a Vue Router, é fortemente recomendado usar o carregamento preguiçoso para os componentes da rota. A Vue Router tem suporte explícito para o carregamento preguiçoso, separado a partir de `defineAsyncComponent`. Consulte [Rotas de Carregamento Preguiçoso](https://router.vuejs.org/guide/advanced/lazy-loading) para mais detalhes.

## Atualizar Otimizações {#update-optimizations}

### Estabilidade de Propriedades {#props-stability}

Na Vue, um componente filho apenas atualiza quando pelo menos uma de suas propriedades recebidas tenha mudado. Considere o seguinte exemplo:

```vue-html
<ListItem
  v-for="item in list"
  :id="item.id"
  :active-id="activeId" />
```

Dentro do componente `<ListItem>`, ele usa as suas propriedades`id` e `activeId` para determinar se ele é o item ativo atualmente. Embora isto funciona, o problema é que sempre que `activeId` mudar, **cada** `<ListItem>` na lista tem que atualizar!

Idealmente, apenas os itens cujos estados ativos mudados devem atualizar. Nós podemos alcançar isto movendo o cálculo de estado ativo para o pai, e fazer o `<ListItem>` aceitar diretamente uma propriedade `active`:

```vue-html
<ListItem
  v-for="item in list"
  :id="item.id"
  :active="item.id === activeId" />
```

Agora, para a maior parte dos componentes a propriedade `active` continuarão a mesma quando `activeId` mudar, assim eles já não precisam de atualizar. No geral, a ideia é manter as propriedades passadas para os componentes filhos o mais estável possível.

### `v-once` {#v-once}

`v-once` é uma diretiva embutida que pode ser usada para apresentar o conteúdo que depende de dados em tempo de execução mas nunca precisa de atualizar. A sub-árvore inteira sobre a qual é usado será ignorada para atualizações futuras. Consulte a [referência da sua API](/api/built-in-directives#v-once) para mais detalhes.

### `v-memo` {#v-memo}

`v-memo` é uma diretiva embutida que pode ser usada para ignorar condicionalmente a atualização de sub-árvores grandes ou listas de `v-for`. Consulte a [referência da sua API](/api/built-in-directives#v-memo) para mais detalhes.

### Estabilidade Computada <sup class="vt-badge" data-text="3.4+" /> {#computed-stability}

Começando na 3.4, uma propriedade computada apenas acionará os efeitos quando seu valor computado tiver mudado a partir do valor anterior. Por exemplo, a seguinte `isEven` computada apenas aciona os efeitos se o valor retornado tiver mudado de `true` ao `false`, ou vice-versa:

```js
const count = ref(0)
const isEven = computed(() => count.value % 2 === 0)

watchEffect(() => console.log(isEven.value)) // true

// não acionará novos registos porque
// o valor computado continua `true`
count.value = 2
count.value = 4
```

Isto reduz acionamentos de efeito desnecessários, mas infelizmente não funciona se o computado cria um novo objeto sobre cada cálculo:

```js
const computedObj = computed(() => {
  return {
    isEven: count.value % 2 === 0
  }
})
```

Uma vez que um novo objeto é criado toda vez, o novo valor é sempre tecnicamente diferente do valor antigo. Mesmo se a propriedade `isEven` permanecer a mesma, a Vue não será capaz de saber a menos que esta realize uma comparação profunda do valor antigo e do novo valor. Tal comparação poderia ser dispendiosa e provavelmente inútil.

Ao invés disto, podemos otimizar isto comparando manualmente o novo valor com o valor antigo, e condicionalmente retornar o valor antigo se sabermos que nada mudou:

```js
const computedObj = computed((oldValue) => {
  const newValue = {
    isEven: count.value % 2 === 0
  }
  if (oldValue && oldValue.isEven === newValue.isEven) {
    return oldValue
  }
  return newValue
})
```

[Exemplo da Zona de Testes](https://play.vuejs.org/#eNqVVMtu2zAQ/JUFgSZK4UpuczMkow/40AJ9IC3aQ9mDIlG2EokUyKVt1PC/d0lKtoEminMQQC1nZ4c7S+7Yu66L11awGUtNoesOwQi03ZzLuu2URtiBFtUECtV2FkU5gU2OxWpRVaJA2EOlVQuXxHDJJZeFkgYJayVC5hKj6dUxLnzSjZXmV40rZfFrh3Vb/82xVrLH//5DCQNNKPkweNiNVFP+zBsrIJvDjksgGrRahjVAbRZrIWdBVLz2yBfwBrIsg6mD7LncPyryfIVnywupUmz68HOEEqqCI+XFBQzrOKR79MDdx66GCn1jhpQDZx8f0oZ+nBgdRVcH/aMuBt1xZ80qGvGvh/X6nlXwnGpPl6qsLLxTtitzFFTNl0oSN/79AKOCHHQuS5pw4XorbXsr9ImHZN7nHFdx1SilI78MeOJ7Ca+nbvgd+GgomQOv6CNjSQqXaRJuHd03+kHRdg3JoT+A3a7XsfcmpbcWkQS/LZq6uM84C8o5m4fFuOg0CemeOXXX2w2E6ylsgj2gTgeYio/f1l5UEqj+Z3yC7lGuNDlpApswNNTrql7Gd0ZJeqW8TZw5t+tGaMdDXnA2G4acs7xp1OaTj6G2YjLEi5Uo7h+I35mti3H2TQsj9Jp6etjDXC8Fhu3F9y9iS+vDZqtK2xB6ZPNGGNVYpzHA3ltZkuwTnFf70b+1tVz+MIstCmmGQzmh/p56PGf00H4YOfpR7nV8PTxubP8P2GAP9Q==)

Nota que sempre devemos realizar a computação completa antes de comparar e retornar o valor antigo, para que as mesmas dependências possam ser colecionadas sobre toda execução.

## Otimizações Gerais {#general-optimizations}

> As seguintes dicas afetam tanto carregamento da página e a desempenho da atualização.

### Virtualizar Listas Grandes {#virtualize-large-lists}

Um dos problemas de desempenho mais comuns em todas aplicações de frontend é apresentação de listas grandes. Não importa o quão otimizada uma abstração seja, apresentar uma lista com milhares de itens **será** lento por causa do número enorme de nós do DOM que o navegador precisa manipular.

No entanto, não temos de necessariamente apresentar todos estes nós adiantado. Na maioria dos casos, o tamanho da tela do utilizador pode apresentar apenas um subconjunto pequeno da nossa lista grande. Nós podes melhorar grandemente o desempenho com a **virtualização da lista**, a técnica de apenas apresentar os itens que estão atualmente em ou próximos à janela de exibição em uma lista grande.

Implementar a virtualização de lista não é fácil, felizmente existem bibliotecas da comunidade existentes que podes usar diretamente:

- [vue-virtual-scroller](https://github.com/Akryum/vue-virtual-scroller)
- [vue-virtual-scroll-grid](https://github.com/rocwang/vue-virtual-scroll-grid)
- [vueuc/VVirtualList](https://github.com/07akioni/vueuc)

### Reduzir as Despesas Gerais de Reatividade para as Grandes Estruturas Imutáveis {#reduce-reactivity-overhead-for-large-immutable-structures}

O sistema de reatividade da Vue é profundo por padrão. Enquanto isto torna a gestão de estado intuitiva, cria um certo nível de despesas gerais quando o tamanho dos dados é grande, porque cada acesso de propriedade aciona armadilhas de delegação que realizam o rastreamento de dependência. Isto normalmente torna-se evidente quando lidamos com grandes arranjos de objetos profundamente encaixados, onde uma única apresentação precisa acessar mais de 100.000 propriedades, assim ele deve apenas afetar casos de uso muito específicos.

A Vue fornece uma escotilha de saída para abandonar a reatividade profunda usando a [`shallowRef()`](/api/reactivity-advanced#shallowref) e a [`shallowReactive()`](/api/reactivity-advanced#shallowreactive). As APIs Superficiais (Shallow, em Inglês) criam o estado que é reativo apenas no nível da raiz, e expõem todos os objetos encaixados intocados. Isto mantém o acesso de propriedade encaixada rápido, com o compromisso sendo que agora devemos tratar todos os objetos encaixados como imutáveis, e as atualizações apenas podem ser acionadas substituindo o estado de raiz:

```js
const shallowArray = shallowRef([
  /* lista grande de objetos profundos */
])

// isto não acionará atualizações...
shallowArray.value.push(newObject)
// isto faz:
shallowArray.value = [...shallowArray.value, newObject]

// isto não acionará atualizações...
shallowArray.value[0].foo = 1
// isto faz:
shallowArray.value = [
  {
    ...shallowArray.value[0],
    foo: 1
  },
  ...shallowArray.value.slice(1)
]
```

### Evitar Abstrações Desnecessárias de Componente {#avoid-unnecessary-component-abstractions}

Algumas vezes podemos criar [componentes sem apresentação](/guide/components/slots#renderless-components) ou componentes de ordem superior (por exemplo, componentes que apresentam outros componentes com propriedades adicionais) para melhor abstração ou organização do código. Embora não haja nada de errado com isto, lembra-te de que as instâncias de componente são mais dispendiosas do que nós simples do DOM, e criar muitos deles por causa de padrões de abstração incorrerá em custos de desempenho.

Nota que reduzir apenas algumas instâncias não terá efeito evidente, então não te preocupes se o componente for apresentado apenas algumas vezes na aplicação. O melhor cenário para considerar esta otimização é novamente listas grandes. Suponha uma lista de 100 itens onde cada componente de item contém muitos componentes filhos. Remover uma abstração desnecessária de componente aqui poderia resultar em uma redução de centenas de instâncias de componente.

---

---
url: /api/built-in-directives.md
---
# Diretivas Embutidas {#built-in-directives}

## `v-text` {#v-text}

Atualiza o conteúdo de texto do elemento.

- **Espera:** `string`

- **Detalhes**

  `v-text` funciona definindo a propriedade [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) do elemento, sobrescreverá qualquer conteúdo existente dentro do elemento. Se precisarmos de atualizar a parte da `textContent`, devemos usar as [interpolações de bigodes](/guide/essentials/template-syntax#text-interpolation).

- **Exemplo**

  ```vue-html
  <span v-text="msg"></span>
  <!-- é o mesmo que -->
  <span>{{msg}}</span>
  ```

- **Consultar também** [Sintaxe do Modelo de Marcação - Interpolação de Texto](/guide/essentials/template-syntax#text-interpolation)

## `v-html` {#v-html}

Atualiza a [`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) do elemento.

- **Espera:** `string`

- **Detalhes:**

  Os conteúdos da `v-html` são inseridos como HTML simples - a sintaxe de modelo de marcação da Vue não será processada. Se estivermos a tentar compor modelos de marcação usando  `v-html`, vamos tentar repensar a solução usando componentes.

  :::warning NOTA DE SEGURANÇA
  Interpretar dinamicamente HTML arbitrário na nossa aplicação pode ser muito perigoso porque pode facilmente conduzir a [ataques de XSS](https://en.wikipedia.org/wiki/Cross-site_scripting). Só deveríamos usar `v-html` sobre conteúdo confiável e **nunca** sobre conteúdo fornecido pelo utilizador.
  :::

  Nos [Componentes de Ficheiro Único](/guide/scaling-up/sfc), os estilos `scoped` não serão aplicados ao conteúdo dentro de `v-html`, porque este HTML não é processado pelo compilador de modelos de marcação da Vue. Se quisermos mirar o conteúdo de `v-html` com CSS isolada, podemos usar os [módulos de CSS](./sfc-css-features#css-modules) ou elemento `<style>` adicional e global com uma estratégia de isolamento manual, como a BEM.

- **Exemplo**

  ```vue-html
  <div v-html="html"></div>
  ```

- **Consultar também** [Sintaxe do Modelo de Marcação - HTML Puro](/guide/essentials/template-syntax#raw-html)

## `v-show` {#v-show}

Alterna a visibilidade do elemento baseado na veracidade do valor da expressão.

- **Espera:** `any`

- **Detalhes**

  `v-show` funciona definindo a propriedade de CSS `display` através de estilos em linha, e tentará respeitar o valor inicial da `display` quando o elemento estiver visível. Também aciona transições quando sua condição muda.

- **Consultar também** [Interpretação Condicional - `v-show`](/guide/essentials/conditional#v-show)

## `v-if` {#v-if}

Interpreta condicionalmente um elemento ou um fragmento de modelo de marcação baseado na veracidade do valor da expressão.

- **Espera:** `any`

- **Detalhes**

  Quando um elemento de `v-if` é alternado, o elemento e suas diretivas ou componentes contidos são destruídos e construídos novamente. Se a condição inicial for falsa, então o conteúdo interno não será interpretado de todo.

  Pode ser usada no `<template>` para denotar um bloco condicional contendo apenas texto ou vários elementos.

  Esta diretiva aciona transições quando sua condição muda.

  Quando usada em conjunto, a `v-if` tem uma prioridade superior à `v-for`. Não recomendados usar estas duas diretivas ao mesmo tempo sobre um elemento — consulte o [guia de interpretação de lista](/guide/essentials/list#v-for-with-v-if) por mais detalhes.

- **Consultar também** [Interpretação Condicional - `v-if`](/guide/essentials/conditional#v-if)

## `v-else` {#v-else}

Denota um "bloco `else`" para a `v-if` ou para uma cadeia `v-if` / `v-else-if`.

- **Não espera expressões**

- **Detalhes**

  - Restrição: o anterior elemento irmão deve ter a `v-if` ou `v-else-if`.

  - Pode ser usada no `<template>` para denotar um bloco condicional contendo apenas texto ou vários elementos.

- **Exemplo**

  ```vue-html
  <div v-if="Math.random() > 0.5">
    Now you see me
  </div>
  <div v-else>
    Now you don't
  </div>
  ```

- **Consultar também** [Interpretação Condicional - `v-else`](/guide/essentials/conditional#v-else)

## `v-else-if` {#v-else-if}

Denota o "bloco `else if`" para a `v-if`. Pode ser encadeada.

- **Espera:** `any`

- **Detalhes**

  - Restrição: o anterior elemento irmão deve ter a `v-if` ou `v-else-if`.

  - Pode ser usada no `<template>` para denotar um bloco condicional contendo apenas texto ou vários elementos.

- **Exemplo**

  ```vue-html
  <div v-if="type === 'A'">
    A
  </div>
  <div v-else-if="type === 'B'">
    B
  </div>
  <div v-else-if="type === 'C'">
    C
  </div>
  <div v-else>
    Not A/B/C
  </div>
  ```

- **Consultar também** [Interpretação Condicional - `v-else-if`](/guide/essentials/conditional#v-else-if)

## `v-for` {#v-for}

Interpreta o elemento ou bloco de modelo de marcação várias vezes baseada na fonte dos dados.

- **Espera:** `Array | Object | number | string | Iterable`

- **Detalhes**

  O valor da diretiva deve usar a sintaxe especial `alias in expression` para fornecer um pseudónimo para o elemento atual a ser iterado:

  ```vue-html
  <div v-for="item in items">
    {{ item.text }}
  </div>
  ```

  Alternativamente, também podemos especificar um pseudónimo para o índice (ou a chave se usada sobre um objeto):

  ```vue-html
  <div v-for="(item, index) in items"></div>
  <div v-for="(value, key) in object"></div>
  <div v-for="(value, name, index) in object"></div>
  ```

  O comportamento padrão da `v-for` tentará remendar os elementos no lugar sem movê-los. Para forçar a reordenação de elementos, devemos fornecer uma sugestão de ordenação com o atributo especial `key`:

  ```vue-html
  <div v-for="item in items" :key="item.id">
    {{ item.text }}
  </div>
  ```

  `v-for` também pode trabalhar com valores que implementam o [Protocolo Iterável](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol), incluindo os `Map` e `Set` nativos.

- **Consultar também**
  - [Interpretação de Lista](/guide/essentials/list)

## `v-on` {#v-on}

Anexa um ouvinte de evento ao elemento.

- **Atalho:** `@`

- **Espera:** `Function | Inline Statement | Object (sem argumento)`

- **Argumento:** `event` (opcional se estivermos usando a sintaxe de Objeto)

- **Modificadores**

  - `.stop` - chama `event.stopPropagation()`.
  - `.prevent` - chama `event.preventDefault()`.
  - `.capture` - adiciona ouvinte de evento no modo de captura.
  - `.self` - apenas aciona o manipulador se o evento fosse despachado a partir deste elemento.
  - `.{keyAlias}` - apenas aciona o manipulador sobre certas teclas.
  - `.once` - aciona o manipulador no máximo uma vez.
  - `.left` - apenas aciona o manipulador para os eventos de rato do botão esquerdo.
  - `.right` - apenas aciona o manipulador para os eventos de rato do botão direito.
  - `.middle` - apenas aciona o manipulador para os eventos de rato do botão do meio.
  - `.passive` - anexa um evento de DOM com `{ passive: true }`.

- **Detalhes**

  O tipo de evento é denotado pelo argumento. A expressão pode ser um nome de método, uma declaração em linha, ou omitida se existirem modificadores presentes.

  Quando usada num elemento normal, apenas ouve os [**eventos de DOM nativos**](https://developer.mozilla.org/en-US/docs/Web/Events). Quando usada num componente de elemento personalizado, ouve os **eventos personalizados** emitidos sobre este componente filho.

  Quando ouvimos os eventos de DOM nativos, o método recebe o evento nativo como único argumento. Se usarmos a declaração em linha, a declaração tem acesso à propriedade `$event` especial: `v-on:click="handle('ok', $event)"`.

  `v-on` também suporta vínculo a um objeto de pares de evento / ouvinte sem um argumento. Nota que quando usamos a sintaxe de objeto, esta não suporta quaisquer modificadores.

- **Exemplo**

  ```vue-html
  <!-- manipulador de método -->
  <button v-on:click="doThis"></button>

  <!-- evento dinâmico -->
  <button v-on:[event]="doThis"></button>

  <!-- declaração em linha -->
  <button v-on:click="doThat('hello', $event)"></button>

  <!-- atalho -->
  <button @click="doThis"></button>

  <!-- atalho de evento dinâmico -->
  <button @[event]="doThis"></button>

  <!-- parar propagação -->
  <button @click.stop="doThis"></button>

  <!-- impedir o padrão -->
  <button @click.prevent="doThis"></button>

  <!-- impedir o padrão sem expressão -->
  <form @submit.prevent></form>

  <!-- encadear modificadores -->
  <button @click.stop.prevent="doThis"></button>

  <!-- modificador de tecla usando pseudónimo de tecla -->
  <input @keyup.enter="onEnter" />

  <!-- o evento de clique será acionado no máximo uma vez -->
  <button v-on:click.once="doThis"></button>

  <!-- sintaxe de objeto -->
  <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>
  ```

  Ouvindo eventos personalizados dum componente filho (o manipulador é chamado quando "my-event" é emitido sobre o filho):

  ```vue-html
  <MyComponent @my-event="handleThis" />

  <!-- declaração em linha -->
  <MyComponent @my-event="handleThis(123, $event)" />
  ```

- **Consultar também**
  - [Manipulação de Eventos](/guide/essentials/event-handling)
  - [Componentes - Eventos Personalizados](/guide/essentials/component-basics#listening-to-events)

## `v-bind` {#v-bind}

Vincula dinamicamente um ou mais atributos, ou uma propriedade de componente à uma expressão.

- **Atalho:**
  - `:` ou `.` (quando usamos o modificador `.prop`)
  - Omitir o valor (quando o atributo e o valor vinculado tiverem o mesmo nome) <sup class="vt-badge">3.4+</sup>

- **Espera:** `any (com argumento) | Object (sem argumento)`

- **Argumento:** `attrOrProp (opcional)`

- **Modificadores**

  - `.camel` - transforma o nome de atributo em caixa espetada em caixa de camelo.
  - `.prop` - força um vínculo a ser definido como uma propriedade do DOM. <sup class="vt-badge">3.2+</sup>
  - `.attr` - força um vínculo a ser definido como um atributo de DOM. <sup class="vt-badge">3.2+</sup>

- **Uso**

  Quando usada para vincular o atributo `class` ou `style`, `v-bind` suporta tipos de valores adicionar como Vetor ou Objeto. Consulte a seção do guia ligado abaixo por mais detalhes.

  Quando definimos um vínculo num elemento, a Vue por padrão verifica se o elemento tem a chave definida como uma propriedade usando uma verificação do operador `in`. Se a propriedade for definida, a Vue definirá o valor como uma propriedade de DOM ao invés dum atributo. Isto deve funciona na maioria dos casos, mas podemos sobrepor este comportamento ao usar explicitamente os modificadores `.prop` ou `.attr`. Isto é algumas vezes necessário, especialmente quando [trabalhamos com elementos personalizados](/guide/extras/web-components#passing-dom-properties).

  Quando usada para vínculos de propriedade de componente, a propriedade deve ser declarada apropriadamente no componente filho.

  Quando usada sem um argumento, pode ser usada para vincular um objeto contendo pares de nome-valor de atributo.

- **Exemplo**

  ```vue-html
  <!-- vincular um atributo -->
  <img v-bind:src="imageSrc" />

  <!-- nome de atributo dinâmico -->
  <button v-bind:[key]="value"></button>

  <!-- atalho -->
  <img :src="imageSrc" />

  <!-- atalho de mesmo nome (3.4+), expande a `:src="src"` -->
  <img :src />

  <!-- atalho de nome de atributo dinâmico -->
  <button :[key]="value"></button>

  <!-- com concatenação de sequência de caracteres em linha -->
  <img :src="'/path/to/images/' + fileName" />

  <!-- vínculos de classe -->
  <div :class="{ red: isRed }"></div>
  <div :class="[classA, classB]"></div>
  <div :class="[classA, { classB: isB, classC: isC }]"></div>

  <!-- vínculos de estilo -->
  <div :style="{ fontSize: size + 'px' }"></div>
  <div :style="[styleObjectA, styleObjectB]"></div>

  <!-- vincular um objeto de atributos -->
  <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>

  <!-- vincular propriedades. -->
  <!-- "prop" deve ser declarada no componente filho. -->
  <MyComponent :prop="someThing" />

  <!-- passar as propriedades do pai em comum com um componente filho -->
  <MyComponent v-bind="$props" />

  <!-- XLink -->
  <svg><a :xlink:special="foo"></a></svg>
  ```

  O modificador `.prop` também tem um atalho dedicado `.`:

  ```vue-html
  <div :someProperty.prop="someObject"></div>

  <!-- equivalente a -->
  <div .someProperty="someObject"></div>
  ```

  O modificador `.camel` permite a camelização dum nome de atributo de `v-bind` quando usamos modelos de marcação no DOM, por exemplo o atributo `viewBox` de SVG:

  ```vue-html
  <svg :view-box.camel="viewBox"></svg>
  ```

  `.camel` não é necessário se estivermos a usar modelos de marcação de sequência de caracteres, pré-compilar o modelo de marcação com uma etapa de construção.

- **Consultar também**
  - [Vínculos de Classe e Estilo](/guide/essentials/class-and-style)
  - [Componentes - Detalhes da Passagem de Propriedade](/guide/components/props#prop-passing-details)

## `v-model` {#v-model}

Cria um vínculo bidirecional num elemento de entrada de formulário ou um componente.

- **Espera:** variar baseado no valor do elemento de entradas de formulário ou na saída de componentes

- **Limitado a:**

  - `<input>`
  - `<select>`
  - `<textarea>`
  - componentes

- **Modificadores**

  - [`.lazy`](/guide/essentials/forms#lazy) - ouve os eventos de `change` ao invés de `input`
  - [`.number`](/guide/essentials/forms#number) - converte uma sequência de caracteres de entrada válida em números.
  - [`.trim`](/guide/essentials/forms#trim) - apara a entrada

- **Consultar também**

  - [Vínculos de Entrada de Formulário](/guide/essentials/forms)
  - [Eventos de Componente - Uso com `v-model`](/guide/components/v-model)

## `v-slot` {#v-slot}

Denota ranhuras nomeadas ou ranhuras isoladas que esperam receber propriedades.

- **Atalho:** `#`

- **Espera:** expressão de JavaScript que é válido numa posição de argumento de função, incluindo suporte para desestruturação. Opcional - apenas necessário se esperamos propriedades serem passadas para a ranhura.

- **Argumento:** nome da ranhura (opcional, predefinido para `default`)

- **Limitado a:**

  - `<template>`
  - [componentes](/guide/components/slots#scoped-slots) (para única ranhura padrão com propriedades)

- **Exemplo**

  ```vue-html
  <!-- Ranhuras nomeadas -->
  <BaseLayout>
    <template v-slot:header>
      Header content
    </template>

    <template v-slot:default>
      Default slot content
    </template>

    <template v-slot:footer>
      Footer content
    </template>
  </BaseLayout>

  <!-- Ranhura nomeada que recebe propriedades -->
  <InfiniteScroll>
    <template v-slot:item="slotProps">
      <div class="item">
        {{ slotProps.item.text }}
      </div>
    </template>
  </InfiniteScroll>

  <!-- Ranhura padrão que recebe propriedades, com desestruturação -->
  <Mouse v-slot="{ x, y }">
    Mouse position: {{ x }}, {{ y }}
  </Mouse>
  ```

- **Consultar também**
  - [Componentes - Ranhuras](/guide/components/slots)

## `v-pre` {#v-pre}

Ignora a compilação para este elemento e todos os seus filhos.

- **Não espera expressão**

- **Detalhes**

  Dentro do elemento com `v-pre`, toda a sintaxe de modelo de marcação da Vue será preservada e desenhada como está. O caso de uso mais comum disto é a exibição de marcadores de bigodes puros.

- **Exemplo**

  ```vue-html
  <span v-pre>{{ this will not be compiled }}</span>
  ```

## `v-once` {#v-once}

Desenha o elemento e o componente apenas uma vez, e ignora as futuras atualizações.

- **Não espera expressão**

- **Detalhes**

  Nos redesenhos subsequentes, o elemento ou componente e todos os seus filhos serão tratados como conteúdo estático e ignorados. Isto pode ser usado para otimizar o desempenho da atualização.

  ```vue-html
  <!-- elemento único -->
  <span v-once>This will never change: {{msg}}</span>
  <!-- o elemento tem filhos -->
  <div v-once>
    <h1>comment</h1>
    <p>{{msg}}</p>
  </div>
  <!-- componente -->
  <MyComponent v-once :comment="msg"></MyComponent>
  <!-- diretiva `v-for` -->
  <ul>
    <li v-for="i in list" v-once>{{i}}</li>
  </ul>
  ```

  Desde a 3.2, também podemos memorizar parte do modelo de marcação com condições de invalidação usando a [`v-memo`](#v-memo).

- **Consultar também**
  - [Sintaxe de Vínculo de Dados - Interpolações](/guide/essentials/template-syntax#text-interpolation)
  - [`v-memo`](#v-memo)

## `v-memo` <sup class="vt-badge" data-text="3.2+" /> {#v-memo}

- **Espera:** `any[]`

- **Detalhes**

  Memoriza uma sub-árvore do modelo de marcação. Pode ser usada em ambos elementos e componentes. A diretiva espera um vetor de valores de dependência de comprimento fixo à comparar para a memorização. Se todos os valores no vetor fossem os mesmos que os da última interpretação, então as atualizações para a sub-árvore inteira serão ignoradas. Por exemplo:

  ```vue-html
  <div v-memo="[valueA, valueB]">
    ...
  </div>
  ```

  Quando o componente redesenha-se, se ambos `valueA` e `valueB` continuarem os mesmos, todas as atualizações para este `<div>` e seus filhos serão ignoradas. De fato, mesmo a criação nó virtual do DOM virtual também será ignorada uma vez que a cópia memorizada da sub-árvore pode ser usada novamente.

  É importante especificar o vetor de memorização corretamente, de outro modo podemos ignorar atualizações que deveriam de fato ser aplicadas. `v-memo` com um vetor de dependência vazio (`v-memo="[]"`) seria funcionalmente equivalente à `v-once`.

  **Uso com `v-for`**

  `v-memo` é fornecida exclusivamente para micro otimizações em cenários de desempenho crítico e deveriam ser raramente necessários. O caso de uso mais comum onde isto pode ser útil é quando desenhamos grandes listas `v-for` (onde `length > 1000`):

  ```vue-html
  <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
    <p>ID: {{ item.id }} - selected: {{ item.id === selected }}</p>
    <p>...more child nodes</p>
  </div>
  ```

  Quando o estado `selected` do componente mudar, será criada uma grande quantidade de nós virtuais, embora a maioria dos itens permaneça exatamente igual. O uso de `v-memo` neste contexto está essencialmente a dizer "apenas atualize este item se tiver passado de não selecionado para selecionado, ou o contrário". Isto permite que todos os itens não afetados reusarem seus anteriores nós virtuais e ignorar a diferenciação inteiramente. Nota que não precisamos incluir `item.id` no vetor de dependência da `v-memo` neste contexto, uma vez que a Vue atualmente a infere a partir da `:key` do item.

  :::warning AVISO
  Quando usamos a `v-memo` com a `v-for`, devemos certificar-nos que são usados no mesmo elemento. **`v-memo` não funciona dentro da `v-for`**.
  :::

  `v-memo` também pode ser usada nos componentes para manualmente impedir atualizações indesejadas em certos casos extremos onde a verificação da atualização do componente filho não foi otimizado. Mas novamente, é responsabilidade do programador especificar os vetores de dependência correta para evitar ignorar atualizações necessárias.

- **Consultar também**
  - [`v-once`](#v-once)

## `v-cloak` {#v-cloak}

Usada para esconder o modelo de marcação que ainda não foi compilado até que estiver pronto.

- **Não espera expressão**

- **Detalhes**

  **Esta diretiva apenas é necessária nas configurações sem etapa de construção.**

  Quando usamos os modelos de marcação no DOM, pode existir um "piscar de modelos de marcação não compilados": o utilizador pode ver os marcadores de bigodes puros até o componente montado substituí-los com componente desenhado.

  `v-cloak` permanecerá no elemento até que a instância do componente associado for montada. Combinada com as regras de CSS como `[v-cloak] { display: none }`, pode ser usada para esconder os modelos de marcação puros até o componente estiver pronto.

- **Exemplo**

  ```css
  [v-cloak] {
    display: none;
  }
  ```

  ```vue-html
  <div v-cloak>
    {{ message }}
  </div>
  ```

  O `<div>` não será visível até que a compilação estiver concluída.

---

---
url: /guide/reusability/custom-directives.md
---
# Diretivas Personalizadas {#custom-directives}

<script setup>
const vFocus = {
  mounted: el => {
    el.focus()
  }
}
</script>

## Introdução {#introduction}

Além do conjunto padrão de diretivas disponibilizadas no núcleo (tais como `v-model` ou `v-show`), a Vue também permite-te registar as tuas próprias diretivas personalizadas.

Nós introduzimos duas formas de reutilizar código na Vue: [Componentes](/guide/essentials/component-basics) e [Funções de Composição](./composables). Os componentes são os principais blocos do edifício, enquanto os constituíveis são focadas na reutilização da lógica com estado. As diretivas, por outro lado, são principalmente destinadas para a reutilização de lógica que envolve acesso de DOM de baixo nível sobre os elementos simples.

Uma diretiva personalizada é definida como um objeto contendo gatilhos de ciclo de vida semelhantes àqueles de um componente. Os gatilhos recebem o elemento em que a diretiva está vinculada. Cá está um exemplo de uma diretiva que foca em uma entrada quando o elemento é inserido no DOM pela Vue:

<div class="composition-api">

```vue
<script setup>
// ativa "v-focus" nos modelos de marcação
const vFocus = {
  mounted: (el) => el.focus()
}
</script>

<template>
  <input v-focus />
</template>
```

</div>

<div class="options-api">

```js
const focus = {
  mounted: (el) => el.focus()
}

export default {
  directives: {
    // ativa "v-focus" no modelo de marcação
    focus
  }
}
```

```vue-html
<input v-focus />
```

</div>

<div class="demo">
  <input v-focus placeholder="This should be focused" />
</div>

Presumindo de que não tens clicado noutro lado na página, a entrada acima deveria ser auto-focada. Esta diretiva é mais útil do que o atributo `autofocus` porque ela funciona não apenas sobre o carregamento da página - ele também funciona quando o elemento for dinamicamente inserido pela Vue.

<div class="composition-api">

No `<script setup>`, qualquer variável em "camelCase" que começa com o prefixo `v` pode ser utilizado como uma diretiva personalizada. No exemplo acima, `vFocus` pode ser utilizado no modelo de marcação como `v-focus`.

Se não estiveres a utilizar `<script setup>`, as diretivas personalizadas podem ser registadas utilizando a opção `directives`:

```js
export default {
  setup() {
    /*...*/
  },
  directives: {
    // ativa "v-focus" no modelo de marcação
    focus: {
      /* ... */
    }
  }
}
```

</div>

<div class="options-api">

Semelhante aos componentes, as diretivas personalizadas devem ser registadas para que elas possam ser utilizadas nos modelos de marcação. No exemplo acima, estamos a utilizar o registo local através da opção `directives`.

</div>

É também comum registar globalmente as diretivas personalizadas no nível de aplicação:

```js
const app = createApp({})

// torna "v-focus" utilizável em todos os componentes
app.directive('focus', {
  /* ... */
})
```

:::tip DICA
As diretivas personalizadas devem apenas ser utilizadas quando a funcionalidade desejada pode ser apenas alcançado através da manipulação direta do DOM. Prefira a marcação de modelos declarativa utilizando as diretivas embutidas tais como `v-bind` quando possível porque elas são mais eficientes e amigáveis a interpretação no lado do servidor.
:::

## Gatilhos de Diretiva {#directive-hooks}

Um objeto de definição de diretiva pode fornecer várias funções de gatilho (todas opcionais):

```js
const myDirective = {
  // chamada antes dos atributos do elemento serem vinculados
  // ou antes dos ouvintes de evento serem aplicados
  created(el, binding, vnode, prevVnode) {
    // consulte abaixo os detalhes sobre os argumentos
  },
  // chamada bem antes do elemento ser inserido no DOM.
  beforeMount() {},
  // chamada quando o componente pai do elemento estiver vinculado
  // e todos os seus filhos estiverem montados.
  mounted() {},
  // chamada antes do componente pai ser atualizado
  beforeUpdate() {},
  // chamada depois do componente pai e
  // todos os seus filhos tiverem sido atualizados
  updated() {},
  // chamada antes do componente pai ser desmontado
  beforeUnmount() {},
  // chamada quando o componente pai estiver desmontado
  unmounted() {}
}
```

### Argumentos de Gatilho {#hook-arguments}

Aos gatilhos de diretiva são passados estes argumentos:

- `el`: o elemento em que a diretiva está vinculada. Isto pode ser utilizado para manipular diretamente o DOM.

- `binding`: um objeto contendo as seguintes propriedades.

  - `value`: O valor passado para a diretiva. Por exemplo em `v-my-directive="1 + 1"`, o valor seria `2`.
  - `oldValue`: O valor anterior, apenas disponível em `beforeUpdate` e `updated`. Está disponível quer o valor tenha mudado ou não.
  - `arg`: O argumento passado para a diretiva, se houver. Por exemplo em `v-my-directive:foo`, o `arg` seria `"foo"`.
  - `modifiers`: Um objeto contendo os modificadores, se houver. Por exemplo `v-my-directive.foo.bar`, o objeto de modificadores seria `{ foo: true, bar: true }`.
  - `instance`: A instância do componente onde a diretiva é utilizada.
  - `dir`: O objeto de definição da diretiva.

- `vnode`: O nó de vue (VNode em Inglês) subjacente representando o elemento vinculado.
- `prevNode`: O nó de vue (VNode em Inglês) representando o elemento vinculado da interpretação anterior. Apenas disponível os gatilhos `beforeUpdate` e `updated`.

Como um exemplo, considere a seguinte utilização de diretiva:

```vue-html
<div v-example:foo.bar="baz">
```

O argumento `binding` (vinculação, em Português) seria um objeto na forma de:

```js
{
  arg: 'foo',
  modifiers: { bar: true },
  value: /* valor de `baz` */,
  oldValue: /* valor de `baz` da atualização anterior */
}
```

Semelhante as diretivas embutidas, os argumentos de diretiva personalizada podem ser dinâmicos. Por exemplo:

```vue-html
<div v-example:[arg]="value"></div>
```

Aqui o argumento da diretiva será atualizado de maneira reativa baseada na propriedade `arg` no nosso estado de componente.

:::tip NOTA
Para além de `el`, deves tratar estes argumentos como de apenas-leitura e nunca modificá-los. Se precisares de partilhar a informação através dos gatilhos, é recomendado fazer isto através do atributo [dataset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) do elemento.
:::

## Abreviação de Função {#function-shorthand}

É comum para uma diretiva personalizada ter o mesmo comportamento para `mounted` e `updated`, sem precisar de outros gatilhos. Nestes casos podemos definir a diretiva como uma função:

```vue-html
<div v-color="color"></div>
```

```js
app.directive('color', (el, binding) => {
  // isto será chamado para ambos `mounted` e `updated`
  el.style.color = binding.value
})
```

## Literais de Objeto {#object-literals}

Se a tua diretiva precisar de vários valores, podes também um literal de objeto de JavaScript. Lembra-te de que, as diretivas podem receber qualquer expressão de JavaScript válida.

```vue-html
<div v-demo="{ color: 'white', text: 'hello!' }"></div>
```

```js
app.directive('demo', (el, binding) => {
  console.log(binding.value.color) // => "white"
  console.log(binding.value.text) // => "hello!"
})
```

## Utilização sobre Componentes {#usage-on-components}

Quando utilizadas sobre os componentes, as diretivas personalizadas sempre aplicar-se-ão à um nó de raiz do componente, semelhante aos [Atributos Herdados](/guide/components/attrs).

```vue-html
<MyComponent v-demo="test" />
```

```vue-html
<!-- modelo de marcação de MyComponent -->

<div> <!-- a diretiva "v-demo" será aplicada aqui -->
  <span>My component content</span>
</div>
```

Nota que os componentes podem potencialmente ter mais de um nó de raiz. Quando aplicada à um componente com vários nó de raiz, a diretiva será ignorada e um aviso será lançado. Ao contrário dos atributos, as diretivas não podem ser passadas para um elemento diferente com `v-bind="$attrs"`. No geral, **não é** recomendado utilizar diretivas personalizadas sobre os componentes.

---

---
url: /api/built-in-special-elements.md
---
# Elementos Especiais {#built-in-special-elements}

:::info Não São Componentes
`<componente>`, `<slot>` e `<template>` são funcionalidades parecidas com componente e parte da sintaxe do modelo de marcação. Eles não são componentes verdadeiros e são compilados durante a compilação. Como tal, são convenientemente escritos com letras minúsculas nos modelos de marcação.
:::

## `<component>` {#component}

Uma "meta componente" para desenhar componentes ou elementos dinâmicos.

- **Propriedades**

  ```ts
  interface DynamicComponentProps {
    is: string | Component
  }
  ```

- **Detalhes**

  O verdadeiro componente à desenhar é determinado pela propriedade `is`.

  - Quando `is` for uma sequência de caracteres, poderia ser ou nome dum marcador de HTML ou o nome dum componente registado.

  - Alternativamente, `is` também pode ser diretamente vinculado à definição dum componente.

- **Exemplo**

  Interpretação dos componentes com nome registado (API de Opções):

  ```vue
  <script>
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'

  export default {
    components: { Foo, Bar },
    data() {
      return {
        view: 'Foo'
      }
    }
  }
  </script>

  <template>
    <component :is="view" />
  </template>
  ```

  Interpretação dos componentes com a definição (API de Composição com `<script setup></script>`):

  ```vue
  <script setup>
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'
  </script>

  <template>
    <component :is="Math.random() > 0.5 ? Foo : Bar" />
  </template>
  ```

  Interpretação dos elementos de HTML:

  ```vue-html
  <component :is="href ? 'a' : 'span'"></component>
  ```

  Os todos os [componentes embutidos](./built-in-components) podem ser passados para `is`, mas devemos registá-los se quisermos passá-los pelo nome. Por exemplo:

  ```vue
  <script>
  import { Transition, TransitionGroup } from 'vue'

  export default {
    components: {
      Transition,
      TransitionGroup
    }
  }
  </script>

  <template>
    <component :is="isGroup ? 'TransitionGroup' : 'Transition'">
      ...
    </component>
  </template>
  ```

  O registo não é obrigatório se passarmos o próprio componente à `is` no lugar do seu nome, por exemplo no `<script setup>`.

  Se `v-model` for usada num marcador `<component>`, o compilador do modelo de marcação a expandirá à uma propriedade `modelValue` e um ouvinte de evento `update:modelValue`, tal como faria com qualquer outro componente. No entanto, isto não será compatível com os elementos de HTML nativos, tais como `<input>` ou `<select>`. Como resultado, usar `v-model` com um elemento nativo criado dinamicamente não funcionará:

  ```vue
  <script setup>
  import { ref } from 'vue'
  
  const tag = ref('input')
  const username = ref('')
  </script>

  <template>
    <!-- Isto não funcionará porque 'input' é um elemento de HTML nativo -->
    <component :is="tag" v-model="username" />
  </template>
  ```

  Na prática, este caso extremo não é comum, porque os campos de formulário nativos normalmente são envolvidos dentro de componentes em aplicações reais. Se precisarmos usar diretamente um elemento nativo então podemos dividir a `v-model` num atributo e evento manualmente.

- **Consulte também** [Componentes Dinâmicos](/guide/essentials/component-basics#dynamic-components)

## `<slot>` {#slot}

Denota as saídas de conteúdo da ranhura nos modelos de marcação

- **Propriedades**

  ```ts
  interface SlotProps {
    /**
     * Quaisquer propriedades passadas ao <slot>
     * são passadas como argumentos para ranhuras isoladas
     */
    [key: string]: any
    /**
     * Reservada para especificação do nome da ranhura.
     */
    name?: string
  }
  ```

- **Detalhes**

  O elemento `<slot>` pode usar o atributo `name` para especificar um nome de ranhura. Quando nenhum `name` for especificado, desenhará a ranhura padrão. Os atributos adicionais passados ao elemento da ranhura serão passados como propriedades de ranhura à ranhura isolada definida no pai.

  O próprio elemento será substituído pelo seu conteúdo de ranhura correspondente.

  Os elementos de `<slot>` nos modelos de marcação da Vue são compilados para JavaScript, então não são para serem confundidos com os [elementos `<slot>` nativos](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).

- **Consulte também** [Componentes - Ranhuras](/guide/components/slots)

## `<template>` {#template}

O marcador `<template>` é usado como um espaço reservado quando queremos usar uma diretiva embutida sem desenhar um elemento no DOM.

- **Detalhes**

  O manipulação especial do `<template>` apenas é acionada se for usada com uma destas diretivas:

  - `v-if`, `v-else-if`, ou `v-else`
  - `v-for`
  - `v-slot`
  
  Se nenhuma destas diretivas estiver presente, então será desenhado como um [elemento `<template>` nativo](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template).

  Um `<template>` com uma `v-for` também pode ter um [atributo `key`](/api/built-in-special-attributes#key). Todos os outros atributos e diretivas serão descartados, porque não são relevantes sem um elemento correspondente.

  Os componentes de ficheiro único usam [marcador `<template>` de alto nível](/api/sfc-spec#language-blocks) para envolver todo o modelo de marcação. Este uso é separado do uso de `<template>` descrito acima. Este marcador de alto nível não faz parte do próprio modelo de marcação e suporta a sintaxe de modelo de marcação, tais como as diretivas.

- **Consulte também**
  - [Guia - `v-if` sobre o `<template>`](/guide/essentials/conditional#v-if-on-template) 
  - [Guia - `v-for` sobre o `<template>`](/guide/essentials/list#v-for-on-template) 
  - [Guia - Ranhuras Nomeadas](/guide/components/slots#named-slots) 

---

---
url: /api/sfc-spec.md
---
# Especificação da Sintaxe {#sfc-syntax-specification}

## Visão Geral {#overview}

Um componente de ficheiro único da Vue, tradicionalmente usando a extensão de ficheiro `*.vue`, é um formato de ficheiro personalizado que usa uma sintaxe semelhante ao HTML para descrever um componente da Vue. Um componente de ficheiro único da Vue é sintaticamente compatível com a HTML.

Cara ficheiro `*.vue` é composto por três tipos de blocos da linguagem de alto nível: `<template>`, `<script>`, e `<style>`, e opcionalmente blocos personalizados adicionais:

```vue
<template>
  <div class="example">{{ msg }}</div>
</template>

<script>
export default {
  data() {
    return {
      msg: 'Hello world!'
    }
  }
}
</script>

<style>
.example {
  color: red;
}
</style>

<custom1>
  This could be e.g. documentation for the component.
</custom1>
```

## Blocos de Linguagem {#language-blocks}

### `<template>` {#template}

- Cada ficheiro `*.vue` pode conter no máximo um bloco `<template>` de alto nível.

- O conteúdo será extraído e passado ao `@vuw/compiler-dom`, pré-compilado dentro de funções de interpretação de JavaScript, e anexado ao componente exportado como sua opção `render`.

### `<script>` {#script}

- Cada ficheiro `*.vue` poder conter no máximo um bloco `<script>` de alto nível (excluindo [`<script setup>`](/api/sfc-script-setup)).

- O programa é executado como um módulo de ECMAScript.

- A **exportação padrão** deve ser um objeto de opções de componente da Vue, ou como um objeto simples ou como valor de retorno da [`defineComponent`](/api/general#definecomponent).

### `<script setup>` {#script-setup}

- Cada ficheiro `*.vue` pode conter no máximo um bloco `<script setup>` (excluindo o `<script>` normal).

- O programa é pré-processado e usado como a função `setup()` do componente, o que significa que será executado **para cada instância do componente**. Os vínculos de alto nível no `<script setup>` são automaticamente expostos ao modelo de marcação. Para mais detalhes, consulte a [documentação dedicada ao `<script setup>`](/api/sfc-script-setup).

### `<style>` {#style}

- Um único ficheiro `*.vue` pode conter vários marcadores de `<style>`.

- Um marcador `<style>` pode ter os atributos `scoped` ou `module` (consulte [Funcionalidades de Estilo do Componente de Ficheiro Único](/api/sfc-css-features) por mais detalhes) para ajudar a encapsular os estilos ao componente atual. Vários marcadores de `<style>` com diferentes modos de encapsulamento podem ser misturados no mesmo componente.

### Blocos Personalizados {#custom-blocks}

Os blocos personalizados podem ser incluídos num ficheiro `*.vue` por qualquer necessidade específica do projeto, por exemplo um bloco `<docs>`. Alguns exemplos do mundo real de blocos personalizados incluem:

- [Gridsome: `<page-query>`](https://gridsome.org/docs/querying-data/)
- [vite-plugin-vue-gql: `<gql>`](https://github.com/wheatjs/vite-plugin-vue-gql)
- [vue-i18n: `<i18n>`](https://github.com/intlify/bundle-tools/tree/main/packages/vite-plugin-vue-i18n#i18n-custom-block)

A manipulação dos blocos personalizados dependerá do ferramental - se quisermos construir as nossas próprias integrações de bloco personalizado, podemos consultar a [seção de ferramental de integrações de bloco personalizado do Componente de Ficheiro Único](/guide/scaling-up/tooling#sfc-custom-block-integrations) por mais detalhes.

## Inferência Automática de Nome {#automatic-name-inference}

Um componente de ficheiro único infere automaticamente o nome do componente a partir do seu **nome de ficheiro** nos seguintes casos:

- Formatação do aviso de desenvolvimento
- Inspeção das ferramentas de programação
- Auto-referência recursiva, por exemplo, um ficheiro nomeado `FooBar.vue` pode refer-se a si mesmo como `<FooBar/>` no seu modelo de marcação. Isto tem a menor prioridade do que os componentes registados ou importados explicitamente.

## Pré-Processadores {#pre-processors}

Os blocos podem declarar linguagens pré-processadoras usando o atributo `lang`. O caso mais comum é usar TypeScript para o bloco `<script>`:


```vue-html
<script lang="ts">
  // usar TypeScript
</script>
```

`lang` pode ser aplicado à qualquer bloco - por exemplo, podemos usar o `<style>` com  a [Sass](https://sass-docs-pt.netlify.app/) e o `<template>` com a [Pug](https://pugjs.org/api/getting-started.html):

```vue-html
<template lang="pug">
p {{ msg }}
</template>

<style lang="scss">
  $primary-color: #333;
  body {
    color: $primary-color;
  }
</style>
```

Nota que a integração com os vários pré-processadores pode diferir conforme a cadeia de ferramenta. Consulte a respetiva documentação por exemplos:

- [Vite](https://pt.vitejs.dev/guide/features#css-pre-processors)
- [Vue CLI](https://cli.vuejs.org/guide/css.html#pre-processors)
- [webpack + vue-loader](https://vue-loader.vuejs.org/guide/pre-processors.html#using-pre-processors)

## Importações com `src` {#src-imports}

Se preferirmos separar os nossos componentes `*.vue` em vários ficheiros, podemos usar o atributo `src` para importar um ficheiro externo para um bloco de linguagem:

```vue
<template src="./template.html"></template>
<style src="./style.css"></style>
<script src="./script.js"></script>
```

Devemos estar ciente de que as importações de `src` seguem as mesmas regras de resolução de caminho que as requisições de módulo da Webpack, o que significa que:

- Os caminhos relativos precisam começar com `./`
- Nós podemos importar recursos a partir das dependências do npm:

```vue
<!-- importar um ficheiro dum pacote "todomvc-app-css" instalado -->
<style src="todomvc-app-css/index.css" />
```

As importações de `src` também funcionam com os blocos personalizados, por exemplo:

```vue
<unit-test src="./unit-test.js">
</unit-test>
```

## Comentários {#comments}

Dentro de cada bloco usaremos a sintaxe de comentário da linguagem em uso (HTML, CSS, JavaScript, Pug, etc.). Para comentários de alto nível, usamos a sintaxe de comentário da HTML: `<!-- eis o conteúdo do comentário -->`

---

---
url: /guide/components/events.md
---
<script setup>
import { onMounted } from 'vue'

if (typeof window !== 'undefined') {
  const hash = window.location.hash

  // The docs for v-model used to be part of this page. Attempt to redirect outdated links.
  const hashes = [
    '#usage-with-v-model',
    '#v-model-arguments',
    '#multiple-v-model-bindings',
    '#handling-v-model-modifiers'
  ]

  if (hashes.includes(hash)) {
    onMounted(() => {
      window.location = './v-model.html' + hash
    })
  }
}
</script>

# Eventos de Componente {#component-events}

> Neste material assume-se conhecimento dos [Fundamentos dos Componentes](/guide/essentials/component-basics). Precisamos entender o básico de componentes para acompanhar este material.

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/defining-custom-events-emits" title="Aula Gratuita Sobre a Definição de Eventos Personalizados na Vue.js"/>
</div>

## Emitindo e Ouvindo Eventos {#emitting-and-listening-to-events}

Um componente pode emitir eventos personalizados diretamente nas expressões de modelo de marcação (por exemplo, num manipulador de `v-on`) utilizando o método `$emit` embutido:

```vue-html
<!-- MyComponent -->
<button @click="$emit('someEvent')">click me</button>
```

<div class="options-api">

O método `$emit()` também está disponível na instância do componente como `this.$emit()`:

```js
export default {
  methods: {
    submit() {
      this.$emit('submit')
    }
  }
}
```

</div>

O componente pai pode então ouvi-lo utilizando a `v-on`:

```vue-html
<MyComponent @some-event="callback" />
```

O modificador `.once` também é suportado nos ouvintes de evento do componente:

```vue-html
<MyComponent @some-event.once="callback" />
```

Tal como os componentes e propriedades, os nomes de eventos fornecem uma transformação de caixa automática. Repara que nós emitimos um evento em "camelCase", mas podemos ouvir ele utilizando um ouvinte em "kebab-case" no componente pai. De acordo com a [caixa dos caracteres das propriedades](/guide/components/props#prop-name-casing), recomendamos a utilização de ouvintes de evento em "kebab-case" nos modelos de marcação.

:::tip DICA
Ao contrário os eventos de DOM nativos, os eventos emitidos do componente **não** transbordam. Tu só podes ouvir os eventos emitidos por um componente filho direto.
:::

## Argumentos de Evento {#event-arguments}

Algumas vezes é útil emitir um valor especifico com um evento. Por exemplo, podemos desejar que o componente `<BlogPost>` esteja encarregado do por quanto aumentar o texto. Naqueles casos, podemos passar argumentos adicionais para a `$emit` para fornecer este valor:

```vue-html
<button @click="$emit('increaseBy', 1)">
  Increase by 1
</button>
```

Então, quando ouvirmos o evento no componente pai, podemos utilizar uma função em flecha em linha como ouvinte, que permite-nos acessar o argumento do evento:

```vue-html
<MyButton @increase-by="(n) => count += n" />
```

Ou, se o manipulador de evento for um método:

```vue-html
<MyButton @increase-by="increaseCount" />
```

Então o valor será passado como primeiro parâmetro daquele método:

<div class="options-api">

```js
methods: {
  increaseCount(n) {
    this.count += n
  }
}
```

</div>
<div class="composition-api">

```js
function increaseCount(n) {
  count.value += n
}
```

</div>

:::tip
Todos os argumentos adicionais passados para o `$emit()` depois do nome do evento serão enviados para o ouvinte. Por exemplo, com `$emit('foo', 1, 2, 3)` a função ouvinte receberá três argumentos.
:::

## Declarando Eventos Emitidos {#declaring-emitted-events}

Um componente pode declarar explicitamente os eventos que ele emitirá usando a <span class="composition-api">macro [`defineEmits()`](/api/sfc-script-setup#defineprops-defineemits)</span><span class="options-api">opção [`emits`](/api/options-state#emits)</span>:

<div class="composition-api">

```vue
<script setup>
defineEmits(['inFocus', 'submit'])
</script>
```

O método `$emit` que utilizamos no `<template>` não é acessível dentro da secção `<script setup>` de um componente, mas a `defineEmits()` retorna uma função equivalente que podemos utilizar no lugar daquela:

```vue
<script setup>
const emit = defineEmits(['inFocus', 'submit'])

function buttonClick() {
  emit('submit')
}
</script>
```

A macro `defineEmits()` **não pode** ser utilizada dentro de uma função, ela deve ser colocada diretamente dentro da `<script setup>`, conforme está no exemplo acima.

Se estiveres utilizando um função `setup` explícita ao invés de `<script setup>`, os eventos devem ser declarados utilizando a opção [`emits`](/api/options-state#emits), e a função `emit` é exposta no contexto de `setup()`:

```js
export default {
  emits: ['inFocus', 'submit'],
  setup(props, ctx) {
    ctx.emit('submit')
  }
}
```

Tal como com outras propriedades do contexto de `setup()`, `emit` pode ser desestruturada com segurança:

```js
export default {
  emits: ['inFocus', 'submit'],
  setup(props, { emit }) {
    emit('submit')
  }
}
```

</div>
<div class="options-api">

```js
export default {
  emits: ['inFocus', 'submit']
}
```

</div>

A opção `emits` também suporta uma sintaxe de objeto, que permite-nos realizar validação de tempo de execução da carga dos eventos emitidos:

<div class="composition-api">

```vue
<script setup>
const emit = defineEmits({
  submit(payload) {
    // retorna `true` ou `false` para indicar
    // que a validação passou ou falhou
  }
})
</script>
```

Se estiveres utilizando a TypeScript com a `<script setup>`, também é possível declarar eventos emitidos utilizando as puras anotações de tipo:

```vue
<script setup lang="ts">
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>
```

Mais detalhes: [Atribuindo Tipos as Emissões de Componente](/guide/typescript/composition-api#typing-component-emits) <sup class="vt-badge ts" />

</div>
<div class="options-api">

```js
export default {
  emits: {
    submit(payload) {
      // retorna `true` ou `false` para indicar
      // que a validação passou ou falhou
    }
  }
}
```

Consulte também: [Atribuindo Tipos as Emissões de Componente](/guide/typescript/options-api#typing-component-emits) <sup class="vt-badge ts" />

</div>

Ainda que opção, é recomendado definir todos eventos emitidos em ordem para documentar melhor como um componente deveria funcionar. Também permite a Vue excluir ouvintes conhecidos dos [atributos que caiem](/guide/components/attrs#v-on-listener-inheritance).

:::tip DICA
Se um evento nativo (por exemplo, `click`) for definido na opção `emits`, o ouvinte agora apenas ouvirá os eventos `click` emitidos pelo componente e não mais responderá aos outros eventos `click` nativos.
:::

## Validação de Eventos {#events-validation}

Semelhante a validação de tipo de propriedade, um evento emitido pode ser validado se for definido com a sintaxe de objeto no lugar da sintaxe de arranjo.

Para adicionar a validação, o evento é atribuído à uma função que recebe os argumentos passados para chamada de <span class="options-api">`this.$emit`</span><span class="composition-api">`emit`</span> e retorna um booleano para indicar se o evento é válido ou não.

<div class="composition-api">

```vue
<script setup>
const emit = defineEmits({
  // Sem validação
  click: null,

  // Valida o evento "submit"
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>
```

</div>
<div class="options-api">

```js
export default {
  emits: {
    // Sem validação
    click: null,

    // Valida o evento "submit"
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}
```

</div>

---

---
url: /guide/scaling-up/tooling.md
---
# Ferramental {#tooling}

## Experimente Online {#try-it-online}

Não será necessário instalar nada em sua máquina para experimentar os Componentes de Arquivo Único do Vue - existem zonas de teste online que lhe permitem fazer isto direto no navegador:

- [Zona de Teste de SFC Vue](https://play.vuejs.org)
  - Sempre disponibilizado com a última versão
  - Projetado para inspecionar os resultados da compilação do componente
- [Vue + Vite na StackBlitz](https://vite.new/vue)
  - Ambiente semelhante a IDE executando um servidor de desenvolvimento Vite real no navegador
  - Mais próximo da configuração local

Também é recomendado usar estas zonas de teste online para fornecer exemplos reproduzíveis ao relatar problemas.

## Estruturação do Projeto {#project-scaffolding}

### Vite {#vite}

[Vite](https://pt.vitejs.dev/) é uma ferramenta de compilação rápida e leve com suporte Vue SFC de primeira classe. Foi criada por Evan You, que também é autor do Vue!

Para começar com Vite + Vue, simplesmente execute:

<VTCodeGroup>
  <VTCodeGroupTab label="npm">

  ```sh
  $ npm create vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="pnpm">
  
  ```sh
  $ pnpm create vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="yarn">
  
  ```sh
  # Para Yarn Moderna (v2+)
  $ yarn create vue@latest
  
  # Para Yarn ^v4.11
  $ yarn dlx create-vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="bun">
  
  ```sh
  $ bun create vue@latest
  ```

  </VTCodeGroupTab>
</VTCodeGroup>

Este comando instalará e executará [create-vue](https://github.com/vuejs/create-vue), a ferramenta de estruturação de projeto oficial do Vue.

- Para aprender mais sobre Vite, consulte a [documentação Vite](https://pt.vitejs.dev).
- Para configurar o comportamento específico do Vue em um projeto Vite, por exemplo passar opções para o compilador Vue, consulte a documentação de [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#readme).

Ambas as zonas de teste online mencionadas acima também suportam o descarregamento dos arquivos como um projeto Vite.

### Interface de Linha de Comando Vue {#vue-cli}

A [Interface de Linha de Comando Vue](https://cli.vuejs.org/) é o conjunto de ferramentas oficial baseado em Webpack para Vue. Agora ele está em modo de manutenção e recomendamos iniciar novos projetos com Vite, a menos que dependa de recursos únicos e específicos do webpack. Vite fornecerá experiência superior ao desenvolvedor na maioria dos casos.

Para mais informações sobre a migração de Vue CLI para Vite:

- [Guia de Migração Vue CLI -> Vite da VueSchool.io](https://vueschool.io/articles/vuejs-tutorials/how-to-migrate-from-vue-cli-to-vite/)
- [Ferramentas / Extensões que ajudam com a migração automática](https://github.com/vitejs/awesome-vite#vue-cli)

### Nota sobre a Compilação de Modelo de Marcação no Navegador {#note-on-in-browser-template-compilation}

Ao usar Vue sem uma etapa de construção, os modelos de marcação do componente são escritos ou diretamente no HTML da página ou como sequências de JavaScript embutidos. Nesses casos, Vue precisa entregar o compilador de modelo de marcação ao navegador para realizar de imediato a compilação do modelo de marcação. Por outro lado, o compilador seria desnecessário se pré-compilarmos os modelos de marcação com uma etapa de construção. Para reduzir o tamanho do pacote do cliente, Vue fornece [diferentes "construções"](https://unpkg.com/browse/vue@3/dist/) otimizadas para diferentes casos.

- Os arquivos de construção que começam com `vue.runtime.*` são **construções somente em tempo de execução**: eles não incluem o compilador. Ao usar estas compilações, todos os modelos de marcação devem ser pré-compilados por meio de uma etapa de construção.

- Os arquivos de construção que não incluem `.runtime` são **construções completas**: eles incluem o compilador e suportam a compilação de modelos de marcação diretamente no navegador. No entanto, eles aumentarão o carregamento em aproximadamente 14kb.

Nossas configurações de ferramentas padrão usam a construção somente em tempo de execução, já que todos os modelos em SFCs são pré-compilados. Se, por algum motivo, for preciso de compilação de modelo no navegador, mesmo com uma etapa de construção, isso pode ser feito configurando a ferramenta de construção para fazer um pseudônimo de `vue` para `vue/dist/vue.esm-bundler.js`.

Para quem busca uma alternativa mais leve para uso sem etapas de construção, dê uma olhada em [petite-vue](https://github.com/vuejs/petite-vue).

## Suporte de IDE {#ide-support}

- A configuração de IDE recomendada é [VS Code](https://code.visualstudio.com/) + a extensão [Volar](https://github.com/johnsoncodehk/volar). Essa extensão fornece destacamento de sintaxe, suporte a TypeScript, e sensor inteligente para expressões de modelo de marcação e propriedades de componentes.

  :::tip DICA
  Volar substitui [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur), a nossa antiga extensão oficial no VS Code para Vue 2. Se o Vetur estiver atualmente instalado, certifique-se de desativá-lo em projetos Vue 3.
  :::

- [WebStorm](https://www.jetbrains.com/webstorm/) também fornece um excelente suporte embutido para SFCs do Vue.

- Outras IDEs que suportam o [Protocolo de Serviço de Linguagem](https://microsoft.github.io/language-server-protocol/) (LSP, sigla em inglês) também podem aproveitar as funcionalidades chave do Volar:

  - Suporte no Sublime Text através do [LSP-Volar](https://github.com/sublimelsp/LSP-volar).

  - Suporte no vim / Neovim através do [coc-volar](https://github.com/yaegassy/coc-volar).

  - Suporte no emacs através do [lsp-mode](https://emacs-lsp.github.io/lsp-mode/page/lsp-volar/)

## Vue Devtools no Navegador {#browser-devtools}

<VueSchoolLink href="https://vueschool.io/lessons/using-vue-dev-tools-with-vuejs-3" title="Assista uma aula gratuita na Vue School"/>

A extensão Vue Devtools no navegador permite explorar árvores de componentes de uma aplicação Vue, inspecionar o estado de componentes individuais, rastrear eventos de gerenciamento de estado, e perfilar o desempenho.

![captura de tela das ferramentas de programação](https://raw.githubusercontent.com/vuejs/devtools/main/media/screenshot-shadow.png)

- [Documentação](https://devtools.vuejs.org/)
- [Extensão do Chrome](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
- [Extensão do Firefox](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
- [Extensão do Edge](https://microsoftedge.microsoft.com/addons/detail/vuejs-devtools/olofadcdnkkjdfgjcmjaadnlehnnihnl)
- [Para Aplicação Electron](https://devtools.vuejs.org/guide/installation.html#standalone)

## TypeScript {#typescript}

Artigo principal: [Usando Vue com TypeScript](/guide/typescript/overview).

- [Volar](https://github.com/johnsoncodehk/volar) fornece a verificação de tipos para SFCs usando blocos `<script lang="ts">`, incluindo expressões de modelo de marcação e a validação de propriedades de componente cruzados.

- Use [`vue-tsc`](https://github.com/johnsoncodehk/volar/tree/master/packages/vue-tsc) para realizar a verificação do mesmo tipo na linha de comando ou para gerar arquivos `d.ts` para SFCs.

## Testagem {#testing}

Artigo principal: [Guia de Testagem](/guide/scaling-up/testing).

- [Cypress](https://www.cypress.io/) é recomendado para testes E2E. Ele também pode ser usado para testagem de componentes SFCs do Vue através do [Executor de Teste de Componente de Cypress](https://docs.cypress.io/guides/component-testing/introduction).

- [Vitest](https://vitest.dev/) é um executor de testes criado pelos membros da comunidade do Vue / Vite com foco na velocidade. Foi especialmente projetado para aplicações baseadas em Vite para fornecer o mesmo ciclo de reação imediata para testes de unidade / componente.

- [Jest](https://jestjs.io/) pode funcionar com o Vite através do [vite-jest](https://github.com/sodatea/vite-jest). No entanto, isto só é recomendado se houverem conjuntos de testes baseados em Jest existentes que precisam migrar para uma configuração baseada em Vite, pois o Vitest fornece funcionalidades semelhantes com uma integração muito mais eficiente.

## _Linting_ {#linting}

O time Vue mantém [eslint-plugin-vue](https://github.com/vuejs/eslint-plugin-vue), uma extensão de [ESLint](https://eslint.org/) que oferece suporte a regras de lint específicas para Componente de Arquivo Único.

Usuários que anteriormente já usaram Vue CLI podem estar acostumados a ter _linters_ configurados através do webpack. No entanto, ao usar uma configuração de construção baseada em Vite, nossa recomendação geral é:

1. `npm install -D eslint eslint-plugin-vue`, depois siga o [guia de configuração](https://eslint.vuejs.org/user-guide/#usage) do `eslint-plugin-vue`.

2. Configure as extensões IDE de ESLint, por exemplo [ESLint para VS Code](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), para que se possa receber o retorno do _linter_ diretamente no seu editor durante o desenvolvimento. Isso também evita processos de _linters_ desnecessários ao iniciar o servidor de desenvolvimento.

3. Execute o ESLint como parte do comando de construção em produção, para que se possa receber o retorno completo do _linter_ antes de enviar para produção.

4. (Opcional) Ferramentas de configuração como [lint-staged](https://github.com/okonet/lint-staged) para realizar mudanças automaticamente nos arquivos em um `git commit`.

## Formatação {#formatting}

- A extensão [Volar](https://github.com/johnsoncodehk/volar) do Visual Studio Code fornece formatação para Componentes de Arquivo Único do Vue (Vue SFCs) pronta para uso.

- Alternativamente, [Prettier](https://prettier.io/) fornece suporte integrado à formatação de Componente de Arquivo Único do Vue.

## Integrações de Bloco Personalizada SFC {#sfc-custom-block-integrations}

Os blocos personalizados são compilados em importações no mesmo arquivo Vue com diferentes consultas de requisição. É a ferramenta de compilação subjacente que decide como manipular estas requisições de importação.

- Ao usar Vite, uma extensão do Vite personalizada deve ser usada para transformar os blocos personalizados combinados em JavaScript executável. [Exemplo](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#example-for-transforming-custom-blocks)

- Ao usar Vue CLI ou webpack, um carregador webpack deve ser configurado para transformar os blocos correspondentes. [Exemplo](https://vue-loader.vuejs.org/guide/custom-blocks.html)

## Pacotes de Baixo Nível {#lower-level-packages}

### `@vue/compiler-sfc` {#vue-compiler-sfc}

- [Documentação](https://github.com/vuejs/core/tree/main/packages/compiler-sfc)

Este pacote é parte do Vue monorepo e é sempre publicado com a mesma versão do pacote principal de `vue`. Ele está incluído como dependência do pacote principal `vue` e delegado sob o `vue/compiler-sfc` então não precisará instalá-lo individualmente.

O pacote em si mesmo fornece utilitários de nível mais baixo para o processamento de SFCs (Componentes de Arquivo Único do Vue) e destina-se apenas a autores de ferramentas que precisam oferecer suporte a SFCs (Componentes de Arquivo Único do Vue) em ferramentas personalizadas.

:::tip DICA
Sempre prefira o uso deste pacote através da importação profunda de `vue/compiler-sfc` já que isto garante que sua versão esteja em sincronia com a versão do Vue em tempo de execução.
:::

### `@vitejs/plugin-vue` {#vitejs-plugin-vue}

- [Documentação](https://github.com/vitejs/vite/tree/main/packages/plugin-vue)

Extensão oficial que fornece suporte a Componente de Arquivo Único em Vite.

### `vue-loader` {#vue-loader}

- [Documentação](https://vue-loader.vuejs.org/)

O carregador oficial que fornece o suporte a Componente de Arquivo Único Vue no webpack. Se usar Vue CLI, consulte também a [documentação sobre a modificação das opções `vue-loader` em Vue CLI](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader).

## Outras Zonas de Teste {#other-online-playgrounds}

- [Zona de Testes VueUse](https://play.vueuse.org)
- [Vue + Vite na Repl.it](https://replit.com/@templates/VueJS-with-Vite)
- [Vue na CodeSandbox](https://codesandbox.io/s/vue-3)
- [Vue na Codepen](https://codepen.io/pen/editor/vue)
- [Vue na Components.studio](https://components.studio/create/vue3)
- [Vue na WebComponents.dev](https://webcomponents.dev/create/cevue)

<!-- TODO ## Backend Framework Integrations -->

---

---
url: /guide/components/provide-inject.md
---
# Fornecer / Injetar {#provide-inject}

> Esta página presume que já fizeste leitura dos [Fundamentos de Componentes](/guide/essentials/component-basics). Leia aquele primeiro se fores novo para os componentes.

## Perfuração de Propriedade {#prop-drilling}

Usualmente, quando precisamos passar dados do componente pai para um componente filho, utilizamos as [propriedades](/guide/components/props). No entanto, imagine o caso onde temos uma grande árvore de componente, e um componente encaixado profundamente precisa de alguma coisa de um componente ancestral distante. Apenas com as propriedades, teríamos de passar a mesmo propriedade através da corrente do componente pai inteira:

![diagrama da perfuração de propriedade](./images/prop-drilling.png)

<!-- https://www.figma.com/file/yNDTtReM2xVgjcGVRzChss/prop-drilling -->

Repara que apesar do componente `<Footer>` pode não importar-se com estas propriedades absolutamente, ele ainda precisa declarar e passá-los exatamente juntos assim o `<DeepChild>` pode acessá-los. Se existir uma corrente pai mais longa, mais componentes seriam afetadas ao longo do caminho. Isto é chamado "perfuração de propriedade" e definitivamente não é divertido de se lidar.

Nós podemos resolver a perfuração de propriedades com `provide` e `inject`. Um componente pai pode servir como um **fornecedor de dependência** para todos os seus descendentes. Qualquer componente na árvore de descendência, independentemente de quão profundo ele esteja, pode **injetar** as dependências fornecidas pelos componentes para cima na corrente do seu componente pai. 

![Esquema Fornecer/Injetar](./images/provide-inject.png)

<!-- https://www.figma.com/file/PbTJ9oXis5KUawEOWdy2cE/provide-inject -->

## Fornecer {#provide}

<div class="composition-api">

Para fornecer dados aos descendentes do componente, utilize a função [`provide()`](/api/composition-api-dependency-injection#provide):

```vue
<script setup>
import { provide } from 'vue'

provide(/* chave */ 'message', /* valor */ 'hello!')
</script>
```

Se estiveres utilizando o `<script setup>`, certifica-te de que `provide()` seja chamada de maneira síncrona dentro da `setup()`:

```js
import { provide } from 'vue'

export default {
  setup() {
    provide(/* chave */ 'message', /* valor */ 'hello!')
  }
}
```

A função `provide()` aceita dois argumentos. O primeiro argumento é chamado de **chave da injeção**, a qual pode ser uma sequência de caracteres ou um `Symbol`. A chave da injeção é utilizada pelos componentes descendentes para pesquisar o valor desejado para injetar. Um único componente pode chamar `provide()` várias vezes com chaves de injeção diferentes para fornecer valores diferentes.

O segundo argumento é o valor fornecido. O valor pode ser de qualquer tipo, incluindo estado reativo tais como referências:

```js
import { ref, provide } from 'vue'

const count = ref(0)
provide('key', count)
```

O fornecimento de valores reativos permite os componentes descendentes utilizar o valor fornecido para estabelecer uma conexão reativa para componente fornecedor.

</div>

<div class="options-api">

Para fornecer dados aos descendentes do componente, utilize a opção [`provide`](/api/options-composition#provide):

```js
export default {
  provide: {
    message: 'hello!'
  }
}
```

Para cada propriedade no objeto `provide`, a chave está utilizado pelos componentes filho para localizar o valor correto para injetar, enquanto o valor é o que acaba sendo injetado.

Se precisarmos fornecer o estado por instância, por exemplo os dados declarado através da `data()`, então `provide` deve utilizar um valor de função:

```js{7-12}
export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    // utiliza a sintaxe de função para possamos acessar o `this`
    return {
      message: this.message
    }
  }
}
```

No entanto, anote que isto **não** torna a injeção reativa. Nós discutiremos [tornando injeções reativas](#working-with-reactivity) abaixo.

</div>

## Fornecimento a Nível de Aplicação {#app-level-provide}

Além do fornecimento de dados em um componente, podemos também fornecer no nível da aplicação:

```js
import { createApp } from 'vue'

const app = createApp({})

app.provide(/* chave */ 'message', /* valor */ 'hello!')
```

Os fornecimentos de nível da aplicação estão disponíveis para todos os componentes interpretados na aplicação. Isto é especialmente útil quando estamos escrevendo [extensões](/guide/reusability/plugins), visto que as extensões normalmente não seriam capazes de fornecer valores utilizando componentes.

## Injetar {#inject}

<div class="composition-api">

Para injetar os dados fornecidos por um componente ancestral, utilize a função [`inject()`](/api/composition-api-dependency-injection#inject):

```vue
<script setup>
import { inject } from 'vue'

const message = inject('message')
</script>
```

Se o valor fornecido for uma referência, ela será injetada como está e **não** será automaticamente desembrulhada. Isto permite o componente injetor conservar a conexão de reatividade para o componente fornecedor. 

[Exemplo de fornecer + injetar com Reatividade completo](https://play.vuejs.org/#eNqFUUFugzAQ/MrKF1IpxfeIVKp66Kk/8MWFDXYFtmUbpArx967BhURRU9/WOzO7MzuxV+fKcUB2YlWovXYRAsbBvQije2d9hAk8Xo7gvB11gzDDxdseCuIUG+ZN6a7JjZIvVRIlgDCcw+d3pmvTglz1okJ499I0C3qB1dJQT9YRooVaSdNiACWdQ5OICj2WwtTWhAg9hiBbhHNSOxQKu84WT8LkNQ9FBhTHXyg1K75aJHNUROxdJyNSBVBp44YI43NvG+zOgmWWYGt7dcipqPhGZEe2ef07wN3lltD+lWN6tNkV/37+rdKjK2rzhRTt7f3u41xhe37/xJZGAL2PLECXa9NKdD/a6QTTtGnP88LgiXJtYv4BaLHhvg==)

Novamente, se não estiveres utilizando `<script setup>`, `inject()` deve apenas ser chamada de maneira síncrona dentro de `setup()`:

```js
import { inject } from 'vue'

export default {
  setup() {
    const message = inject('message')
    return { message }
  }
}
```

</div>

<div class="options-api">

Para injetar os dados fornecidos por um componente ancestral, utilize a opção [`inject`](/api/options-composition#inject):

```js
export default {
  inject: ['message'],
  created() {
    console.log(this.message) // valor injetado
  }
}
```

As injeções são resolvidas **antes** do estado do próprio componente, assim podes acessar as propriedades injetas na `data()`:

```js
export default {
  inject: ['message'],
  data() {
    return {
      // dados iniciais baseados no valor injetado
      fullMessage: this.message
    }
  }
}
```

[Exemplo de fornecer + injetar completo](https://play.vuejs.org/#eNqFUUFugzAQ/MrKF1IpxfeIVKp66Kk/8MWFDXYFtmUbpArx967BhURRU9/WOzO7MzuxV+fKcUB2YlWovXYRAsbBvQije2d9hAk8Xo7gvB11gzDDxdseCuIUG+ZN6a7JjZIvVRIlgDCcw+d3pmvTglz1okJ499I0C3qB1dJQT9YRooVaSdNiACWdQ5OICj2WwtTWhAg9hiBbhHNSOxQKu84WT8LkNQ9FBhTHXyg1K75aJHNUROxdJyNSBVBp44YI43NvG+zOgmWWYGt7dcipqPhGZEe2ef07wN3lltD+lWN6tNkV/37+rdKjK2rzhRTt7f3u41xhe37/xJZGAL2PLECXa9NKdD/a6QTTtGnP88LgiXJtYv4BaLHhvg==)

### Pseudónimo da Injeção \* {#injection-aliasing}

Quando estiveres utilizando uma sintaxe de arranjo para a `inject`, as propriedades injetadas são expostas sobre a instância do componente utilizando a mesma chave. No exemplo acima, a propriedade foi fornecida sob a chave `"message"`, e injetados como `this.message`. A chave local é a mesma que a chave da injeção.

Se queremos injetar a propriedades utilizando uma chave local diferente, precisamos utilizar a sintaxe de objeto para a opção `inject`:

```js
export default {
  inject: {
    /* chave local */ localMessage: {
      from: /* chave da injeção */ 'message'
    }
  }
}
```

Aqui, o componente localizará a propriedade fornecida com a chave `"message"`, e então a exporá como `this.localMessage`.

</div>

### Valores Padrão da Injeção {#injection-default-values}

Por padrão, a `inject` presume que a chave injetada é fornecida em algum lugar na corrente do componente pai. No caso onde a chave não é fornecida, haverá um aviso de tempo de execução.

Se queremos fazer uma propriedade injetada funcionar com fornecedores opcionais, precisamos declarar um valor padrão, semelhante as propriedades:

<div class="composition-api">

```js
// `value` será "default value"
// se nenhum dado correspondendo "message" foi passado
const value = inject('message', 'default value')
```

Em alguns casos, o valor padrão pode precisar ser criado chamando uma função ou instanciando uma nova classe. Para evitar cálculo desnecessário ou efeitos colaterais no caso do valor opcional não for passado, podemos utilizar uma função de fábrica ("factory function", se preferires) para criação do valor padrão:

```js
const value = inject('key', () => new ExpensiveClass())
```

</div>

<div class="options-api">

```js
export default {
  // a sintaxe de objeto é obrigatória
  // quando estiveres declarando valores padrão para injeções
  inject: {
    message: {
      from: 'message', // isto é opcional se estiveres utilizando a mesma chave para injeção
      default: 'default value'
    },
    user: {
      // utilize uma função de fábrica para valores não primitivos que são caros
      // de criar, ou aqueles que deveriam ser únicos por instância de componente.
      default: () => ({ name: 'John' })
    }
  }
}
```

</div>

## Trabalhando com Reatividade {#working-with-reactivity}

<div class="composition-api">

Quando estiveres utilizando os valores reativos de fornecer e injetar, **é recomendado manter quaisquer mutações para o estado reativo dentro do _fornecedor_ sempre que possível**. Isto garante que o estado fornecido e suas possíveis mutações são co-localizados no mesmo componente, tornando mais fácil manter no futuro.

Talvez exista momentos em que precisamos atualizar os dados a partir de um componente injetor. Em tais casos, recomendamos o fornecimento de uma função que seja responsável pela mutação do estado: 

```vue{7-9,13}
<!-- dentro do componente fornecedor -->
<script setup>
import { provide, ref } from 'vue'

const location = ref('North Pole')

function updateLocation() {
  location.value = 'South Pole'
}

provide('location', {
  location,
  updateLocation
})
</script>
```

```vue{5}
<!-- no componente injetor -->
<script setup>
import { inject } from 'vue'

const { location, updateLocation } = inject('location')
</script>

<template>
  <button @click="updateLocation">{{ location }}</button>
</template>
```

Finalmente, podes envolver o valor fornecido com a [`readonly()`](/api/reactivity-core#readonly) se quiseres garantir que os dados passados através de `provide` não possam ser alterados pelo componente injetado.

```vue
<script setup>
import { ref, provide, readonly } from 'vue'

const count = ref(0)
provide('read-only-count', readonly(count))
</script>
```

</div>

<div class="options-api">

Para tornar as injeções ligadas de maneira reativa ao fornecedor, precisamos fornecer um propriedade computada utilizando a função [computed()](/api/reactivity-core#computed):

```js{10}
import { computed } from 'vue'

export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    return {
      // fornecer explicitamente uma propriedade computada
      message: computed(() => this.message)
    }
  }
}
```

[Exemplo completo sobre fornecer + injetar com Reatividade](https://play.vuejs.org/#eNqFUUFugzAQ/MrKF1IpxfeIVKp66Kk/8MWFDXYFtmUbpArx967BhURRU9/WOzO7MzuxV+fKcUB2YlWovXYRAsbBvQije2d9hAk8Xo7gvB11gzDDxdseCuIUG+ZN6a7JjZIvVRIlgDCcw+d3pmvTglz1okJ499I0C3qB1dJQT9YRooVaSdNiACWdQ5OICj2WwtTWhAg9hiBbhHNSOxQKu84WT8LkNQ9FBhTHXyg1K75aJHNUROxdJyNSBVBp44YI43NvG+zOgmWWYGt7dcipqPhGZEe2ef07wN3lltD+lWN6tNkV/37+rdKjK2rzhRTt7f3u41xhe37/xJZGAL2PLECXa9NKdD/a6QTTtGnP88LgiXJtYv4BaLHhvg==)

A função `computed()` é normalmente utilizada nos componentes da API de Composição, mas podem também ser utilizadas para complementar certos casos de uso na API de Opções. Tu podes aprender mais a respeito disto lendo os [Fundamentos de Reatividade](/guide/essentials/reactivity-fundamentals) e as [Propriedades Computadas](/guide/essentials/computed) com a Preferência de API definida para API de Composição.

</div>

## Trabalhando com Chaves de `Symbol` {#working-with-symbol-keys}

Até aqui, temos estado utilizando chaves de injeção de sequência de caracteres nos exemplos. Se estiveres trabalhando em uma aplicação grande com vários provedores de dependência, ou estiveres criando componentes que serão utilizados por outros programadores, é melhor utilizar as chaves de injeção de `Symbol` ("Símbolo") para evitar potenciais colisões.

É recomendado exportar os símbolos em um ficheiro dedicado:

```js
// keys.js
export const myInjectionKey = Symbol()
```

<div class="composition-api">

```js
// no componente fornecedor
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, {
  /* dados a fornecer */
})
```

```js
// no componente injetor
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)
```

Consulte também: [Tipando `provide` / `inject`](/guide/typescript/composition-api#typing-provide-inject) <sup class="vt-badge ts" />

</div>

<div class="options-api">

```js
// no componente fornecedor
import { myInjectionKey } from './keys.js'

export default {
  provide() {
    return {
      [myInjectionKey]: {
        /* dados a fornecer */
      }
    }
  }
}
```

```js
// no componente injetor
import { myInjectionKey } from './keys.js'

export default {
  inject: {
    injected: { from: myInjectionKey }
  }
}
```

</div>

---

---
url: /api/sfc-css-features.md
---
# Funcionalidades de CSS {#sfc-css-features}

## CSS Isolado {#scoped-css}

Quando um marcador `<style>` tiver o atributo `scoped`, o seu CSS apenas aplicar-se-á aos elementos do componente atual. Isto é semelhante ao encapsulamento de estilo encontrado no DOM de Sombra. Ele vem com algumas advertências, mas não exige quaisquer preenchimento de funcionalidade. Ele é alcançado usando PostCSS para transformar o seguinte:

```vue
<style scoped>
.example {
  color: red;
}
</style>

<template>
  <div class="example">hi</div>
</template>
```

No seguinte:

```vue
<style>
.example[data-v-f3f3eg9] {
  color: red;
}
</style>

<template>
  <div class="example" data-v-f3f3eg9>hi</div>
</template>
```

### Elementos de Raiz do Componente Filho {#child-component-root-elements}

Com `scoped`, os estilos do componente pai não passarão para os componentes filhos. No entanto, um nó de raiz do componente filho será afetado por ambas CSS isolada do pai e a CSS isolada do filho. Isto é de propósito para que o pai possa estilizar o elemento de raiz filho para fins de disposição.

### Seletores Profundos {#deep-selectors}

Se quisermos que um seletor nos estilos `scoped` torne-se "profundo", ou seja, afete componentes filho, podemos usar a pseudo-classe `:deep()`:

```vue
<style scoped>
.a :deep(.b) {
  /* ... */
}
</style>
```

O código acima será compilado para:

```css
.a[data-v-f3f3eg9] .b {
  /* ... */
}
```

:::tip DICA
Os conteúdos do DOM criados com `v-html` não são afetados pelos estilos isolados, mas ainda podemos estilizá-los usando seletores profundos.
:::

### Seletores Inseridos {#slotted-selectors}

Por padrão, os estilos isolados não afetam os conteúdos interpretados pelo `<slot/>`, uma vez que são considerados ser propriedade do componente pai que está a passá-los. Para explicitamente atingir o conteúdo da ranhura, usamos a pseudo-classe `:slotted`:

```vue
<style scoped>
:slotted(div) {
  color: red;
}
</style>
```

### Seletores Globais {#global-selectors}

Se quisermos que apenas uma regra aplique-se globalmente, podemos usar a pseudo-classe `:global` ao invés de criar um outro `<style>` (consulte o exemplo abaixo):

```vue
<style scoped>
:global(.red) {
  color: red;
}
</style>
```

### Misturando Estilos Locais e Globais {#mixing-local-and-global-styles}

Nós também podemos incluir ambos estilos isolados e não isolados no mesmo componente:

```vue
<style>
/* estilos globais */
</style>

<style scoped>
/* estilos locais */
</style>
```

### Dicas de Estilo Isolado {#scoped-style-tips}

- **Os estilos isolados não eliminam a necessidade de classes**. Por causa da maneira que os navegadores interpretam os vários seletores de CSS, `p { color: red }` será muitas vezes mais lento quando isolado (ou seja, quando combinado com um seletor de atributo). Se usarmos as classes (por exemplo, `.class-name`) ou identificadores (por exemplo, `#id-name`), tal como em `.example { color: red }`, então eliminamos virtualmente este impacto de desempenho.

- **Temos que ter cuidado com os seletores de descendentes nos componentes recursivos!** Para um regara de CSS com o seletor `.a .b`, se o elemento que corresponde `.a` contiver um componente filho recursivo, então todos os `.b` neste componente filho serão correspondidos pela regra.

## Módulos de CSS {#css-modules}

Um marcador `<style module>` é compilado como [Módulos de CSS](https://github.com/css-modules/css-modules) e expõe as classes de CSS resultantes ao componente como um objeto sob a chave de `$style`:

```vue
<template>
  <p :class="$style.red">This should be red</p>
</template>

<style module>
.red {
  color: red;
}
</style>
```

As classes resultantes têm o seu nome gerados com caracteres embaralhados para evitar colisões, alcançando o mesmo efeito de isolar o CSS apenas ao componente atual.

Consulte a [especificação dos Módulos de CSS](https://github.com/css-modules/css-modules) por mais detalhes, tais como [exceções globais](https://github.com/css-modules/css-modules/blob/master/docs/composition.md#exceptions) e [composição](https://github.com/css-modules/css-modules#composition).

### Nome de Injeção Personalizado {#custom-inject-name}

Nós podemos personalizar a chave da propriedade do objeto de classes injetadas dando ao atributo `module` um valor:

```vue
<template>
  <p :class="classes.red">red</p>
</template>

<style module="classes">
.red {
  color: red;
}
</style>
```

### Uso com API de Composição {#usage-with-composition-api}

As classes injetadas podem ser acessadas na `setup()` e no `<script setup>` através da API `useCssModule`. Para os blocos `<style module>` com nomes de injeção personalizados, `useCssModule` aceita o valor do atributo `module` correspondente como primeiro argumento:

```js
import { useCssModule } from 'vue'

// dentro do âmbito de setup()...
// padrão, retorna as classes do marcador `<style module>`
useCssModule()

// personalizado, retorna as classes do marcador `<style module="classes">`
useCssModule('classes')
```

## `v-bind()` na CSS {#v-bind-in-css}

Os marcadores `<style>` do componente de ficheiro único suportam vincular os valores de CSS ao estado do componente dinâmico usando a função de CSS `v-bind`:

```vue
<template>
  <div class="text">hello</div>
</template>

<script>
export default {
  data() {
    return {
      color: 'red'
    }
  }
}
</script>

<style>
.text {
  color: v-bind(color);
}
</style>
```

A sintaxe funciona com o [`<script setup>`](./sfc-script-setup), e suporta expressões de JavaScript (devem estar envoltos por aspas):

```vue
<script setup>
const theme = {
  color: 'red'
}
</script>

<template>
  <p>olá</p>
</template>

<style scoped>
p {
  color: v-bind('theme.color');
}
</style>
```

O verdadeiro valor será compilado numa propriedade personalizada de CSS com nome composto por caracteres embaralhados, assim a CSS continua estática. A propriedade personalizada será aplicada ao elemento de raiz do componente através de estilos em linha e atualizada de maneira reativa se o valor de origem for mudado.

---

---
url: /guide/reusability/composables.md
---
# Funções de Composição {#composables}

<script setup>
import { useMouse } from './mouse'
const { x, y } = useMouse()
</script>

:::tip DICA
Esta seção presume conhecimento básico da API de Composição. Se estivermos a aprender a Vue com a API de Opções apenas, podemos definir a Preferência de API para API de Composição (usando o interruptor em cima do menu lateral) e reler os capítulos [Fundamentos de Reatividade](/guide/essentials/reactivity-fundamentals) e [Gatilhos do Ciclo de Vida](/guide/essentials/lifecycle).
:::

## O Que é uma "Função de Composição"? {#what-is-a-composable}

No contexto das aplicações de Vue, uma "função de composição" é uma função que influencia a API de Composição da Vue a resumir e reutilizar **lógica com estado**.

Quando estamos a construir aplicações de frontend, frequentemente precisamos reutilizar a lógica para tarefas comuns. Por exemplo, podemos precisar formatar datas em muitos lugares, assim extraímos uma função reutilizável para isto. Esta função formatadora resume a **lógica sem estado**: ela recebe alguma entrada e imediatamente retorna a saída esperada. Existem muitas bibliotecas por aí a fora para reutilização de lógica sem estado - por exemplo [`lodash`](https://lodash.com/) e [`date-fns`](https://date-fns.org/), as quais já podes ter ouvido falar.

Em contrapartida, a lógica com estado envolve a gestão de estado que muda ao longo do tempo. Um exemplo simples seria o rastreio da posição atual do rato em uma página. Nos cenários do mundo real, poderia ser também lógica mais complexa tal como gestos de toque ou estado da conexão com uma base de dados.

## Exemplo de Rastreador de Rato {#mouse-tracker-example}

Se fossemos implementar a funcionalidade de rastreio de rato utilizando a API de Composição diretamente de dentro de um componente, ela se pareceria com isto:

```vue
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const x = ref(0)
const y = ref(0)

function update(event) {
  x.value = event.pageX
  y.value = event.pageY
}

onMounted(() => window.addEventListener('mousemove', update))
onUnmounted(() => window.removeEventListener('mousemove', update))
</script>

<template>Mouse position is at: {{ x }}, {{ y }}</template>
```

Mas e se quisermos reutilizar a mesma lógica em vários componentes? Nós podemos extrair a lógica em um ficheiro externo, como uma função de composição:

```js
// mouse.js
import { ref, onMounted, onUnmounted } from 'vue'

// por convenção, os nomes da função de composição começa com "use"
export function useMouse() {
  // estado resumido e gerido pela função de composição
  const x = ref(0)
  const y = ref(0)

  // a composable can update its managed state over time.
  // uma função de composição pode atualizar o seu estado gerido ao longo do tempo.
  function update(event) {
    x.value = event.pageX
    y.value = event.pageY
  }

  // uma função de composição também pode prender-se no ciclo de vida do seu
  // componente proprietário para configurar e deitar abaixo os
  // efeitos colaterais
  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  // expor o estado gerido como valor de retorno
  return { x, y }
}
```

E isto é como pode ser utilizada nos componentes:

```vue
<script setup>
import { useMouse } from './mouse.js'

const { x, y } = useMouse()
</script>

<template>Mouse position is at: {{ x }}, {{ y }}</template>
```

<div class="demo">
  Mouse position is at: {{ x }}, {{ y }}
</div>

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNkj1rwzAQhv/KocUOGKVzSAIdurVjoQUvJj4XlfgkJNmxMfrvPcmJkkKHLrbu69H7SlrEszFyHFDsxN6drDIeHPrBHGtSvdHWwwKDwzfNHwjQWd1DIbd9jOW3K2qq6aTJxb6pgpl7Dnmg3NS0365YBnLgsTfnxiNHACvUaKe80gTKQeN3sDAIQqjignEhIvKYqMRta1acFVrsKtDEQPLYxuU7cV8Msmg2mdTilIa6gU5p27tYWKKq1c3ENphaPrGFW25+yMXsHWFaFlfiiOSvFIBJjs15QJ5JeWmaL/xYS/Mfpc9YYrPxl52ULOpwhIuiVl9k07Yvsf9VOY+EtizSWfR6xKK6itgkvQ/+fyNs6v4XJXIsPwVL+WprCiL8AEUxw5s=)

Conforme podemos ver, a lógica fundamental permanece idêntica - tudo o que tivemos que fazer foi movê-la para uma função externa e retornar o estado que deveria ser exposto. Tal como dentro de um componente, podes utilizar uma grama completa de [funções de API de Composição](/api/#composition-api) nas funções de composição. A mesma funcionalidade de `useMouse()` pode agora ser utilizada em qualquer componente.

Mesmo assim a parte mais fantástica das funções de composição, é que podes também encaixá-las: uma função de composição pode chamar uma ou mais outras funções funções de composição. Isto permite-nos compor lógica complexa utilizando pequenas unidades isoladas, semelhante a como compomos uma aplicação inteira utilizando componentes. De fato, é por isto que decidimos chamar a coleção de APIs que torna este padrão possível de API de Composição.

Por exemplo, podemos extrair a lógica de adição e remoção dum ouvinte de evento de DOM para a sua própria função de composição:

```js
// event.js
import { onMounted, onUnmounted } from 'vue'

export function useEventListener(target, event, callback) {
  // se quiseres, podes também fazer isto suportar
  // sequências de caracteres de seletor como alvo
  onMounted(() => target.addEventListener(event, callback))
  onUnmounted(() => target.removeEventListener(event, callback))
}
```

E agora a nossa função de composição `useMouse()` pode ser simplificada para:

```js{3,9-12}
// mouse.js
import { ref } from 'vue'
import { useEventListener } from './event'

export function useMouse() {
  const x = ref(0)
  const y = ref(0)

  useEventListener(window, 'mousemove', (event) => {
    x.value = event.pageX
    y.value = event.pageY
  })

  return { x, y }
}
```

:::tip DICA
Cada instância de componente chamando `useMouse()` criará as suas próprias cópias do estado `x` e `y` então elas não interferirão umas com as outras. Se quiseres lidar com o estado partilhado entre os componentes, leia o capítulo [Gestão de Estado](/guide/scaling-up/state-management).
:::

## Exemplo de Estado Assíncrono {#async-state-example}

A função de composição `useMouse()` não recebe quaisquer argumentos, então vamos dar uma vista de olhos em um outro exemplo que utiliza um argumento. Quando estamos a fazer requisição de dados assíncronos, frequentemente precisamos manipular estados diferentes: carregamento, sucesso e erro:

```vue
<script setup>
import { ref } from 'vue'

const data = ref(null)
const error = ref(null)

fetch('...')
  .then((res) => res.json())
  .then((json) => (data.value = json))
  .catch((err) => (error.value = err))
</script>

<template>
  <div v-if="error">Oops! Error encountered: {{ error.message }}</div>
  <div v-else-if="data">
    Data loaded:
    <pre>{{ data }}</pre>
  </div>
  <div v-else>Loading...</div>
</template>
```

Seria entediante ter de repetir este padrão em todo componente que precisar requisitar dados. Vamos extraí-lo para uma função de composição:

```js
// fetch.js
import { ref } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)

  fetch(url)
    .then((res) => res.json())
    .then((json) => (data.value = json))
    .catch((err) => (error.value = err))

  return { data, error }
}
```

Agora no nosso componente podes apenas fazer:

```vue
<script setup>
import { useFetch } from './fetch.js'

const { data, error } = useFetch('...')
</script>
```

### Aceitando Estado Reativo {#accepting-reactive-state}

A `useFetch()` recebe uma sequência de caracteres de URL estática como entrada - depois realiza a requisição apenas uma vez e depois está feito. E se quiséssemos requisitar novamente sempre que a URL mudar? No sentido de alcançar isto, precisamos de passar o estado reativo numa função de composição, e deixar a função de composição criar os observadores que realizam ações usando o estado passado.

Por exemplo, `useFetch()` deve ser capaz de aceitar uma referência:

```js
const url = ref('/initial-url')

const { data, error } = useFetch(url)

// isto deve acionar novamente uma requisição
url.value = '/new-url'
```

Ou, aceitar uma função recuperadora:

```js
// requisitar novamente quando `props.id` mudar
const { data, error } = useFetch(() => `/posts/${props.id}`)
```

Nós podemos refazer a nossa implementação existente com as APIs [`watchEffect()`](/api/reactivity-core.html#watcheffect) e [`toValue()`](/api/reactivity-utilities.html#tovalue)

```js{8,13}
// fetch.js
import { ref, watchEffect, toValue } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)

  const fetchData = (dt) => {
    fetch(toValue(url))
    .then((res) => res.json())
    .then((json) => (data.value = json))
    .catch((err) => (error.value = error))
  }

  watchEffect(() => {
    // reiniciar o estado antes de requisitar
    fetchData(url)
  })

  return { data, error }
}
```

`toValue()` é uma API adicionada na 3.3. Está desenhada para normalizar referências e recuperadores para valores. Se o argumento for uma referência, retorna o valor da referência; se o argumento for uma função, chamará a função e retornará o seu valor de retorno. De outro modo, retorna o argumento como está. Funciona de maneira semelhante ao [`unref()`](/api/reactivity-utilities#unref), mas com tratamento especial para funções.

Repara que a `toValue(url)` é chamada **dentro** da função de resposta da `watchEffect`. Isto garante que quaisquer dependências reativas acessadas durante a normalização da `toValue()` sejam rastreadas pelo observador.

Esta versão da `useFetch()` agora aceita sequências de caracteres de URL estáticas, referências, e recuperadores, tornando-a mais flexível. O efeito de observação executará imediatamente, e rastreará quaisquer dependências acessadas durante a `toValue(url)`. Se nenhum dependência for rastreada (por exemplo, a URL já é uma sequência de caracteres), o efeito apenas executa uma vez; de outro modo, executará novamente sempre que uma dependência rastreada mudar.

Eis [a versão atualizada de `useFetch()`](https://play.vuejs.org/#eNptVMFu2zAM/RXOFztYZncodgmSYAPWnTZsKLadfFFsulHrSIZEJwuC/PtIyXaTtkALxxT5yPf45FPypevyfY/JIln6yumOwCP13bo0etdZR3ACh80cKrvresIaztA4u4OUi9KLpN7jN6RqO53nxRjKHz1nlqayxhNslMc/roUVpFuizi+K4tFb07Wqwq1ta3Q5HTtd2RpzblqQra0vGCCW65oreaIs/ZjOxmAf8MYRs2wGq/XU6D3X5HvV9sj5Y8UJakVqDuicdXMGJHfk0VcTj4wxOX9ZRFVYD34h3PGchPwG8N2qGjobZlpIYLnpiayB/YfGulWZaNAGPpUJfK5aXT1JRIbXZbI+nUDD+bwsYklAL2lZ6z1X64ZTw2CcKcAM3a1/2s6/gzsJAzKL3hA6rBfAWCE536H36gEDriwwFA4zTSMEpox7L8+L/pxacPv4K86Brcc4jGjFNV/5AS3TlrbLzqHwkLPYkt/fxFiLUto85Hk+ni+LScpknlwYhX147buD4oO7psGK5kD2r+zxhQdLg/9CSdObijSzvVoinGSeuPYwbPSP6VtZ8HgSJHx5JP8XA2TKH00F0V4BFaAouISvDHhiNrBB3j1CI90D5ZglfaMHuYXAx3Dc2+v4JbRt9wi0xWDymCpTbJ01tvftEbwFTakHcqp64guqPKgJoMYOTc1+OcLmeMUlEBzZM3ZUdjVqPPj/eRq5IAPngKwc6UZXWrXcpFVH4GmVqXkt0boiHwGog9IEpHdo+6GphBmgN6L1DA66beUC9s4EnhwdeOomMlMSkwsytLac5g7aR11ibkDZSLUABRk+aD8QoMiS1WSCcaKwISEZ2MqXIaBfLSpmchUb05pRsTNUIiNkOFjr9SZxyJTHOXx1YGR49eGRDP4rzRt6lmay86Re7DcgGTzAL74GrEOWDUaRL9kjb/fSoWzO3wPAlXNB9M1+KNrmcXF8uoab/PaCljQLwCN5oS93+jpFWmYyT/g8Zel9NEJ4S2fPpYMsc7i9uQlREeecnP8DWEwr0Q==), com um atraso artificial e erro posto aleatório para propósitos de demonstração.

## Convenções e Boas Práticas {#conventions-and-best-practices}

### Nomeação {#naming}

É uma convenção nomear as funções funções de composição com nomes em "camelCase" que começam com o termo "use".

### Argumentos de Entrada {#input-arguments}

Uma função de composição pode aceitar argumentos de referência mesmo se não depender delas para a reatividade. Se estiveres a escrever uma função de composição que pode ser utilizada por outros programadores, é uma boa ideia lidar com o caso de os argumentos de entrada serem referências no lugar de valores brutos. A função utilitária [`unref()`](/api/reactivity-utilities#unref) dará jeito para este propósito:

```js
import { unref } from 'vue'

function useFeature(maybeRef) {
  // se "maybeRef" for de fato uma referência, seu ".value"
  // será retornado, de outro modo, "maybeRef" é retornada como está
  const value = unref(maybeRef)
}
```

Se a tua função de composição produzir efeitos reativos quando a entrada é uma referência, certifica-te de ou explicitamente observar a referência com `watch()`, ou chamar `unref()` dentro de uma `watchEffect()` para que seja apropriadamente rastreada.

### Valores de Retorno {#return-values}

Tu tens provavelmente reparado que tens estado exclusivamente utilizando `ref()` ao invés de `reactive()` nas funções de composição. A convenção recomendada é para os funções de composição sempre retornar um objeto não reativo simples contendo várias referências. Isto permite que seja desestruturada nos componentes enquanto preserva a reatividade:

```js
// "x" e "y" são referências
const { x, y } = useMouse()
```

O retorno de um objeto reativo de uma função de composição causará que tais desestruturações percam a conexão de reatividade com o estado dentro da função de composição, enquanto as referências preservarão esta conexão.

Se preferires usar o estado retornado dos funções de composição como propriedades de objeto, podes envolver o objeto retornado com `reactive()` para que as referências sejam desembrulhadas. Por exemplo:

```js
const mouse = reactive(useMouse())
// "mouse.x" está ligado a referência original
console.log(mouse.x)
```

```vue-html
Mouse position is at: {{ mouse.x }}, {{ mouse.y }}
```

### Efeitos Colaterais {#side-effects}

É aceitável realizar efeitos colaterais (por exemplo, adicionando ouvintes de evento de DOM ou requisitando dados) nas funções de composição, porém preste atenção as seguintes regras:

- Se estiveres a trabalhar sobre uma aplicação que usa a [Interpretação no Lado do Servidor](/guide/scaling-up/ssr) (SSR, sigla em Inglês), certifica-te de realizar os efeitos colaterais específicos de DOM nos gatilhos de ciclo de vida de pós-montagem, por exemplo, `onMounted()`. Estes gatilhos são apenas chamados no navegador, assim podes estar certo de que o código dentro deles tem acesso ao DOM.

- Lembra-te de limpar os efeitos colaterais no `onUnmounted()`. Por exemplo, se uma função de composição definir um ouvinte de evento de DOM, ele deve remover este ouvinte no `onUnmounted()` conforme temos visto no exemplo `useMouse()`. Pode ser uma boa ideia usar uma função de composição que automaticamente faz isto por ti, como exemplo da `useEventListener()`.

### Restrições de Uso {#usage-restrictions}

As funções de composição devem apenas ser chamadas de maneira **síncrona** no `<script setup>` ou no gatilho `setup()`. Em alguns casos, podes também chamá-las nos gatilhos de ciclo de vida tais como `onMounted()`.

Existem os contextos onde a Vue é capaz de determinar a atual instância de componente ativo. Para ter acesso à uma instância de componente ativa é necessária para que:

1. Os gatilhos de ciclo de vida possam ser registadas a ela.

2. As propriedades computadas e observadores possam ser ligados a ela, para que elas possam ser colocadas quando a instância for desmontada para evitar fugas de memória.

:::tip DICA
O `<script setup>` é o único lugar onde podes chamar as funções de composição **depois** do uso de `await`. O compilador restaura automaticamente o contexto da instância ativa por ti depois da operação assíncrona.
:::

## Extraindo Funções de Composição para Organização de Código {#extracting-composables-for-code-organization}

As funções de composição podem ser extraídas não apenas para reaproveitar, mas também para a organização de código. A medida que a complexidade dos teus componentes crescer, podes acabar com componentes que são muito grandes para navegar e compreender. A API de Composição dá-te completa flexibilidade para organizar o código do teu componente em funções mais pequenas baseadas nas preocupações lógicas:

```vue
<script setup>
import { useFeatureA } from './featureA.js'
import { useFeatureB } from './featureB.js'
import { useFeatureC } from './featureC.js'

const { foo, bar } = useFeatureA()
const { baz } = useFeatureB(foo)
const { qux } = useFeatureC(baz)
</script>
```

Até certo ponto, podes pensar destas funções de composição extraídas como serviços isolados de componente que podem conversar uns com os outros.

## Usando Funções de Composição na API de Opções {#using-composables-in-options-api}

Se estiveres usando a API de Opções, as funções de composição devem ser chamadas dentro de `setup()`, e as vinculações retornadas dem ser retornadas a partir de `setup()` para que elas sejam expostas ao `this` e para o modelo de marcação:

```js
import { useMouse } from './mouse.js'
import { useFetch } from './fetch.js'

export default {
  setup() {
    const { x, y } = useMouse()
    const { data, error } = useFetch('...')
    return { x, y, data, error }
  },
  mounted() {
    // As propriedades expostas de "setup()" podem ser acessadas no ``this
    console.log(this.x)
  }
  // ...outras opções
}
```

## Comparações com Outras Técnicas {#comparisons-with-other-techniques}

### vs. Misturas (Mixins) {#vs-mixins}

Os utilizadores chegando da Vue 2 podem estar familiarizados com a opção [mixins](/api/options-composition#mixins), que também permite-nos extrair a lógica do componente em unidades reutilizáveis. Existem três desvantagens primarias em relação ao mixins:

1. **Fonte obscura de propriedades**: quando estiver utilizando muitos mixins, torna-se pouco claro qual propriedade de instância é injetada por qual mixin, tornando-o difícil localizar a implementação e entender o comportamento do componente. É também o do porquê que nós recomendamos a utilização do padrão de referências + desestruturação para as funções de composição: isto torna a fonte da propriedade clara nos componentes consumindo.

2. **Colisão de nome de espaço**: vários mixins de diferentes autores podem potencialmente registar a mesmas chaves de propriedade, causando colisões de nome de espaço. Com as funções de composição, podes renomear os valores desestruturados se houverem chaves conflituosas de diferentes funções de composição. 

3. **Comunicação cruzada de mixin implícita**: vários mixins que precisam interagir uns com os outros têm de depender de chaves de propriedade partilhas, tornando-os implicitamente associados. Com as funções de composição, os valores retornados de uma função de composição podem ser passados para uma outra como argumentos, tal como as funções normais.

Pelas razões acima, não mais recomendamos a utilização de mixins na Vue 3. A funcionalidade é mantida apenas por razões de migração e familiaridade.

### vs. Componentes Sem Interpretação {#vs-renderless-components}

No capítulo de ranhuras de componente, discutimos o padrão de [Componente Sem Interpretação](/guide/components/slots#renderless-components) baseado nas ranhuras isoladas. Nós até implementamos a mesma demonstração de rastreio de rato usando os componentes sem interpretação.

A principal vantagem das funções de composição sobre os componentes sem interpretação é que as funções de composição não incorrem em despesas gerais da instância de componente adicional. Quando utilizadas por uma aplicação inteira, a quantidade de instâncias de componente adicionais criadas pelo padrão de componente sem interpretação pode tornar-se em despesas gerais de desempenho visível.

A recomendação é usar as funções de composição quando reutilizar a lógica pura, e usar os componentes quando estiveres reutilizando tanto a lógica e o esquema visual.

### vs. Gatilhos de React (React Hooks) {#vs-react-hooks}

Se tens experiência com a React, talvez notes que isto parece muito semelhante aos gatilhos de React personalizados. A API de Composição foi em parte inspirada pelos gatilhos de React, e as funções de composição de Vue são de fato semelhantes aos gatilhos de React em termos de capacidades de composição lógica. No entanto, as funções de composição de Vue são baseadas no sistema de reatividade refinado da Vue, o qual é fundamentalmente diferente do modelo de execução dos gatilhos de React. Isto é discutido em mais detalhes nas [Perguntas Frequentes sobre API de Composição](/guide/extras/composition-api-faq#comparison-with-react-hooks).

## Leituras Adicionais {#further-reading}

- [Reatividade Em Profundidade](/guide/extras/reactivity-in-depth): para um entendimento de baixo nível de como o sistema de reatividade da Vue funciona.
- [Gestão de Estado](/guide/scaling-up/state-management): para padrões de gerência de estado partilhado por vários componentes.
- [Testagem de Funções de Composição](/guide/scaling-up/testing#testing-composables): dicas sobre teste unitário de funções de composição.
- [VueUse](https://vueuse.org/): Um coleção que sempre cresce de funções de composição de Vue. O código-fonte é também um grande recurso de aprendizado.

---

---
url: /guide/extras/render-function.md
---

# Funções de Interpretação & JSX {#render-functions-jsx}

A Vue recomenda usar modelos de marcação para construir aplicações na vasta maioria dos casos. No entanto, existem situações onde precisamos de todo o poder programático da JavaScript. É onde podemos usar a **função de interpretação**.

> Se fores novo para o conceito de DOM virtual e funções de interpretação, certifica-te de ler o capítulo [Mecanismo de Interpretação](/guide/extras/rendering-mechanism) antes deste.

## Uso Básico {#basic-usage}

### Criando Nós de Vue {#creating-vnodes}

A Vue fornece uma função `h()` para criação de nós de Vue:

```js
import { h } from 'vue'

const vnode = h(
  'div', // tipo
  { id: 'foo', class: 'bar' }, // propriedades
  [
    /* filhos */
  ]
)
```

`h()` é abreviação para **hyperscript** - que significa "JavaScript que produz HTML (linguagem de marcação de hipertexto)". Este nome é herdado das convenções partilhadas por muitas implementações do DOM virtual. Uma nome mais descritivo poderia ser `createVnode()`, mas um nome mais curto ajuda quando temos que chamar esta função muitas vezes numa função de interpretação.

A função `h()` está desenhada para ser muito flexível:

```js
// todos os argumentos exceto o tipo são opcionais
h('div')
h('div', { id: 'foo' })

// ambos atributos e propriedades podem ser usados nas propriedades
// a Vue escolhe automaticamente a maneira correta de atribuir
h('div', { class: 'bar', innerHTML: 'hello' })

// os modificadores de propriedade tais como `.prop` e `.attr`
// podem ser adicionados com os prefixos `.` e `^` respetivamente
h('div', { '.name': 'some-name', '^width': '100' })

// a classe e estilo têm o mesmo suporte de valor de objeto e arranjo
// que têm nos modelos de marcação
h('div', { class: [foo, { bar }], style: { color: 'red' } })

// os ouvintes de evento devem ser passados como onXxx
h('div', { onClick: () => {} })

// os filhos podem ser uma sequência de caracteres
h('div', { id: 'foo' }, 'hello')

// as propriedades podem ser omitidas quando não existirem
h('div', 'hello')
h('div', [h('span', 'hello')])

// os arranjos de filhos podem conter nós de vue e
// sequência de caracteres misturados
h('div', ['hello', h('span', 'hello')])
```

O nó de vue resultante tem a seguinte forma:

```js
const vnode = h('div', { id: 'foo' }, [])

vnode.type // 'div'
vnode.props // { id: 'foo' }
vnode.children // []
vnode.key // null
```

:::warning NOTA
A interface de `VNode` completa contém muitas outras propriedades internas, mas é fortemente recomendado evitar depender de quaisquer outras propriedades além das listadas aqui. Isto evita rutura não intencional no caso das propriedades internas forem mudadas.
:::

### Declarando as Funções de Interpretação {#declaring-render-functions}

<div class="composition-api">

Quando usamos os modelos de marcação com a API de Composição, o valor de retorno do gatilho `setup()` é usado para expor os dados ao modelo de marcação. Quando usamos as funções de interpretação, no entanto, podemos retornar diretamente a função de interpretação:

```js
import { ref, h } from 'vue'

export default {
  props: {
    /* ... */
  },
  setup(props) {
    const count = ref(1)

    // retorna a função de interpretação
    return () => h('div', props.msg + count.value)
  }
}
```

A função de interpretação é declarada dentro de `setup()` assim naturalmente tem acesso às propriedades e qualquer estado reativo declarado no mesmo âmbito.

Além de retornar um único nó de vue, podemos também retornar sequências de caracteres ou arranjos:

```js
export default {
  setup() {
    return () => 'hello world!'
  }
}
```

```js
import { h } from 'vue'

export default {
  setup() {
    // usar um arranjo para retornar vários nós de raiz
    return () => [
      h('div'),
      h('div'),
      h('div')
    ]
  }
}
```

:::tip
Certifica-te de retornar uma função ao invés de retornar diretamente os valores! A função `setup` é chamada apenas uma vez por componente, enquanto a função de interpretação será chamada várias vezes.
:::

</div>
<div class="options-api">

Nós podemos declarar as funções de interpretação usando a opção `render`:

```js
import { h } from 'vue'

export default {
  data() {
    return {
      msg: 'hello'
    }
  },
  render() {
    return h('div', this.msg)
  }
}
```

A função `render()` tem acesso à instância do componente através de `this`.

Além de retornar um único nó de vue, podemos também retornar sequências de caracteres ou arranjos:

```js
export default {
  render() {
    return 'hello world!'
  }
}
```

```js
import { h } from 'vue'

export default {
  render() {
    // usar um arranjo para retornar vários nós de raiz
    return [
      h('div'),
      h('div'),
      h('div')
    ]
  }
}
```

</div>

Se um componente de função de interpretação não precisar de nenhum estado da instância, também podem ser declarados diretamente como uma função por brevidade:

```js
function Hello() {
  return 'hello world!'
}
```

Exatamente, isto é um componente de Vue válido! Consulte os [Componentes Funcionais](#functional-components) por mais detalhes a respeito desta sintaxe.

### Nós de Vue Devem Ser Únicos {#vnodes-must-be-unique}

Todos os nós de Vue na árvore de componente devem ser únicos. Isto significa que a seguinte função de interpretação é inválida:

```js
function render() {
  const p = h('p', 'hi')
  return h('div', [
    // Yikes - nós de Vue duplicados!
    p,
    p
  ])
}
```

Se realmente quisermos duplicar o mesmo elemento ou componente várias vezes, podemos fazer isto com uma função de fábrica. Por exemplo, a seguinte função de interpretação é uma maneira perfeitamente válida de desenhar 20 parágrafos idênticos:

```js
function render() {
  return h(
    'div',
    Array.from({ length: 20 }).map(() => {
      return h('p', 'hi')
    })
  )
}
```

## JSX / TSX {#jsx-tsx}

A [JSX](https://facebook.github.io/jsx/) é uma extensão parecida com a XML para a JavaScript que permite-nos escrever código como este:

```jsx
const vnode = <div>hello</div>
```

No lugar das expressões de JSX, use chavetas para valores dinâmicos embutidos:

```jsx
const vnode = <div id={dynamicId}>hello, {userName}</div>
```

Ambas `create-vue` e a interface da linha de comando da Vue têm opções para estruturar projetos com suporte de JSX pré-configurado. Se estiveres a configurar a JSX manualmente, consulte a documentação da [`@vue/babel-plugin-jsx`](https://github.com/vuejs/jsx-next) por detalhes.

Embora introduzida primeiro pela React, a JSX na realidade não semânticas de execução definida e pode ser compilada para várias saídas diferentes. Se trabalhaste com a JSX antes, nota que a **transformação de JSX da Vue é diferente da transformação de JSX da React**, então não podes usar a transformação de JSX da React nas aplicações de Vue. Algumas diferenças notáveis da JSX da React incluem:

- Nós podemos usar atributos de HTML tais como `class` e `for` como propriedades - sem precisar de usar `className` ou `htmlFor`.
- A passagem de filhos para os componentes (por exemplos, ranhuras) [funciona de maneira diferente](#passing-slots).

A definição de tipo da Vue também fornece inferência de tipo para o uso de TSX. Quando usares TSX, certifica-te de especificar `"jsx": "preserve"` no `tsconfig.json` para que a TypeScript deixe a sintaxe de JSX intacta para a transformação de JSX da Vue processar.

### Inferência de Tipo da JSX {#jsx-type-inference}

Semelhante a transformação, a JSX da Vue também precisa de definições de tipo diferentes. Atualmente, os tipos da Vue registam os tipos de JSX da Vue globalmente. Isto significa que a TSX funcionará fora da caixa quando o tipo da Vue estiver disponível.

Os tipos de JSX globais podem causar conflitos quando usados juntos com outras bibliotecas que também precisam da inferência de tipo de JSX, em especial React. Desde a versão 3.3, a Vue suporta a especificação de espaço reservado de JSX através da opção [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource) da TypeScript. Nós planeamos remover o registo de espaço reservado de JSX global padrão na versão 3.4 da Vue.

Para os utilizadores de TSX, é sugerido definir [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource) para `vue` no `tsconfig.json` depois de atualizar para 3.3, optar por participar por ficheiro com `/* @jsxImportSource vue */`. Isto permitir-te-á optar para o novo comportamento agora e atualiza de maneira transparente quando 3.4 ser lançada.

Se existir código que depende da presença do espaço reservado `JSX` global, podes reter o comportamento global exato antes da 3.4 fazendo referência de maneira explicita ao `vue/jsx`, que regista o espaço reservado de `JSX` global.

## Receitas de Função de Interpretação {#render-function-recipes}

Abaixo fornecemos algumas receitas comuns para implementar funcionalidades do modelo de marcação conforme as suas funções de interpretação ou JSX equivalentes.

### `v-if` {#v-if}

Modelo de marcação:

```vue-html
<div>
  <div v-if="ok">yes</div>
  <span v-else>no</span>
</div>
```

Função de interpretação ou JSX equivalente:

<div class="composition-api">

```js
h('div', [ok.value ? h('div', 'yes') : h('span', 'no')])
```

```jsx
<div>{ok.value ? <div>yes</div> : <span>no</span>}</div>
```

</div>
<div class="options-api">

```js
h('div', [this.ok ? h('div', 'yes') : h('span', 'no')])
```

```jsx
<div>{this.ok ? <div>yes</div> : <span>no</span>}</div>
```

</div>

### `v-for` {#v-for}

Modelo de marcação:

```vue-html
<ul>
  <li v-for="{ id, text } in items" :key="id">
    {{ text }}
  </li>
</ul>
```

Função de interpretação ou JSX equivalente:

<div class="composition-api">

```js
h(
  'ul',
  // assumindo que `items` é uma referência com valor de arranjo
  items.value.map(({ id, text }) => {
    return h('li', { key: id }, text)
  })
)
```

```jsx
<ul>
  {items.value.map(({ id, text }) => {
    return <li key={id}>{text}</li>
  })}
</ul>
```

</div>
<div class="options-api">

```js
h(
  'ul',
  this.items.map(({ id, text }) => {
    return h('li', { key: id }, text)
  })
)
```

```jsx
<ul>
  {this.items.map(({ id, text }) => {
    return <li key={id}>{text}</li>
  })}
</ul>
```

</div>

### `v-on` {#v-on}

As propriedades com nomes que começam com `on` seguido por uma letra maiúscula são tratadas como ouvintes de evento. Por exemplo, `onClick` é o equivalente de `@click` nos modelos de marcação:

```js
h(
  'button',
  {
    onClick(event) {
      /* ... */
    }
  },
  'click me'
)
```

```jsx
<button
  onClick={(event) => {
    /* ... */
  }}
>
  click me
</button>
```

#### Modificadores de Evento {#event-modifiers}

Para os modificadores de evento `.passive`, `.capture`, `.once`, podem ser concatenados depois do nome de evento usando caixa de camelo.

Por exemplo:

```js
h('input', {
  onClickCapture() {
    /* ouvinte em mode de captura */
  },
  onKeyupOnce() {
    /* aciona apenas uma vez */
  },
  onMouseoverOnceCapture() {
    /* once + capture */
  }
})
```

```jsx
<input
  onClickCapture={() => {}}
  onKeyupOnce={() => {}}
  onMouseoverOnceCapture={() => {}}
/>
```

Para outros modificadores de chave e evento, o auxiliar [`withModifiers`](/api/render-function#withmodifiers) pode ser usado:

```js
import { withModifiers } from 'vue'

h('div', {
  onClick: withModifiers(() => {}, ['self'])
})
```

```jsx
<div onClick={withModifiers(() => {}, ['self'])} />
```

### Componentes {#components}

Para criar um nó de Vue para um componente, o primeiro argumento passado para `h()` deve ser a definição do componente. Isto significa que quando usamos funções de interpretação, é desnecessário registar componentes - podemos apenas usar os componentes importados diretamente:

```js
import Foo from './Foo.vue'
import Bar from './Bar.jsx'

function render() {
  return h('div', [h(Foo), h(Bar)])
}
```

```jsx
function render() {
  return (
    <div>
      <Foo />
      <Bar />
    </div>
  )
}
```

Conforme podemos ver, `h` pode trabalhar com os componentes importados a partir de qualquer formato de ficheiro enquanto for um componente de Vue válido.

Os componentes dinâmicos são diretos com as funções de interpretação:

```js
import Foo from './Foo.vue'
import Bar from './Bar.jsx'

function render() {
  return ok.value ? h(Foo) : h(Bar)
}
```

```jsx
function render() {
  return ok.value ? <Foo /> : <Bar />
}
```

Se um componente for registado pelo nome e não puder ser importado diretamente (por exemplo, registado globalmente por uma biblioteca), isto pode ser resolvido programaticamente usando a auxiliar [`resolveComponent()`](/api/render-function#resolvecomponent).

### Interpretando Ranhuras {#rendering-slots}

<div class="composition-api">

Nas funções de interpretação, as ranhuras podem ser acessadas a partir do contexto de `setup()`. Cada ranhura no objeto `slots` é uma **função que retorna um arranjo de nós de Vue**:

```js
export default {
  props: ['message'],
  setup(props, { slots }) {
    return () => [
      // ranhura padrão:
      // <div><slot /></div>
      h('div', slots.default()),

      // ranhura nomeada:
      // <div><slot name="footer" :text="message" /></div>
      h(
        'div',
        slots.footer({
          text: props.message
        })
      )
    ]
  }
}
```

Equivalente de JSX:

```jsx
// padrão
<div>{slots.default()}</div>

// nomeada
<div>{slots.footer({ text: props.message })}</div>
```

</div>
<div class="options-api">

Nas funções de interpretação, as ranhuras podem ser acessadas a partir da [`this.$slots`](/api/component-instance#slots):

```js
export default {
  props: ['message'],
  render() {
    return [
      // <div><slot /></div>
      h('div', this.$slots.default()),

      // <div><slot name="footer" :text="message" /></div>
      h(
        'div',
        this.$slots.footer({
          text: this.message
        })
      )
    ]
  }
}
```

Equivalente de JSX:

```jsx
// <div><slot /></div>
<div>{this.$slots.default()}</div>

// <div><slot name="footer" :text="message" /></div>
<div>{this.$slots.footer({ text: this.message })}</div>
```

</div>

### Passando Ranhuras {#passing-slots}

A passagem de filhos para os componentes funciona de maneira um pouco diferente da passagem de filhos para os elementos. No lugar dum arranjo, precisamos passar ou uma função de ranhura, ou um objeto de funções de ranhura. As funções de ranhura podem retornar qualquer coisa que uma função de interpretação normal pode retornar - o que sempre será normalizado para os arranjos de nós de Vue quando acessado no componente filho:

```js
// ranhura padrão única
h(MyComponent, () => 'hello')

// ranhuras nomeadas
// repara que o `null` é obrigatório para evitar
// que o objeto de ranhuras seja tratado como propriedade
h(MyComponent, null, {
  default: () => 'default slot',
  foo: () => h('div', 'foo'),
  bar: () => [h('span', 'one'), h('span', 'two')]
})
```

Equivalente de JSX:

```jsx
// padrão
<MyComponent>{() => 'hello'}</MyComponent>

// nomeado
<MyComponent>{{
  default: () => 'default slot',
  foo: () => <div>foo</div>,
  bar: () => [<span>one</span>, <span>two</span>]
}}</MyComponent>
```

Passar as ranhuras como funções as permite serem invocadas preguiçosamente pelo componente filho. Isto leva as dependências da ranhura a serem rastreadas pelo filho no lugar do pai, o que resulta em atualizações mais precisas e eficientes.

### Componentes Embutidos {#built-in-components}

Os [componentes embutidos](/api/built-in-components) tais como `<KeepAlive>`, `<Transition>`, `<TransitionGroup>`, `<Teleport>` e `<Suspense>` devem ser importados para uso nas funções de interpretação:

<div class="composition-api">

```js
import { h, KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'

export default {
  setup () {
    return () => h(Transition, { mode: 'out-in' }, /* ... */)
  }
}
```

</div>
<div class="options-api">

```js
import { h, KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'

export default {
  render () {
    return h(Transition, { mode: 'out-in' }, /* ... */)
  }
}
```

</div>

### `v-model` {#v-model}

A diretiva `v-model` é expandida para as propriedades `modelValue` e `onUpdate:modelValue` durante a compilação do modelo de marcação — teremos de fornecer estas propriedades nós mesmos:

<div class="composition-api">

```js
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  setup(props, { emit }) {
    return () =>
      h(SomeComponent, {
        modelValue: props.modelValue,
        'onUpdate:modelValue': (value) => emit('update:modelValue', value)
      })
  }
}
```

</div>
<div class="options-api">

```js
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  render() {
    return h(SomeComponent, {
      modelValue: this.modelValue,
      'onUpdate:modelValue': (value) => this.$emit('update:modelValue', value)
    })
  }
}
```

</div>

### Diretivas Personalizadas {#custom-directives}

As diretivas personalizadas podem ser aplicadas à um nó de Vue usando [`withDirectives`](/api/render-function#withdirectives):

```js
import { h, withDirectives } from 'vue'

// uma diretiva personalizada
const pin = {
  mounted() { /* ... */ },
  updated() { /* ... */ }
}

// <div v-pin:top.animate="200"></div>
const vnode = withDirectives(h('div'), [
  [pin, 200, 'top', { animate: true }]
])
```

Se a diretiva for registada pelo nome e puder ser importada diretamente, isto pode ser resolvido usando a auxiliar [`resolveDirective`](/api/render-function#resolvedirective).

### Referências do Modelo de Marcação {#template-refs}

<div class="composition-api">

Com a API de Composição, as referências do modelo de marcação são criadas passando a própria `ref()` como uma propriedade ao nó de Vue:

```js
import { h, ref } from 'vue'

export default {
  setup() {
    const divEl = ref()

    // <div ref="divEl">
    return () => h('div', { ref: divEl })
  }
}
```

</div>
<div class="options-api">

Com a API de Opções, as referências do modelo de marcação são criadas passando o nome da referência como uma sequência de caracteres nas propriedades do nó de Vue: 

```js
export default {
  render() {
    // <div ref="divEl">
    return h('div', { ref: 'divEl' })
  }
}
```

</div>

## Componentes Funcionais {#functional-components}

Os componentes funcionais são uma forma alternativa do componente que não tem nenhum estado por si mesmo. Eles agem como funções puras: propriedades entram, e nós de Vue saem. Eles são desenhados sem criar uma instância de componente (por exemplo, sem `this`), e sem os gatilhos do ciclo de vida do componente habitual.

Para criar um componente funcional usamos uma função simples, no lugar dum objeto de opções. A função é efetivamente a função `render` para o componente.

<div class="composition-api">

A assinatura dum componente funcional é a mesmo do gatilho `setup`:

```js
function MyComponent(props, { slots, emit, attrs }) {
  // ...
}
```

</div>
<div class="options-api">

Já que não existe referência de `this` para um componente funcional, a Vue passará as `props` como primeiro argumento:

```js
function MyComponent(props, context) {
  // ...
}
```

O segundo argumento, `context`, contém três propriedades: `attrs`, `emit` e `slots`. Existem equivalentes para as propriedades [`$attrs`](/api/component-instance#attrs), [`$emit`](/api/component-instance#emit), e [`$slots`](/api/component-instance#slots) da instância respetivamente.

</div>

A maioria das opções de configuração habitual para os componentes não estão disponíveis para os componentes funcionais. No entanto, é possível definir [`props`](/api/options-state#props) e [`emits`](/api/options-state#emits) adicionando-as como propriedades:

```js
MyComponent.props = ['value']
MyComponent.emits = ['click']
```

Se a opção `props` não for especificada, então o objeto `props` passado para a função função conterá todos os atributos, os mesmos que a `attrs`. Os nomes da propriedade não serão normalizados para caixa de camelo ao menos que a opção `props` seja especificada.

Para os componentes funcionais com `props` explicita, a [herança de atributo](/guide/components/attrs) funciona da mesmíssima maneira que os componentes normais. No entanto, para os componentes funcionais que não especificam explicitamente as suas `props`, apenas a `class`, `style` e ouvintes de evento `onXxx` serão herdados das `attrs` por padrão. Em ambos casos, `inheritAttrs` pode ser definido para `false` para desativar a herança de atributo:

```js
MyComponent.inheritAttrs = false
```

Os componentes funcionais podem ser registados e consumidos tal como os componentes normais. Se passarmos uma função como primeiro argumento para `h()`, será tratada como um componente funcional.

---

---
url: /guide/essentials/lifecycle.md
---
# Funções Gatilho do Ciclo de Vida {#lifecycle-hooks}

Cada instância do componente de Vue percorre uma série de etapas de inicialização quando for criado - por exemplo, este precisa definir a observação de dados, compilar o modelo de marcação, montar a instância ao DOM, e atualizar o DOM quando os dados mudarem. Pelo caminho, este também executa funções chamadas de funções gatilhos do ciclo de vida, dando aos utilizadores a oportunidade de adicionar o seu próprio código em estágios específicos.

## Registando Funções Gatilho do Ciclo de Vida {#registering-lifecycle-hooks}

Por exemplo, a função gatilho <span class="composition-api">`onMounted`</span><span class="options-api">`mounted`</span> pode ser usada para executar o código depois do componente ter terminado a interpretação inicial e criado os nós do DOM:

<div class="composition-api">

```vue
<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  console.log(`the component is now mounted.`)
})
</script>
```

</div>
<div class="options-api">

```js
export default {
  mounted() {
    console.log(`the component is now mounted.`)
  }
}
```

</div>

Também existem outras funções gatilhos que serão chamadas em diferentes estágios do ciclo de vida da instância, com as mais comummente usadas sendo <span class="composition-api">[`onMounted`](/api/composition-api-lifecycle#onmounted), [`onUpdated`](/api/composition-api-lifecycle#onupdated), e [`onUnmounted`](/api/composition-api-lifecycle#onunmounted).</span><span class="options-api">[`mounted`](/api/options-lifecycle#mounted), [`updated`](/api/options-lifecycle#updated), e [`unmounted`](/api/options-lifecycle#unmounted).</span>

<div class="options-api">

Todas as funções gatilhos do ciclo de vida são chamadas com o seu contexto de `this` apontando a instância ativa atualmente que estiver invocando-a. Nota que isto significa que devemos evitar usar funções flecha quando declaramos funções gatilhos do ciclo de vida, uma vez que não seremos capazes de acessar a instância do componente através da `this` se o fizermos.

</div>

<div class="composition-api">

Quando chamamos `onMounted`, a Vue associa automaticamente a função de resposta registada com a instância do componente ativo atualmente. Isto exige que estas funções gatilhos estejam registadas **de maneira síncrona** durante a definição do componente. Por exemplo, não devemos fazer isto:

```js
setTimeout(() => {
  onMounted(() => {
    // isto não funcionará.
  })
}, 100)
```

Reparemos que isto não significa que a chamada deve ser colocada de maneira léxica dentro da `setup()` ou `<script setup>`. A `onMounted()` pode ser chamada numa função externa enquanto a pilha de chamada for síncrona e surgir de dentro da `setup()`.

</div>

## Diagrama do Ciclo de Vida {#lifecycle-diagram}

Eis um diagrama do ciclo de vida da instância. Nós não precisamos entender completamente o que está acontecendo neste momento, mas a medida que aprendermos e construirmos mais, será uma referência útil:

![Diagrama do Ciclo de Vida do Componente](./images/lifecycle.png)

<!-- https://www.figma.com/file/Xw3UeNMOralY6NV7gSjWdS/Vue-Lifecycle -->

Consultar a <span class="composition-api">[referência da API das Funções Gatilhos do Ciclo de Vida](/api/composition-api-lifecycle)</span><span class="options-api">[referência da API das Funções Gatilhos do Ciclo de Vida](/api/options-lifecycle)</span> por detalhes sobre todas as funções gatilhos do ciclo de vida e seus respetivos casos de uso.

---

---
url: /guide/essentials/reactivity-fundamentals.md
---

# Fundamentos da Reatividade {#reactivity-fundamentals}

:::tip PREFERÊNCIA DE API
Esta página e muitos outros capítulos adiante neste guia contém conteúdo diferente para API de Opções e a API de Composição. Nossa preferência atual é a <span class="options-api">API de Opções</span><span class="composition-api">API de Composição</span>. Nós podemos alternar entre os estilos de API usando os interruptores de "Preferência de API" acima da barra lateral esquerda.
:::

<div class="options-api">

## Declarando Estado Reativo \* {#declaring-reactive-state}

Com a API de Opções, usamos a opção `data` para declarar o estado reativo dum componente. O valor da opção deve ser uma função que retorna um objeto. A Vue chamará a função quando criarmos uma nova instância de componente, e embrulha o objeto retornado no seu sistema de reatividade. Quaisquer propriedades de alto nível deste objeto são delegadas sobre a instância do componente (`this` nos métodos e funções gatilhos do ciclo de vida):

```js{2-6}
export default {
  data() {
    return {
      count: 1
    }
  },

  // `mounted` é uma função gatilho do
  // ciclo de vida que explicaremos depois
  mounted() {
    // `this` refere-se a instância do componente.
    console.log(this.count) // => 1

    // o dado também pode ser alterado
    this.count = 2
  }
}
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpFUNFqhDAQ/JXBpzsoHu2j3B2U/oYPpnGtoetGkrW2iP/eRFsPApthd2Zndilex7H8mqioimu0wY16r4W+Rx8ULXVmYsVSC9AaNafz/gcC6RTkHwHWT6IVnne85rI+1ZLr5YJmyG1qG7gIA3Yd2R/LhN77T8y9sz1mwuyYkXazcQI2SiHz/7iP3VlQexeb5KKjEKEe2lPyMIxeSBROohqxVO4E6yV6ppL9xykTy83tOQvd7tnzoZtDwhrBO2GYNFloYWLyxrzPPOi44WWLWUt618txvASUhhRCKSHgbZt2scKy7HfCujGOqWL9BVfOgyI=)

Estas propriedades da instância apenas são adicionadas depois da instância ser criada, então precisamos garantir que estas estão todas presentes no objeto retornado pela função `data`. Onde necessário, usamos `null`, `undefined` ou outros valores marcadores de posição para as propriedades onde o valor desejado ainda não estiver disponível.

É possível adicionar uma nova propriedade diretamente ao `this` sem a incluir na `data`. No entanto, as propriedades adicionadas desta maneira não serão capazes de acionar as atualizações reativas.

A Vue usa um prefixo `$` quando expõe suas próprias APIs embutidas através da instância do componente. Esta também reserva o prefixo `_` para as propriedades internas. Nós devemos evitar usar nomes para as propriedades `data` de alto nível que começam com qualquer um destes caracteres.

### Delegação Reativa vs Original \* {#reactive-proxy-vs-original}

Na Vue 3, os dados são tornados reativos influenciando as [Delegações da JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Os utilizadores vindo da Vue 2 devem estar cientes do seguinte caso extremo:

```js
export default {
  data() {
    return {
      someObject: {}
    }
  },
  mounted() {
    const newObject = {}
    this.someObject = newObject

    console.log(newObject === this.someObject) // false
  }
}
```

Quando acessamos `this.someObject` depois de atribuí-lo, o valor é uma delegação reativa do `newObject` original. **Diferente da Vue 2, o `newObject` original é deixado intacto e não será tornado reativo: devemos certificar-nos de acessar sempre o estado reativo como uma propriedade do `this`**.

</div>

<div class="composition-api">

## Declarando Estado Reativo \*\* {#declaring-reactive-state-1}

### `ref()` \*\* {#ref}

Na API de Composição, a maneira recomendada de declarar estado reativo é usando a função [`ref()`](/api/reactivity-core#ref):

```js
import { ref } from 'vue'

const count = ref(0)
```

A `ref()` recebe o argumento e retorna-o embrulhado dentro dum objeto de referência com uma propriedade `.value`:

```js
const count = ref(0)

console.log(count) // { value: 0 }
console.log(count.value) // 0

count.value++
console.log(count.value) // 1
```

> Consulte também: [Tipificando as Referências](/guide/typescript/composition-api#typing-ref) <sup class="vt-badge ts" />

Para acessarmos as referências no modelo de marcação dum componente, as declaramos e as retornamos a partir da função `setup()` dum componente:

```js{5,9-11}
import { ref } from 'vue'

export default {
  // `setup()` é uma função gatilho especial
  // dedicada a API de Composição.
  setup() {
    const count = ref(0)

    // expor a referência ao modelo de marcação
    return {
      count
    }
  }
}
``` 

```vue-html
<div>{{ count }}</div>
```

Repara que **não** precisamos anexar `.value` quando usamos a referência no modelo de marcação. Por conveniência, as referências são desembrulhadas automaticamente quando usadas dentro dos modelos de marcação (com algumas [advertências](#caveat-when-unwrapping-in-templates)).

Nós também podemos modificar a referência diretamente nos manipuladores de evento:

```vue-html
<button @click="count++">
  {{ count }}
</button>
```

Para lógica mais complexa, podemos declarar função que alteram as referências no mesmo âmbito de aplicação e as expor como métodos ao lado do estado:

```js{7-10,15}
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    function increment() {
      // `.value` é necessário na JavaScript
      count.value++
    }

    // não esqueçamos também de expor a função.
    return {
      count,
      increment
    }
  }
}
```

Os métodos expostos podem então ser usados como manipuladores de evento:

```vue-html
<button @click="increment">
  {{ count }}
</button>
```

Eis o exemplo ao vivo na [Codepen](https://codepen.io/vuejs-examples/pen/WNYbaqo), sem usar quaisquer ferramentas de construção.

### `<script setup>` \*\* {#script-setup}

Pode ser verboso expor manualmente o estado e os métodos através da `setup()`. Felizmente, isto pode ser evitado quando usamos [Componentes de Ficheiro Único](/guide/scaling-up/sfc). Nós podemos simplificar o uso com o `<script setup>`:

```vue{1}
<script setup>
import { ref } from 'vue'

const count = ref(0)

function increment() {
  count.value++
}
</script>

<template>
  <button @click="increment">
    {{ count }}
  </button>
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNo9jUEKgzAQRa8yZKMiaNcllvYe2dgwQqiZhDhxE3L3jrW4/DPvv1/UK8Zhz6juSm82uciwIef4MOR8DImhQMIFKiwpeGgEbQwZsoE2BhsyMUwH0d66475ksuwCgSOb0CNx20ExBCc77POase8NVUN6PBdlSwKjj+vMKAlAvzOzWJ52dfYzGXXpjPoBAKX856uopDGeFfnq8XKp+gWq4FAi)

As importações, variáveis, e funções de alto nível declaradas no `<script setup>` são automaticamente usáveis no modelo de marcação do mesmo componente. Pense no modelo de marcação como uma função de JavaScript declarada no mesmo âmbito de aplicação - esta naturalmente tem acesso a tudo que foi declarado ao seu lado.

:::tip NOTA
Para o resto do guia, usaremos primariamente a sintaxe de Componente de Ficheiro Único + `<script setup>` para os exemplos de código da API de Composição, uma vez que é o uso mais comum para os programadores de Vue.

Se não estivermos usando o Componente de Ficheiro Único, ainda podemos usar a API de Composição com a opção [`setup()`](/api/composition-api-setup).
::::

### Por que Referências? \*\* {#why-refs}

Nós podemos estar a perguntar-nos por que razão precisamos de referências com `.value` ao invés de variáveis simples. Para explicarmos isto, precisaremos discutir brevemente como o sistema de reatividade da Vue funciona.

Quando usamos uma referência num modelo de marcação, e mudamos o valor da referência em seguida, a Vue deteta automaticamente a mudança e atualiza o DOM por consequência. Isto é tornado possível com um rastreio de dependência baseado no sistema de reatividade. Quando um componente é desenhado pela primeira vez, a Vue **rastreia** toda referência que foi usada durante a interpretação. Mais tarde, quando uma referência for alterada, esta **acionará** uma reinterpretação dos componentes que a estiverem rastreando.

Na JavaScript padrão, não existe nenhuma maneira de detetar o acesso ou mutação das variáveis simples. No entanto, podemos intercetar as opções de recuperação e definição duma propriedade.

A propriedade `.value` dá à Vue a oportunidade de detetar quando uma referência foi acessada ou alterada. Nos bastidores, a Vue realiza o rastreio no seu recuperador, e realiza acionamento no seu definidor. Concetualmente, podemos pensar numa referência como um objeto que parece-se com isto:

```js
// pseudo-código, e não implementação verdadeira
const myRef = {
  _value: 0,
  get value() {
    track()
    return this._value
  },
  set value(newValue) {
    this._value = newValue
    trigger()
  }
}
```

Uma outra característica fantástica das referências é a que diferente das variáveis simples, podemos passar as referências às funções enquanto retemos o acesso ao valor mais recente e a conexão da reatividade. Isto é especialmente útil quando refazemos uma lógica complexa em código reutilizável.

O sistema de reatividade é discutido em mais detalhes na seção [Reatividade em Profundidade](/guide/extras/reactivity-in-depth).
</div>

<div class="options-api">

## Declarando Métodos \* {#declaring-methods}

<VueSchoolLink href="https://vueschool.io/lessons/methods-in-vue-3" title="Aula Gratuita Sobre Métodos de Vue.js"/>

Para adicionarmos métodos à instância dum componente usamos a opção `methods`. Esta deve ser um objeto contendo os métodos desejados:

```js{7-11}
export default {
  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  },
  mounted() {
    // os métodos podem ser chamados nas
    // funções gatilhos do ciclo de vida, ou noutros métodos!
    this.increment()
  }
}
```

A Vue vincula automaticamente o valor de `this` dos `methods` para que refira-se sempre à instância do componente. Isto garante que um método retém o valor de `this` correto se for usado como um ouvinte de evento ou função de resposta. Nós devemos evitar usar funções de flecha quando definimos `methods`, uma vez que estas impedem a Vue de vincular o valor de `this` apropriado:

```js
export default {
  methods: {
    increment: () => {
      // MAU: nenhum acesso ao `this` nesta declaração!
    }
  }
}
```

Tal como todas as outras propriedades da instância do componente, as propriedades de `methods` são acessíveis a partir de dentro do modelo de marcação do componente. Dentro dum modelo de marcação são comummente usadas como ouvintes de evento:

```vue-html
<button @click="increment">{{ count }}</button>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNplj9EKwyAMRX8l+LSx0e65uLL9hy+dZlTWqtg4BuK/z1baDgZicsPJgUR2d656B2QN45P02lErDH6c9QQKn10YCKIwAKqj7nAsPYBHCt6sCUDaYKiBS8lpLuk8/yNSb9XUrKg20uOIhnYXAPV6qhbF6fRvmOeodn6hfzwLKkx+vN5OyIFwdENHmBMAfwQia+AmBy1fV8E2gWBtjOUASInXBcxLvN4MLH0BCe1i4Q==)

No exemplo acima, o método `increment` será chamado quando o `<button>` for clicado.

</div>

### Reatividade Profunda {#deep-reactivity}

Na Vue, o estado é profundamente reativo por padrão. Isto significa que podemos esperar as mudanças serem detetadas mesmo quando alteramos os objetos e vetores encaixados:

<div class="options-api">

```js
export default {
  data() {
    return {
      obj: {
        nested: { count: 0 },
        arr: ['foo', 'bar']
      }
    }
  },
  methods: {
    mutateDeeply() {
      // estas funcionarão como o esperado.
      this.obj.nested.count++
      this.obj.arr.push('baz')
    }
  }
}
```

</div>

<div class="composition-api">

As referências podem segurar qualquer tipo de valor, incluindo objetos profundamente encaixados, vetores, ou estruturas de dados embutidas da JavaScript como a `Map`.

Uma referência tornará o seu valor profundamente reativo. Isto significa que podemos esperar as mudanças serem detetadas mesmo quando mudarmos os objetos ou vetores encaixados:

```js
import { ref } from 'vue'

const obj = ref({
  nested: { count: 0 },
  arr: ['foo', 'bar']
})

function mutateDeeply() {
  // estas funcionarão como esperado.
  obj.value.nested.count++
  obj.value.arr.push('baz')
}
```

Os valores não primitivos são transformados em delegações reativas através da [`reactive()`](#reactive), que é discutida abaixo.

Também é possível abandonar a reatividade profunda com as [referências superficiais](/api/reactivity-advanced#shallowref). Para as referências superficiais, apenas o acesso de `.value` é rastreado para reatividade. As referências superficiais podem ser usadas para otimização do desempenho evitando o custo de observação dos grandes objetos, ou em casos onde o estado interno é gerido por uma biblioteca externa.

Leitura avançada:

- [Custos de Reatividade Reduzido pelas Estruturas Imutáveis](/guide/best-practices/performance#reduce-reactivity-overhead-for-large-immutable-structures)
- [Integração com Sistemas de Estado Externos](/guide/extras/reactivity-in-depth#integration-with-external-state-systems)

</div>

### Tempo de Atualização do DOM {#dom-update-timing}

Quando alteramos o estado reativo, o DOM é atualizado automaticamente. No entanto, deve ser notado que as atualizações do DOM não são aplicadas de maneira síncrona. Ao invés disto, a Vue amortece-as até o "próximo tiquetaque" no ciclo de atualização para garantir que cada componente atualize-se apenas uma vez não importa quantas mudanças de estado fizemos.

Para aguardar-mos a atualização do DOM terminar depois duma mudança de estado, podemos usar a API global [`nextTick()`](/api/general#nexttick):

<div class="composition-api">

```js
import { nextTick } from 'vue'

async function increment() {
  state.count++
  await nextTick(() => {
    // Agora o DOM está atualizado
  })
}
```

</div>
<div class="options-api">

```js
import { nextTick } from 'vue'

export default {
  methods: {
    async increment() {
      this.count++
      await nextTick(() => {
        // Agora o DOM está atualizado
      })
    }
  }
}
```

</div>

<div class="composition-api">

## `reactive()` \*\* {#reactive}

Existe uma outra maneira de declarar o estado reativo, com a API `reactive()`. Ao contrário duma referência que embrulha o valor interno num objeto especial, a `reactive()` torna um objeto reativo:

```js
import { reactive } from 'vue'

const state = reactive({ count: 0 })
```

> Consulte também: [Tipificando a Função  `reactive`](/guide/typescript/composition-api#typing-reactive) <sup class="vt-badge ts" />

Uso no modelo de marcação:

```vue-html
<button @click="state.count++">
  {{ state.count }}
</button>
```

Os objetos reativos são [Delegações de JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) e comportam-se como objetos normais. A diferença é que a Vue é capaz de intercetar o acesso e mutação de todas as propriedades dum objeto reativo para rastreio e acionamento da reatividade.

`reactive()` converte o objeto profundamente: os objetos encaixados também são embrulhados com a `reactive()` quando acessados. Esta também é chamada pela `ref()` internamente quando o valor da referência for um objeto. Semelhante às referências superficiais, existe também a API [`shallowReactive()`](/api/reactivity-advanced#shallowreactive) para abandonar a reatividade profunda.

### Delegação Reativa vs. Original \*\* {#reactive-proxy-vs-original-1}

É importante notar que o valor retornado a partir da `reactive()` é uma [Delegação](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) do objeto original, a qual não é igual ao objeto original:

```js
const raw = {}
const proxy = reactive(raw)

// a delegação NÃO é igual ao original.
console.log(proxy === raw) // false
```

Apenas a delegação é reativa - alterar o objeto original não acionará atualizações. Portanto, a boa prática quando trabalhamos com o sistema de reatividade da Vue é **usar exclusivamente as versões delegadas do nosso estado**.

Para garantir o acesso consistente à delegação, chamar `reactive()` sobre o mesmo objeto sempre retorna a mesma delegação, e chamar `reactive()` sobre uma delegação existente também retorna a mesma delegação:

```js
// chamar `reactive()` sobre o mesmo objeto
// retorna a mesma delegação
console.log(reactive(raw) === proxy) // true

// chamar `reactive()` sobre uma delegação
// retorna a si mesma
console.log(reactive(proxy) === proxy) // true
```

Este regra também aplica-se aos objetos encaixados. Por causa da reatividade profunda, os objetos encaixados dentro dum objeto reativo também são delegações:

```js
const proxy = reactive({})

const raw = {}
proxy.nested = raw

console.log(proxy.nested === raw) // false
```

### Limitações da `reactive()` \*\* {#limitations-of-reactive}

A API de `reactive()` tem algumas limitações:

1. **Tipos de valores limitados**: apenas funciona para os tipos de objetos (objetos, vetores, e [tipos de coleção](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects#keyed_collections) tais como `Map` e `Set`). Esta não pode segurar [tipos primitivos](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) tais como `string`, `number`, ou `boolean`.

2. **Não é possível substituir um objeto inteiro**: uma vez que o rastreio da reatividade da Vue funciona sobre o acesso de propriedade, sempre devemos manter a mesma referência ao objeto reativo. Isto significa que não podemos "substituir" facilmente um objeto reativo porque a conexão da reatividade à primeira referência é perdida:

   ```js
   let state = reactive({ count: 0 })

   // a referência acima ({ count: 0 }) já não está sendo rastreada
   // (conexão da reatividade está perdida!)
   state = reactive({ count: 1 })
   ```

3. **Não é amigável à desestruturação**: quando desestruturamos a propriedade de tipo primitivo dum objeto reativo em variáveis locais, ou quando passamos esta propriedade à uma função, perderemos a conexão da reatividade:

   ```js
   const state = reactive({ count: 0 })

   // `count` é desconectada de `state.count` quando desestruturada.
   let { count } = state.count
   // não afeta o estado original
   count++

   // a função recebe um número simples e
   // não será capaz de rastrear as mudanças para `state.count`
   // temos de passar o objeto inteiro para manter a reatividade
   callSomeFunction(state.count)
   ```

Por causa destas limitações, recomendados usar `ref()` como API primária  para declarar o estado reativo.

## Detalhes Adicionais do Desembrulho de Referência \*\* {#additional-ref-unwrapping-details}

### Como Propriedade de Objeto Reativo \*\* {#ref-unwrapping-as-reactive-object-property}

Uma referência é automaticamente desembrulhada quando acessada ou alterada como uma propriedade dum objeto reativo. Em outras palavras, comporta-se como uma propriedade normal:

```js
const count = ref(0)
const state = reactive({
  count
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1
```

Se uma nova referência for atribuída à uma propriedade ligada à uma referência existente, esta substituirá a referência antiga:

```js
const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
// a referência original agora está desconectada da `state.count`
console.log(count.value)
```

O desembrulho de referência apenas acontece quando encaixada dentro dum objeto reativo profundo. Não se aplica quando é acessada como uma propriedade dum [objeto reativo superficial](/api/reactivity-advanced#shallowreactive).

### Advertências nos Vetores e Coleções \*\* {#caveat-in-arrays-and-collections}

Ao contrário dos objetos reativos, **não é efetuado** nenhum desembrulho quando a referência é acessada como um elemento dum vetor reativo ou um tipo de coleção nativa como `Map`:

```js
const books = reactive([ref('Vue 3 Guide')])
// neste caso precisamos de `.value`
console.log(books[0].value)

const map = reactive(new Map([['count', ref(0)]]))
// neste caso precisamos de `.value`
console.log(map.get('count').value)
```

### Advertências Quando Desembrulhamos nos Modelos de Marcação \*\* {#caveat-when-unwrapping-in-templates}

O desembrulho de referência nos modelos de marcação apenas aplica-se se a referência for uma propriedade de alto nível no contexto de interpretação do modelo de marcação.

No exemplo abaixo, `count` e `object` são propriedades de alto nível, mas `object.id` não:

```js
const count = ref(0)
const object = { id: ref(0) }
```

Portanto, esta expressão funciona como esperado:

```vue-html
{{ count + 1 }}
```

...enquanto esta **NÃO**:

```vue-html
{{ object.id + 1 }}
```

O resultado desenhado será `[object Object]1` uma vez que `object.id` não é desembrulhado quando avaliamos a expressão e continua um objeto de referência. Para corrigir isto, podemos desestruturar `id` à uma propriedade de alto nível:

```js
const { id } = object
```

```vue-html
{{ id + 1 }}
```

Agora o resultado da interpretação será `2`.

Um outra coisa à notar é que uma referência é desembrulhada se for o valor avaliado final duma interpolação de texto (por exemplo, um marcador <code v-pre>{{ }}</code>, então o seguinte exemplo desenhará `1`):

```vue-html
{{ object.id }}
```

Isto é apenas um funcionalidade de conveniência da interpolação de texto e é equivalente ao <code v-pre>{{ object.id.value }}</code>.

</div>

<div class="options-api">

### Métodos com Estado \* {#stateful-methods}

Em alguns casos, podemos precisar criar dinamicamente uma função de método, por exemplo, criando um manipulador de evento de chamada reduzida:

```js
import { debounce } from 'lodash-es'

export default {
  methods: {
    // Reduzir chamadas com a Lodash
    click: debounce(function () {
     // ... responde ao clique ...
    }, 500)
  }
}
```

No entanto, esta abordagem é problemática porque os componentes que são reutilizados porque uma função de chamada reduzida **tem estado**: esta mantém algum estado interno sobre o tempo decorrido. Se várias instância do componente partilharem a mesma função de chamada reduzida, interferirão umas com as outras.

Para manter a função de chamada reduzida de cada instância do componente independente das outras, podemos criar uma versão de chamada reduzida na função gatilho do ciclo de vida `created`:

```js
export default {
  created() {
    // agora cada instância tem sua própria cópia do
    // manipulador de chamada reduzida
    this.debouncedClick = _.debounce(this.click, 500)
  },
  unmounted() {
    // também é uma boa ideia cancelar o temporizador
    // quando o componente for removido
    this.debouncedClick.cancel()
  },
  methods: {
    click() {
     // ... responder ao clique ...
    }
  }
}
```
</div>

---

---
url: /guide/essentials/component-basics.md
---
# Fundamentos dos Componentes {#components-basics}

Os componentes permitem-nos separar os elementos da interface em pedaços independentes e reutilizáveis, e pensar sobre cada pedaço em isolamento. É comum para uma aplicação ser organizada numa árvore de componentes encaixados:

![Árvore de Componente](./images/components.png)

<!-- https://www.figma.com/file/qa7WHDQRWuEZNRs7iZRZSI/components -->

Isto é muito semelhante a como encaixamos os elementos de HTML nativos, mas a Vue implementa o seu próprio modelo de componente que permite-nos encapsular o conteúdo personalizado e a lógica em cada componente. A Vue também lida muito bem com os Componentes da Web nativos. Se estivermos curiosos sobre a relação entre os Componentes da Vue e os Componentes da Web nativos, [podemos ler mais sobre isto neste artigo](/guide/extras/web-components).

## Definindo um Componente {#defining-a-component}

Quando usamos uma etapa de construção, normalmente definimos cada componente num ficheiro dedicado usando a extensão `.vue` - conhecido como [Componente de Ficheiro Único](/guide/scaling-up/sfc) (SFC, que é a forma abreviada no idioma original):

<div class="options-api">

```vue
<script>
export default {
  data() {
    return {
      count: 0
    }
  }
}
</script>

<template>
  <button @click="count++">You clicked me {{ count }} times.</button>
</template>
```

</div>
<div class="composition-api">

```vue
<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">You clicked me {{ count }} times.</button>
</template>
```

</div>

Quando não usamos uma etapa de construção, um componente da Vue pode ser definido como um simples objeto de JavaScript contendo opções específicas da Vue: 

<div class="options-api">

```js
export default {
  data() {
    return {
      count: 0
    }
  },
  template: `
    <button @click="count++">
      You clicked me {{ count }} times.
    </button>`
}
```

</div>
<div class="composition-api">

```js
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)
    return { count }
  },
  template: `
    <button @click="count++">
      You clicked me {{ count }} times.
    </button>`
  // Também pode mirar um modelo de marcação no DOM:
  // template: '#my-template-element'
}
```

</div>

Neste exemplo o modelo de marcação é incorporado como uma sequência de caracteres de JavaScript, a qual a Vue compilará rapidamente. Nós também podemos usar um seletor de identificador único apontando para um elemento (normalmente elementos `<template>` nativos) - a Vue usará o seu conteúdo como fonte do modelo de marcação.

O exemplo acima define um único componente e exporta-o como exportação padrão dum ficheiro `.js`, mas podemos usar exportações nomeadas para exportar vários componentes a partir do mesmo ficheiro.

## Usando um Componente {#using-a-component}

:::tip NOTA
Nós usaremos a sintaxe de SFC para o resto deste guia - os conceitos em torno dos componentes são os mesmos independentemente de se estivermos usando uma etapa de construção ou não. A seção dos [Exemplos](/examples/) mostra o uso do componente em ambos cenários.
:::

Para usarmos um componente filho, precisamos de importá-lo no componente pai. Assumindo que colocamos o nosso componente contador dentro dum ficheiro chamado `ButtonCounter.vue`, o componente será exposto como exportação padrão do ficheiro:

<div class="options-api">

```vue
<script>
import ButtonCounter from './ButtonCounter.vue'

export default {
  components: {
    ButtonCounter
  }
}
</script>

<template>
  <h1>Here is a child component!</h1>
  <ButtonCounter />
</template>
```

Para expormos o componente importado ao nosso modelo de marcação, precisamos [registá-lo](/guide/components/registration) com a opção `components`. O componente estará então disponível como um marcador usando a chave sob a qual está registado.

</div>

<div class="composition-api">

```vue
<script setup>
import ButtonCounter from './ButtonCounter.vue'
</script>

<template>
  <h1>Here is a child component!</h1>
  <ButtonCounter />
</template>
```

Com o `<script setup>`, os componentes importados são disponibilizados automaticamente ao modelo de marcação.

</div>

Também é possível registar um componente globalmente, tornando-o disponível para todos os componentes numa dada aplicação sem ter de importá-lo. As vantagens e inconvenientes do registo global contra o registo local é discutido na seção de [Registo de Componente](/guide/components/registration) dedicada.

Os componentes podem ser reutilizados quantas vezes quisermos:

```vue-html
<h1>Here are many child components!</h1>
<ButtonCounter />
<ButtonCounter />
<ButtonCounter />
```

<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqVUE1LxDAQ/StjLqusNHotcfHj4l8QcontLBtsJiGdiFL6301SdrEqyEJyeG9m3ps3k3gIoXlPKFqhxi7awDtN1gUfGR4Ts6cnn4gxwj56B5tGrtgyutEEoAk/6lCPe5MGhqmwnc9KhMRjuxCwFi3UrCk/JU/uGTC6MBjGglgdbnfPGBFM/s7QJ3QHO/TfxC+UzD21d72zPItU8uQrrsWvnKsT/ZW2N2wur45BI3KKdETlFlmphZsF58j/RgdQr3UJuO8G273daVFFtlstahngxSeoNezBIUzTYgPzDGwdjk1VkYvMj4jzF0nwsyQ=)

</div>
<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqVj91KAzEQhV/lmJsqlY3eSlr8ufEVhNys6ZQGNz8kE0GWfXez2SJUsdCLuZiZM9+ZM4qnGLvPQuJBqGySjYxMXOJWe+tiSIznwhz8SyieKWGfgsOqkyfTGbDSXsmFUG9rw+Ti0DPNHavD/faVEqGv5Xr/BXOwww4mVBNPnvOVklXTtKeO8qKhkj++4lb8+fL/mCMS7TEdAy6BtDfBZ65fVgA2s+L67uZMUEC9N0s8msGaj40W7Xa91qKtgbdQ0Ha0gyOM45E+TWDrKHeNIhfMr0DTN4U0me8=)

</div>

Repara que quando clicamos sobre os botões, cada um mantém o seu próprio `count` separado. Isto porque cada vez que usarmos um componente, uma nova **instância** do mesmo é criada.

Nos componentes de ficheiro único, é recomendado usar os nomes de marcadores em `PascalCase` para os componentes filhos para diferenciá-los dos elementos de HTML nativos. Apesar dos nomes dos marcadores de HTML nativos serem insensíveis a caracteres maiúsculos e minúsculos, o componente de ficheiro único da Vue é um formato compilado então somos capazes de usar nomes de marcadores sensíveis a caracteres maiúsculos e minúsculos nele. Nós também somos capazes de usar `/>` para fechar um marcador.

Se estivermos escrevendo os nossos modelos de marcação diretamente no DOM (por exemplo, como conteúdo dum elemento `<template>` nativo), o modelo de marcação estará sujeito ao comportamento de analise sintática de HTML nativo do navegador. Em tais casos, precisaremos usar `kebab-case` e fechar explicitamente os marcadores dos componentes:

```vue-html
<!-- se este modelo de marcação for escrito no DOM -->
<button-counter></button-counter>
<button-counter></button-counter>
<button-counter></button-counter>
```

Consulte as [Advertências da Analise Sintática do Modelo de Marcação no DOM](#in-dom-template-parsing-caveats) por mais detalhes.

## Passando as Propriedades {#passing-props}

Se estivermos construindo um blogue, precisaremos possivelmente dum componente representando uma publicação de blogue. Nós queremos que todas as publicações de blogue partilhem a mesma disposição visual, mas com conteúdo diferente. Tal componente não será útil a menos que possamos passar dados a este, tais como o título e conteúdo da publicação específica que queremos exibir. É onde as propriedades entram.

As propriedades são atributos personalizados que podemos registar sobre um componente. Para passarmos um título ao nosso componente de publicação de blogue, devemos declará-lo na lista de propriedades que este componente aceita, usando a <span class="options-api">opção [`props`](/api/options-state#props)</span><span class="composition-api">macro [`defineProps`](/api/sfc-script-setup#defineprops-defineemits)</span>:

<div class="options-api">

```vue
<!-- BlogPost.vue -->
<script>
export default {
  props: ['title']
}
</script>

<template>
  <h4>{{ title }}</h4>
</template>
```

Quando um valor for passado a um atributo da propriedade, este torna-se uma propriedade sobre a instância deste componente. O valor desta propriedade é acessível dentro do modelo de marcação e sobre o conteúdo `this` do componente, tal como qualquer outra propriedade do componente.

</div>
<div class="composition-api">

```vue
<!-- BlogPost.vue -->
<script setup>
defineProps(['title'])
</script>

<template>
  <h4>{{ title }}</h4>
</template>
```

A `defineProps` é uma macro do momento da compilação que apenas está disponível dentro do `<script setup>` e não precisa de ser explicitamente importada. As propriedades declaradas são automaticamente expostas ao modelo de marcação. A `defineProps` também retorna um objeto que contém todas as propriedades passadas ao componente, para que possamos acessá-las na JavaScript se necessário:

```js
const props = defineProps(['title'])
console.log(props.title)
```

Consulte também: [Tipificando as Propriedades do Componente](/guide/typescript/composition-api#typing-component-props) <sup class="vt-badge ts" />

Se não estivermos usando o `<script setup>`, as propriedades devem ser declaradas usando a opção `props`, e o objeto de `props` será passado à `setup()` como primeiro argumento:

```js
export default {
  props: ['title'],
  setup(props) {
    console.log(props.title)
  }
}
```

</div>

Um componente pode ter quantas propriedades acharmos conveniente, por padrão, qualquer valor pode ser passado a qualquer propriedade.

Depois duma propriedade ser registada, podemos passar os dados à esta como um atributo personalizado, desta maneira:

```vue-html
<BlogPost title="My journey with Vue" />
<BlogPost title="Blogging with Vue" />
<BlogPost title="Why Vue is so fun" />
```

Numa aplicação normal, no entanto, possivelmente teremos um vetor de publicações no nosso componente pai:

<div class="options-api">

```js
export default {
  // ...
  data() {
    return {
      posts: [
        { id: 1, title: 'My journey with Vue' },
        { id: 2, title: 'Blogging with Vue' },
        { id: 3, title: 'Why Vue is so fun' }
      ]
    }
  }
}
```

</div>
<div class="composition-api">

```js
const posts = ref([
  { id: 1, title: 'My journey with Vue' },
  { id: 2, title: 'Blogging with Vue' },
  { id: 3, title: 'Why Vue is so fun' }
])
```

</div>

Então desejaremos interpretar um componente para cada uma, usando `v-for`:

```vue-html
<BlogPost
  v-for="post in posts"
  :key="post.id"
  :title="post.title"
 />
```

<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9UU1rhDAU/CtDLrawVfpxklRo74We2kPtQdaoaTUJ8bmtiP+9ia6uC2VBgjOZeXnz3sCejAkPnWAx4+3eSkNJqmRjtCU817p81S2hsLpBEEYL4Q1BqoBUid9Jmosi62rC4Nm9dn4lFLXxTGAt5dG482eeUXZ1vdxbQZ1VCwKM0zr3x4KBATKPcbsDSapFjOClx5d2JtHjR1KFN9fTsfbWcXdy+CZKqcqL+vuT/r3qvQqyRatRdMrpF/nn/DNhd7iPR+v8HCDRmDoj4RHxbfyUDjeFto8p8yEh1Rw2ZV4JxN+iP96FMvest8RTTws/gdmQ8HUr7ikere+yHduu62y//y3NWG38xIOpeODyXcoE8OohGYZ5VhhHHjl83sD4B3XgyGI=)

</div>
<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9kU9PhDAUxL/KpBfWBCH+OZEuid5N9qSHrQezFKhC27RlDSF8d1tYQBP1+N78OpN5HciD1sm54yQj1J6M0A6Wu07nTIpWK+MwwPASI0qjWkQejVbpsVHVQVl30ZJ0WQRHjwFMnpT0gPZLi32w2h2DMEAUGW5iOOEaniF66vGuOiN5j0/hajx7B4zxxt5ubIiphKz+IO828qXugw5hYRXKTnqSydcrJmk61/VF/eB4q5s3x8Pk6FJjauDO16Uye0ZCBwg5d2EkkED2wfuLlogibMOTbMpf9tMwP8jpeiMfRdM1l8Tk+/F++Y6Cl0Lyg1Ha7o7R5Bn9WwSg9X0+DPMxMI409fPP1PELlVmwdQ==)

</div>

Repara como a [sintaxe de `v-bind`](/api/built-in-directives#v-bind) (`:title="post.title"`) é usada para passar os valores dinâmicos da propriedade. Isto é especialmente útil quando não sabemos antecipadamente qual é o exato conteúdo que iremos interpretar.

É tudo o que precisamos saber sobre as propriedades por agora, mas depois de terminarmos a leitura desta página e estivermos confortáveis com o seu conteúdo, recomendamos voltar mais tarde para ler o guia completo sobre as [Propriedades](/guide/components/props).

## Ouvindo Eventos {#listening-to-events}

Conforme desenvolvermos o nosso componente `<BlogPost>`, algumas funcionalidades podem precisar de comunicarem-se de volta ao componente pai. Por exemplo, podemos decidir incluir uma funcionalidade de acessibilidade para ampliar o texto das publicações de blogue, enquanto deixamos o resto da página no seu tamanho padrão.

No componente pai, podemos suportar esta funcionalidade adicionando uma <span class="options-api">propriedade de dados</span><span class="composition-api">referência</span> `postFontSize`:

<div class="options-api">

```js{6}
data() {
  return {
    posts: [
      /* ... */
    ],
    postFontSize: 1
  }
}
```

</div>
<div class="composition-api">

```js{5}
const posts = ref([
  /* ... */
])

const postFontSize = ref(1)
```

</div>

A qual pode ser usada no modelo de marcação para controlar o tamanho da fonte de todas as publicações de blogue:

```vue-html{1,7}
<div :style="{ fontSize: postFontSize + 'em' }">
  <BlogPost
    v-for="post in posts"
    :key="post.id"
    :title="post.title"
   />
</div>
```

Agora adicionaremos um botão ao modelo de marcação do componente `<BlogPost>`:

```vue{5}
<!-- BlogPost.vue, omitindo <script> -->
<template>
  <div class="blog-post">
    <h4>{{ title }}</h4>
    <button>Enlarge text</button>
  </div>
</template>
```

O botão ainda não faz nada - queremos clicar sobre o botão para comunicar ao pai que este deve ampliar o tamanho da fonte do texto de todas as publicações. Para solucionarmos este problema, os componentes fornecem um sistema de eventos personalizados. O pai pode escolher ouvir qualquer evento sobre a instância do componente filho com a `v-on` ou `@`, tal como faríamos com um evento de DOM nativo:

```vue-html{3}
<BlogPost
  ...
  @enlarge-text="postFontSize += 0.1"
 />
```

Então o componente filho pode emitir um evento sobre si mesmo chamando o [método **`$emit`**](/api/component-instance#emit) embutido, passando o nome do evento:

```vue{5}
<!-- BlogPost.vue, omitindo <script> -->
<template>
  <div class="blog-post">
    <h4>{{ title }}</h4>
    <button @click="$emit('enlarge-text')">Enlarge text</button>
  </div>
</template>
```

Graças ao ouvinte `@enlarge-text="postFontSize += 0.1"`, o pai receberá o evento e atualizará o valor da `postFontSize`.

<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNUsFOg0AQ/ZUJMaGNbbHqidCmmujNxMRED9IDhYWuhV0CQy0S/t1ZYIEmaiRkw8y8N/vmMZVxl6aLY8EM23ByP+Mprl3Bk1RmCPexjJ5ljhBmMgFzYemEIpiuAHAFOzXQgIVeESNUKutL4gsmMLfbBPStVFTP1Bl46E2mup4xLDKhI4CUsMR+1zFABTywYTkD5BgzG8ynEj4kkVgJnxz38Eqaut5jxvXAUCIiLqI/8TcD/m1fKhTwHHIJYSEIr+HbnqikPkqBL/yLSMs23eDooNexel8pQJaksYeMIgAn4EewcyxjtnKNCsK+zbgpXILJEnW30bCIN7ZTPcd5KDNqoWjARWufa+iyfWBlV13wYJRvJtWVJhiKGyZiL4vYHNkJO8wgaQVXi6UGr51+Ndq5LBqMvhyrH9eYGePtOVu3n3YozWSqFsBsVJmt3SzhzVaYY2nm9l82+7GX5zTGjlTM1SyNmy5SeX+7rqr2r0NdOxbFXWVXIEoBGz/m/oHIF0rB5Pz6KTV6aBOgEo7Vsn51ov4GgAAf2A==)

</div>
<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1Uk1PwkAQ/SuTxqQYgYp6ahaiJngzITHRA/UAZQor7W7TnaK16X93th8UEuHEvPdm5s3bls5Tmo4POTq+I0yYyZTAIOXpLFAySXVGUEKGEVQQZToBl6XukXqO9XahDbXc2OsAO5FlAIEKtWJByqCBqR01WFqiBLnxYTIEkhSjD+5rAV86zxQW8C1pB+88Aaphr73rtXbNVqrtBeV9r/zYFZYHacBoiHLFykB9Xgfq1NmLVvQmf7E1OGFaeE0anAMXhEkarwhtRWIjD+AbKmKcBk4JUdvtn8+6ARcTu87hLuCf6NJpSoDDKNIZj7BtIFUTUuB0tL/HomXHcnOC18d1TF305COqeJVtcUT4Q62mtzSF2/GkE8/E8b1qh8Ljw/if8I7nOkPn9En/+Ug2GEmFi0ynZrB0azOujbfB54kki5+aqumL8bING28Yr4xh+2vePrI39CnuHmZl2TwwVJXwuG6ZdU6kFTyGsQz33HyFvH5wvvyaB80bACwgvKbrYgLVH979DQc=)

</div>

Nós podemos opcionalmente declarar os eventos emitidos usando a <span class="options-api">opção [`emits`](/api/options-state#emits)</span><span class="composition-api">macro [`defineEmits`](/api/sfc-script-setup#defineprops-defineemits)</span>:

<div class="options-api">

```vue{5}
<!-- BlogPost.vue -->
<script>
export default {
  props: ['title'],
  emits: ['enlarge-text']
}
</script>
```

</div>
<div class="composition-api">

```vue{4}
<!-- BlogPost.vue -->
<script setup>
defineProps(['title'])
defineEmits(['enlarge-text'])
</script>
```

</div>

Isto documenta todos os eventos que um componente emite e [valida-os](/guide/components/events#events-validation) opcionalmente. Também permite a Vue evitar aplicá-los implicitamente como ouvintes nativos ao elemento de raiz do componente filho.

<div class="composition-api">

Semelhante à `defineProps`, a `defineEmits` apenas é utilizável no `<script setup>` e não precisa de ser importada. Esta retorna uma função `emit` que é equivalente ao método `$emit`. Esta pode ser usada para emitir eventos na seção `<script setup>` dum componente, onde `$emit` não está diretamente acessível:

```vue
<script setup>
const emit = defineEmits(['enlarge-text'])

emit('enlarge-text')
</script>
```

Consulte também: [Tipificando as Emissões do Componente](/guide/typescript/composition-api#typing-component-emits) <sup class="vt-badge ts" />

Se não estivermos usando o `<script setup>`, podemos declarar os eventos emitidos usando a opção `emits`. Nós podemos acessar a função `emit` como uma propriedade do contexto de configuração (passada à `setup()` como segundo argumento):

```js
export default {
  emits: ['enlarge-text'],
  setup(props, ctx) {
    ctx.emit('enlarge-text')
  }
}
```

</div>

É tudo que precisamos saber sobre os eventos personalizados dos componentes por agora, mas depois que terminarmos a leitura desta página e estivermos confortáveis como o seu conteúdo, recomendamos voltar para ler o guia completa sobre os [Eventos Personalizados](/guide/components/events).

## Distribuição de Conteúdo com as Ranhuras {#content-distribution-with-slots}

Tal como com os elementos de HTML, é muitas vezes útil ser capaz de passar conteúdo para um componente, desta maneira:

```vue-html
<AlertBox>
  Something bad happened.
</AlertBox>
```

O qual pode interpretar alguma coisa do tipo:

:::danger ISTO É UM ERRO PARA FINS DE DEMONSTRAÇÃO
Something bad happened.
:::

Isto pode ser alcançado usando o elemento `<slot>` personalizado da Vue:

```vue{4}
<template>
  <div class="alert-box">
    <strong>This is an Error for Demo Purposes</strong>
    <slot />
  </div>
</template>

<style scoped>
.alert-box {
  /* ... */
}
</style>
```

Conforme veremos acima, usamos `<slot>` como uma reserva de espaço de onde queremos que conteúdo seja interpretado - e é isto. Terminamos!

<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpVUcFOwzAM/RUTDruwFhCaUCmThsQXcO0lbbKtIo0jx52Kpv07TreWouTynl+en52z2oWQnXqrClXGhtrA28q3XUBi2DlL/IED7Ak7WGX5RKQHq8oDVN4Oo9TYve4dwzmxDcp7bz3HAs5/LpfKyy3zuY0Atl1wmm1CXE5SQeLNX9hZPrb+ALU2cNQhWG9NNkrnLKIt89lGPahlyDTVogVAadoTNE7H+F4pnZTrGodKjUUpRyb0h+0nEdKdRL3CW7GmfNY5ZLiiMhfP/ynG0SL/OAuxwWCNMNncbVqSQyrgfrPZvCVcIxkrxFMYIKJrDZA1i8qatGl72ehLGEY6aGNkNwU8P96YWjffB8Lem/Xkvn9NR6qy+fRd14FSgopvmtQmzTT9Toq9VZdfIpa5jQ==)

</div>
<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpVUEtOwzAQvcpgFt3QBBCqUAiRisQJ2GbjxG4a4Xis8aQKqnp37PyUyqv3mZn3fBVH55JLr0Umcl9T6xi85t4VpW07h8RwNJr4Cwc4EXawS9KFiGO70ubpNBcmAmDdOSNZR8T5Yg0IoOQf7DSfW9tAJRWcpXPaapWM1nVt8ObpukY8ie29GHNzAiBX7QVqI73/LIWMzn2FQylGMcieCW1TfBMhPYSoE5zFitLVZ5BhQnkadt6nGKt5/jMafI1Oq8Ak6zW4xrEaDVIGj4fD4SPiCknpQLy4ATyaVgFptVH2JFXb+wze3DDSTioV/iaD1+eZqWT92xD2Vu2X7af3+IJ6G7/UToVigpJnTzwTO42eWDnELsTtH/wUqH4=)

</div>

É tudo o que precisamos saber sobre as ranhuras por agora, mas depois de terminarmos a leitura desta página e estivermos confortáveis com o seu conteúdo, recomendamos voltar mais tarde para ler o guia completo sobre as [Ranhuras](/guide/components/slots).

## Componentes Dinâmicos {#dynamic-components}

Algumas vezes é útil alternar dinamicamente entre os componentes, como numa interface composta por abas:

<div class="options-api">

[Abrir o exemplo na Zona de Testes](https://play.vuejs.org/#eNqNVE2PmzAQ/Ssj9kArLSHbrXpwk1X31mMPvS17cIxJrICNbJMmivLfO/7AEG2jRiDkefP85sNmztlr3y8OA89ItjJMi96+VFJ0vdIWfqqOQ6NVB/midIYj5sn9Sxlrkt9b14RXzXbiMElEO5IAKsmPnljzhg6thbNDmcLdkktrSADAJ/IYlj5MXEc9Z1w8VFNLP30ed2luBy1HC4UHrVH2N90QyJ1kHnUALN1gtLeIQu6juEUMkb8H5sXHqiS+qzK1Cw3Lu76llqMFsKrFAVhLjVlXWc07VWUeR89msFbhhhAWDkWjNJIwPgjp06iy5CV7fgrOOTgKv+XoKIIgpnoGyiymSmZ1wnq9dqJweZ8p/GCtYHtUmBMdLXFitgDnc9ju68b0yxDO1WzRTEcFRLiUJsEqSw3wwi+rMpFDj0psEq5W5ax1aBp7at1y4foWzq5R0hYN7UR7ImCoNIXhWjTfnW+jdM01gaf+CEa1ooYHzvnMVWhaiwEP90t/9HBP61rILQJL3POMHw93VG+FLKzqUYx3c2yjsOaOwNeRO2B8zKHlzBKQWJNH1YHrplV/iiMBOliFILYNK5mOKdSTMviGCTyNojFdTKBoeWNT3s8f/Vpsd7cIV61gjHkXnotR6OqVkJbrQKdsv9VqkDWBh2bpnn8VXaDcHPexE4wFzsojO9eDUOSVPF+65wN/EW7sHRsi5XaFqaexn+EH9Xcpe8zG2eWG3O0/NVzUaeJMk+jGhUXlNPXulw5j8w7t2bi8X32cuf/Vv/wF/SL98A==)

</div>
<div class="composition-api">

[Abrir o exemplo na Zona de Testes](https://play.vuejs.org/#eNqNVMGOmzAQ/ZURe2BXCiHbrXpwk1X31mMPvS1V5RiTWAEb2SZNhPLvHdvggLZRE6TIM/P8/N5gpk/e2nZ57HhCkrVhWrQWDLdd+1pI0bRKW/iuGg6VVg2ky9wFDp7G8g9lrIl1H80Bb5rtxfFKMcRzUA+aV3AZQKEEhWRKGgus05pL+5NuYeNwj6mTkT4VckRYujVY63GT17twC6/Fr4YjC3kp5DoPNtEgBpY3bU0txwhgXYojsJoasymSkjeqSHweK9vOWoUbXIC/Y1YpjaDH3wt39hMI6TUUSYSQAz8jArPT5Mj+nmIhC6zpAu1TZlEhmXndbBwpXH5NGL6xWrADMsyaMj1lkAzQ92E7mvYe8nCcM24xZApbL5ECiHCSnP73KyseGnvh6V/XedwS2pVjv3C1ziddxNDYc+2WS9fC8E4qJW1W0UbUZwKGSpMZrkX11dW2SpdcE3huT2BULUp44JxPSpmmpegMgU/tyadbWpZC7jCxwj0v+OfTDdU7ITOrWiTjzTS3Vei8IfB5xHZ4PmqoObMEJHryWXXkuqrVn+xEgHZWYRKbh06uLyv4iQq+oIDnkXSQiwKymlc26n75WNdit78FmLWCMeZL+GKMwlKrhLRcBzhlh51WnSwJPFQr9/zLdIZ007w/O6bR4MQe2bseBJMzer5yzwf8MtzbOzYMkNsOY0+HfoZv1d+lZJGMg8fNqdsfbbio4b77uRVv7I0Li8xxZN1PHWbeHdyTWXc/+zgw/8t/+QsROe9h)

</div>

O exemplo acima foi possível através do elemento `<component>` da Vue com o atributo especial `is`:

<div class="options-api">

```vue-html
<!-- O componente muda quando `currentTab` mudar -->
<component :is="currentTab"></component>
```

</div>
<div class="composition-api">

```vue-html
<!-- O componente muda quando `currentTab` mudar -->
<component :is="tabs[currentTab]"></component>
```

</div>

No exemplo acima, o valor passado para `:is` pode conter ou:

- a sequência de caracteres do nome dum componente registado, OU
- o verdadeiro objeto do componente importado

Nós também podemos usar o atributo `is` para criar os elementos de HTML normais.

Quando alternamos entre vários componentes com o `<component :is="...">`, um componente será desmontado quando este for alternado para fora. Nós podemos forçar os componentes inativos para manterem-se "vivos" com o [componente `<KeepAlive>`](/guide/built-ins/keep-alive) embutido.

## Advertências da Analise do Modelo de Marcação no DOM {#in-dom-template-parsing-caveats}

Se estivermos escrevendo os nossos modelos de marcação de Vue diretamente no DOM, a Vue precisará de recuperar a sequência de caracteres do modelo de marcação a partir do DOM. Isto leva a algumas advertências devido ao comportamento da analise sintática do HTML nativo do navegador.

:::tip NOTA
Deve ser notado que as limitações discutidas abaixo apenas aplicam-se se estivermos escrevendo os nossos modelos de marcação diretamente no DOM. Elas NÃO aplicam-se se estivermos usando os modelos de marcação de sequência de caracteres a partir das seguintes fontes:

- Componentes de Ficheiro Único
- Sequências de Caracteres de Modelo de Marcação Incorporado (por exemplo, `template: '...'`)
- `<script type="text/x-template">`
:::

### Insensibilidade aos Caracteres Maiúsculos e Minúsculos {#case-insensitivity}

Os marcadores da HTML e nomes de atributo são insensíveis aos caracteres maiúsculos e minúsculos, assim os navegadores interpretarão quaisquer caracteres maiúsculos como minúsculos. Isto significa que quando usamos os modelos de marcação no DOM, os nomes de componente de `PascalCase` e nomes de propriedade em `camelCase` ou os nomes de evento de `v-on`, todos precisam usar os seus equivalentes em `kebab-case` (delimitados por hífen):

```js
// `camelCase` em JavaScript
const BlogPost = {
  props: ['postTitle'],
  emits: ['updatePost'],
  template: `
    <h3>{{ postTitle }}</h3>
  `
}
```

```vue-html
<!-- `kebab-case` em HTML -->
<blog-post post-title="hello!" @update-post="onUpdatePost"></blog-post>
```

### Marcadores de Auto-Fechamento {#self-closing-tags}

Nós temos estado a usar os marcadores de auto-fechamento para os componentes nos anteriores exemplos de código:

```vue-html
<MyComponent />
```

Isto é porque o analisador sintático do modelo de marcação da Vue respeita o `/>` como uma indicação para o final de qualquer marcador, independentemente do seu tipo.

Nos modelos de marcação no DOM, no entanto, devemos sempre incluir explicitamente os marcadores de fechamento:

```vue-html
<my-component></my-component>
```

Isto porque a especificação da HTML apenas permite [alguns elementos específicos](https://html.spec.whatwg.org/multipage/syntax.html#void-elements) omitirem os marcadores de fechamento, os mais comuns sendo `<input>` e `<img>`. Para todos os outros elementos, se omitirmos o marcador de fechamento, o analisador sintático da HTML nativa pensará que nunca terminamos a marcação de abertura. Por exemplo, o seguinte trecho:

```vue-html
<my-component /> <!-- tencionamos fechar o marcador nesta linha... -->
<span>hello</span>
```

será analisado sintaticamente como:

```vue-html
<my-component>
  <span>hello</span>
</my-component> <!-- mas o navegador fechará nesta linha. -->
```

### Restrições da Colocação do Elemento {#element-placement-restrictions}

Alguns elementos da HTML, tais como `<ul>`, `<ol>`, `<table>` e `<select>` têm restrições sobre quais elementos podem aparecer dentro destes, e alguns elementos tais como `<li>`, `<tr>`, e `<option>` apenas podem aparecer dentro de outros certos elementos.

Isto levará a problemas quando usarmos componentes com os elementos que têm tais restrições. Por exemplo:

```vue-html
<table>
  <blog-post-row></blog-post-row>
</table>
```

O componente personalizado `<blog-post-row>` será içado para fora como conteúdo inválido, causando erros na eventual saída interpretada. Nós podemos usar o [atributo especial `is`](/api/built-in-special-attributes#is) como uma solução:

```vue-html
<table>
  <tr is="vue:blog-post-row"></tr>
</table>
```

:::tip NOTA
Quando usado sobre os elementos da HTML nativa, o valor do `is` deve ser prefixado com `vue:` no sentido de ser interpretado como um componente de Vue. Isto é obrigatório para evitar a confusão com os [elementos personalizados embutidos](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example) nativos.
:::

É tudo o que precisamos saber sobre as advertências da analise do modelo de marcação no DOM por agora - e é de fato, o fim dos _Fundamentos_ da Vue. Parabéns! Existe ainda muito mais para se aprender, mas primeiro, recomendamos dar uma pausa para experimentar a Vue por conta própria - construa alguma coisa divertida, ou consulte alguns dos [Exemplos](/examples/) se já não o fizeste.

Depois de estivermos confortáveis com o conhecimento que já digerimos, podemos seguir com o guia para aprendermos mais sobre os componentes em profundidade.

---

---
url: /guide/scaling-up/state-management.md
---
# Gestão de Estado {#state-management}

## O Que é a Gestão de Estado? {#what-is-state-management}

Tecnicamente, cada instância de componente da Vue já "gere" o seu próprio estado reativo. Tomemos como exemplo um simples componente de contador:

<div class="composition-api">

```vue
<script setup>
import { ref } from 'vue'

// estado
const count = ref(0)

// ações
function increment() {
  count.value++
}
</script>

<!-- visão -->
<template>{{ count }}</template>
```

</div>
<div class="options-api">

```vue
<script>
export default {
  // estado
  data() {
    return {
      count: 0
    }
  },
  // ações
  methods: {
    increment() {
      this.count++
    }
  }
}
</script>

<!-- visão -->
<template>{{ count }}</template>
```

</div>

É uma unidade autónoma com as seguintes partes:

- O **estado**, a fonte de verdade que orienta a nossa aplicação.
- A **visão**, um mapeamento declarativo do **estado**;
- As **ações**, as possíveis maneiras de como o estado poderia mudar em reação às entradas do utilizador a partir da **visão**.

Isto é uma representação simples do conceito de "fluxo de dados unidirecional":

<p style="text-align: center">
  <img alt="diagrama do fluxo de estado" src="./images/state-flow.png" width="252px" style="margin: 40px auto">
</p>

No entanto, a simplicidade começa a ser quebrada quando temos **vários componentes que partilham um estado comum**:

1. Várias visões que podem depender do mesmo pedaço de estado.
2. As ações de diferentes visões podem precisar de alterar o mesmo pedaço de estado.

Para o primeiro caso, uma possível solução alternativa é "elevar" o estado partilhado até um componente ancestral comum e depois passá-lo como propriedades. No entanto, isto torna-se rapidamente tedioso em árvores de componentes com hierarquias profundas, levando a outro problema conhecido como [Perfuração de Propriedade](/guide/components/provide-inject#prop-drilling).

Para o segundo caso, muitas vezes recorremos a soluções como procurar instâncias diretas de pais ou filhos por meio de referências de modelos de marcação, ou tentar alterar e sincronizar várias cópias do estado por meio de eventos emitidos. Ambos os padrões são frágeis e conduzem rapidamente a código impossível de manter.

Uma solução mais simples e direta é extrair o estado partilhado dos componentes e geri-lo num objeto autónomo global. Com isto, a nossa árvore de componentes transforma-se numa grade "visão" e qualquer componente pode aceder ao estado ou desencadear ações, independentemente da sua posição na árvore!

## Gestão de Estado Simples com API de Reatividade {#simple-state-management-with-reactivity-api}

<div class="options-api">

Na API de Opções, os dados reativos são declarados usando a opção `data()`. Internamente, o objeto retornado por `data()` é tornado reativo através da função [`reactive()`](/api/reactivity-core#reactive), que também está disponível como uma API pública.

</div>

Se tivermos um pedaço de estado que deve ser partilhado por várias instâncias, podemos usar [`reactive()`](/api/reactivity-core#reactive) para criar um objeto reativo, e depois importá-lo em vários componentes:

```js
// store.js
import { reactive } from 'vue'

export const store = reactive({
  count: 0
})
```

<div class="composition-api">

```vue
<!-- ComponentA.vue -->
<script setup>
import { store } from './store.js'
</script>

<template>From A: {{ store.count }}</template>
```

```vue
<!-- ComponentB.vue -->
<script setup>
import { store } from './store.js'
</script>

<template>From B: {{ store.count }}</template>
```

</div>
<div class="options-api">

```vue
<!-- ComponentA.vue -->
<script>
import { store } from './store.js'

export default {
  data() {
    return {
      store
    }
  }
}
</script>

<template>From A: {{ store.count }}</template>
```

```vue
<!-- ComponentB.vue -->
<script>
import { store } from './store.js'

export default {
  data() {
    return {
      store
    }
  }
}
</script>

<template>From B: {{ store.count }}</template>
```

</div>

Agora, sempre que o objeto `store` for alterado, tanto `<ComponentA>` como `<ComponentB>` atualizarão suas visões automaticamente — temos agora uma única fonte de verdade.

No entanto, isto também significa que qualquer componente que importe `store` pode alterá-lo como quiser:

```vue-html{2}
<template>
  <button @click="store.count++">
    From B: {{ store.count }}
  </button>
</template>
```

Embora isto funcione em casos simples, o estado global que pode ser arbitrariamente alterado por qualquer componente não será muito sustentável a longo prazo. Para garantir que a lógica de alteração do estado está centralizada, tal como o próprio estado, recomenda-se a definição de métodos na memória com nomes que expressam a intenção das ações:

```js{6-8}
// store.js
import { reactive } from 'vue'

export const store = reactive({
  count: 0,
  increment() {
    this.count++
  }
})
```

```vue-html{2}
<template>
  <button @click="store.increment()">
    From B: {{ store.count }}
  </button>
</template>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNrNkk1uwyAQha8yYpNEiUzXllPVrtRTeJNSqtLGgGBsVbK4ewdwnT9FWWSTFczwmPc+xMhqa4uhl6xklRdOWQQvsbfPrVadNQ7h1dCqpcYaPp3pYFHwQyteXVxKm0tpM0krnm3IgAqUnd3vUFIFUB1Z8bNOkzoVny+wDTuNcZ1gBI/GSQhzqlQX3/5Gng81pA1t33tEo+FF7JX42bYsT1BaONlRguWqZZMU4C261CWMk3EhTK8RQphm8Twse/BscoUsvdqDkTX3kP3nI6aZwcmdQDUcMPJPabX8TQphtCf0RLqd1csxuqQAJTxtYnEUGtIpAH4pn1Ou17FDScOKhT+QNAVM)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNrdU8FqhDAU/JVHLruyi+lZ3FIt9Cu82JilaTWR5CkF8d8bE5O1u1so9FYQzAyTvJnRTKTo+3QcOMlIbpgWPT5WUnS90gjPyr4ll1jAWasOdim9UMum3a20vJWWqxSgkvzTyRt+rocWYVpYFoQm8wRsJh+viHLBcyXtk9No2ALkXd/WyC0CyDfW6RVTOiancQM5ku+x7nUxgUGlOcwxn8Ppu7HJ7udqaqz3SYikOQ5aBgT+OA9slt9kasToFnb5OiAqCU+sFezjVBHvRUimeWdT7JOKrFKAl8VvYatdI6RMDRJhdlPtWdQf5mdQP+SHdtyX/IftlH9pJyS1vcQ2NK8ZivFSiL8BsQmmpMG1s1NU79frYA1k8OD+/I3pUA6+CeNdHg6hmoTMX9pPSnk=)

</div>

:::tip DICA
Nota que o manipulador de clique usa `store.increment()` com parênteses — isto é necessário para chamar o método com o contexto de `this` apropriado, já que não é um método de componente.
:::

Embora aqui estejamos usando um único objeto reativo como memória, também podemos partilhar o estado reativo criado usando outras [APIs de Reatividade](/api/reactivity-core), como `ref()` ou `computed()`, ou mesmo retornar o estado global duma [Função de Composição](/guide/reusability/composables):

```js
import { ref } from 'vue'

// estado global, criado no âmbito do módulo
const globalCount = ref(1)

export function useCount() {
  // estado local, criado por componente
  const localCount = ref(1)

  return {
    globalCount,
    localCount
  }
}
```

O fato de o sistema de reatividade da Vue estar dissociado do modelo de componente torna-o extremamente flexível.

## Considerações da Interpretação do Lado do Servidor {#ssr-considerations}

Se estivermos construindo uma aplicação que recorre à [Interpretação do Lado do Servidor (SSR)](./ssr), o padrão acima pode dar origem a problemas pelo fato da memória ser um simples elemento partilhado entre várias requisições. Esta questão é abordada [mais detalhadamente](./ssr#cross-request-state-pollution) no guia da Interpretação do Lado do Servidor.

## Pinia {#pinia}

Embora a nossa solução de gestão de estado manual satisfaça cenários simples, existe muitos outros aspetos a considerar em aplicações de produção em grande escala:

- Convenções mais fortes para colaboração em equipa
- Integração com as Ferramentas de Programação da Vue, incluindo linha de tempo, inspeção no componente e depuração de viagens no tempo
- Substituição de Módulo Instantânea
- Suporte à Interpretação do Lado do Servidor

[Pinia](https://pinia-docs-pt.netlify.app/) é uma biblioteca de gestão de estado que implementa todos itens acima. É mantida pela equipa principal da Vue, e funciona tanto com a Vue 2 como com a Vue 3.

Os utilizadores existentes podem estar familiarizados com a [Vuex](https://vuex.vuejs.org/), a anterior biblioteca oficial de gestão de estados da Vue. Com a Pinia a desempenhar o mesmo papel no ecossistema, a Vuex está agora em modo de manutenção. Ela ainda funciona, mas não receberá mais novos recursos. Recomenda-se o uso da Pinia para as novas aplicações.

A Pinia começou como uma exploração do que poderia ser a próxima iteração da Vuex, incorporando muitas ideias das discussões da equipa principal para a Vuex 5. Eventualmente, percebemos que a Pinia já implementa a maioria do que queríamos na Vuex 5, e decidimos fazer dela a nova recomendação.

Em comparação com a Vuex, a Pinia fornece uma API mais simples com menos cerimónias, oferece APIs de estilo da API de Composição e, mais importante, tem um suporte sólido de inferência de tipos quando usada com a TypeScript. 

---

---
url: /glossary/index.md
---
# Glossário {#glossary}

Este glossário está destinado a fornecer alguma orientação sobre os significados de termos técnicos que são de uso comum quando falamos sobre a Vue. Está destinado a ser *descritivo* de como os termos são comummente usados, e não a ser uma especificação *prescritiva* de como devem ser usados. Alguns termos podem ter significados ou nuances ligeiramente diferentes dependendo do contexto envolvente.

[[TOC]]

## componente assíncrono {#async-component}

Um *componente assíncrono* é um embrulho em torno dum componente que permite que o componente embrulhado seja carregado preguiçosamente. Este é normalmente usado como uma maneira de reduzir o tamanho dos ficheiros `.js` construídos.

A Vue Router tem uma funcionalidade semelhante para o [carregamento preguiçoso de componentes de rota](https://vue-router-docs-pt.netlify.app/guide/advanced/lazy-loading), embora esta não use a funcionalidade de componentes assíncronos da Vue.

Para mais detalhes consulte:
- [Guia - Componentes Assíncronos](/guide/components/async)

## macro de compilador {#compiler-macro}

Um *macro de compilador* é o código especial que é processado por um compilador e convertido para outra coisa. Eles são efetivamente uma forma inteligente de substituição de sequência de caracteres.

O compilador de [SFC](#single-file-component) da Vue suporta várias macros, tais como `defineProps()`, `defineEmits()`, e `defineExpose()`. Estas macros são intencionalmente desenhadas para parecerem-se com funções normais de JavaScript para que possam influenciar o mesmo analisador e ferramental de inferência de tipo em torno da JavaScript ou TypeScript. No entanto, não são funções verdadeiras que são executadas no navegador. Estas são sequências de caracteres especiais que o compilador deteta e substitui pelo código de JavaScript que verdadeiramente será executado.

As macros têm limitações no seu uso que não aplicam-se ao código de JavaScript normal. Por exemplo, podes pensar que `const dp = defineProps` permitiria-te criar um pseudónimo para `defineProps`, mas na verdade resultará num erro. Existem também limitações em quais valores podem ser passados para `defineProps()`, visto que os 'argumentos' têm de ser processados pelo compilador e não em tempo de execução.

Para mais detalhes consulte:
- [`<script setup>` - `defineProps()` & `defineEmits()`](/api/sfc-script-setup#defineprops-defineemits)
- [`<script setup>` - `defineExpose()`](/api/sfc-script-setup#defineexpose)

## componente {#component}

O termo *componente* não é exclusivo à Vue. É comum às muitas abstrações de interface de utilizador. Ele descreve um pedaço da interface de utilizador, tal como um botão ou caixa de confirmação. Os componentes também pode ser combinados para formar componentes maiores.

Os componentes são o mecanismo primário fornecido pela Vue para separar uma interface de utilizador em pedaços menores, tanto para melhorar a capacidade de manutenção e permitir a reutilização de código.

Um componente de Vue é um objeto. Todas as propriedades são opcionais, mas nem um modelo de marcação ou função de interpretação é obrigatório para o componente desenhar. Por exemplo, o seguinte objeto seria um componente válido:

```js
const HelloWorldComponent = {
  render() {
    return 'Hello world!'
  }
}
```

Na prática, a maioria das aplicações de Vue são escritas usando [Componentes de Ficheiro Único](#single-file-component) (ficheiros `.vue`). Embora estes componentes podem não parecer ser objetos à primeira vista, o compilador de componentes de ficheiro único os converterá num objeto, que é usado como exportação padrão para o ficheiro. Duma perspetiva externa, um ficheiro `.vue` é apenas um módulo de ECMAScript que exporta um objeto de componente.

As propriedades dum objeto de componente são normalmente referidas como *opções*. Isto é onde a [API de Opções](#options-api) recebe o seu nome.

As opções para um componente definem como as instâncias deste componente deveriam ser criadas. Os componentes são concetualmente semelhantes às classes, apesar da Vue não usar verdadeiras classes de JavaScript para as definir.

O termo componente também pode ser usado mais vagamente para fazer referência às instâncias do componente.

Para mais detalhes consulte:
- [Guia - Fundamentos de Componentes](/guide/essentials/component-basics)

A palavra 'componente' também aparece em vários outros termos:
- [componente assíncrono](#async-component)
- [componente dinâmico](#dynamic-component)
- [componente funcional](#functional-component)
- [Componente da Web](#web-component)

## função de composição {#composable}

O termo *função de composição* descreve um padrão de uso comum na Vue. Não é uma funcionalidade separa de Vue, é apenas uma maneira de usar a [API de Composição](#composition-api) da abstração.


* Um função de composição é uma função.
* As funções de composição são usadas para encapsular e reutilizar lógica com estado.
* O nome da função normalmente começa com `use`, para que outros programadores saibam que é uma função de composição.
* A função é normalmente esperada ser chamada durante a execução síncrona da função `setup()` do componente (ou, equivalentemente, durante a execução dum bloco `<script setup>`). Isto ata a invocação da função de composição para o contexto do componente atual, por exemplo através de chamadas para `provide()`, `inject()` ou `onMounted()`.
* As funções de composição normalmente retornam um objeto simples, e não um objeto reativo. Este objeto normalmente contém referências e funções e é esperado ser desestruturado dentro do código de chamada.

Tal como acontece com muitos padrões, pode existir alguma discordância sobre se um código específico qualifica para o rótulo. Nem todas as funções utilitárias de JavaScript são funções de composição. Se uma função não usa a API de Composição então provavelmente não é uma função de composição. Se não espera ser chamada durante a execução síncrona da `setup()` então provavelmente não é uma função de composição. As funções de composição são especialmente usadas para encapsular lógica com estado, não são apenas uma convenção de nomenclatura para funções.

Consulte [Guia - Funções de Composição](/guide/reusability/composables) para mais detalhes sobre a escrita de funções de composição.

## API de Composição {#composition-api}

A *API de Composição* é uma coleção de funções usadas para escrever componentes e funções de composição na Vue.

O termo é também usado para descrever um dos dois estilos principais usados para escrever componentes, o outro sendo a [API de Opções](#options-api). Os componentes escritos usando a API de Composição usam ou `<script setup>` ou uma função `setup()` explícita.

Consulte as [Questões Frequentes sobre API de Composição](/guide/extras/composition-api-faq) por mais detalhes.

## elemento personalizado {#custom-element}

Um *elemento personalizado* é uma funcionalidade do padrão dos [Componentes da Web](#web-component), que é implementado nos navegadores da Web modernos. Faz referência a habilidade de usar um elemento de HTML personalizado na tua marcação de HTML para incluir um Componente da Web naquele ponto na página.

A Vue tem suporte embutido para interpretar elementos personalizados e permiti-los que sejam usados diretamente nos modelos de marcação do componente da Vue.

Os elementos personalizados não deveriam ser confundidos com a habilidade de incluir componentes da Vue como marcadores dentro dum outro modelo de marcação do componente da Vue. Os elementos personalizados são usados para criar os Componentes da Web, e não componentes da Vue.

Para mais detalhes consulte:
- [Guia - Vue e os Componentes da Web](/guide/extras/web-components)

## diretiva {#directive}

O termo *diretiva* refere-se aos atributos do modelo de marcação começando com o prefixo `v-`, ou suas abreviaturas equivalentes.

As diretivas embutidas incluem `v-if`, `v-for`, `v-bind`, `v-on`, `v-slot`.

A Vue também suporta a criação de diretivas personalizadas, embora sejam normalmente apenas usadas como uma 'escotilha de fuga' para manipulação de nós do DOM diretamente. As diretivas personalizadas geralmente não podem ser usadas para recriar a funcionalidade das diretivas embutidas.

Para mais detalhes consulte:
- [Guia - Sintaxe do Modelo de Marcação - Diretivas](/guide/essentials/template-syntax#directives)
- [Guia - Diretivas Personalizadas](/guide/reusability/custom-directives)

## componente dinâmico {#dynamic-component}

O termo *componente dinâmico* é usado para descrever casos onde a escolha de qual componente filho à desenhar precisa ser feita dinamicamente. Normalmente, isto é alcançado usando `<component :is="type">`.

Um componente dinâmico não é um tipo especial de componente. Qualquer componente pode ser usado como um componente dinâmico. É a escolha do componente que é dinâmica, ao invés do próprio componente.

Para mais detalhes consulte:
- [Guia - Fundamentos de Componentes - Componentes Dinâmicos](/guide/essentials/component-basics#dynamic-components)

## efeito {#effect}

Consulte [efeito reativo](#reactive-effect) e [efeito colateral](#side-effect).

## evento {#event}

O uso de eventos para comunicação entre diferentes partes dum programa é comum para muitas áreas diferentes da programação. Dentro da Vue, o termo é comummente aplicado à ambos eventos de elemento de HTML nativo e eventos de componentes de Vue. A diretiva `v-on` é usada nos modelos de marcação para ouvir ambos tipos de evento.

Para mais detalhes consulte:
- [Guia - Manipulação de Evento](/guide/essentials/event-handling)
- [Guia - Eventos de Componente](/guide/components/events)

## fragmento {#fragment}

O termo *fragmento* refere-se à um tipo especial de [VNode](#vnode) que é usado como pai para outros nós virtuais, mas que por si mesmo não interpreta quaisquer elementos.

O nome provém do conceito semelhante dum [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) na API do DOM nativa.

Os fragmentos são usados para suportar componentes com vários nós de raiz. Embora tais componentes possam parecer ter várias raízes, nos bastidores usam um nó de fragmento como uma única raiz, como pai dos nós de 'raiz'.

Os fragmentos são também usados pelo compilador do modelo de marcação como uma maneira de envolver vários nós dinâmicos, por exemplo aqueles criados através de `v-for` ou `v-if`. Isto permite sugestões adicionais a serem passadas para o algoritmo de remendo do [VDOM ou  DOM Virtual](#virtual-dom). Muito disto é manipulado internamente, mas um lugar onde podes encontrar isto diretamente é usando uma `key` num marcador `<template>` com `v-for`. Neste cenário, a `key` é adicionada como uma [propriedade](#prop) ao nó virtual do fragmento.

Os nós do fragmento são atualmente desenhados para o DOM como nós de texto vazio, ainda que seja um detalhe de implementação. Tu podes encontrar estes nós de texto se usares `$el` ou tentares percorrer o DOM com as APIs do navegador embutido.

## componente funcional {#functional-component}

Uma definição de componente é normalmente um objeto contendo opções. Pode não parecer assim se estiveres usando `<script setup>`, mas o componente exportado a partir do ficheiro `.vue` continuará a ser um objeto.

Um *componente funcional* é uma forma alternativa de componente que é declarado usando uma função. Esta função age como [função de interpretação](#render-function) para o componente.

Um componente funcional não pode ter nenhum estado de si mesmo. Também não passa pelo ciclo de vida do componente normal, então os gatilhos do ciclo de vida não podem ser usados. Isto torna-os ligeiramente mais leves do que os componentes com estado normais.

Para mais detalhes consulte:
- [Guia - Funções de Interpretação & JSX - Componentes Funcionais](/guide/extras/render-function#functional-components)

## Içamento {#hoisting}

O termo *içamento* é usado para descrever a execução duma seção de código antes dela ser alcançada, antes do outro código. A execução é 'içada' para um ponto anterior.

A JavaScript usa içamento para algumas estruturas, tais como `var`, `import` e declarações de função.

Num contexto de Vue, o compilador de modelo de marcação aplica *içamento estático* para melhorar o desempenho. Quando convertes um modelo de marcação para uma função de interpretação, os nós virtuais que correspondem ao conteúdo estático podem ser criados de uma vez e depois reutilizados. Estes nós virtuais estáticos são descritos como içados porque são criados fora da função de interpretação, antes de executar. Uma forma semelhante de içamento é aplicada aos objetos ou arranjos estáticos que são gerados pelo compilador de modelo de marcação.

Por mais detalhes consulte:
- [Guia - Mecanismo de Interpretação - Içamento Estático](/guide/extras/rendering-mechanism#static-hoisting)

## Modelo de Marcação no DOM {#in-dom-template}

Existem várias maneiras de especificar um modelo de marcação para um componente. Na maioria dos casos o modelo de marcação é fornecido como uma sequência de caracteres.

O termo *modelo de marcação no DOM* refere-se ao cenário onde o modelo de marcação é fornecido na forma de nós de DOM, ao invés duma sequência de caracteres. A Vue então converte os nós de DOM numa sequência de caracteres de modelo de marcação usando `innerHTML`.

Normalmente, um modelo de marcação em DOM começa como marcação de HTML escrita diretamente no HTML da página. O navegador então analisa esta em nós de DOM, o que a Vue então usa para ler a `innerHTML`.

Para mais detalhes consulte:
- [Guia - Criação duma Aplicação - Modelo de Marcação do Componente de Raiz no DOM](/guide/essentials/application#in-dom-root-component-template)
- [Guia - Fundamentos de Componente - Advertências de Analise de Modelo de Marcação de DOM](/guide/essentials/component-basics#dom-template-parsing-caveats)
- [Opções: Interpretação - modelo de marcação](/api/options-rendering#template)

## injetar {#inject}

Consulte [fornecer / injetar](#provide-inject).

## gatilhos do ciclo de vida {#lifecycle-hooks}

Uma instância de componente da Vue passa por um ciclo de vida. Por exemplo, é criada, montada, atualizada, e desmontada.

Os *gatilhos do ciclo de vida* são uma maneira de ouvir todos estes eventos do ciclo de vida.

Com a API de Opções, cada gatilho é fornecido como uma opção separada, por exemplo `mounted`. A API de Composição usa funções, tais como `onMounted()`.

Para mais detalhes consulte:
- [Guia - Gatilhos do Ciclo de Vida](/guide/essentials/lifecycle)

## macro {#macro}

Consulte a [macro do compilador](#compiler-macro).

## ranhura nomeada {#named-slot}

Um componente pode ter várias ranhuras, diferenciadas por nome. As ranhuras exceto a ranhura padrão são referidas como *ranhuras nomeadas*.

Para mais detalhes consulte:
- [Guia - Ranhuras - Ranhuras Nomeadas](/guide/components/slots#named-slots)

## API de Opções {#options-api}

Os componentes de Vue são definidas usando objetos. As propriedades destes objetos de componente são conhecidas como *opções*.

Os componentes podem ser escritos em dois estilos. Um estilo usa a [API de Composição](#composition-api) em conjunto com `setup` (ou através uma opção `setup()` ou `<script setup>`). O outro estilo faz uso muito pouco direto da API de Composição, usando várias opções de componente para alcançar um resultado semelhante. As opções do componente que são usadas nesta maneira são referidas como *API de Opções*.

A API de Opções inclui opções tais como `data()`, `computed`, `methods` e `created()`.

Algumas opções, tais como `props`, `emits` e `inheritAttrs`, podem ser usados quando escrevemos componentes com qualquer API. Já que são opções de componente, poderiam ser consideradas parte da API de Opções. No entanto, uma vez que estas opções também são usadas em conjunto com a `setup()`, é normalmente mais útil pensar delas como características partilhadas entre os dois estilos de componente.

A própria função `setup()` é uma opção de componente, então *poderia* ser considerada como parte da API de Opções. No entanto, isto não é como o termo 'API de Opções' é normalmente usado. Ao invés disto, a função `setup()` é considerada como parte da API de Composição.

## extensão {#plugin}

Embora o termo *extensão* possa ser usado numa grande variedade de contextos, a Vue tem um conceito específico duma extensão como uma maneira de adicionar funcionalidade à uma aplicação.

As extensões são adicionadas à uma aplicação chamando `app.use(plugin)`. A própria extensão ou é uma função ou um objeto com uma função `install`. Esta função será passada à instância da aplicação e pode então fazer tudo aquilo que precisa fazer.

Para mais detalhes consulte:
- [Guia - Extensões](/guide/reusability/plugins)

## propriedade {#prop}

Existem três usos comuns do termo *propriedade* na Vue:

* Propriedades de componente
* Propriedades de nó virtual
* Propriedades de ranhura

As *propriedades de componente* são o que a maioria das pessoas consideram como propriedades. Estas são explicitamente definidas por um componente usando ou `defineProps()` ou a opção `props`.

O termo *propriedades de nó virtual* referem-se às propriedades do objeto passado como segundo argumento à `h()`. Estas podem incluir propriedades de componente, mas também podem incluir eventos de componente, eventos de DOM, atributos de DOM e propriedades de DOM. Normalmente apenas encontrarias propriedades de nó virtual se estivesses a trabalhar com funções de interpretação para manipular diretamente os nós virtuais.

As *propriedades de ranhura* são propriedades passadas à uma ranhura isolada.

Em todos os casos, as propriedades são propriedades que são a partir doutro lado.

Embora a palavra *props* derive da palavra *propriedades*, o termo *props* tem um significado muito mais específico no contexto da Vue. Tu deves evitar usá-a como uma abreviação de propriedades.

Para mais detalhes consulte:
- [Guia - Propriedades](/guide/components/props)
- [Guia - Funções de Interpretação & JSX](/guide/extras/render-function)
- [Guia - Ranhuras - Ranhuras Isoladas](/guide/components/slots#scoped-slots)

## fornecer / injetar {#provide-inject}

`provide` e `inject` são uma forma de comunicação inter-componente.

Quando um componente *fornece* um valor, todos os descendentes deste componente podem então escolher agarrar este valor, usando `inject`. Ao contrário das propriedades, o componente fornecedor não sabe precisamente qual componente está a receber o componente.

`provide` e `inject` são algumas usadas para evitar a *perfuração de propriedade*. Elas também podem ser usadas como uma maneira implícita para um componente comunicar com os conteúdos da sua ranhura.

`provide` também pode ser usada no nível da aplicação, tornando um valor disponível para todos os componentes dentro desta aplicação.

Para mais detalhes consulte
- [Guia - fornecer / injetar](/guide/components/provide-inject)

## efeito reativo {#reactive-effect}

Um *efeito reativo* é a parte do sistema de reatividade da Vue. Refere-se ao processo de rastrear as dependências duma função e re-executar esta função quando os valores destas dependências mudarem.

`watchEffect()` é a maneira mais direta de criar um efeito. Várias outras partes da Vue usam os efeitos internamente, por exemplo, atualizações de interpretação de componente, `computed()` e `watch()`.

A Vue apenas pode rastrear dependências dentro dum efeito reativo. Se o valor duma propriedade for lido fora dum efeito reativo 'perderá' a reatividade, no sentido de que a Vue não saberá o que fazer se esta propriedade mudar subsequentemente.

O termo deriva de 'efeito colateral'. A chamada da função de efeito é um efeito colateral do valor da propriedade sendo mudada.

Para mais detalhes consulte:
- [Guia - Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## reatividade {#reactivity}

Em geral, a *reatividade* refere-se à habilidade de automaticamente realizar ações em resposta às mudanças de dados. Por exemplo, atualizar o DOM ou fazer uma requisição de rede quando um valor de dado mudar.

No contexto da Vue, a reatividade é usada para descrever uma coleção de funcionalidades. Estas funcionalidades combinam-se para formar um *sistema de reatividade*, que é exposto através da [API de Reatividade](#reactivity-api).

Existem várias diferentes maneiras que um sistema de reatividade poderia ser implementado. Por exemplo, poderia ser feito pela analise estática do código para determinar suas dependências. No entanto, a Vue não emprega esta forma de sistema de reatividade.

Ao invés disto, o sistema de reatividade da Vue rastreia o acesso de propriedade em tempo de execução. Ele faz isto usando embrulhos de delegação e funções de recuperação e definição para a propriedades.

Para mais detalhes consulte:
- [Guia - Fundamentos da Reatividade](/guide/essentials/reactivity-fundamentals)
- [Guia - Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## API de Reatividade {#reactivity-api}

A *API de Reatividade* é uma coleção de funções do núcleo da Vue relacionadas à [reatividade](#reactivity). Estas podem ser usadas independentemente dos componentes. Ela inclui funções tais como `ref()`, `reactive()`, `computed()`, `watch()` e `watchEffect()`.

A API de Reatividade é um subconjunto da API de Composição.

Para mais detalhes consulte:
- [API de Reatividade: Núcleo](/api/reactivity-core)
- [API de Reatividade: Utilitários](/api/reactivity-utilities)
- [API de Reatividade: Avançado](/api/reactivity-advanced)

## referência {#ref}

> Esta entrada é sobre o uso de `ref` para a reatividade. Para o atributo `ref` usado nos modelos de marcação, consulte [referência do modelo de marcação](#template-ref).

Uma `ref` é parte do sistema de reatividade da Vue. Ela é um objeto com uma única propriedade reativa, chamada de `value`.

Existem vários tipos diferentes de referência. Por exemplo, referências podem ser criadas usando `ref()`, `shallowRef()`, `computed()`, e `customRef()`. A função `isRef()` pode ser usada para verificar se um objeto é uma referência, e `isReadonly()` pode ser usado para verificar se a referência permite a re-atribuição direta do seu valor.

Para mais detalhes consulte:
- [Guia - Fundamentos da Reatividade](/guide/essentials/reactivity-fundamentals)
- [API de Reatividade: Núcleo](/api/reactivity-core)
- [API de Reatividade: Utilitários](/api/reactivity-utilities)
- [API de Reatividade: Avançado](/api/reactivity-advanced)

## função de interpretação {#render-function}

Uma *função de interpretação* é a parte dum componente que gera os nós virtuais usados durante a interpretação. Os modelos de marcação são compilados para as funções de interpretação.

Para mais detalhes consulte:
- [Guia - Funções de Interpretação & JSX](/guide/extras/render-function)

## agendador {#scheduler}

O *agendador* é a parte do interior da Vue que controla o horário de quando os [efeitos de reatividade](#reactive-effect) são executados.

Quando estado de reatividade muda, a Vue não aciona imediatamente a atualização da interpretação. Ao invés disto, ela organiza-os por grupos usando uma fila. Isto garante que um componente apenas re-interpreta-se uma vez, mesmo se várias mudanças forem feitas aos dados subjacentes.

Os [observadores](/guide/essentials/watchers) são também organizados por grupos usando a fila agendadora. Os observadores com `flush: 'pre'` (o padrão) executarão antes da interpretação do componente, ao passo que aqueles com `flush: 'post'` executarão depois da interpretação do componente.

As tarefas no agendador são também usadas para realizar várias outras tarefas internas, tais como acionar alguns [gatilhos do ciclo de vida](#lifecycle-hooks) e atualizar [referências do modelo de marcação](#template-ref).

## ranhura isolada {#scoped-slot}

O termo *ranhura isolada* é usado para referir-se à [ranhura](#slot) que recebe [propriedades](#prop).

Historicamente, a Vue fez uma distinção muito maior entre ranhuras isoladas e não isoladas. Até algum ponto poderiam ser consideradas como duas funcionalidades separadas, unificadas por trás duma sintaxe de modelo de marcação comum.

Na Vue 3, as APIs da ranhura foram simplificadas para fazer todas as ranhuras comportarem-se como ranhuras isoladas. No entanto, os casos de uso para ranhuras isoladas e não isoladas muitas vezes diferem, assim o termo ainda prova-se útil como uma maneira para referir-se às ranhuras com propriedades.

As propriedades passadas à uma ranhura apenas podem ser usadas dentro duma região específica do modelo de marcação pai, responsável por definir os conteúdos da ranhura. Esta região do modelo de marcação comporta-se como uma âmbito de variável para as propriedades, daí o nome 'ranhura isolada'.

Para mais detalhes consulte:
- [Guia - Ranhuras - Ranhuras Isoladas](/guide/components/slots#scoped-slots)

## SFC {#sfc}

Consulte o [Componente Ficheiro Único](#single-file-component).

## efeito colateral {#side-effect}

O termo *efeito colateral* não é específico à Vue. Ele é usado para descrever operações ou funções que fazem algo além dos seus âmbitos locais.

Por exemplo, no contexto de definição duma propriedade como `user.name = null`, é esperado que esta mudará o valor de `user.name`. Se também fizer outra coisa, como acionar o sistema de reatividade da Vue, então isto deveria ser descrito como um efeito colateral. Este é origem do termo [efeito de reatividade](#reactive-effect) dentro da Vue.

Quando uma função é descrita como tendo efeitos colaterais, significa que a função realiza alguma tipo de ação que é observável fora da função, à parte de só retornar um valor. Isto pode significar que atualiza um valor no estado, ou aciona uma requisição de rede.

O termo é frequentemente usado quando descrevemos a interpretação ou propriedades computadas. É considerado boa prática para interpretação não ter nenhum efeito colateral. Do mesmo modo, a função recuperadora para uma propriedade computada não deveria ter nenhum efeito colateral.

## Componente de Ficheiro Único {#single-file-component}

O termo *Componente de Ficheiro Único*, ou SFC em Inglês, refere-se ao formato de ficheiro `.vue` que é comummente usado para os componentes da Vue.

Consulte também:
- [Guia - Componentes de Ficheiro Único](/guide/scaling-up/sfc)
- [Especificação da Sintaxe do SFC](/api/sfc-spec)

## ranhura {#slot}

As ranhuras são usadas para passar conteúdo para componentes filhos. Ao passo que as propriedades são usadas para passar valores de dados, as ranhuras são usadas para passar conteúdo mais rico consistindo de elementos de HTML e outros componentes de Vue.

Para mais detalhes consulte:
- [Guia - Ranhuras](/guide/components/slots)

## referência do modelo de marcação {#template-ref}

O termo *referência do modelo de marcação* refere-se ao uso dum atributo `ref` num marcador dentro dum modelo de marcação. Depois do componente ser desenhado, este atributo é usado para povoar uma propriedade correspondente com ou o elemento de HTML ou a instância do componente que corresponde ao marcador no modelo de marcação.

Se estiveres a usar a API de Opções então as referências são expostas através das propriedades do objeto `$refs`.

Com a API de Composição, as referências do modelo de marcação povoam uma [referência](#ref) reativa com o mesmo nome.

As referências do modelo de marcação não devem ser confundidas com as referências reativas encontradas no sistema de reatividade da Vue.

Para mais detalhes consulte:
- [Guia - Referências do Modelo de Marcação](/guide/essentials/template-refs)

## VDOM {#vdom}

Consulte o [DOM virtual](#virtual-dom).

## DOM virtual {#virtual-dom}

O termo *DOM virtual* (VDOM como é conhecido em Inglês) não é exclusivo à Vue. É uma abordagem comum usada por várias abstrações da Web para gestão de atualizações da interface de utilizador.

Os navegadores usam uma árvore de nós para representar o estado atual da página. Esta árvore, e as APIs de JavaScript usadas para interagir com esta, são referidas como *modelo do objeto do documento*, ou *DOM* na sua abreviatura em Inglês.

A manipulação do DOM é uma dos maiores obstáculo do desempenho. O DOM virtual fornece uma estratégia para lidar com isto.

No lugar de criar nós de DOM diretamente, os componentes da Vue geram uma descrição de quais nós de DOM gostariam. Estas descrições são objetos de JavaScript simples, conhecidos como nós do DOM virtual (ou VDOM na sua abreviatura em Inglês). A criação de nós de DOM virtual é relativamente barato.

Toda vez que um componente é reinterpretado, a nova árvore de nós de DOM é compara à árvore anterior de nós de DOM e quaisquer diferenças são então aplicadas ao DOM verdadeiro. Se nada tiver mudado então o DOM não precisa de ser tocado.

A Vue usa uma abordagem híbrida que chamamos de [DOM Virtual Informado pelo Compilador](/guide/extras/rendering-mechanism#compiler-informed-virtual-dom). O compilador de modelo de marcação da Vue é capaz de aplicar otimizações de desempenho baseado na analise estática do modelo de marcação. No lugar de realizar uma comparação completa das antigas e novas árvores de nós virtuais do componente em tempo de execução, a Vue pode usar a informação extraída pelo compilador para reduzir a comparação apenas às partes da árvore que podem de fato mudar.

Para mais detalhes consulte:
- [Guia - Mecanismo de Interpretação](/guide/extras/rendering-mechanism)
- [Guia - Funções de Interpretação & JSX](/guide/extras/render-function)

## nó virtual {#vnode}

Um *nó virtual* mas conhecido como (VNode, abreviatura em Inglês) é um *nó de DOM virtual*. Eles podem ser criados usando a função [`h()`](/api/render-function#h).

Consulte a seção do [DOM virtual] para mais informação.

## Componente da Web {#web-component}

O padrão dos *Componentes da Web* é uma coleção de funcionalidade implementadas nos navegadores da Web modernos.

Os componentes da Vue não são Componentes da Web, mas `defineCustomElement()` pode ser usado para criar um [elemento personalizado](#custom-element) a partir dum componente de Vue. A Vue também suporta o uso de elementos personalizados dentro dos componentes da Vue.

Para mais detalhes consulte:
- [Guia - Vue e os Componentes da Web](/guide/extras/web-components)

---

---
url: /guide/built-ins/transition-group.md
---
<script setup>
import ListBasic from './transition-demos/ListBasic.vue'
import ListMove from './transition-demos/ListMove.vue'
import ListStagger from './transition-demos/ListStagger.vue'
</script>

# Grupo de Transição {#transitiongroup}

`<TransitionGroup>` é um componente embutido desenhado para animação da inserção, remoção, e mudança da ordem dos elementos ou componentes que são interpretados em uma lista.

## Diferenças em relação ao `<Transition>` {#differences-from-transition}

`<TransitionGroup>` suporta as mesmas propriedades, classes de transição de CSS, e ouvintes de gatilhos de JavaScript tal como o `<Transition>`, com as seguintes diferenças:

- Por padrão, ele não interpreta um elemento envolvedor. Mas podes especificar um elemento a ser interpretado com a propriedade `tag`.

- Os [modos de transição](./transition.html#modos-de-transição) não estão disponíveis, porque não estamos mais alternando entre mutuamente elementos exclusivos.

- Os elementos de dentro são **sempre obrigados** a ter um atributo `key` único.

- As classes de transição de CSS serão aplicadas aos elementos individuais na lista, **não** ao grupo ou ao próprio contentor.

:::tip Dica
Quando usada nos [modelos de marcação do DOM](/guide/essentials/component-basics.html#advertências-de-analise-de-modelo-de-marcação-de-dom), deve ser referenciado como `<transition-group>`.
:::

## Transições de Entrada e Saída {#enter-leave-transitions}

Cá está um exemplo de aplicação de transições de entrada e saída à uma lista `v-for` usando `<TransitionGroup>`:

```vue-html
<TransitionGroup name="list" tag="ul">
  <li v-for="item in items" :key="item">
    {{ item }}
  </li>
</TransitionGroup>
```

```css
.list-enter-active,
.list-leave-active {
  transition: all 0.5s ease;
}
.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
```

<ListBasic />

## Transições de Movimento {#move-transitions}

A demonstração acima tem defeitos óbvios: quando um item é inserido ou removido, seus itens circundantes "saltam" instantaneamente para lugar ao invés de moverem-se suavemente. Nós podemos corrigir isto adicionando algumas regras de CSS a mais:

```css{1,13-17}
.list-move, /* aplica transição aos elementos em movimento */
.list-enter-active,
.list-leave-active {
  transition: all 0.5s ease;
}

.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}

/* garanta que os itens saindo sejam tirados do fluxo do esquema para
   as animações de movimento possam ser calculadas corretamente. */
.list-leave-active {
  position: absolute;
}
```

Agora está muito melhor - ainda animando suavemente quando a lista inteira é baralhada:

<ListMove />

[Exemplo Completo](/examples/#list-transition)

## Transições de Lista Surpreendente {#staggering-list-transitions}

Ao comunicar com as transições de JavaScript através dos atributos de dados, é também possível alterar o horário de transições em uma lista. Primeiro, interpretamos o índice de um item como um atributo de dados no elemento de DOM:

```vue-html{11}
<TransitionGroup
  tag="ul"
  :css="false"
  @before-enter="onBeforeEnter"
  @enter="onEnter"
  @leave="onLeave"
>
  <li
    v-for="(item, index) in computedList"
    :key="item.msg"
    :data-index="index"
  >
    {{ item.msg }}
  </li>
</TransitionGroup>
```

Depois, nos gatilhos de JavaScript, animamos o elemento com um atraso baseado no atributo de dados. Este exemplo está usando a [biblioteca GreenSock](https://greensock.com/) para realizar a animação:

```js{5}
function onEnter(el, done) {
  gsap.to(el, {
    opacity: 1,
    height: '1.6em',
    delay: el.dataset.index * 0.15,
    onComplete: done
  })
}
```

<ListStagger />

<div class="composition-api">

[Exemplo Completo na Zona de Testes](https://play.vuejs.org/#eNqlVMuu0zAQ/ZVRNklRm7QLWETtBW4FSFCxYkdYmGSSmjp28KNQVfl3xk7SFyvEponPGc+cOTPNOXrbdenRYZRHa1Nq3lkwaF33VEjedkpbOIPGeg6lajtnsYIeaq1aiOlSfAlqDOtG3L8SUchSSWNBcPrZwNdCAqVqTZND/KxdibBDjKGf3xIfWXngCNs9k4/Udu/KA3xWWnPz1zW0sOOP6CcnG3jv9ImIQn67SvrpUJ9IE/WVxPHsSkw97gbN0zFJZrB5grNPrskcLUNXac2FRZ0k3GIbIvxLSsVTq3bqF+otM5jMUi5L4So0SSicHplwOKOyfShdO1lariQo+Yy10vhO+qwoZkNFFKmxJ4Gp6ljJrRe+vMP3yJu910swNXqXcco1h0pJHDP6CZHEAAcAYMydwypYCDAkJRdX6Sts4xGtUDAKotIVs9Scpd4q/A0vYJmuXo5BSm7JOIEW81DVo77VR207ZEf8F23LB23T+X9VrbNh82nn6UAz7ASzSCeANZe0AnBctIqqbIoojLCIIBvoL5pJw31DH7Ry3VDKsoYinSii4ZyXxhBQM2Fwwt58D7NeoB8QkXfDvwRd2XtceOsCHkwc8KCINAk+vADJppQUFjZ0DsGVGT3uFn1KSjoPeKLoaYtvCO/rIlz3vH9O5FiU/nXny/pDT6YGKZngg0/Zg1GErrMbp6N5NHxJFi3N/4dRkj5IYf5ULxCmiPJpI4rIr4kHimhvbWfyLHOyOzQpNZZ57jXNy4nRGFLTR/0fWBqe7w==)

</div>
<div class="options-api">

[Exemplo Completo na Zona de Testes](https://play.vuejs.org/#eNqtVE2P0zAQ/SujXNqgNmkPcIjaBbYCJKg4cSMcTDJNTB07+KNsVfW/M3aabNpyQltViT1vPPP8Zian6H3bJgeHURatTKF5ax9yyZtWaQuVYS3stGpg4peTXOayUNJYEJwea/ieS4ATNKbKYPKoXYGwRZzAeTYGPrNizxE2NZO30KZ2xR6+Kq25uTuGFrb81vrFyQo+On0kIJc/PCV8CmxL3DEnLJy8e8ksm8bdGkCjdVr2O4DfDvWRgtGN/JYC0SOkKVTTOotl1jv3hi3d+DngENILkey4sKinU26xiWH9AH6REN/Eqq36g3rDDE7jhMtCuBLN1NbcJIFEHN9RaNDWqjQDAyUfcac0fpA+CYoRCRSJsUeBiWpZwe2RSrK4w2rkVe2rdYG6LD5uH3EGpZI4iuurTdwDNBjpRJclg+UlhP914UnMZfIGm8kIKVEwciYivhoGLQlQ4hO8gkWyfD1yVHJDKgu0mAUmPXLuxRkYb5Ed8H8YL/7BeGx7Oa6hkLmk/yodBoo21BKtYBZpB7DikroKDvNGUeZ1HoVmyCNIO/ibZtJwy5X8pJVru9CWVeTpRB51+6wwhgw7Jgz2tnc/Q6/M0ZeWwKvmGZye0Wu78PIGexC6swdGxEnw/q6HOYUkt9DwMwhKxfS6GpY+KPHc45G8+6EYAV7reTjucf/uwUtSmvvTME1wDuISlVTwTqf0RiiyrtKR0tEs6r5l84b645dRkr5zoT8oXwBMHg2Tlke+jbwhj2prW5OlqZPtvkroYqnH3lK9nLgI46scnf8Cn22kBA==)

</div>

---

**Relacionado ao**

- [Referência de API de `<TransitionGroup>`](/api/built-in-components.html#transitiongroup)

---

---
url: /about/community-guide.md
---

# Guia da Comunidade {#community-guide}

A comunidade da Vue está a crescer incrivelmente rápido e se estás a ler isto, existe uma boa possibilidade de estares pronto para juntares-te a ela. Então... bem-vindo ou bem-vinda!

Agora responderemos tanto o que a comunidade pode fazer por ti quanto o que podes fazer pela comunidade.

## Recursos {#resources}

### Código de Conduta {#code-of-conduct}

O nosso [Código de Conduta](/about/coc) é um guia para facilitar enriquecer-nos a todos e as comunidades técnicas nas quais participamos.

### Ficar a Par de Tudo {#stay-in-the-know}

- Siga a nossa [conta da Twitter oficial](https://twitter.com/vuejs).
- Siga os [membros da nossa equipa](./team) na Twitter ou GitHub.
- Siga as [discussões de Pedidos por Comentários](https://github.com/vuejs/rfcs).
- Subscreva-te ao [blogue oficial](https://blog.vuejs.org/).

### Obter Suporte {#get-support}

- [Conversa da Discord](https://discord.com/invite/vue): Um lugar para os programadores de Vue encontrarem-se e conversar em tempo real.
- [Fórum](https://forum.vuejs.org/): O melhor lugar para fazer perguntas e obter respostas sobre a Vue e o seu ecossistema.
- [Comunidade da DEV](https://dev.to/t/vue): Partilhe e discuta tópicos relacionados a Vue na Dev.to.
- [Encontros](https://events.vuejs.org/meetups): Queres encontrar entusiastas de Vue locais como tu? Tens interesse em tornares-te líder comunitário? Nós temos a ajuda e suporte que precisas exatamente aqui!
- [GitHub](https://github.com/vuejs): Se tiveres um erro de programação a relatar ou funcionalidade a pedir, é para isto que as questões da GitHub servem. Ser gentil em respeitar as regras especificadas em cada modelo de questão do repositório.
- [Comunidade da Twitter (não oficial)](https://twitter.com/i/communities/1516368750634840064): Uma comunidade da Twitter, onde podes conhecer outros entusiastas de Vue, receber ajuda, ou apenas conversar sobre a Vue.

### Explorar o Ecossistema {#explore-the-ecosystem}

- [A Página da AwesomeVue](https://github.com/vuejs/awesome-vue): Consulte quais outros recursos fantásticos têm sido publicados por outras pessoas incríveis.
- [Explorador do Telescópio da Vue](https://vuetelescope.com/explore): Explore aplicações de Web feitas com a Vue, com perceções sobre qual a abstração ou bibliotecas usam.
- [Feitas com a Vue.js](https://madewithvuejs.com/): mostruários de projetos e bibliotecas feitas com a Vue.
- [Categoria "Show and Tell" do Fórum da GitHub](https://github.com/vuejs/core/discussions/categories/show-and-tell): Um outro excelente lugar para consultar o que outros construíram com e para o crescimento do ecossistema da Vue.

## O Que Podes Fazer? {#what-you-can-do}

### Ajudar os Outros Utilizadores {#help-fellow-users}

Contribuição de código não é a única forma de contribuição para a comunidade da Vue. Responder uma questão para um colega utilizador da Vue na Discord ou no fórum também é considerado uma contribuição valiosa.

### Ajudar na Triagem de Problemas {#help-triage-issues}

Fazer a triagem de uma questão significa recolher informações em falta, executar a reprodução, verificar a validade da questão, e investigar a causa do problema.

Nós recebemos muitas questões nos [nossos repositórios na GitHub](https://github.com/vuejs) todos os dias. A nossa banda larga é limitada comparada a quantidade de utilizadores que temos, então a triagem de questões pode, por si só, custar um enorme esforço da equipa. Ao ajudar-nos a triar as questões, estás a ajudar-nos a tornar-nos mais eficientes, permitindo-nos investir tempo sobre trabalho de maior prioridade.

Tu não tens de triar uma questão com o objetivo de corrigi-lo (embora que também seria simpático). Partilhar o resultado da tua investigação, por exemplo a consolidação que levou ao erro de programação, já pode economizar-nos muitíssimo tempo.

### Contribuir com Código {#contribute-code}

Contribuir com correções de erro de programação ou novas funcionalidades é a forma mais direta de contribuição que podes fazer.

O repositório principal da Vue fornece um [guia de contribuição](https://github.com/vuejs/core/blob/main/.github/contributing.md), que contém diretrizes de pedido de atualização e informação a respeito da configuração de construção e arquitetura de alto nível. Outros repositórios de subprojeto também pode conter o seu próprio guia de contribuição - certifica-te de lê-los antes de submeter pedidos de atualização de repositório.

As correções de erros de programação são bem-vindas a qualquer momento. Para novas funcionalidades, é melhor discutir o caso de uso e detalhes de implementação primeiro no [repositório RFC](https://github.com/vuejs/rfcs/discussions).

### Partilhar (e Construir) a Tua Experiência {#share-and-build-your-experience}

Para além de responder questões e partilhar recursos no fórum e na conversa, existem algumas outras maneiras menos óbvias de partilhar e expandir o que sabes:

- **Desenvolver materiais de aprendizado.** É frequentemente dito que a melhor maneira de aprender é ensinar. Se existir algo interessante que estiveres a fazer com a Vue, reforçando a tua competência escrevendo uma publicação de blogue, desenvolvendo uma oficina, ou mesmo publicando uma ideia geral que partilhas na media social.
- **Observar um repositório do teu interesse.** Isto enviar-te-á notificações sempre que existir atividade naquele repositório, dando-te conhecimento de alguém de dentro sobre discussões em curso e futuras funcionalidades. É uma maneira fantástica de construir competência para que sejas eventualmente capaz de ajudar abordar questões e pedidos de atualização do repositório.

### Traduzir a Documentação {#translate-docs}

Eu espero que agora mesmo, estejas a ler esta sentença no teu idioma preferido. Se não, gostarias de ajudar-nos a chegar lá?

Consulte o [guia de Traduções](/translations/) por mais detalhes sobre como podes involver-te.

### Tornar-se um Líder Comunitário {#become-a-community-leader}

Há muito que podes fazer para ajudar a Vue a crescer na tua comunidade:

- **Apresentar no teu encontro local.** Quer seja dando uma palestra ou executando uma oficina, podes trazer muito valor para a tua comunidade ajudando tanto novos quanto programadores de Vue mais experientes a continuar a crescer.
- **Começar o teu próprio encontro.** Se já não existir um encontro de Vue na tua zona, podes começar o teu próprio encontro! Use os [recursos na events.vuejs.org](https://events.vuejs.org/resources/#getting-started) para ajudarem-te a ser bem-sucedido!
- **Ajudar organizadores de encontro.** Toda ajuda é pouca no que diz respeito a executar um evento, então ofereça uma mão para ajudar os organizadores locais a ajudar a fazer de todo evento um sucesso.

Se tiveres quaisquer questões sobre como podes involver-te mais com a tua comunidade de Vue local, chame na Twitter em [@vuejs_events](https://www.twitter.com/vuejs_events)!

---

---
url: /style-guide/index.md
---

# Guia de Estilo {#style-guide}

:::warning AVISO DO ESTADO
O guia de estilo está atualmente um pouco desatualizado. A maioria dos exemplos estão apenas na API de Opções, e não existem quaisquer regras relativamente a `<script setup>` e a API de Composição. Nós estamos a planear melhorá-lo no futuro.
:::

Este é o guia de estilo oficial para o código específico de Vue. Se usas a Vue num projeto, é uma grande referência para evitar erros, ciclismo, e anti-padrões. No entanto, não acreditamos que qualquer guia de estilo seja ideal para todas as equipas ou projetos, então desvios cuidadosos são encorajados baseados na experiência passada, a pilha tecnológica circundante, e valores pessoais.

Geralmente, também evitamos sugestões sobre JavaScript ou HTML em geral. Nós não importamos-nos se usas pontos e vírgulas ou vírgulas finais. Nós não importamos-nos se o teu HTML usa aspas simples ou aspas duplas para valores de atributo. No entanto, algumas exceções existirão, onde encontramos este padrão em particular é útil no contexto da Vue.

Finalmente, separamos as regras em quatro categorias:

## Categorias de Regra {#rule-categories}

### Prioridade A: Essencial (Prevenção de Erro) {#priority-a-essential-error-prevention}

Estas regras ajudam prevenir os erros, assim aprenda e acate-os a todo custo. As exceções podem existir, mas devem ser muito raro e apenas ser feitos por aqueles com conhecimento especialista de ambas JavaScript e Vue.

- [Consulte todas as regras de prioridade A](./rules-essential)

### Prioridade B: Fortemente Recomendado {#priority-b-strongly-recommended}

Estas regras tem sido encontradas para melhorar legibilidade ou experiência de programação na maioria dos projetos. O teu código continuarão a executar se violá-los, mas violações devem ser raras e bem justificados.

- [Consulte todas as regras de prioridade B](./rules-strongly-recommended)

### Prioridade C: Recomendado {#priority-c-recommended}

Onde vários, opções igualmente boas existem, uma escolha arbitrária pode ser feita para garantir consistência. Nestas regras, descrevemos cada opção de aceitação e sugerimos uma escolha padrão. Isto significa que podes sentires-te livre para fazer uma escolha diferente na tua própria base de código, enquanto fores consistente e teres uma boa razão. Mesmo assim por favor tenha uma boa razão! Ao adaptar ao padrão da comunidade, tu:

1. Treinarás o teu cérebro para analisar facilmente a maior parte do código da comunidade que encontras.
2. Serás capaz de copiar e colar a maior parte dos exemplos de código da comunidade sem modificação.
3. Frequentemente encontrarás novos contratos que já estão acostumados ao teu estilo de codificação preferido, pelo menos no que diz respeito a Vue.

- [Consulte todas as regras de prioridade C](./rules-recommended)

### Prioridade D: Use com Cautela {#priority-d-use-with-caution}

Algumas funcionalidades da Vue existem para acomodar casos extremos raros ou suavizar as migrações duma base de código legada. Quando usado em excesso, podem tornar o teu código mais difícil de manter ou mesmo tornar-se uma fonte de erros de programação. Estas regras fazem brilhar um luz sobre funcionalidades potencialmente arriscadas, descrevendo quando e o porquê deveriam ser evitadas.

- [Consulte todas as regras de prioridade D](./rules-use-with-caution)

---

---
url: /guide/best-practices/production-deployment.md
---
# Implementação em Produção {#production-deployment}

## Desenvolvimento vs. Produção {#development-vs-production}

Durante o desenvolvimento, a Vue fornece vários recursos para melhorar a experiência de programação:

- Avisos para erros comuns e armadilhas
- Propriedades / validação de eventos
- [Gatilhos de depuração da reatividade](/guide/extras/reactivity-in-depth.html#reactivity-debugging)
- Integração com ferramentas de programação

No entanto, estas funcionalidades tornam-se inúteis em produção. Algumas das verificações de alerta também podem gerar uma pequena sobrecarga de desempenho. Ao implementar em produção, devemos eliminar todas as ramificações de código escritos para executar apenas em desenvolvimento e não usados em produção, para obter um tamanho de carga útil menor e um melhor desempenho.

## Sem Ferramentas de Construção {#without-build-tools}

Se estiver usando a Vue sem uma ferramenta de construção carregando-a a partir da CDN ou programa hospedado de maneira autónoma, certifique-se de usar o pacote de produção (ficheiros de distribuição que terminam em `.prod.js`) quando estiver a implementar a aplicação em produção. Os pacotes de produção são pré-minificados onde têm todos os ramos de código escrito para ser apenas usado em desenvolvimento removido.

- Se estiver usando o pacote global (acessando através da global `Vue`): use `vue.global.prod.js`.
- Se estiver usando o pacote de Módulo de ECMAScript (acessando através de importações de Módulo de ECMAScript nativas): use `vue.esm-browser.prod.js`.

Consulte o [guia do ficheiro de distribuição](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use) para mais detalhes.

## Com Ferramentas de Construção {#with-build-tools}

Os projetos estruturados via `create-vue` (baseado em Vite) ou a Interface de Linha de Comando da Vue (baseada na Webpack) são pré-configuradas para construções de produção.

Se estiver usando uma configuração personalizada, certifique-se de que:

1. `vue` resolve para `vue.runtime.esm-bundler.js`.
2. As [opções da funcionalidade de tempo de compilação](https://github.com/vuejs/core/tree/main/packages/vue#bundler-build-feature-flags) são configuradas apropriadamente.
3. <code>process.env<wbr>.NODE_ENV</code> é substítuido com a `"production"` durante a construção.

Referências adicionais:

- [Guia de construção de produção da Vite](https://vitejs.dev/guide/build.html)
- [Guia de implementação em produção da Vite](https://vitejs.dev/guide/static-deploy.html)
- [Guia de implementação em produção da Vue CLI](https://cli.vuejs.org/guide/deployment.html)

## Rastreando erros em Tempo de Execução {#tracking-runtime-errors}

O [manipulador de erro de nível da aplicação](/api/application.html#app-config-errorhandler) pode ser usado para comunicar os erros aos serviços de rastreamento:

```js
import { createApp } from 'vue'

const app = createApp(...)

app.config.errorHandler = (err, instance, info) => {
  // comunicar erro aos serviços de rastreio
}
```

Serviços como [Sentry](https://docs.sentry.io/platforms/javascript/guides/vue/) e [Bugsnag](https://docs.bugsnag.com/platforms/javascript/vue/) também fornecem integrações oficiais para Vue.

---

---
url: /api/component-instance.md
---
# Instância do Componente {#component-instance}

:::info
Esta página documenta as propriedades e os métodos embutidos expostos na instância pública do componente, por exemplo, `this`.

Todas as propriedades listadas nesta página são de apenas leitura (exceto propriedades encaixadas na `$data`).
:::

## `$data` {#data}

O objeto retornado a partir da opção [`data`](./options-state#data), tornado reativo pelo componente. A instância do componente delega o acesso às propriedades sobre o seu objeto de dados.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $data: object
  }
  ```

## `$props` {#props}

Um objeto que representa as propriedades atuais e resolvidas do componente.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $props: object
  }
  ```

- **Detalhes**

  Apenas as propriedades declarados através da opção [`props`](./options-state#props) serão incluídas. A instância do componente delega o acesso às propriedades sobre o seu objeto de propriedades.

## `$el` {#el}

O nó de DOM de raiz que a instância do componente está gerir.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $el: Node | undefined
  }
  ```

- **Detalhes**

  `$el` será `undefined` até o component ser [montado](./options-lifecycle#mounted).

  - Para componentes com um único elemento de raiz, `$el` apontará para este elemento.
  - Para componentes com raiz de texto, `$el` apontará para o nó de texto.
  - Para componentes com vários nós de raiz, `$el` será o nó de DOM de espaço reservado que a Vue usa para continuar a rastrear a posição do componente no DOM (um nó de texto ou um nó de comentário no modo de hidratação da interpretação no lado do servidor).

  :::tip DICA
  Por questões consistência, é recomendado usar [referências de modelo de marcação](/guide/essentials/template-refs) para o acesso direto aos elementos em vez de depender de `$el`.
  :::

## `$options` {#options}

As opções de componente resolvidas usadas para instanciar a instância do componente atual.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $options: ComponentOptions
  }
  ```

- **Detalhes**

  O objeto `$options` expõe as opções resolvidas para o componente atual e é o resultado da combinação destas possíveis fontes:

  - Misturas globais
  - Base de `extends` do componente
  - Misturas do componente

  É normalmente usado para suportar opções de componente personalizadas:

  ```js
  const app = createApp({
    customOption: 'foo',
    created() {
      console.log(this.$options.customOption) // => 'foo'
    }
  })
  ```

- **Consulte também:** [`app.config.optionMergeStrategies`](/api/application#app-config-optionmergestrategies)

## `$parent` {#parent}

A instância pai, se a instância atual tiver uma. Será `null` para a própria instância de raiz.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $parent: ComponentPublicInstance | null
  }
  ```

## `$root` {#root}

A instância do componente de raiz da árvore do componente atual. Se a instância atual não tiver pais, este valor será ele próprio.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $root: ComponentPublicInstance
  }
  ```

## `$slots` {#slots}

Um objeto que representa as [ranhuras](/guide/components/slots) passadas pelo componente pai.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $slots: { [name: string]: Slot }
  }

  type Slot = (...args: any[]) => VNode[]
  ```

- **Detalhes**

  Normalmente usada quando escrevemos manualmente [funções de interpretação](/guide/extras/render-function), mas também pode ser usada para detetar se uma ranhura está presente.

  Cada ranhura é exposta sobre `this.$slots` como uma função que retorna um vetor de nós virtuais sob a chave correspondendo ao nome daquela ranhura. A ranhura padrão é exposta como `this.$slots.default`.

  Se uma ranhura for uma [ranhura isolada](/guide/components/slots#scoped-slots), os argumentos passados às funções da ranhura estão disponíveis à ranhura como suas propriedades de ranhura.

- **Consulte também:** [Funções de Interpretação - Interpretação de Ranhuras](/guide/extras/render-function#rendering-slots)

## `$refs` {#refs}

Um objeto de elementos de DOM e as instâncias de componente, registadas através das [referências do modelo de marcação](/guide/essentials/template-refs).

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $refs: { [name: string]: Element | ComponentPublicInstance | null }
  }
  ```

- **Consulte também:**

  - [Referências do Modelo de Marcação](/guide/essentials/template-refs)
  - [Atributos Especiais - `ref`](./built-in-special-attributes#ref)

## `$attrs` {#attrs}

Um objeto que contém os atributos de passagem do componente.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $attrs: object
  }
  ```

- **Detalhes**

  [Atributos de Passagem](/guide/components/attrs) são atributos e manipuladores de eventos passados ​​pelo componente pai, mas não declarados como uma propriedade ou um evento emitido pelo filho.

  Por padrão, tudo na `$attrs` será herdado automaticamente no elemento de raiz do componente se houver apenas um único elemento de raiz. Este comportamento é desativado se o componente tiver vários nós de raiz e pode ser explicitamente desativado com a opção [`inheritAttrs`](./options-misc#inheritattrs).

- **Consulte também:**

  - [Atributos de Passagem](/guide/components/attrs)

## `$watch()` {#watch}

API imperativa para criar observadores.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $watch(
      source: string | (() => any),
      callback: WatchCallback,
      options?: WatchOptions
    ): StopHandle
  }

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  interface WatchOptions {
    immediate?: boolean // predefinida como: false
    deep?: boolean // predefinida como: false
    flush?: 'pre' | 'post' | 'sync' // predefinida como: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }

  type StopHandle = () => void
  ```

- **Detalhes**

  O primeiro argumento é a fonte do observador. Pode ser uma sequência de caracteres do nome da propriedade do componente, uma simples sequência de caracteres do caminho delimitada por ponto, ou uma função recuperadora.

  O segundo argumento é a função de resposta. A função de resposta recebe o novo valor e o valor antigo da fonte observada.

  - **`immediate`**: aciona a função de resposta imediatamente na criação do observador. O valor antigo será `undefined` na primeira chamada.
  - **`deep`**: força a travessia profunda da fonte se for um objeto, para que a função de resposta dispare sobre as mutações profundas. Consulte [Observadores Profundos](/guide/essentials/watchers#deep-watchers).
  - **`flush`**: ajusta o tempo de descarga da função de resposta. Consulte [Tempo de Descarga da Função de Resposta](/guide/essentials/watchers#callback-flush-timing) e [`watchEffect()`](/api/reactivity-core#watcheffect).
  - **`onTrack / onTrigger`**: depura as dependências do observador. Consulte [Depuração do Observador](/guide/extras/reactivity-in-depth#watcher-debugging).

- **Exemplo**

  Observar um nome de propriedade:

  ```js
  this.$watch('a', (newVal, oldVal) => {})
  ```

  Observar um caminho delimitado por ponto:

  ```js
  this.$watch('a.b', (newVal, oldVal) => {})
  ```

  Usar função recuperadora para expressões mais complexas:

  ```js
  this.$watch(
    // sempre que a expressão `this.a + this.b` retornar
    // um resultado diferente, o manipulador será chamado.
    // É como se estivéssemos observando uma propriedade computada
    // sem definir a própria propriedade computada.
    () => this.a + this.b,
    (newVal, oldVal) => {}
  )
  ```

  Parar o observador:

  ```js
  const unwatch = this.$watch('a', cb)

  // depois...
  unwatch()
  ```

- **Consulte também:**
  - [Opções - `watch`](/api/options-state#watch)
  - [Guia - Observadores](/guide/essentials/watchers)

## `$emit()` {#emit}

Aciona um evento personalizado na instância atual. Quaisquer argumentos adicionais serão passados à função de resposta do ouvinte.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $emit(event: string, ...args: any[]): void
  }
  ```

- **Exemplo**

  ```js
  export default {
    created() {
      // único evento
      this.$emit('foo')
      // com argumentos adicionais
      this.$emit('bar', 1, 2, 3)
    }
  }
  ```

- **Consulte também:**

  - [Componente - Eventos](/guide/components/events)
  - [Opção `emits`](./options-state#emits)

## `$forceUpdate()` {#forceupdate}

Força a instância do componente à desenhar novamente

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $forceUpdate(): void
  }
  ```

- **Detalhes**

  Isto deve ser raramente necessário dado o sistema de reatividade totalmente automático da Vue. Os únicos casos em que podemos precisar dela é quando críamos explicitamente um estado de componente que não é reativo usando APIs de reatividade avançadas.

## `$nextTick()` {#nexttick}

Versão vinculada à instância da [`nextTick()`](./general#nexttick) global.

- **Tipo**

  ```ts
  interface ComponentPublicInstance {
    $nextTick(callback?: (this: ComponentPublicInstance) => void): Promise<void>
  }
  ```

- **Detalhes**

  A única diferença da versão global de `nextTick()` é que a função de resposta passada à `this.$nextTick()` terá o seu contexto `this` vinculado à instância do componente atual.

- **Consulte também:** [`nextTick()`](./general#nexttick)

---

---
url: /guide/essentials/conditional.md
---
# Interpretação Condicional {#conditional-rendering}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/conditional-rendering-in-vue-3" title="Aula Gratuita de Interpretação Condicional da Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-conditionals-in-vue" title="Aula Gratuita de Interpretação Condicional da Vue.js"/>
</div>

<script setup>
import { ref } from 'vue'
const awesome = ref(true)
</script>

## `v-if` {#v-if}

A diretiva `v-if` é usada para interpretar um bloco condicionalmente. O bloco apenas será interpretado se a expressão da diretiva retornar um valor verdadeiro:

```vue-html
<h1 v-if="awesome">Vue is awesome!</h1>
```

## `v-else` {#v-else}

Nós podemos usar a diretiva `v-else` para indicar um "bloco `else`" à `v-if`:

```vue-html
<button @click="awesome = !awesome">Toggle</button>

<h1 v-if="awesome">Vue is awesome!</h1>
<h1 v-else>Oh no 😢</h1>
```

<div class="demo">
  <button @click="awesome = !awesome">Toggle</button>
  <h1 v-if="awesome">Vue is awesome!</h1>
  <h1 v-else>Oh no 😢</h1>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpFjkEOgjAQRa8ydIMulLA1hegJ3LnqBskAjdA27RQXhHu4M/GEHsEiKLv5mfdf/sBOxux7j+zAuCutNAQOyZtcKNkZbQkGsFjBCJXVHcQBjYUSqtTKERR3dLpDyCZmQ9bjViiezKKgCIGwM21BGBIAv3oireBYtrK8ZYKtgmg5BctJ13WLPJnhr0YQb1Lod7JaS4G8eATpfjMinjTphC8wtg7zcwNKw/v5eC1fnvwnsfEDwaha7w==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpFjj0OwjAMha9iMsEAFWuVVnACNqYsoXV/RJpEqVOQqt6DDYkTcgRSWoplWX7y56fXs6O1u84jixlvM1dbSoXGuzWOIMdCekXQCw2QS5LrzbQLckje6VEJglDyhq1pMAZyHidkGG9hhObRYh0EYWOVJAwKgF88kdFwyFSdXRPBZidIYDWvgqVkylIhjyb4ayOIV3votnXxfwrk2SPU7S/PikfVfsRnGFWL6akCbeD9fLzmK4+WSGz4AA5dYQY=)

</div>

Um elemento `v-else` deve seguir imediatamente um elemento `v-if` ou `v-else-if` - de outro modo não será reconhecido.

## `v-else-if` {#v-else-if}

A diretiva `v-else-if`, como o nome sugere, serve como um "bloco `else if`" à `v-if`. Esta também pode ser encadeada várias vezes:

```vue-html
<div v-if="type === 'A'">
  A
</div>
<div v-else-if="type === 'B'">
  B
</div>
<div v-else-if="type === 'C'">
  C
</div>
<div v-else>
  Not A/B/C
</div>
```

Semelhante à `v-else`, um elemento `v-else-if` deve seguir imediatamente um elemento `v-if` ou um `v-else-if`.

## `v-if` no `<template>` {#v-if-on-template}

Uma vez que a `v-if` é uma diretiva, esta precisa ser atribuída a um único elemento. Porém, e se quiséssemos alternar mais que um elemento? Neste caso podemos usar a `v-if` sobre um elemento `<template>`, que serve como um embrulhador invisível. O resultado final interpretado não incluirá o elemento `<template>`:

```vue-html
<template v-if="ok">
  <h1>Title</h1>
  <p>Paragraph 1</p>
  <p>Paragraph 2</p>
</template>
```

A `v-else` e a `v-else-if` também podem ser usadas sobre o `<template>`.

## `v-show` {#v-show}

Uma outra opção para exibir condicionalmente um elemento é a diretiva `v-show`. O uso é maioritariamente o mesmo:

```vue-html
<h1 v-show="ok">Hello!</h1>
```

A diferença é que um elemento com a `v-show` sempre será interpretado e permanecerá no DOM; A `v-show` apenas alterna a propriedade de CSS `display` do elemento.

A `v-show` não suporta o elemento `<template>`, nem funciona com a `v-else`.

## `v-if` vs `v-show` {#v-if-vs-v-show}

A `v-if` é a interpretação condicional "verdadeira" porque esta garante que os ouvintes de evento e componentes filhos dentro do bloco condicional sejam destruídos corretamente e recriados durante as alternâncias.

A `v-if` também é **preguiçosa**: se a condição for falsa na interpretação inicial, esta não fará nada - o bloco condicional não será interpretado até a condição tornar-se verdadeira pela primeira vez.

Em comparação, a `v-show` é muito mais simples - o elemento é sempre interpretado independentemente da condição inicial, com alternância baseada em CSS.

Dum modo geral, a `v-if` tem custos de alternância mais elevados enquanto a `v-show` tem custos de interpretação inicial mais elevados. Então devemos preferir a `v-show` se precisarmos de alternar algo com muita frequência, e devemos preferir `v-if` se for pouco provável que a condição se altere em execução.

## `v-if` com `v-for` {#v-if-with-v-for}

:::warning AVISO
**Não** é recomendado usar a `v-if` e `v-for` sobre o mesmo elemento devido à precedência implícita. Consultar o [guia de estilo](/style-guide/rules-essential#avoid-v-if-with-v-for) por detalhes.
:::

Quando a `v-if` e a `v-for` forem ambas usadas sobre o mesmo elemento, a `v-if` será avaliada primeiro. Consultar o [guia de interpretação de lista](list#v-for-with-v-if) por detalhes.

---

---
url: /guide/essentials/list.md
---
# Interpretação de Lista {#list-rendering}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/list-rendering-in-vue-3" title="Aula Gratuida Sobre Interpretação de Lista em Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-list-rendering-in-vue" title="Aula Gratuida Sobre Interpretação de Lista em Vue.js"/>
</div>

## `v-for` {#v-for}

Nós podemos utilizar a diretiva `v-for` para interpretar uma lista de itens baseados em um arranjo. A diretiva `v-for` exije uma sintaxe especial na forma de `item in items`, onde `items` é o arranjo de dados de origem e o `item` é um **pseudónimo** para o elemento do arranjo sobre qual é interado:

<div class="composition-api">

```js
const items = ref([{ message: 'Foo' }, { message: 'Bar' }])
```

</div>

<div class="options-api">

```js
data() {
  return {
    items: [{ message: 'Foo' }, { message: 'Bar' }]
  }
}
```

</div>

```vue-html
<li v-for="item in items">
  {{ item.message }}
</li>
```

Dentro do escopo de `v-for`, as expressões do modelo de marcação tem acesso a todas propriedades do escopo do pai. Além disto, a `v-for` também suporta um segundo pseudónimo opcional para índice do item atual:

<div class="composition-api">

```js
const parentMessage = ref('Parent')
const items = ref([{ message: 'Foo' }, { message: 'Bar' }])
```

</div>
<div class="options-api">

```js
data() {
  return {
    parentMessage: 'Parent',
    items: [{ message: 'Foo' }, { message: 'Bar' }]
  }
}
```

</div>

```vue-html
<li v-for="(item, index) in items">
  {{ parentMessage }} - {{ index }} - {{ item.message }}
</li>
```

<script setup>
const parentMessage = 'Parent'
const items = [{ message: 'Foo' }, { message: 'Bar' }]
</script>
<div class="demo">
  <li v-for="(item, index) in items">
    {{ parentMessage }} - {{ index }} - {{ item.message }}
  </li>
</div>

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpdTsuqwjAQ/ZVDNlFQu5d64bpwJ7g3LopOJdAmIRlFCPl3p60PcDWcM+eV1X8Iq/uN1FrV6RxtYCTiW/gzzvbBR0ZGpBYFbfQ9tEi1ccadvUuM0ERyvKeUmithMyhn+jCSev4WWaY+vZ7HjH5Sr6F33muUhTR8uW0ThTuJua6mPbJEgGSErmEaENedxX3Z+rgxajbEL2DdhR5zOVOdUSIEDOf8M7IULCHsaPgiMa1eK4QcS6rOSkhdfapVeQLQEWnH)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpVTssKwjAQ/JUllyr0cS9V0IM3wbvxEOxWAm0a0m0phPy7m1aqhpDsDLMz48XJ2nwaUZSiGp5OWzpKg7PtHUGNjRpbAi8NQK1I7fbrLMkhjc5EJAn4WOXQ0BWHQb2whOS24CSN6qjXhN1Qwt1Dt2kufZ9ASOGXOyvH3GMNCdGdH75VsZVjwGa2VYQRUdVqmLKmdwcpdjEnBW1qnPf8wZIrBQujoff/RSEEyIDZZeGLeCn/dGJyCSlazSZVsUWL8AYme21i)

</div>

O escopo de variável da `v-for` é similar ao seguinte código de JavaScript:

```js
const parentMessage = 'Parent'
const items = [
  /* ... */
]

items.forEach((item, index) => {
  // tem acesso ao `parentMessage` do escopo externo 
  // mas `item` e `index` apenas estão disponíveis aqui
  console.log(parentMessage, item.message, index)
})
```

Repare como o valor de `v-for` corresponde a assinatura de função da resposta de `forEach`. Na realidade, podes utilizar a desestruturação no pseudónimo do item de `v-for` similar a desestruturação de argumentos de função:

```vue-html
<li v-for="{ message } in items">
  {{ message }}
</li>

<!-- with index alias -->
<!-- com o pseudónimo de índice ("index") -->
<li v-for="({ message }, index) in items">
  {{ message }} {{ index }}
</li>
```

Para `v-for` encaixados, o escopo também funciona de maneira similar as funções encaixadas. Cada escope de `v-for` em acesso aos escopos pai:

```vue-html
<li v-for="item in items">
  <span v-for="childItem in item.children">
    {{ item.message }} {{ childItem }}
  </span>
</li>
```

Tu também podes utilizar `of` como delimitador no lugar de `in`, para que esteja mais próximo da sintaxe da JavaScript para iteradores:

```vue-html
<div v-for="item of items"></div>
```

## `v-for` com um Objeto {#v-for-with-an-object}

Tu também podes utilizar a `v-for` para iterar através das propriedades de um objeto. A ordem de iteração será baseada no resultado da chamada de `Object.keys()` sobre o objeto:

<div class="composition-api">

```js
const myObject = reactive({
  title: 'How to do lists in Vue',
  author: 'Jane Doe',
  publishedAt: '2016-04-10'
})
```

</div>
<div class="options-api">

```js
data() {
  return {
    myObject: {
      title: 'How to do lists in Vue',
      author: 'Jane Doe',
      publishedAt: '2016-04-10'
    }
  }
}
```

</div>

```vue-html
<ul>
  <li v-for="value in myObject">
    {{ value }}
  </li>
</ul>
```

Tu também podes fornecer um segundo pseudónimo para o nome da propriedade (também conhecido como chave):

```vue-html
<li v-for="(value, key) in myObject">
  {{ key }}: {{ value }}
</li>
```

E um outro para o índice:

```vue-html
<li v-for="(value, key, index) in myObject">
  {{ index }}. {{ key }}: {{ value }}
</li>
```

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNo9jjFvgzAQhf/KE0sSCQKpqg7IqRSpQ9WlWycvBC6KW2NbcKaNEP+9B7Tx4nt33917Y3IKYT9ESspE9XVnAqMnjuFZO9MG3zFGdFTVbAbChEvnW2yE32inXe1dz2hv7+dPqhnHO7kdtQPYsKUSm1f/DfZoPKzpuYdx+JAL6cxUka++E+itcoQX/9cO8SzslZoTy+yhODxlxWN2KMR22mmn8jWrpBTB1AZbMc2KVbTyQ56yBkN28d1RJ9uhspFSfNEtFf+GfnZzjP/oOll2NQPjuM4xTftZyIaU5VwuN0SsqMqtWZxUvliq/J4jmX4BTCp08A==)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNo9T8FqwzAM/RWRS1pImnSMHYI3KOwwdtltJ1/cRqXe3Ng4ctYS8u+TbVJjLD3rPelpLg7O7aaARVeI8eS1ozc54M1ZT9DjWQVDMMsBoFekNtucS/JIwQ8RSQI+1/vX8QdP1K2E+EmaDHZQftg/IAu9BaNHGkEP8B2wrFYxgAp0sZ6pn2pAeLepmEuSXDiy7oL9gduXT+3+pW6f631bZoqkJY/kkB6+onnswoDw6owijIhEMByjUBgNU322/lUWm0mZgBX84r1ifz3ettHmupYskjbanedch2XZRcAKTnnvGVIPBpkqGqPTJNGkkaJ5+CiWf4KkfBs=)

</div>

## `v-for` com um Limite {#v-for-with-a-range}

A `v-for` também pode aceitar um inteiro. Neste caso repetirá o modelo de marcação que aquelas muitas vezes, baseado em um limite de `1...n`.

```vue-html
<span v-for="n in 10">{{ n }}</span>
```

Nota que aqui `n` começa com um valor inicial de `1` no lugar de `0`.

## `v-for` no `<template>` {#v-for-on-template}

Semelhante a `v-if` do modelo de marcação, também podes utilizar o marcador `<template>` para interpretar um bloco com vários elementos. Por exemplo:

```vue-html
<ul>
  <template v-for="item in items">
    <li>{{ item.msg }}</li>
    <li class="divider" role="presentation"></li>
  </template>
</ul>
```

## `v-for` com `v-if` {#v-for-with-v-if}

:::warning AVISO
**Não** é recomendado utilizar `v-if` e `v-for` no mesmo elemento devido a precedência implicita. Consulte o [guia de estilo](/style-guide/rules-essential#avoid-v-if-with-v-for) para obter mais detalhes.
:::

Quando elas existem no mesmo nó, a `v-if` tem uma prioridade mais alta do que a `v-for`. Que significa que a condição `v-if` não terá acesso as variáveis do escope do `v-for`:

```vue-html
<!--
Isto lançará um erro porque a propriedade "todo"
não está definida na instância
-->
<li v-for="todo in todos" v-if="!todo.isComplete">
  {{ todo.name }}
</li>
```

Isto pode ser corrigido movendo `v-for` para um marcodor `<template>` de embrulho (que também é mais explicito):

```vue-html
<template v-for="todo in todos">
  <li v-if="!todo.isComplete">
    {{ todo.name }}
  </li>
</template>
```

## Mantendo o Estado com `key` {#maintaining-state-with-key}

Quando a Vue está atualizando um lista de elementos interpretados com a `v-for`, por padrão ela utiliza uma estratégia de "remendar no lugar (in-place patch)". Se a ordem dos itens de dados mudou, no lugar de mover os elementos do DOM para corresponder a ordem dos itens, a Vue remendará cada elemento no lugar e certificar-se de que ela refleta o que deveria ser interpretado naquele índice particular.

Este modo padrão é eficiente, mas **só é adequando quando o resultado da interpretação da tua lista não depender do estado do componente filho ou do estado temporário do DOM (por exemplo, valores de entrada de formulário)**.

Para dar a Vue uma sugestão para que ela possa rastreiar qualquer identidade do nó, e assim reutilizar e reorganizar os elementos existente, precisas fornecer um atributo `key` único para cada item:

```vue-html
<div v-for="item in items" :key="item.id">
  <!-- content -->
  <!-- conteúdo -->
</div>
```

Quando estiveres utilizando `<template v-for>`, o `key` deve ser colocado no contentor `<template>`:

```vue-html
<template v-for="todo in todos" :key="todo.name">
  <li>{{ todo.name }}</li>
</template>
```

:::tip NOTA
Aqui `key` é um atributo especial sendo vinculado com a `v-bind`. Ela não deveria ser confundida com a variável chave (`key`) de propriedade quando estiveres [utilizando a `v-for` com um objeto](#v-for-with-an-object).
:::

[É recomendado](/style-guide/rules-essential#use-keyed-v-for) fornecer um atributo `key` com a `v-for` sempre que possível, a menos que o conteúdo de DOM iterado seja simples (por exemplo, não contém quaisquer componentes ou elementos de DOM com conteúdo), estás intencionalmente confiando no comportamento padrão para ganhos de desempenho.

O vinculação de `key` aguarda por valores primitivos - por exemplo, sequências de caracteres e números. Não utilize objetos como chaves de `v-for`. Para utilização detalhada do atributo `key`, favor de consultar a [documentação da API de `key`](/api/built-in-special-attributes#key).

## `v-for` com um Componente {#v-for-with-a-component}

> Esta secção presume conhecimento de [Componentes](/guide/essentials/component-basics). Esteja livre para ignorá-la e voltar mais tarde.

Tu podes utilizar a `v-for` diretamente sobre um componente, tal como qualquer elemento normal (não te esqueças de fornecer um `key`):

```vue-html
<MyComponent v-for="item in items" :key="item.id" />
```

No entanto, isto não passará quaisquer dados automaticamente para o componente, porque os componentes têm seus próprios escopos isolados. Para passar o dado iterado para dentro do componente, também devemos utilizar as propriedades:

```vue-html
<MyComponent
  v-for="(item, index) in items"
  :item="item"
  :index="index"
  :key="item.id"
/>
```

A razão para não injetar automaticamte o `item` para dentro do componente é porque isto torna o componente fortemente acoplado à como a `v-for` funciona. Ser explicito a respeito de onde os teus dados vem torna o componente reutilizável em outras situações.

<div class="composition-api">

Consulte [este exemplo de uma lista de afazeres simples](https://play.vuejs.org/#eNp1U8Fu2zAM/RXCGGAHTWx02ylwgxZYB+ywYRhyq3dwLGYRYkuCJTsZjPz7KMmK3ay9JBQfH/meKA/Rk1Jp32G0jnJdtVwZ0Gg6tSkEb5RsDQzQ4h4usG9lAzGVxldoK5n8ZrAZsTQLCduRygAKUUmhDQg8WWyLZwMPtmESx4sAGkL0mH6xrMH+AHC2hvuljw03Na4h/iLBHBAY1wfUbsTFVcwoH28o2/KIIDuaQ0TTlvrwNu/TDe+7PDlKXZ6EZxTiN4kuRI3W0dk4u4yUf7bZfScqw6WAkrEf3m+y8AOcw7Qv6w5T1elDMhs7Nbq7e61gdmme60SQAvgfIhExiSSJeeb3SBukAy1D1aVBezL5XrYN9Csp1rrbNdykqsUehXkookl0EVGxlZHX5Q5rIBLhNHFlbRD6xBiUzlOeuZJQz4XqjI+BxjSSYe2pQWwRBZizV01DmsRWeJA1Qzv0Of2TwldE5hZRlVd+FkbuOmOksJLybIwtkmfWqg+7qz47asXpSiaN3lxikSVwwfC8oD+/sEnV+oh/qcxmU85mebepgLjDBD622Mg+oDrVquYVJm7IEu4XoXKTZ1dho3gnmdJhedEymn9ab3ysDPdc4M9WKp28xE5JbB+rzz/Trm3eK3LAu8/E7p2PNzYM/i3ChR7W7L7hsSIvR7L2Aal1EhqTp80vF95sw3WcG7r8A0XaeME=) para veres como interpretar uma lista de componentes utilizando a `v-for`, passando diferentes dados para cada instância.

</div>
<div class="options-api">

Consulte [este exemplo de uma lista de afazeres simples](https://play.vuejs.org/#eNqNVE2PmzAQ/SsjVIlEm4C27Qmx0a7UVuqhPVS5lT04eFKsgG2BSVJF+e8d2xhIu10tihR75s2bNx9wiZ60To49RlmUd2UrtNkUUjRatQa2iquvBhvYt6qBOEmDwQbEhQQoJJ4dlOOe9bWBi7WWiuIlStNlcJlYrivr5MywxdIDAVo0fSvDDUDiyeK3eDYZxLGLsI8hI7H9DHeYQuwjeAb3I9gFCFMjUXxSYCoELroKO6fZP17Mf6jev0i1ZQcE1RtHaFrWVW/l+/Ai3zd1clQ1O8k5Uzg+j1HUZePaSFwfvdGhfNIGTaW47bV3Mc6/+zZOfaaslegS18ZE9121mIm0Ep17ynN3N5M8CB4g44AC4Lq8yTFDwAPNcK63kPTL03HR6EKboWtm0N5MvldtA8e1klnX7xphEt3ikTbpoYimsoqIwJY0r9kOa6Ag8lPeta2PvE+cA3M7k6cOEvBC6n7UfVw3imPtQ8eiouAW/IY0mElsiZWqOdqkn5NfCXxB5G6SJRvj05By1xujpJWUp8PZevLUluqP/ajPploLasmk0Re3sJ4VCMnxvKQ//0JMqrID/iaYtSaCz+xudsHjLpPzscVGHYO3SzpdixIXLskK7pcBucnTUdgg3kkmcxhetIrmH4ebr8m/n4jC6FZp+z7HTlLsVx1p4M7odcXPr6+Lnb8YOne5+C2F6/D6DH2Hx5JqOlCJ7yz7IlBTbZsf7vjXVBzjvLDrH5T0lgo=) para veres como interpretar uma lista de componentes utilizando a `v-for`, passando diferentes dados para cada instância.

</div>

## Deteção de Mudança de Arranjo {#array-change-detection}

### Métodos de Mutação {#mutation-methods}

A Vue é capaz de detetar quando métodos de mutação de um arranjo reativo são chamados e aciona as atualizações necessárias. Estes métodos de mutação são:

- `push()`
- `pop()`
- `shift()`
- `unshift()`
- `splice()`
- `sort()`
- `reverse()`

### Substituindo um Arranjo {#replacing-an-array}

Os métodos de mutação, como o nome sugere, alteram o arranjo original sobre o qual eles são chamados. Em comparação, também existem métodos que não realizam mutação, por exemplo, `filter()`, `concat()` e `slice()`, que não alteram o arranjo original mas **sempre retornam um arranjo novo**. Quando estivermos trabalhando como métodos que não realizam mutação, devemos substituir o arranjo antigo com o arranjo novo:

<div class="composition-api">

```js
// `items` é uma referência com valor de arranjo
items.value = items.value.filter((item) => item.message.match(/Foo/))
```

</div>
<div class="options-api">

```js
this.items = this.items.filter((item) => item.message.match(/Foo/))
```

</div>

Tu podes achar que isto fará a Vue deixar fora o DOM existente e reinterpretar a lista inteira - felizmente, este não é o caso. A Vue implementa algumas heurísticas inteligentes para maximizar a reutilização do elemento do DOM, assim substituir um arranjo com um outro arranjo contendo objetos que se sobrepõem é uma operação muito eficiente.

## Exibindo Resultados Filtrados ou Organizados {#displaying-filtered-sorted-results}

Algumas vezes queremos exibir uma versão filtrada ou organizada de um arranjo sem alterar ou redefinir os dados originais. Neste caso, podes criar uma propriedade computada que retorna o arranjo filtrado ou organizado. 

Por exemplo:

<div class="composition-api">

```js
const numbers = ref([1, 2, 3, 4, 5])

const evenNumbers = computed(() => {
  return numbers.value.filter((n) => n % 2 === 0)
})
```

</div>
<div class="options-api">

```js
data() {
  return {
    numbers: [1, 2, 3, 4, 5]
  }
},
computed: {
  evenNumbers() {
    return this.numbers.filter(n => n % 2 === 0)
  }
}
```

</div>

```vue-html
<li v-for="n in evenNumbers">{{ n }}</li>
```

Em situações onde as propriedades computadas não são viáveis (por exemplo, dentro de laços `v-for` encaixados), podes utilizar um método:

<div class="composition-api">

```js
const sets = ref([
  [1, 2, 3, 4, 5],
  [6, 7, 8, 9, 10]
])

function even(numbers) {
  return numbers.filter((number) => number % 2 === 0)
}
```

</div>
<div class="options-api">

```js
data() {
  return {
    sets: [[ 1, 2, 3, 4, 5 ], [6, 7, 8, 9, 10]]
  }
},
methods: {
  even(numbers) {
    return numbers.filter(number => number % 2 === 0)
  }
}
```

</div>

```vue-html
<ul v-for="numbers in sets">
  <li v-for="n in even(numbers)">{{ n }}</li>
</ul>
```

Tenha cuidado com `reverse()` e `sort()` dentro de uma propriedade computada! Estes dois métodos alterarão o arranjo original, o que deve ser evitado nos recuperadores computados. Crie uma copia do arranjo original antes de chamar estes métodos:

```diff
- return numbers.reverse()
+ return [...numbers].reverse()
```

---

---
url: /guide/scaling-up/ssr.md
---

# Interpretação no Lado do Servidor (SSR) {#server-side-rendering-ssr}

## Visão Geral {#overview}

### O que é SSR? {#what-is-ssr}

Vue.js é uma abstração para a construção de aplicações no lado do cliente. Por padrão, os componentes de Vue produzem e manipulam o DOM no navegador como resultado. No entanto, também é possível interpretar no servidor os mesmos componentes em strings HTML, enviá-los diretamente para o navegador, e finalmente "hidratar" a marcação estática para uma aplicação completamente interativa no cliente.

Uma aplicação Vue.js interpretada no servidor também pode ser considerada "isomórfica" ou "universal", no sentido que a maioria do código da aplicação executa no servidor **e** também no cliente.

### Por que SSR? {#why-ssr}

Comparado a uma Aplicação de Página Única (SPA, sigla em inglês) do lado do cliente, a vantagem de SSR primeiramente encontra-se em:

- **Carregamento mais rápido**: isto é mais proeminente em dispositivos lentos ou em conexões lentas. A marcação gerada pelo servidor não precisa esperar até que todo o JavaScript seja carregado e executado para ser mostrada, assim o usuário verá uma página completamente gerada mais cedo. Além disto, a requisição de dados é feita no lado do servidor para a visita inicial, que provavelmente tem uma conexão mais rápida à base de dados do que o cliente. Isto geralmente resulta em melhores métricas [Core Web Vitals](https://web.dev/vitals/), melhor experiência de usuário, e pode ser crítico para aplicações onde o tempo de carregamento está diretamente associado com a taxa de conversão.

- **Modelo mental unificado**: pode-se usar a mesma linguagem e o mesmo modelo mental declarativo e orientado ao componente para o desenvolvimento de toda a aplicação, ao invés de ficar para lá e para cá entre um sistema de criação de modelos de marcação backend e uma abstração frontend.

- **SEO Melhor**: os rastreaedores dos motores de busca enxergarão a página completamente interpretada de maneira direta.

  :::tip DICA
  Neste momento, Google e Bing podem indexar aplicações de JavaScript síncronas muito bem. Onde a palavra-chave aqui é síncrono. Se a aplicação começar com um carregador, depois requisitar conteúdo através de AJAX, o rastreador não a esperará. Isto significa que se houver conteúdo requisitado de maneira assíncrona nas páginas onde SEO é importante, SSR pode ser necessário.
  :::

Também existem algumas contrapartidas a considerar ao usar SSR:

- Restrições no desenvolvimento. O código específico de navegador só pode ser usado dentro certos gatilhos do ciclo de vida; algumas bibliotecas externas podem precisar de tratamento especial para serem capazes de funcionar em uma aplicação interpretada no servidor.

- Mais configurações de construção e de requisitos de implantação. Ao contrário de uma SPA completamente estática que pode ser implantada em qualquer servidor de arquivo estático, uma aplicação interpretada no servidor exige um ambiente onde um servidor Node.js possa executar.

- Mais carga do lado do servidor. A interpretação de uma aplicação completa em Node.js será mais intensa para a CPU do que apenas servir arquivos estáticos, então caso se espere tráfego elevado, prepare-se para uma carga correspondente no servidor e empregue prudentemente estratégias de cache.

Antes de usar SSR em uma aplicação, a primeira pergunta que se deve fazer é se realmente se necessita dela. Isto depende na maior parte das vezes de quão o carregamento de conteúdo é importante para a aplicação. Por exemplo, se em uma construção de um painel de controle interno onde algumas centenas de milissegundos adicionais no carregamento inicial não importam tanto, SSR seria exagero. Entretanto, em casos onde o carregamento é absolutamente crítico, SSR pode ajudar a alcançar o melhor desempenho de carregamento inicial possível.

### SSR x SSG {#ssr-vs-ssg}

**Geração de Site Estático (SSG, sigla em Inglês)**, também referenciado como pré-interpretação, é uma outra técnica popular para construir sites rápidos. Se os dados necessários para o servidor interpretar uma página são os mesmo para todos os usuários, então ao invés de interpretar a página cada vez que uma requisição chegar, podemos interpretá-la apenas uma vez, com antecedência, durante o processo de construção. Páginas pré-interpretadas são geradas e servidas como arquivos HTML estáticos.

SSG conserva as mesmas características de desempenho de aplicações SSR: fornece excelente desempenho de carregamento de conteúdo. Ao mesmo tempo, é mais barata e mais fácil de implantar do que aplicações de SSR pois a saída são HTML e recursos estáticos. A palavra-chave aqui é **estático**: SSG só pode ser aplicado em páginas que consomem dados estáticos, por exemplo, dados que são conhecidos no momento da construção e não mudam entre implantações. Toda vez que os dados mudarem, uma nova implantação é necessária.

Se a busca por SSR se dá para melhorar o SEO de algumas páginas de publicidade (por exemplo, `/`, `/about`, `/contact`, etc.), então provavelmente é melhor SSG no lugar de SSR. SSG também é ótima para sites baseados em conteúdo tais como páginas de documentação ou blogs. Na verdade, esta exata página atual é gerada estaticamente com o uso de [VitePress](https://vitepress.vuejs.org/), um gerador de site estático movido por Vue.js.

## Tutorial Básico {#basic-tutorial}

### Interpretando uma Aplicação {#rendering-an-app}

Vamos dar uma olhada no exemplo mais básico de SSR Vue.

1. Crie um novo diretório e entre nele com `cd`
2. Execute `npm init -y`
3. Adicione `"type": "module"` no `package.json` para que Node.js execute no [modo de módulos de ECMAScript](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
4. Execute `npm install vue`
5. Crie um arquivo `example.js`:

```js
// isto roda em Node.js no servidor.
import { createSSRApp } from 'vue'
// A API Vue de interpretação do servidor é exposta sob `vue/server-renderer`.
import { renderToString } from 'vue/server-renderer'

const app = createSSRApp({
  data: () => ({ count: 1 }),
  template: `<button @click="count++">{{ count }}</button>`
})

renderToString(app).then((html) => {
  console.log(html)
})
```

Depois execute:

```sh
> node example.js
```

Isto deve imprimir o seguinte na linha de comando:

```
<button>1</button>
```

[`renderToString()`](/api/ssr.html#rendertostring) recebe uma instância de aplicação Vue e retorna uma Promise que resolve para HTML interpretada da aplicação. Também é possível interpretar em fluxo usando [API Stream Node.js](https://nodejs.org/api/stream.html) ou [API Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). Consulte a [Referência da API de SSR](/api/ssr.html) para detalhes completos.

Podemos então mover o código Vue SSR para um manipulador de requisição do servidor, que envolve a marcação da aplicação com o HTML completo da página. Usaremos o [`express`](https://expressjs.com/) para as próximas etapas:

- Execute `npm install express`
- Cria o seguinte arquivo `server.js`:

```js
import express from 'express'
import { createSSRApp } from 'vue'
import { renderToString } from 'vue/server-renderer'

const server = express()

server.get('/', (req, res) => {
  const app = createSSRApp({
    data: () => ({ count: 1 }),
    template: `<button @click="count++">{{ count }}</button>`
  })

  renderToString(app).then((html) => {
    res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <title>Exemplo Vue SSR</title>
      </head>
      <body>
        <div id="app">${html}</div>
      </body>
    </html>
    `)
  })
})

server.listen(3000, () => {
  console.log('pronto')
})
```

Finalmente, execute `node server.js` e visite `http://localhost:3000`. A página funcional deve ser mostrada com o botão.

[Experimente na StackBlitz](https://stackblitz.com/fork/vue-ssr-example-basic?file=index.js)

### Hidratação do Cliente {#client-hydration}

Se clicarmos no botão, notamos que o número não muda. O HTML é completamente estático no cliente já que não estamos carregando Vue no navegador.

Para tornar a aplicação no lado do cliente interativa, Vue precisa realizar a etapa de **hidratação**. Durante a hidratação, ela cria a mesma aplicação de Vue que foi executada no servidor, combina cada componente aos nós DOM que ela deveria controlar, e conecta os ouvintes de evento DOM.

Para montar uma aplicação no modo de hidratação, precisamos usar [`createSSRApp()`](/api/application.html#createssrapp) ao invés de `createApp()`:

```js{2}
// isso executa no navegador.
import { createSSRApp } from 'vue'

const app = createSSRApp({
  // ...a mesma aplicação do servidor
})

// a montagem de uma aplicação de SSR no cliente presume
// que o HTML foi pré-interpretado e realizará
// a hidratação em vez de montar novos nós DOM.
app.mount('#app')
```

### Estrutura do Código {#code-structure}

Perceba como precisamos reutilizar a mesma implementação da aplicação como é feita no servidor. Aqui é onde precisamos começar a pensar sobre como estruturar o código em uma aplicação SSR - como compartilhamos o mesmo código de aplicação entre o servidor e o cliente?

Aqui demonstraremos a configuração mais básica. Primeiro, dividiremos a lógica de criação da aplicação em um arquivo dedicado, `app.js`:

```js
// app.js (compartilhado entre o servidor e o cliente)
import { createSSRApp } from 'vue'

export function createApp() {
  return createSSRApp({
    data: () => ({ count: 1 }),
    template: `<button @click="count++">{{ count }}</button>`
  })
}
```

Este arquivo e suas dependências são compartilhados entre o servidor e o cliente - nós o chamamos de **código universal**. Há uma porção de coisas em que precisamos prestar atenção quando escrevemos código universal, conforme [discutiremos abaixo](#writing-ssr-friendly-code).

A nossa entrada do cliente importa o código universal, cria a aplicação, e realiza a montagem:

```js
// client.js
import { createApp } from './app.js'

createApp().mount('#app')
```

E o servidor usa a mesma lógica de criação da aplicação no manipulador de requisição:

```js{2,5}
// server.js (código irrelevante omitido)
import { createApp } from './app.js'

server.get('/', (req, res) => {
  const app = createApp()
  renderToString(app).then(html => {
    // ...
  })
})
```

Além disso, para carregar os arquivos do cliente no navegador, também precisamos:

1. Servir os arquivos do cliente adicionando `server.use(express.static('.'))` no `server.js`.
2. Carregar a entrada do cliente adicionando `<script type="module" src="/client.js"></script>` à estrutura do HTML.
3. Suportar o uso de `import * from 'vue'` no navegador adicionando um [Mapa de Importação](https://github.com/WICG/import-maps) na estrutura do HTML.

[Experimento o exemplo completo na StackBlitz](https://stackblitz.com/fork/vue-ssr-example?file=index.js). O botão agora é interativo!

## Soluções de Alto Nível {#higher-level-solutions}

Indo do exemplo para uma aplicação SSR pronta para produção envolve muito mais. Precisaremos de:

- Suportar SFCs Vue e outros requisitos da etapa de construção. Na verdade, precisaremos coordenar duas construções para a mesma aplicação: uma para o cliente, e outra para o servidor.

  :::tip Dica
  Componentes Vue são compilados de maneira diferente quando usados para SSR - os modelos de marcação são compilados em concatenações string ao invés de funções de interpretação no DOM Virtual para um desempenho de interpretação mais eficiente.
  :::

- No manipulador de requisição do servidor, interpretar o HTML com as ligações de recurso corretas e sugestões de recurso ideais no lado do cliente. Podemos também precisar alternar entre SSR e SSG, ou até mesmo misturar ambos na mesma aplicação.

- Gerenciar o roteamento, requisição de dados, e as bases de gerenciamento de estado de uma maneira universal.

Uma implementação completa seria bastante complexa e depende do conjunto de ferramentas de construção que foram escolhidas para se trabalhar. Portanto, recomendamos fortemente proceder com uma solução de alto nível, opinativa, que abstrai a complexidade. Abaixo introduziremos algumas das soluções recomendadas no ecossistema Vue.

### Nuxt {#nuxt}

[Nuxt](https://v3.nuxtjs.org/) é uma abstração de alto nível construída sobre o ecossistema Vue que fornece uma experiência de desenvolvimento otimizada para escrever aplicações Vue universais. Ainda melhor, também se pode usá-la como um gerador de site estático! Recomendamos fortemente que você experimente.

### Quasar {#quasar}

[Quasar](https://quasar.dev) é uma solução completa baseada em Vue que permite escolher entre SPA, SSR, PWA, aplicativo móvel, aplicativo de computador, e extensão de navegador, tudo usando uma base de código. Ela não apenas trata da configuração de construção, mas também fornece uma coleção completa de componentes UI aderentes ao Material Design.

### Vite SSR {#vite-ssr}

Vite fornece [suporte para interpretação Vue no lado do servidor](https://vitejs.dev/guide/ssr.html) embutido, mas é intencionalmente de baixo nível. Se desejar seguir diretamente com Vite, consulte o [vite-plugin-ssr](https://vite-plugin-ssr.com/), uma extensão da comunidade que abstrai muitos detalhes desafiadores.

Também pode-se encontrar um exemplo de projeto Vue + Vite SSR usando configuração manual [aqui](https://github.com/vitejs/vite/tree/main/playground/ssr-vue), o qual pode servir como uma base para construir sobre. Nota que isto é apenas recomendado para experientes com SSR / ferramentas de construção e se realmente quiser ter controle completo sobre a arquitetura de alto nível.

## Escrevendo Código SSR Amigável {#writing-ssr-friendly-code}

Independentemente da escolha de configuração de construção ou abstração de alto nível, existem alguns princípios que se aplicam a todas aplicações SSR Vue.

### Reatividade no Servidor {#reactivity-on-the-server}

Durante a SSR, cada URL de requisição faz um mapa para um estado desejado da nossa aplicação. Não existe interação de usuário e nem atualizações no DOM, então a reatividade é desnecessária no servidor. Por padrão, a reatividade é desabilitada durante a SSR para melhor desempenho.

### Gatilhos do Ciclo de Vida do Componente {#component-lifecycle-hooks}

Como não existem atualizações dinâmicas, os gatilhos do ciclo de vida tais como <span class="options-api">`mounted`</span><span class="composition-api">`onMounted`</span> ou <span class="options-api">`updated`</span><span class="composition-api">`onUpdated`</span> **NÃO** serão chamados durante a SSR e serão executados apenas no cliente.<span class="options-api"> Os únicos gatilhos que são chamados durante a SSR são `beforeCreate` e `created`</span>.

Deve-se evitar código que produz efeitos colaterais que precisam de limpeza no <span class="options-api">`beforeCreate` e `created`</span><span class="composition-api">`setup()` ou no escopo raiz do `<script setup>`</span>. Um exemplo de tais efeitos colaterais é a definição de temporizadores com `setInterval`. Apenas no código do lado do cliente podemos definir um temporizador e então destruí-lo no <span class="options-api">`beforeUnmount`</span><span class="composition-api">`onBeforeUnmount`</span> ou <span class="options-api">`unmounted`</span><span class="composition-api">`onUnmounted`</span>. No entanto, como os gatilhos de desmontagem nunca serão chamados durante a SSR, os temporizadores ficarão ativos para sempre. Para evitar isto, mova o código de efeito colateral para <span class="options-api">`mounted`</span><span class="composition-api">`onMounted`</span>.

### Acesso à APIs Específicas de Plataforma {#access-to-platform-specific-apis}

O código universal não pode assumir o acesso às APIs específicas de plataforma, então se o código usa diretamente globais exclusivas do navegador como `window` ou `document`, eles lançarão erros ao serem executados em Node.js, e vice-versa.

Para tarefas que são compartilhadas entre o servidor e o cliente mas com diferentes APIs de plataforma, é recomendado envolver as implementações específicas de plataforma dentro de uma API universal, ou usar bibliotecas que fazem isto. Por exemplo, pode-se usar [`node-fetch`](https://github.com/node-fetch/node-fetch) para usar a mesma API de requisição tanto no servidor e no cliente.

Para APIs específicas de navegador, a abordagem comum é acessá-las ociosamente apenas dentro de gatilhos do ciclo de vida do cliente tais como <span class="options-api">`mounted`</span><span class="composition-api">`onMounted`</span>.

Note que se uma biblioteca de terceiros não for escrita com uso universal em mente, pode ser difícil integrá-la em uma aplicação interpretada no servidor. Talvez _seja possível_ fazê-la funcionar ao simular alguns dos globais, mas pode ser ousado e pode interferir com o código de detecção de ambiente de outras bibliotecas.

### Poluição do Estado em Requisição Cruzada {#cross-request-state-pollution}

No capítulo de Gerencimamento de Estado, introduzimos um [padrão simples de gerenciamento de estado com uso das APIs de Reatividade](state-management#simple-state-management-with-reactivity-api). Em um contexto SSR, este padrão exige alguns ajustes adicionais.

O padrão declara o estado compartilhado em um escopo raiz de um módulo JavaScript. Isto torna-os **singletons** - por exemplo, existe apenas uma instância do objeto reativo ao longo de todo o ciclo de vida da nossa aplicação. Isso funciona como esperado em uma aplicação Vue pura do lado do cliente, já que os módulos em nossa aplicação são inicializados para cada visita de página no navegador.

No entanto, num contexto SSR, os módulos da aplicação são normalmente inicializados apenas uma vez no servidor, quando o servidor é ligado. As mesmas instâncias de módulo serão reutilizadas através de várias requisições de servidor, e então o mesmo acontecerá com os nossos objetos de estado singleton. Se alterarmos o estado singleton compartilhado com dados específicos de um usuário, isso pode vazar acidentalmente para uma requisição de outro usuário. Nós chamamos isso de **poluição do estado em requisição cruzada**.

Nós podemos tecnicamente reinicializar todos os módulos JavaScript em cada requisição, tal como fazemos nos navegadores. No entanto, a inicialização de módulos de JavaScript pode custar caro, então isto afetaria de maneira significativa o desempenho do servidor.

A solução recomendada é criar uma nova instância da aplicação inteira - incluindo o roteador e as memórias globais - em cada requisição. Depois, ao invés de importá-lo diretamente em nossos componentes, fornecemos o estado partilhado usando [fornecimento a nível de aplicação](/guide/components/provide-inject#app-level-provide) e injetando-o nos componentes que precisam dele:

```js
// app.js (compartilhado entre o servidor e cliente)
import { createSSRApp } from 'vue'
import { createStore } from './store.js'

// chamada em cada requisição
export function createApp() {
  const app = createSSRApp(/* ... */)
  // cria nova instância da memória por requisição
  const store = createStore(/* ... */)
  // fornece a memória no nível da aplicação
  app.provide('store', store)
  // também expõe a memória para fins de hidratação
  return { app, store }
}
```

Bibliotecas de Gerenciamento de Estado como Pinia são projetadas com isto em mente. Consulte o [Guia SSR Pinia](https://pinia.vuejs.org/ssr/) para mais detalhes.

### Incompatibilidade na Hidratação {#hydration-mismatch}

Se a estrutura DOM do HTML pré-interpretado não corresponde a saída esperada da aplicação do lado do cliente, haverá um erro de incompatibilidade na hidratação. Incompatibilidade na hidratação é mais habitulamente introduzida pelas seguintes causas:

1. O modelo de marcação contém estrutura de aninhamento HTML inválida, e o HTML interpretado foi "corrigido" pelo interpretador de HTML nativo do navegador. Por exemplo, uma pegadinha comum é que [`<div>` não pode ser colocado dentro de `<p>`](https://stackoverflow.com/questions/8397852/why-cant-the-p-tag-contain-a-div-tag-inside-it):

   ```html
   <p><div>oi</div></p>
   ```

   Se produzirmos isto em nosso HTML interpretado pelo servidor, o navegador terminará o primeiro `<p>` quando o `<div>` for encontrado e o interpretará como a seguinte estrutura DOM:

   ```html
   <p></p>
   <div>oi</div>
   <p></p>
   ```

2. Os dados usados durante a interpretação contêm valores gerados aleatoriamente. Já que a mesma aplicação executará duas vezes - uma vez no servidor, e uma vez no cliente - não é garantido que os valores aleatórios sejam os mesmos entre as duas execuções. Há duas maneiras de evitar disparidades de valor-aleatório-induzido:

   1. Use `v-if` + `onMounted` para interpretar a parte que depende de valores aleatórios apenas no cliente. A abstração também pode ter funcionalidades embutidas para tornar isto mais fácil, por exemplo o componente `<ClientOnly>` em VitePress.

   2. Use uma biblioteca de gerador de número aleatório que suporta geração com sementes, e garante que a execução do servidor e a execução do cliente usarão a mesma semente (por exemplo, ao incluir a semente no estado serializado e obtê-la no cliente).

3. O servidor e o cliente estão em fusos horários diferentes. Algumas vezes, podemos querer converter um registro de data e hora para a data local do usuário. Entretanto, o fuso horário durante a execução do servidor e o fuso horário durante a execução do cliente não são sempre os mesmos, e não podemos saber com confiança o fuso horário do usuário durante a execução do servidor. Em tais casos, a conversão para hora local também deve ser realizada como uma operação no lado do cliente.

Quando Vue encontra uma incompatibilidade na hidratação, tentará se recuperar automaticamente e ajustar o DOM pré-interpretado para corresponder ao estado no lado do cliente. Isto conduzirá a alguma perda de desempenho de interpretação devido aos nós incorretos serem descartados e novos nós serem montados, mas na maioria dos casos, a aplicação deve continuar a funcionar como esperado. Dito isto, ainda é melhor eliminar as incompatibilidades na hidratação durante o desenvolvimento.

### Diretivas Personalizadas {#custom-directives}

Já que a maior parte das diretivas personalizadas envolvem manipulação direta do DOM, elas são ignoradas durante a SSR. No entanto, se é preciso especificar como uma diretiva personalizadas deve ser interpretada (por exemplo, quais atributos ela deve adicionar ao elemento interpretado), pode-se usar o gatilho de diretiva `getSSRProps`.

```js
const myDirective = {
  mounted(el, binding) {
    // implementação do lado do cliente:
    // atualiza diretamente o DOM
    el.id = binding.value
  },
  getSSRProps(binding) {
    // implementação no lado do servidor:
    // retornar as propriedades a serem interpretadas
    // `getSSProps` apenas recebe o vinculo de diretiva.
    return {
      id: binding.value
    }
  }
}
```

### Teletransportes {#teleports}

Teletransportes exigem manipulação especial durante a SSR. Se a aplicação interpretada contém Teletransportes, o conteúdo teletransportado não será parta da string interpretada. Uma solução mais fácil é interpretar condicoinalmente o Teletransporte na montagem.

Se é preciso hidratar o conteúdo teletransportado, eles são expostos sob a propriedade `teleports` do objeto do contexto SSR:

```js
const ctx = {}
const html = await renderToString(app, ctx)

console.log(ctx.teleports) // { '#teleported': 'teleported content' }
```

Precisamos injetar a marcação do teletransporte na localização correta na página de HTML final semelhante a como precisamos injetar a marcação da aplicação principal.

:::tip DICA
Evite o `body` como alvo ao usar Teletransportes e SSR juntos - geralmente, `<body>` conterá outro conteúdo interpretado no lado do servidor que torna-o impossível para os Teletransportes determinarem a localização inicial correta para hidratação.

Em vez disto, prefira um contentor dedicado, por exemplo, `<div id="teleported"></div>` que contém apenas conteúdo teletransportado.
:::

---

---
url: /guide/introduction.md
---

# Introdução {#introduction}

:::info Estamos Lendo a Documentação da Vue 3!

- O suporte da Vue 2 terminou no dia **31 de Dezembro de 2023**. Saber mais sobre o [Fim da Vida da Vue 2](https://v2.vuejs.org/eol/).
- Estamos migrando da Vue 2? Consultar o [Guia de Migração](https://v3-migration.vuejs.org/pt).
:::

<style src="@theme/styles/vue-mastery.css"></style>
<div class="vue-mastery-link">
  <a href="https://www.vuemastery.com/courses/" target="_blank">
    <div class="banner-wrapper">
      <img class="banner" alt="Faixa da Vue Mastery" width="96px" height="56px" src="https://storage.googleapis.com/vue-mastery.appspot.com/flamelink/media/vuemastery-graphical-link-96x56.png" />
    </div>
    <p class="description">Estudar Vue com a <span>VueMastery.com</span></p>
    <div class="logo-wrapper">
        <img alt="Logótipo da Vue Mastery" width="25px" src="https://storage.googleapis.com/vue-mastery.appspot.com/flamelink/media/vue-mastery-logo.png" />
    </div>
  </a>
</div>

## Que é Vue? {#what-is-vue}

Vue (pronunciado /vjuː/, como **view** ) é uma abstração de JavaScript para construção de interfaces de aplicações de utilizador. Ela constrói sobre a HTML, CSS e JavaScript padrão, e fornece um modelo de programação declarativa baseado em componente que ajuda-nos a desenvolver eficientemente interfaces de utilizador de qualquer complexidade.

Eis um exemplo minimalista:

<div class="options-api">

```js
import { createApp } from 'vue'

createApp({
  data() {
    return {
      count: 0
    }
  }
}).mount('#app')
```
</div>

<div class="composition-api">

```js
import { createApp, ref } from 'vue'

createApp({
  setup() {
    return {
      count: ref(0)
    }
  }
}).mount('#app')
```

</div>

```vue-html
<div id="app">
  <button @click="count++">
    Count is: {{ count }}
  </button>
</div>
```

**Resultado**

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<div class="demo">
  <button @click="count++">
    Count is: {{ count }}
  </button>
</div>

O exemplo acima demonstra as duas funcionalidades principais da Vue:

- **Interpretação Declarativa**: a Vue estende a HTML padrão com uma sintaxe de modelo de marcação que permite-nos descrever de maneira declarativa o resultado de HTML baseado no estado de JavaScript.

- **Reatividade**: a Vue rastreia automaticamente as mudanças de estado de JavaScript e atualiza eficientemente o DOM quando as mudanças ocorrerem.

Se houverem questões, não é coisa de preocupar-se porque cobriremos todos os pequenos detalhes no resto da documentação. Por agora, vamos ler, assim podemos ter uma compreensão de alto nível do que a Vue oferece.

:::tip PRÉ-REQUISITOS
O resto da documentação presume familiaridade básica com a HTML, CSS e JavaScript. Se formos totalmente novos ao desenvolvimento do frontend, pode não ser a melhor ideia saltar direto para uma abstração como primeiro passo - dominamos os fundamentos e depois avançamos para uma abstração! Nós podemos confirmar o nosso nível de conhecimento com estas visões gerais para [ JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript), [HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML) e [CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) se necessário. Experiência prévia com outras abstração ajuda, mas não é obrigatória.
:::

## A Abstração Progressiva {#the-progressive-framework}

A Vue é uma abstração e ecossistema que cobre a maioria das funcionalidades comuns necessárias no desenvolvimento de frontend. Porém a web é extremamente diversa - as coisas que construimos na web podem variar drasticamente na forma e escala. Com isto em mente, a Vue está desenhada para ser flexível e adotável incrementalmente. Dependendo do teu caso de uso, a Vue pode ser utilizada nas diferentes maneiras:

- Otimizando o HTML estático sem uma etapa de construção
- Embutindo como Componentes da Web em qualquer página
- Aplicação de Página Única, ou SPA
- Interpretação do Lado do Servidor, ou SSR
- Geração de Aplicação Estática, ou SSG
- Mirando aplicações de nativas de área de trabalho, móvel, WebGL, e até mesmo o terminal

Se considerarmos estes conceitos intimidantes, não precisamos de preocupar-nos! O tutorial e o guia apenas exigem conhecimento básico de HTML, CSS e JavaScript, e devemos ser capazes de acompanhar sem sermos um especialista em quaisquer um destes.

Se formos programadores experientes interessados em como integrar melhor a Vue na nossa pilha, ou formos curiosos sobre o que estes termos significam, os discutimos com mais detalhes na seção [Maneiras de Usar a Vue](/guide/extras/ways-of-using-vue).

Apesar da flexibilidade, o conhecimento principal sobre como a Vue funciona é partilhado por todos estes casos de uso. Mesmo se formos apenas iniciantes no momento, o conhecimento adquirido ao longo do caminho ainda será útil a medida que crescermos para enfrentarmos objetivos mais ambiciosos no futuro. Se formos veteranos, podemos escolher uma maneira ideal de entregar a Vue baseado nos problemas que estamos a tentar resolver, enquanto conservamos a mesma produtividade. É por isto que chamamos a Vue de "A Abstração Progressiva": é uma abstração que pode crescer connosco e adaptar-se às nossas necessidades.

## Componentes de Ficheiro Único {#single-file-components}

Na maioria dos projetos de Vue com a ferramenta de construção ativada, críamos os componentes da Vue usando um formato de ficheiro parecido com a HTML chamado de **Componente de Ficheiro Único** (também conhecido como ficheiros de extensão `*.vue`, abreviado como **SFC** na sua versão de nome em Inglês). Um componente de ficheiro único de Vue, como o nome sugere, encapsula a lógica do componente (JavaScript), o modelo de marcação (HTML), e os estilos (CSS) num único ficheiro. Eis o exemplo anterior, escrito no formato de componente de ficheiro único:

<div class="options-api">

```vue
<script>
export default {
  data() {
    return {
      count: 0
    }
  }
}
</script>

<template>
  <button @click="count++">Count is: {{ count }}</button>
</template>

<style scoped>
button {
  font-weight: bold;
}
</style>

```

</div>
<div class="composition-api">

```vue
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<template>
  <button @click="count++">Count is: {{ count }}</button>
</template>

<style scoped>
button {
  font-weight: bold;
}
</style>
```

</div>

O componente de ficheiro único é uma funcionalidade de definição da Vue e é a maneira recomendada para criar componentes de Vue *se* o nosso caso de uso justificar uma configuração de construção. Nós podemos aprender mais sobre [como e porquê do componente de ficheiro único](/guide/scaling-up/sfc) nesta seção dedicada - mas por agora, apenas saibamos que a Vue lidará com toda a configuração das ferramentas de construção por nós.

## Estilos de API {#api-styles}

Os componentes de Vue podem ser criados dentro de dois diferentes estilos de API: **API de Opções** e **API de Composição**.

### API de Opções {#options-api}

Com a API de Opções, definimos a lógica do componente usando um objeto de opções tais como `data`, `methods`, e `mounted`. As propriedades definidas pelas opções são expostas sobre o `this` dentro das funções, o qual aponta para instância do componente:

```vue
<script>
export default {
  // As propriedades retornadas a partir da `data()`
  // tornam-se estados reativos e serão expostas no `this`.
  data() {
    return {
      count: 0
    }
  },

  // Os métodos são funções que alteram o estado e acionam atualizações.
  // Elas podem ser vinculadas como ouvintes de evento nos
  // modelos de marcação.
  methods: {
    increment() {
      this.count++
    }
  },

  // Os gatilhos do ciclo de vida são chamados em diferentes fases
  // do ciclo de vida do componente.
  // Esta função será chamada quando o componente estiver montado.
  mounted() {
    console.log(`The initial count is ${this.count}.`)
  }
}
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNptkMFqxCAQhl9lkB522ZL0HNKlpa/Qo4e1ZpLIGhUdl5bgu9es2eSyIMio833zO7NP56pbRNawNkivHJ25wV9nPUGHvYiaYOYGoK7Bo5CkbgiBBOFy2AkSh2N5APmeojePCkDaaKiBt1KnZUuv3Ky0PppMsyYAjYJgigu0oEGYDsirYUAP0WULhqVrQhptF5qHQhnpcUJD+wyQaSpUd/Xp9NysVY/yT2qE0dprIS/vsds5Mg9mNVbaDofL94jZpUgJXUKBCvAy76ZUXY53CTd5tfX2k7kgnJzOCXIF0P5EImvgQ2olr++cbRE4O3+t6JxvXj0ptXVpye1tvbFY+ge/NJZt)

### API de Composição {#composition-api}

Com a API de Composição, definimos a lógica do componente usando funções da API importadas. Nos componentes de ficheiro único, a API de Composição é normalmente usada com o [`<script setup>`](/api/sfc-script-setup). O atributo `setup` é dica que faz a Vue realizar transformações no momento da compilação que permite-nos usar a API de Composição com menos padrões. Por exemplo, importações e variáveis de alto nível ou funções declaradas no `<script setup>` são diretamente usáveis no modelo de marcação.

Eis o mesmo componente, com o mesmo exato modelo de marcação, mas usando a API de Composição e o `<script setup>`:

```vue
<script setup>
import { ref, onMounted } from 'vue'

// o estado reativo
const count = ref(0)

// as funções que alteram o estado e acionam atualizações
function increment() {
  count.value++
}

// os gatilhos de ciclo de vida
onMounted(() => {
  console.log(`The initial count is ${count.value}.`)
})
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpNkMFqwzAQRH9lMYU4pNg9Bye09NxbjzrEVda2iLwS0spQjP69a+yYHnRYad7MaOfiw/tqSliciybqYDxDRE7+qsiM3gWGGQJ2r+DoyyVivEOGLrgRDkIdFCmqa1G0ms2EELllVKQdRQa9AHBZ+PLtuEm7RCKVd+ChZRjTQqwctHQHDqbvMUDyd7mKip4AGNIBRyQujzArgtW/mlqb8HRSlLcEazrUv9oiDM49xGGvXgp5uT5his5iZV1f3r4HFHvDprVbaxPhZf4XkKub/CDLaep1T7IhGRhHb6WoTADNT2KWpu/aGv24qGKvrIrr5+Z7hnneQnJu6hURvKl3ryL/ARrVkuI=)

### Qual Escolher? {#which-to-choose}

Ambos estilos de API são completamente capazes de cobrir casos de uso comuns. São interfaces diferentes alimentadas pelo mesmo exato sistema subjacente. Na verdade, a API de Opções está implementada em cima da API de Composição! Os conceitos fundamentais e conhecimentos sobre a Vue são partilhados por ambos estilos.

A API de Opções está centrada em torno do conceito duma "instância de componente" (`this` como visto no exemplo), a qual normalmente alinha-se melhor com um modelo mental baseado em classe para os utilizadores provenientes de linguagens orientadas a objetos. Também é mais amigável aos iniciantes abstraindo muito os detalhes da reatividade e forçando a organização do código através de grupos de opções.

A API de Composição está centrada em torno da declaração de variáveis de estado reativo diretamente no âmbito de aplicação da função e da composição de estado a partir de várias funções juntas para lidar com a complexidade. É a forma mais livre e exige um entendimento de como a reatividade funciona na Vue para ser usada efetivamente. Em troca, sua flexibilidade permite padrões mais poderosos para organização e reutilização da lógica.

Nós podemos aprender mais sobre a comparação entre os dois estilos e os potenciais benefícios da API de Composição nas [Questões Frequentes da API de Composição](/guide/extras/composition-api-faq).

Se formos novos para a Vue, eis a nossa recomendação geral:

- Para fins de aprendizado, devemos seguir com o estilo que parecer mais fácil de entender para nós. Novamente, a maioria dos conceitos são partilhados entre os dois estilos. Nós podemos sempre escolher o outro estilo mais tarde.

- Para uso de produção:

  - Sigamos com a API de Opções se não estivermos a usar ferramentas de construção, ou planejamos usar a Vue primariamente em cenários de menor complexidade, por exemplo otimização progressiva.

  - Sigamos com a API de Composição + Componentes de Ficheiro Único se planejamos construir aplicações completas com a Vue.

Nós não precisamos de nos comprometer com apenas um estilo durante a fase de aprendizado. O resto da documentação fornecerá exemplos de código em ambos estilos onde for aplicável, e podemos alternar entre os estilos a qualquer momento usando o **interruptor de preferência de API** no canto superior esquerdo da página (em cima do menu lateral).

## Questões? {#still-got-questions}

Consulte as nossas [Questões Feitas Com Frequência](/about/faq).

## Escolha o Teu Caminho de Aprendizado {#pick-your-learning-path}

Diferentes programadores têm diferentes estilos de aprendizado. Sintamos à vontade para escolhermos um caminho de aprendizado que adapta-se às nossas preferências - apesar de recomendarmos avançar por todo o conteúdo, se possível!

<div class="vt-box-container next-steps">
  <a class="vt-box" href="/tutorial/">
    <p class="next-steps-link">Experimentar o Tutorial</p>
    <p class="next-steps-caption">Para aqueles que preferem aprender as coisas na prática.</p>
  </a>
  <a class="vt-box" href="/guide/quick-start.html">
    <p class="next-steps-link">Ler o Guia</p>
    <p class="next-steps-caption">O guia acompanha-nos por todos os aspetos da abstração em completo detalhe.</p>
  </a>
  <a class="vt-box" href="/examples/">
    <p class="next-steps-link">Consultar os Exemplos Interativos</p>
    <p class="next-steps-caption">Explore os exemplos interativos das funcionalidades principais e tarefas de interfaces de aplicações comuns.</p>
  </a>
</div>

---

---
url: /guide/quick-start.md
---

<script setup>
import { VTCodeGroup, VTCodeGroupTab } from '@vue/theme'
</script>

# Introdução Rápida {#quick-start}

## Experimentar a Vue no Navegador {#try-vue-online}

- Para termos rapidamente um gostinho de como é programar com a Vue, podemos experimentá-la diretamente na nossa [Zona de Testes](https://play.vuejs.org/#eNo9jcEKwjAMhl/lt5fpQYfXUQfefAMvvRQbddC1pUuHUPrudg4HIcmXjyRZXEM4zYlEJ+T0iEPgXjn6BB8Zhp46WUZWDjCa9f6w9kAkTtH9CRinV4fmRtZ63H20Ztesqiylphqy3R5UYBqD1UyVAPk+9zkvV1CKbCv9poMLiTEfR2/IXpSoXomqZLtti/IFwVtA9A==).

- Se preferirmos uma configuração de HTML simples sem quaisquer etapas de construção podemos usar esta [JSFiddle](https://jsfiddle.net/yyx990803/2ke1ab0z/) como nosso ponto de partida.

- Se já estivermos familiarizados com a Node.js e com o conceito de ferramentas de construção, também podemos experimentar uma configuração de construção completa diretamente dentro do nosso navegador na [StackBlitz](https://vite.new/vue).

## Criando uma Aplicação de Vue {#creating-a-vue-application}

:::tip PRÉ-REQUISITOS

- Familiaridade com a linha de comando
- Instalar a versão 18.3 ou superior da [Node.js](https://nodejs.org/).

:::

Nesta secção introduziremos como estruturar uma [Aplicação de Página Única](/guide/extras/ways-of-using-vue#single-page-application-spa) de Vue na nossa máquina local. O projeto criado usará uma configuração de construção baseada na [Vite](https://pt.vitejs.dev), e nos permitirá usar os [Componentes de Ficheiro Único](/guide/scaling-up/sfc) da Vue.

Temos que certificar-nos de que temos uma versão atualizada da [Node.js](https://nodejs.org) instalada e o nosso diretório de trabalho atual é aquele onde tencionamos criar um projeto. Executamos o seguinte comando na nossa linha de comando (sem o sinal `$`):

<VTCodeGroup>
  <VTCodeGroupTab label="npm">

  ```sh
  $ npm create vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="pnpm">

  ```sh
  $ pnpm create vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="yarn">

  ```sh
  # Para Yarn Moderna (v2+)
  $ yarn create vue@latest

  # Para Yarn ^v4.11
  $ yarn dlx create-vue@latest
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="bun">

  ```sh
  $ bun create vue@latest
  ```

  </VTCodeGroupTab>
</VTCodeGroup>

Este comando instalará e executará a [`create-vue`](https://github.com/vuejs/create-vue), a ferramenta de estruturação de projeto de Vue oficial. Nós seremos presenteados com prontos para várias funcionalidades opcionais tais como o suporte da TypeScript e testes:

<div class="language-sh"><pre><code><span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Project name: <span style="color:#888;">… <span style="color:#89DDFF;">&lt;</span><span style="color:#888;">your-project-name</span><span style="color:#89DDFF;">&gt;</span></span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add TypeScript? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add JSX Support? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add Vue Router for Single Page Application development? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add Pinia for state management? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add Vitest for Unit testing? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add an End-to-End Testing Solution? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Cypress / Playwright</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add ESLint for code quality? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add Prettier for code formatting? <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span style="color:var(--vt-c-green);">✔</span> <span style="color:#A6ACCD;">Add Vue DevTools 7 extension for debugging? (experimental) <span style="color:#888;">… <span style="color:#89DDFF;text-decoration:underline">No</span> / Yes</span></span>
<span></span>
<span style="color:#A6ACCD;">Scaffolding project in ./<span style="color:#89DDFF;">&lt;</span><span style="color:#888;">your-project-name</span><span style="color:#89DDFF;">&gt;</span>...</span>
<span style="color:#A6ACCD;">Done.</span></code></pre></div>

Se estivermos inseguros sobre uma opção, por agora podemos simplesmente escolher `No` pressionando `Enter`. Logo que o projeto for criado, seguimos as instruções para instalarmos as dependências e iniciar o servidor de desenvolvimento:

<VTCodeGroup>
  <VTCodeGroupTab label="npm">

  ```sh
  $ cd <your-project-name>
  $ npm install
  $ npm run dev
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="pnpm">

  ```sh
  $ cd <your-project-name>
  $ pnpm install
  $ pnpm run dev
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="yarn">

  ```sh
  $ cd <your-project-name>
  $ yarn
  $ yarn dev
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="bun">

  ```sh
  $ cd <your-project-name>
  $ bun install
  $ bun run dev
  ```

  </VTCodeGroupTab>
</VTCodeGroup>

Nós devemos ter agora o nosso primeiro projeto de Vue em execução! Nota que os componentes de exemplo no projeto gerado estão escritos usando a [API de Composição](/guide/introduction#composition-api) e o `<script setup>`, ao invés da [API de Opções](/guide/introduction#options-api). Eis algumas dicas adicionais:

- A configuração de ambiente de desenvolvimento integrado recomendada é o editor de texto [Visual Studio Code](https://code.visualstudio.com/) mais a [Vue - extensão oficial](https://marketplace.visualstudio.com/items?itemName=Vue.volar). Se usarmos outros editores, temos que consultar a [secção do suporte de ambiente de desenvolvimento integrado](/guide/scaling-up/tooling#ide-support).
- Mais detalhes sobre o ferramental, incluindo a integração com abstrações de backend, são discutidos no [Guia de Ferramental](/guide/scaling-up/tooling).
- Para sabermos mais sobre a ferramenta de construção subjacente Vite, temos que consultar a [documentação da Vite](https://pt.vitejs.dev).
- Se escolhermos usar a TypeScript, temos que consultar o [Guia de Uso de TypeScript](typescript/overview).

Quando estivermos prontos para disponibilizar a nossa aplicação em produção, executaremos o seguinte:

<VTCodeGroup>
  <VTCodeGroupTab label="npm">

  ```sh
  $ npm run build
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="pnpm">
  
  ```sh
  $ pnpm run build
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="yarn">
  
  ```sh
  $ yarn build
  ```

  </VTCodeGroupTab>
  <VTCodeGroupTab label="bun">
  
  ```sh
  $ bun run build
  ```

  </VTCodeGroupTab>
</VTCodeGroup>

Isto criará uma construção preparada para produção da nossa aplicação dentro do diretório `./dist` do projeto. Consulte o [Guia de Implementação de Produção](/guide/best-practices/production-deployment) por mais informação sobre a disponibilização da nossa aplicação em produção.

[Próximos Passos >](#next-steps)

## Usando a Vue da Rede de Entrega de Conteúdo {#using-vue-from-cdn}

Nós podemos usar a Vue diretamente a partir duma rede de entrega de conteúdo através dum marcador `script`:

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
```

Eis que usamos a [unpkg](https://unpkg.com/), mas também podemos usar qualquer rede de entrega de conteúdo que serve pacotes de npm, por exemplo a [jsdelivr](https://www.jsdelivr.com/package/npm/vue) ou a [cdnjs](https://cdnjs.com/libraries/vue). E claro, também podemos descarregar este ficheiro e o servir por conta própria. 

Quando usamos a Vue a partir duma rede de entrega de conteúdo, não existe nenhuma "etapa de construção" envolvida. Isto torna a configuração muito mais simples, e é adequando para otimizar a HTML estática ou integrar com uma abstração de backend. No entanto, não serás capaz de usar a sintaxe do Componente de Ficheiro Único (ou, SFC).

### Usando a Construção Global {#using-the-global-build}

A ligação acima carrega a _construção global_ da Vue, onde todas as APIs  de alto nível são expostas como propriedades sobre o objeto `Vue` global. Eis um exemplo completo usando a construção global:

<div class="options-api">

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp } = Vue

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/QWJwJLp)

</div>

<div class="composition-api">

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp, ref } = Vue

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/eYQpQEG)

</div>

:::tip NOTA
Muitos dos exemplos para a API de Composição ao longo do guia usarão a sintaxe do `<script setup>`, que exige ferramentas de construção. Se tencionamos usar a API de Composição sem uma etapa de construção, temos que consultar o uso da [opção `setup()`](/api/composition-api-setup).
:::

### Usando a Construção de Módulo de ECMAScript {#using-the-es-module-build}

Por toda a documentação, usaremos essencialmente a sintaxe de [módulos de ECMAScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). A maioria dos navegadores agora suportam os módulos de ECMAScript de maneira nativa, então podemos usar a Vue a partir duma rede de entrega de conteúdo através dos módulos de ECMScript desta maneira:

<div class="options-api">

```html{3,4}
<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

</div>

<div class="composition-api">

```html{3,4}
<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

</div>

Repara que usamos o `<script type="module">`, e que a URL da rede de entrega de conteúdo importada aponta para uma **construção de módulos de ECMAScript** da Vue.

<div class="options-api">

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/VwVYVZO)

</div>
<div class="composition-api">

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/MWzazEv)

</div>

### Ativando os Mapas de Importação {#enabling-import-maps}

No exemplo acima, importamos a partir da URL completa da rede de entrega de conteúdo, mas no resto da documentação veremos o código desta maneira:

```js
import { createApp } from 'vue'
```

Nós podemos ensinar o navegador onde localizar a importação da `vue` usando os [Mapas de Importação](https://caniuse.com/import-maps):

<div class="options-api">

```html{1-7,12}
<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'vue'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/wvQKQyM)

</div>

<div class="composition-api">

```html{1-7,12}
<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'vue'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

[Demonstração da Codepen](https://codepen.io/vuejs-examples/pen/YzRyRYM)

</div>

Nós também podemos adicionar entradas para outras dependências ao mapa de importação - porém temos que certificar-nos de que apontam às versões de módulos de ECMAScript da biblioteca que tencionamos usar.

:::tip SUPORTE DO NAVEGADOR DE MAPAS DE IMPORTAÇÃO
Os mapas de importação são uma funcionalidade do navegador relativamente nova. Temos que certificar-nos de usar um navegador dentro do seu [limite de suporte](https://caniuse.com/import-maps). Em especial, apenas é suportada no Safari 16.4+.
:::

:::warning NOTAS SOBRE O USO DE PRODUÇÃO
Os exemplos até qui usam a construção de desenvolvimento da Vue - se tencionamos usar a Vue a partir duma rede de entrega de conteúdo em produção, temos de certificar-nos de consultar o [Guia de Implementação de Produção](/guide/best-practices/production-deployment#without-build-tools).
:::

### Separando os Módulos {#splitting-up-the-modules}

Conforme mergulharmos mais fundo no guia, podemos precisar dividir o código em ficheiros de JavaScript separados para serem mais fáceis de gerir. Por exemplo:

```html
<!-- index.html -->
<script type="module">
  import { createApp } from 'vue'
  import MyComponent from './my-component.js'

  createApp(MyComponent).mount('#app')
</script>
```

<div class="options-api">

```js
// my-component.js
export default {
  data() {
    return { count: 0 }
  },
  template: `<div>count is {{ count }}</div>`
}
```

</div>
<div class="composition-api">

```js
// my-component.js
import { ref } from 'vue'
export default {
  setup() {
    const count = ref(0)
    return { count }
  },
  template: `<div>count is {{ count }}</div>`
}
```

</div>

Se abrirmos o `index.html` acima diretamente no nosso navegador, descobriremos que lança um erro porque os módulos de ECMAScript não podem funcionar sobre o protocolo `file://`, que é o protocolo que o navegador usa quando abrimos um ficheiro local.

Por razões de segurança, os módulos de ECMAScript apenas podem funcionar sobre o protocolo `http://`, que é o que os navegadores usam quando abrimos as páginas na Web. Para os módulos de ECMAScript funcionarem na nossa máquina local, precisamos servir o `index.html` sobre o protocolo `http://`, com um servidor de HTTP local.

Para iniciar um servidor de HTTP local, temos de certificar-nos que temos a [Node.js](https://nodejs.org/en/) instalada, depois executamos `npx serve` a partir da linha de comando no mesmo diretório onde o nosso ficheiro de HTML está. Nós também podemos usar qualquer outro servidor de HTTP que pode servidor ficheiros estáticos com os tipos de tipo de ficheiro corretos.

Nós podemos ter reparado que o modelo de marcação do componente importado está em linha como uma sequência de caracteres de JavaScript. Se usamos o VS Code, podemos instalar a extensão [`es6-string-html`](https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html) e prefixar as sequências de caracteres com um comentário `/*html*/` para obtermos destacamento da sua sintaxe.

## Próximos Passos {#next-steps}

Se saltamos a [Introdução](/guide/introduction), é recomendado fortemente a leitura da introdução antes de avançarmos para o resto da documentação.

<div class="vt-box-container next-steps">
  <a class="vt-box" href="/guide/essentials/application">
    <p class="next-steps-link">Continuar o Guia</p>
    <p class="next-steps-caption">
      O guia conduz-nos através de todos os aspetos da abstração com detalhes.
    </p>
  </a>
  <a class="vt-box" href="/tutorial/">
    <p class="next-steps-link">Experimentar o Tutorial</p>
    <p class="next-steps-caption">
      Para o caso de preferirmos aprender através de coisas práticas.
    </p>
  </a>
  <a class="vt-box" href="/examples/">
    <p class="next-steps-link">Consultar os Exemplos</p>
    <p class="next-steps-caption">
      Nós podemos explorar os exemplos de código que apresentam as funcionalidades principais e tarefas comuns da interface do utilizador.
    </p>
  </a>
</div>

---

---
url: /about/releases.md
---

<script setup>
import { onMounted, ref } from 'vue'

let version = ref()

onMounted(async () => {
  const res = await fetch('https://api.github.com/repos/vuejs/core/releases/latest')
  version.value = (await res.json()).name
})
</script>

# Lançamentos {#releases}

<p v-if="version">
A versão estável mais recente da Vue é a <strong>{{ version }}</strong>.
</p>
<p v-else>
Consultando a versão mais recente...
</p>

Um relatório completo dos lançamentos passados está disponível na [GitHub](https://github.com/vuejs/core/blob/main/CHANGELOG.md).

## Ciclo de Lançamento {#release-cycle}

A Vue não tem um ciclo de lançamento fixo.

- Os lançamentos de remedo são feitos quando necessários.

- Os lançamentos secundários sempre contém novas funcionalidades, com um quando de tempo normal entre 3 à aproximadamente 6 meses. Os lançamentos secundários sempre passam por uma fase de pré-lançamento beta.

- Os lançamentos primários serão anunciados com antecedência, e passarão primeiro por uma fase de discussão e fases de pré-lançamentos alfa ou beta.

## Casos Extremos de Versionamento Semântico {#semantic-versioning-edge-cases}

Os lançamentos da Vue seguem o [Versionamento Semântico](https://semver.org/) com alguns casos extremos.

### Definições de TypeScript {#typescript-definitions}

Nós podemos entregar mudanças incompatíveis com as definições de TypeScript entre versões **secundárias**. Isto porque:

1. Algumas vezes a própria TypeScript entrega mudanças incompatíveis entre versões secundárias, e podemos ter de ajustar os tipos para suportar versões mais novas de TypeScript.

2. Ocasionalmente podemos precisar de adotar funcionalidades que apenas estão disponíveis numa versão mais nova da TypeScript, elevando a versão mínima exigida da TypeScript.

Se estiveres a usar a TypeScript, podes usar um limite de versionamento semântico que tranca a versão secundária atual e manualmente atualizar quando uma nova versão secundária da Vue for lançada.

### Compatibilidade de Código Compilado com Executores Mais Antigos {#compiled-code-compatibility-with-older-runtime}

Uma versão **secundária** mais recente do compilador da Vue pode gerar código que não é compatível com o executor da Vue duma versão secundária mais antiga. Por exemplo, o código gerado pelo compilador da Vue 3.2 pode não ser completamente compatível se consumido pelo executor da Vue 3.1.

Isto é apenas uma preocupação para os autores de biblioteca, porque nas aplicações, a versão do compilador e a versão do executor é sempre a mesma. Uma divergência de versão apenas pode acontecer se entregares código de componente de Vue pré-compilado como um pacote, e um consumidor usá-lo num projeto usando uma versão mais antiga da Vue. Como resultado, o teu pacote pode precisar de declarar explicitamente uma versão secundária obrigatória mínima da Vue.

## Pré-Lançamentos {#pre-releases}

Os lançamentos secundários normalmente passam por um número não fixo de lançamentos beta. Os lançamentos primários passarão por uma fase alfa e uma fase beta.

Os pré-lançamentos estão destinados para testes de integração ou estabilidade, e para primeiros adotantes fornecerem comentários para as funcionalidades instáveis. Não use os pré-lançamentos em produção. Todos os pré-lançamentos são considerados instáveis e podem entrar mudanças de rutura consigo, então sempre fixe as versões exatas quando usares pré-lançamentos.

## Depreciações {#deprecations}

Nós podemos periodicamente depreciar funcionalidades que têm novas e melhores substitutos nos lançamentos secundários. As funcionalidades depreciadas continuarão a funcionar, e serão removidas no próximo lançamento primário depois de entrada no estado de depreciação.

## RFCs {#rfcs}

As novas funcionalidades com superfície de API substancial e mudanças primárias para Vue passarão pelo processo de **Pedidos Por Comentários**. Este processo está destinado a fornecer um caminho consistente e controlado para as novas funcionalidades entrarem na abstração, e dar aos utilizadores uma oportunidade de participar e oferecer comentários no processo de desenho.

O processo é conduzido no repositório [vuejs/rfcs](https://github.com/vuejs/rfcs) na GitHub.

## Funcionalidades Experimentais {#experimental-features}

Algumas funcionalidades são entregadas e documentadas numa versão estável da Vue, mas marcadas como experimentais. As funcionalidades experimentais são normalmente funcionalidades que têm uma discussão de RFC associada com a maioria dos problemas de desenho resolvidos no estudo, mas continua carente de comentário de uso do mundo real.

O objetivo das funcionalidades experimentais é permitir os utilizadores fornecerem comentários para elas testando-as numa configuração de produção, sem ter de usar uma versão instável da Vue. As próprias funcionalidades experimentais são consideradas instáveis, e deveriam ser apenas usadas duma maneira controlada, com a expetativa de que a funcionalidade pode mudar entre quaisquer tipos de lançamento.

---

---
url: /guide/extras/ways-of-using-vue.md
---
# Maneiras de Usar a Vue {#ways-of-using-vue}

Nós acreditamos não existir "uma solução que resolva tudo" na Web. É por isto que a Vue é desenhada para ser flexível e adotável incrementalmente. Dependendo do teu caso de uso, a Vue pode ser usada de diferentes maneiras para encontrar a harmonia ideal entre a complexidade da pilha, experiência de programação e desempenho final.

## Extensão Isolada {#standalone-script}

A Vue pode ser usada como um ficheiro de extensão isolada - sem a necessidade da etapa de construção! se já tiveres uma abstração de backend a gerar a maior parte da HTML, ou a lógica do teu frontend não complexa o suficiente para justificar uma etapa de construção, esta é a maneira mais fácil de integrar a Vue na tua pilha. Nestes casos, podes pensar da Vue como sendo mais uma substituição declarativa da jQuery.

A Vue também fornece uma distribuição alternativa chamada [petite-vue](https://github.com/vuejs/petite-vue) que é especialmente otimizada para otimizar progressivamente a HTML existente. Ela tem um conjunto de funcionalidade mais pequeno, mas é extremamente leve e usa uma implementação que é mais eficiente em cenários onde não existem etapas de construção.

## Componentes de Web Embutidos {#embedded-web-components}

Tu podes usar a Vue para [construir Componentes de Web padronizados](/guide/extras/web-components) que podem ser embutidos em qualquer página de HTML, independentemente de como eles são apresentados. Esta opção permite-te influenciar a Vue de uma maneira completamente agnóstica em relação o consumidor: os componentes de web resultantes podem ser embutidos em aplicações legadas, HTML estático, ou mesmo em aplicações construídas com outras abstrações.

## Aplicação de Página Única (SPA) {#single-page-application-spa}

Algumas aplicações exigem riqueza de interatividade, profundidade de sessão profunda, e lógica com estado não trivial no frontend. A melhor maneira de construir tais aplicações é usar uma arquitetura onde a Vue não apenas controla a página inteira, mas também manipula as atualizações de dados e a navegação sem ter de recarregar a página. Este tipo de aplicação é normalmente remetida para uma Aplicação de Página Única (SPA, sigla em Inglês).

A Vue fornece as bibliotecas principais e [suporte ferramental exaustivo](/guide/scaling-up/tooling) com incrível experiência de programação para a construção de SPAs modernas, incluindo:

- Roteador no lado do cliente
- Cadeia de ferramenta de construção extremamente rápida
- Suporte de IDE
- Ferramentas de programação do navegador
- Integrações de TypeScript
- Utilitários de Testes

As SPAs normalmente exigem backend para expor os destinos da API - mas também podes parear a Vue com soluções como [Inertia.js](https://inertiajs.com) para teres os benefícios da SPA enquanto manténs um modelo de desenvolvimento centrado no servidor.

## Pilha Completa (Fullstack) / SSR {#fullstack-ssr}

SPAs do lado do cliente puras são problemáticas quando a aplicação for sensível ao SEO e tempo-para-o-conteúdo. Isto é o porque que o navegador receberá uma página de HTML em grande parte vazia, e terá de esperar até o código JavaScript ser carregado antes da apresentação de qualquer coisa.

A Vue fornece APIs de primeira classe para "gerar" uma aplicação de Vue em sequências de caracteres de HTML no servidor. Isto permite o servidor devolver o HTML pronto, permitindo os utilizadores finais ver o conteúdo imediatamente enquanto o JavaScript estiver a ser carregado. A Vue então "hidratará" a aplicação no lado do cliente para torná-la interativa. Isto é chamado [Interpretação no Lado do Servidor (SSR, sigla em Inglês)](/guide/scaling-up/ssr) e melhora grandemente as métricas Vitais da Núcleo da Web tais como [Pintura Alargada do Conteúdo (LCP)](https://web.dev/lcp/).

Existem abstrações de alto nível baseadas na Vue construídas sobre este paradigma, tal com a [Nuxt](https://nuxt.com/), que permite-te programar uma aplicação de pilha completa usando a Vue e JavaScript (e TypeScript também).

## JAMStack / SSG {#jamstack-ssg}

A interpretação no lado do servidor pode ser feita antes da hora marcada se o dado necessário for estático. Isto significa que podemos pré-gerar uma aplicação inteira em HTML e servi-la como ficheiros estáticos. Isto melhora o desempenho da aplicação e torna a implementação em produção muito mais simples já que não mais precisamos gerar as páginas dinamicamente em cada requisição. A Vue pode continuar a hidratar tais aplicações para fornecer riqueza de interatividade no cliente. Esta técnica é comummente remetida para a "Static-Site Generation (SSG)" ou Geração de Páginas Estáticas em Português, também conhecida como [JAMStack](https://jamstack.org/what-is-jamstack/).

Existem dois sabores de SSG: "single-page" ou única-página e "multi-page" ou várias-páginas. Ambos sabores geram previamente a aplicação como HTML estático, a diferença é que:

- Depois do carregamento inicial da página, a abordagem de única página "hidrata" a página para uma SPA. Isto exige a carga de JavaScript mais adiantada e custo de hidratação, mas as navegações subsequentes serão mais rápidas, já que ela apenas precisa atualizar parcialmente a página ao invés de recarregar a página inteira.

- Um abordagem de várias páginas carrega uma nova página em cada navegação. A diferença é que ela pode entregar o mínimo de JavaScript - ou nenhum JavaScript de todo se a página não exigir nenhuma interação! Algumas das abstrações que aplicam a abordagem de várias páginas tais como a [Astro](https://astro.build/) também suportam a "hidratação parcial" - o qual permite-te usar os componentes de Vue para criar "ilhas" interativas dentro do HTML estático.

As abstrações que suportam a abordagem de única página são mais adequadas se imaginas interatividade fora do comum, longas sessões, ou elementos e estados persistidos através da navegações. Caso contrário, a abordagem de várias páginas seria a melhor escolha.

A equipa da Vue também mantém um gerador de aplicação estática chamado [VitePress](https://vitepress.vuejs.org/), o qual alimenta esta página que estás a ler neste preciso momento! a VitePress suporta ambos sabores de SSG. A [Nuxt](https://nuxt.com/) também suporta SSG. Tu podes até mesmo misturar SSR e SSG para diferentes rotas na mesma aplicação de Nuxt.

## Para Além da Web {#beyond-the-web}

Embora a Vue esteja primariamente desejada para a construção de aplicações de web, de maneira nenhuma esta limitada apenas ao navegador. Tu podes:

- Construir aplicações desktop com [Electron](https://www.electronjs.org/) ou [Tauri](https://tauri.studio/en/)
- Construir aplicações móveis com a [Ionic Vue](https://ionicframework.com/docs/vue/overview)
- Construir aplicações desktop e móveis a partir da mesma base de código com [Quasar](https://quasar.dev/)
- Use a [API do Interpretador Personalizada](/api/custom-renderer) da Vue para construir interpretadores personalizados apontando para [WebGL](https://troisjs.github.io/) ou mesmo [o terminal](https://github.com/ycmjason/vuminal)!

---

---
url: /guide/essentials/event-handling.md
---
# Manipulação de Evento {#event-handling}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/user-events-in-vue-3" title="Aula Gratuita Sobre Eventos em Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-user-events-in-vue-3" title="Aula Gratuita Sobre Eventos em Vue.js"/>
</div>

## Ouvindo Eventos {#listening-to-events}

Nós podemos utilizar a diretiva `v-on`, que normalmente abreviamos para o símbolo `@`, para ouvir os eventos do DOM e executar algum código de JavaScript quando são acionadas. A utilização seria `v-on:click="handler"` ou com o atalho, `@click="handler"`.

O valor de `handler` (manipulador) pode ser um dos seguintes:

1. **Manipuladores em linha:** O código de JavaScript em linha pode ser executado quando o evento é acionado (semelhante ao atributo `onclick` nativo).

2. **Manipuladores de método:** O nome da propriedade ou o caminho que aponta para um método definido no componente.

## Manipuladores Em Linha {#inline-handlers}

Os manipuladores em linha normalmente são utilizados em casos simples, por exemplo:

<div class="composition-api">

```js
const count = ref(0)
```

</div>
<div class="options-api">

```js
data() {
  return {
    count: 0
  }
}
```

</div>

```vue-html
<button @click="count++">Add 1</button>
<p>Count is: {{ count }}</p>
```

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNo9jssKgzAURH/lko0tgrbbEqX+Q5fZaLxiqHmQ3LgJ+fdqFZcD58xMYp1z1RqRvRgP0itHEJCia4VR2llPkMDjBBkmbzUUG1oII4y0JhBIGw2hh2Znbo+7MLw+WjZ/C4TaLT3hnogPkcgaeMtFyW8j2GmXpWBtN47w5PWBHLhrPzPCKfWDXRHmPsCAaOBfgSOkdH3IGUhpDBWv9/e8vsZZ/gFFhFJN)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNo9jcEKgzAQRH9lyKlF0PYqqdR/6DGXaLYo1RjiRgrivzepIizLzu7sm1XUzuVLIFEKObe+d1wpS183eYahtw4DY1UWMJr15ZpmxYAnDt7uF0BxOwXL5Evc0kbxlmyxxZLFyY2CaXSDZkqKZROYJ4tnO/Tt56HEgckyJaraGNxlsVt2u6teHeF40s20EDo9oyGy+CPIYF1xULBt4H6kOZeFiwBZnOFi+wH0B1hk)

</div>

## Manipuladores de Método {#method-handlers}

A lógica para muitos manipuladores de evento será mais complexa, e provavelmente não é viável com manipuladores em linha. É por isto que a `v-on` também pode aceitar o nome ou caminho de um método do componente que gostarias de chamar.

Por exemplo:

<div class="composition-api">

```js
const name = ref('Vue.js')

function greet(event) {
  alert(`Hello ${name.value}!`)
  // `event` é um evento de DOM nativo
  if (event) {
    alert(event.target.tagName)
  }
}
```

</div>
<div class="options-api">

```js
data() {
  return {
    name: 'Vue.js'
  }
},
methods: {
  greet(event) {
    // `this` dentro de métodos aponta para atual instância ativa
    alert(`Hello ${this.name}!`)
    // `event` é um evento de DOM nativo
    if (event) {
      alert(event.target.tagName)
    }
  }
}
```

</div>

```vue-html
<!-- `greet` é o nome do método definido acima -->
<button @click="greet">Greet</button>
```

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpVj0FLxDAQhf/KMwjtXtq7dBcFQS/qzVMOrWFao2kSkkkvpf/dJIuCEBgm771vZnbx4H23JRJ3YogqaM+IxMlfpNWrd4GxI9CMA3NwK5psbaSVVjkbGXZaCediaJv3RN1XbE5FnZNVrJ3FEoi4pY0sn7BLC0yGArfjMxnjcLsXQrdNJtFxM+Ys0PcYa2CEjuBPylNYb4THtxdUobj0jH/YX3D963gKC5WyvGZ+xR7S5jf01yPzeblhWr2ZmErHw0dizivfK6PV91mKursUl6dSh/4qZ+vQ/+XE8QODonDi)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNplUE1LxDAQ/StjEbYL0t5LXRQEvag3Tz00prNtNE1CMilC6X83SUkRhJDJfLz3Jm8tHo2pFo9FU7SOW2Ho0in8MdoSDHhlXhKsnQIYGLHyvL8BLJK3KmcAis3YwOnDY/XlTnt1i2G7i/eMNOnBNRkwWkQqcUFFByVAXUNPk3A9COXEgBkGRgtFDkgDTQjcWxuAwDiJBeMsMcUxszCJlsr+BaXUcLtGwiqut930579KST1IBd5Aqlgie3p/hdTIk+IK//bMGqleEbMjxjC+BZVDIv0+m9CpcNr6MDgkhLORjDBm1H56Iq3ggUvBv++7IhnUFZfnGNt6b4fRtj5wxfYL9p+Sjw==)

</div>

Um manipulador de método recebe automaticamente o objeto de evento de DOM nativo que o aciona - no exemplo acima, somos capazes de acessar o elemento despachando o evento através de `event.target.tagName`.

<div class="composition-api">

Consulte: [Tipos para os Manipuladores de Evento](/guide/typescript/composition-api#typing-event-handlers) <sup class="vt-badge ts" />

</div>
<div class="options-api">

Consulte: [Tipos para os Manipuladores de Evento](/guide/typescript/options-api#typing-event-handlers) <sup class="vt-badge ts" />

</div>

### Método vs. Deteção Em Linha {#method-vs-inline-detection}

O compilador do modelo de marcação deteta os manipuladores de método verificando se o valor de sequência de caracteres de `v-on` é um identificador de JavaScript válido ou caminho de acesso de propriedade. Por exemplo, `foo`, `foo.bar` e `foo['bar']` são tratados como manipuladores de métodos, enquanto `foo()` e `count++` são tratados como manipuladores em linha.

## Chamando Métodos em Manipuladores Em Linha {#calling-methods-in-inline-handlers}

No lugar de vincular diretamente para um nome de método, também podemos chamar métodos em um manipulador em linha. Isto permite-nos passar os argumentos personalizados do método ao invés do evento nativo:

<div class="composition-api">

```js
function say(message) {
  alert(message)
}
```

</div>
<div class="options-api">

```js
methods: {
  say(message) {
    alert(message)
  }
}
```

</div>

```vue-html
<button @click="say('hello')">Say hello</button>
<button @click="say('bye')">Say bye</button>
```

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNp9jTEOwjAMRa8SeSld6I5CBWdg9ZJGBiJSN2ocpKjq3UmpFDGx+Vn//b/ANYTjOxGcQEc7uyAqkqTQI98TW3ETq2jyYaQYzYNatSArZTzNUn/IK7Ludr2IBYTG4I3QRqKHJFJ6LtY7+zojbIXNk7yfmhahv5msvqS7PfnHGjJVp9w/hu7qKKwfEd1NSg==)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNptjUEKwjAQRa8yZFO7sfsSi57B7WzGdjTBtA3NVC2ldzehEFwIw8D7vM9f1cX742tmVSsd2sl6aXDgjx8ngY7vNDuBFQeAnsWMXagToQAEWg49h0APLncDAIUcT5LzlKJsqRBfPF3ljQjCvXcknEj0bRYZBzi3zrbPE6o0UBhblKiaKy1grK52J/oA//23IcmNBD8dXeVBtX0BF0pXsg==)

</div>

## Acessando Argumento de Evento nos Manipuladores Em Linha {#accessing-event-argument-in-inline-handlers}

Algumas vezes também precisamos acessar o evento de DOM original em um manipulador em linha. Tu podes passá-lo para um método utilizando variável especial `$event`, ou utilizar uma função em flecha em linha:

```vue-html
<!-- utilizando a variável especial $event -->
<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

<!-- utilizando a função em flecha em linha -->
<button @click="(event) => warn('Form cannot be submitted yet.', event)">
  Submit
</button>
```

<div class="composition-api">

```js
function warn(message, event) {
  // agore temos acesso ao evento nativo
  if (event) {
    event.preventDefault()
  }
  alert(message)
}
```

</div>
<div class="options-api">

```js
methods: {
  warn(message, event) {
    // agore temos acesso ao evento nativo
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}
```

</div>

## Modificadores de Evento {#event-modifiers}

É muito comum precisar chamar `event.preventDefault()` ou `event.stopPropagation()` dentro de manipuladores de evento. Ainda que possamos fazer isto facilmente dentro de métodos, seria melhor se os métodos pudessem ser puramente a respeito da lógica dos dados em vez de ter que lidar com detalhes de evento de DOM.

Para tratar este problema, a Vue fornece **modificadores de evento** para `v-on`. Recorda-te de que os modificadores são nomes especiais depois do nome do evento denotados por um ponto.

- `.stop`
- `.prevent`
- `.self`
- `.capture`
- `.once`
- `.passive`

```vue-html
<!-- o propagação do evento de clique será interrompida -->
<a @click.stop="doThis"></a>

<!-- o evento de submeter já não recarregará a página -->
<form @submit.prevent="onSubmit"></form>

<!-- modificadores podem ser encadeados -->
<a @click.stop.prevent="doThat"></a>

<!-- apenas o modificador -->
<form @submit.prevent></form>

<!-- apenas aciona o manipulador se `event.target` for o próprio elemento -->
<!-- por exemplo, não um elemento filho -->
<div @click.self="doThat">...</div>
```

:::tip DICA
A ordem importa quando estiveres utilizando modificadores porque o código relevante é gerado na mesma ordem. Portanto a utilização de `@click.prevent.self` impedirá **a ação de cliques padrão sobre o próprio elemento e seus filhos** enquanto `@click.self.prevent` só impedirá a ação de cliques padrão sobre o próprio elemento.
:::

Os modificadores `.capture`, `.once`, e `.passive` refletem as [opções do método `addEventListener` nativo](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options):

```vue-html
<!-- utilize o modo de captura quando estiveres adicionando o ouvinte de evento -->
<!-- por exemplo, um evento mirando um elemento interno é manipulado aqui antes de ser manipulado por aquele elemento -->
<div @click.capture="doThis">...</div>

<!-- o evento de clique será acionado no máximo uma vez -->
<a @click.once="doThis"></a>

<!-- o comportamento padrão do evento de deslocamento (deslocando) acontecerá -->
<!-- imediatamente, no lugar de esperar o `onScroll` terminar  -->
<!-- neste caso ele contém `event.preventDefault()`                -->
<div @scroll.passive="onScroll">...</div>
```

O modificador `.passive` é normalmente utilizado com o ouvintes de evento de toque para [melhorar o desempenho nos dispositivos móveis](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#improving_scrolling_performance_with_passive_listeners).

:::tip DICA
Não utilize `.passive` e `.prevent` juntos, porque `.passive` já indica para o navegador que _não_ tencionas prevenir o comportamento padrão do evento, e provavelmente verás um aviso a partir do navegador se o fizeres.
:::

## Modificadores de Tecla {#key-modifiers}

Quando estivermos ouvindo por eventos teclado, precisamos com frequência verificar por teclas especificas. A Vue permite a adição de modificadores de tecla para `v-on` ou `@` quando estivermos ouvindo por eventos de tecla:

```vue-html
<!-- só chama `vm.submit()` quando a `tecla` pressionada for `Enter` -->
<input @keyup.enter="submit" />
```

Tu podes utilizar diretamente quaisquer nomes de tecla válidos expostos através de [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) como modificadores convertendo-os para "kebab-case".

```vue-html
<input @keyup.page-down="onPageDown" />
```

No exemplo acima, o manipulador só será chamado se `$event.key` for igual a `'PageDown'`.

### Pseudónimos de Tecla {#key-aliases}

A Vue fornece pseudónimos para as teclas mais comummente utilizadas:

- `.enter`
- `.tab`
- `.delete` (captura ambas teclas "Delete" e "Backspace")
- `.esc`
- `.space`
- `.up`
- `.down`
- `.left`
- `.right`

### Teclas Modificadoras do Sistema {#system-modifier-keys}

Tu podes utilizar os seguintes modificadores para acionares ouvintes de eventos de teclado ou rato apenas quando a tecla modificadora correspondente for pressionada:

- `.ctrl`
- `.alt`
- `.shift`
- `.meta`

:::tip NOTA
Nos teclados de Macintosh, meta é a tecla de comando (⌘). Nos teclados de Windows, meta é a tecla de Windows (⊞). Nos teclados de Sun Microsystems, meta é marcado como um diamante sólido (◆). Em certos teclados, especialmente teclados de MIT e máquina de Lisp e sucessores, tais como o teclado de Knight, teclado space-cadet, meta é rotulado “META”. Nos teclados simbólicos, meta é rotulado “META” ou “Meta”.
:::

Por exemplo:

```vue-html
<!-- Alt + Enter -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Do something</div>
```

:::tip NOTA
Nota que as teclas modificadoras são diferentes das teclas normais e quando utilizadas com eventos de `keyup`, elas têm que ser pressionadas quando o evento for emitido. Em outras palavras, `keyup.ctrl` só acionará se libertares uma tecla enquanto estiveres pressionando `ctrl` para baixo. Não acionará se libertares apenas a tecla `ctrl`. 
:::

### O Modificador `.exact` {#exact-modifier}

O modificador `.exact` permite o controlo da combinação exata de modificadores de sistema necessária para acionar um evento.

```vue-html
<!-- isto disparará mesmo se Alt ou Shift também for pressionado -->
<button @click.ctrl="onClick">A</button>

<!-- isto só disparará quando Ctrl e não outras teclas for pressionado -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- isto só disparará quando nenhum dos modificadores do sistema for pressionado -->
<button @click.exact="onClick">A</button>
```

## Modificadores de Botão de Rato {#mouse-button-modifiers}

- `.left`
- `.right`
- `.middle`

Estes modificadores limitam o manipulador para os eventos acionados por um botão de rato especifico.

---

---
url: /guide/extras/rendering-mechanism.md
---

# Mecanismo de Interpretação {#rendering-mechanism}

Como é que a Vue pega um modelo de marcação e transforma-o em nós de DOM reais? Como é que a Vue atualiza estes nós de DOM de maneira efetiva? Nós tentaremos lançar alguma luz sobre estas questões nesta seção mergulhando para dentro do mecanismo interno de interpretação da Vue.

## DOM Virtual {#virtual-dom}

Tu provavelmente tens ouvido o termo "DOM virtual" ou "virtual DOM", que é sobre o qual o sistema de interpretação da Vue é baseado.

O DOM virtual é um conceito de programação onde uma representação ideal, ou “virtual” de uma Interface de Utilizador é mantida em memória e sincronizada com o DOM “real”. O conceito foi explorado pela [React](https://reactjs.org/), e tem sido adaptado em muitas outras abstrações com diferentes implementações, incluindo a Vue.

O DOM virtual é mais um padrão do que uma tecnologia específica, assim não existe uma implementação canónica. Nós podemos ilustrar a ideia usando um exemplo simples:

```js
const vnode = {
  type: 'div',
  props: {
    id: 'hello'
  },
  children: [
    /* mais vnodes */
  ]
}
```

Aqui, o `vnode` é um objeto simples de JavaScript (um "nó virtual") representando um elemento `<div>`. Ele contém todas as informações que precisamos para criar o elemento verdadeiro. Ele também contém `vnodes` filhos, o que o torna a raiz de uma árvore de DOM virtual.

Um interpretador de tempo de execução pode percorrer uma árvore de DOM virtual e construir um árvore de DOM real a partir dela. Este processo é chamado de **montagem**.

Se tiveres duas copias de árvores de DOM virtual, o interpretador também pode percorrer e comparar as duas árvores descobrindo as diferenças, e aplicar estas mudanças ao DOM real. Este processo é chamado de **remendo**, também conhecido como "diferenciação" ou "reconciliação".

O principal benefício do DOM virtual é que dá ao programador a habilidade de criar, inspecionar e compor programaticamente as estruturas de Interface de Utilizador desejadas de uma maneira declarativa, enquanto deixa a manipulação direta do DOM por conta do interpretador.

## Conduta de Interpretação {#render-pipeline}

Em alto nível, isto é o que acontece quando um componente de Vue é montado:

1. **Compilação**: Os modelos de marcação de Vue são compilado em **funções de interpretação**: funções que retornam árvores de DOM virtual. Esta etapa pode ser feita ou antecipadamente através de uma etapa de construção, ou durante o despacho usando o compilador do tempo de execução.

2. **Montagem**: O interpretador do momento da execução invoca as funções de interpretação, percorre a árvore de DOM virtual retorna e cria os nós de DOM real baseado nela. Esta etapa é realizada como [efeito reativo](./reactivity-in-depth), assim preserva todos as dependências reativas que foram usadas.

3. **Remendo**: Quando uma dependência usada durante a montagem mudar, o efeito é executado novamente. Desta vez, uma nova, árvore de DOM virtual atualizada é criada. O interpretador do momento da execução percorre a nova árvore, compara-a com a antiga, e aplica as atualizações necessárias ao DOM real.

![conduta de interpretação](./images/render-pipeline.png)

<!-- https://www.figma.com/file/elViLsnxGJ9lsQVsuhwqxM/Rendering-Mechanism -->

## Modelos de Marcação vs. Funções de Interpretação {#templates-vs-render-functions}

Os modelos de marcação são compilados para as funções de interpretação do DOM virtual. A Vue também fornece APIs que permitem-nos ignorar a etapa de compilação do modelo de marcação e escrever diretamente as funções de interpretação. As funções de interpretação são mais flexíveis do que os modelos de marcação quando lidamos com lógica altamente dinâmica, porque podes trabalhar com `vnodes` usando o poder máximo da JavaScript.

Então porquê que a Vue recomenda os modelos de marcação por padrão? Existem um número de razões:

1. Os modelos de marcação estão mais próximo do HTML real. Isto torna-o muito mais fácil de reutilizar trechos de HTML existentes, aplicar boas práticas de acessibilidade, estilizar com a CSS, e para os desenhadores entenderem e modificarem.

2. Os modelos de marcação são muito mais fáceis de analisar estaticamente devido a sua sintaxe mais determinística. Isto permite o compilador de modelo de marcação da Vue aplicar muitas otimizações no momento da compilação para melhorar o desempenho do DOM virtual (o qual discutiremos abaixo).

Na prática, os modelos de marcação são suficientes para maioria dos casos de uso nas aplicações. As funções de interpretação são normalmente apenas usadas em componentes reutilizáveis que precisam de lidar com lógica de apresentação altamente dinâmica. O uso da função de interpretação é discutido em mais detalhes na seção [Funções de Interpretação & JSX](./render-function).

## DOM Virtual Informado Pelo Compilador {#compiler-informed-virtual-dom}

A implementação do DOM virtual em React e a maioria das outras implementações do DOM virtual são puramente de tempo de execução: o algoritmo de reconciliação não pode fazer quaisquer suposições sobre a futura árvore do DOM virtual, assim tem de atravessar completamente a árvore e diferenciar as propriedades de cada `vnode` para assegurar correção. Além disto, mesmo se uma parte da árvore nunca mudar, os novos `vnodes` sempre serão criados para eles em cada re-interpretação, resultando em pressão de memória desnecessária. Isto é, um dos aspetos mais criticados do DOM virtual: o um tanto de processo de reconciliação de força bruta sacrifica a eficiência em troca da declaritividade e correção.

Mas isto não tem de ser desta maneira. Na Vue, a abstração controla tanto o compilador quanto o tempo de execução. Isto permite-nos implementar várias otimizações em tempo de compilação que apenas um interpretador emparelhado com firmeza pode tirar partido. O compilador pode analisar estaticamente o modelo de marcação e deixar sugestões no código gerado para que o tempo de execução possa pegar atalhos sempre que possível. Ao mesmo tempo, continuamos a preserver a capacidade do utilizador de largar para a camada da função de interpretação para controlo mais direto em casos extremos. Nós chamamos disto abordagem híbrida **DOM Virtual Informado Pelo Compilador**.

Abaixo, discutiremos algumas das otimizações principais feitas pelo compilador de modelo de marcação da Vue para melhorar o desempenho de tempo de execução do DOM virtual.

### Içamento Estático {#static-hoisting}

Muito frequentemente existirão partes num modelo de marcação que não contém quaisquer vínculos dinâmicos:

```vue-html{2-3}
<div>
  <div>foo</div> <!-- içado -->
  <div>bar</div> <!-- içado -->
  <div>{{ dynamic }}</div>
</div>
```

[Inspecionar no Explorador de Modelo de Marcação](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2PlxuICA8ZGl2PmZvbzwvZGl2PlxuICA8ZGl2PmJhcjwvZGl2PlxuICA8ZGl2Pnt7IGR5bmFtaWMgfX08L2Rpdj5cbjwvZGl2PiIsInNzciI6ZmFsc2UsIm9wdGlvbnMiOnsiaG9pc3RTdGF0aWMiOnRydWV9fQ==)

Os divisores `foo` e `bar` são estáticos - a recriação de `vnodes` e a diferenciação deles em cada reinterpretação é desnecessária. O compilador da Vue iça automaticamente as chamadas de criação de seus `vnode` fora da função de interpretação, e reutiliza os mesmos `vnodes` em toda interpretação. O interpretador também é capaz de ignorar complemente a diferenciação deles quando notar que o antigo `vnode` e o novo `vnode` o mesmo.

Além disto, quando existirem elementos estáticos consecutivos suficientes, serão condensados em um único "`vnode` estático" que contém a sequência de caracteres de HTML simples para todos estes nós ([Exemplo](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2PlxuICA8ZGl2IGNsYXNzPVwiZm9vXCI+Zm9vPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmb29cIj5mb288L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImZvb1wiPmZvbzwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZm9vXCI+Zm9vPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmb29cIj5mb288L2Rpdj5cbiAgPGRpdj57eyBkeW5hbWljIH19PC9kaXY+XG48L2Rpdj4iLCJzc3IiOmZhbHNlLCJvcHRpb25zIjp7ImhvaXN0U3RhdGljIjp0cnVlfX0=)). Estes `vnodes` estáticos são montados definindo `innerHTML` diretamente. Eles também armazenam os seus nós de DOM correspondentes para consulta imediata na montagem inicial - se o pedaço de conteúdo for reutilizado noutro lado na aplicação, novos nós de DOM são criados usando `cloneNode()` nativo, o qual é extremamente eficiente.

### Opções de Remendo {#patch-flags}

Para um único elemento com vínculos dinâmicos, também podemos inferir muita informação a partir deste em tempo de compilação:

```vue-html
<!-- apenas vinculação de classe -->
<div :class="{ active }"></div>

<!-- apenas vínculos de identificador e valor -->
<input :id="id" :value="value">

<!-- apenas filhos de texto -->
<div>{{ dynamic }}</div>
```

[Inspecionar no Explorador de Modelo de Marcação](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2IDpjbGFzcz1cInsgYWN0aXZlIH1cIj48L2Rpdj5cblxuPGlucHV0IDppZD1cImlkXCIgOnZhbHVlPVwidmFsdWVcIj5cblxuPGRpdj57eyBkeW5hbWljIH19PC9kaXY+Iiwib3B0aW9ucyI6e319)

Quando estiveres a gerar o código da função de interpretação para estes elementos, a Vue codifica o tipo de atualização que cada uma delas precisa diretamente na chamada de criação de `vnode`:

```js{3}
createElementVNode("div", {
  class: _normalizeClass({ active: _ctx.active })
}, null, 2 /* CLASS */)
```

O último argumento, `2`, é uma [opção de remendo](https://github.com/vuejs/core/blob/main/packages/shared/src/patchFlags.ts). Um elemento pode ter várias opções de remendo, as quais serão combinadas em um único número. O interpretador de tempo de execução pode então verificar contra as opções usando [operações de bitwise](https://en.wikipedia.org/wiki/Bitwise_operation) para determinar se precisa de fazer certo trabalho:

```js
if (vnode.patchFlag & PatchFlags.CLASS /* 2 */) {
  // atualiza a classe do elemento
}
```

As verificações de bitwise são extremamente rápida. Com as opções de remendo, a Vue é capaz de fazer a quantidade mínima de trabalho necessário quando estiveres a atualizar os elementos com vínculos dinâmicos.

A Vue também codifica o tipo de filhos que um `vnode` tem. Por exemplo, um modelo de marcação que tem vários nós de raiz é representado como um fragmento. Na maioria dos casos, sabemos com certeza que a ordem destes nós de raiz nunca mudarão, assim esta informação também pode ser fornecida para o executor como opção de remendo:

```js{4}
export function render() {
  return (_openBlock(), _createElementBlock(_Fragment, null, [
    /* children */
  ], 64 /* STABLE_FRAGMENT */))
}
```

O executor pode assim ignorar complemente a reconciliação de ordem do filho para o fragmento de raiz.

### Aplainamento de Árvore {#tree-flattening}

Dando uma outra vista de olhos no código gerado pelo exemplo anterior, notarás que a raiz da árvore de DOM virtual retornada é criada usando uma chamada especial de `createElementBlock()`:

```js{2}
export function render() {
  return (_openBlock(), _createElementBlock(_Fragment, null, [
    /* children */
  ], 64 /* STABLE_FRAGMENT */))
}
```

Conceitualmente, um "bloco" é uma parte do modelo de marcação que tem estrutura interna estável. Neste caso, modelo de marcação inteiro tem um único bloco porque não contém quaisquer diretivas estruturais como `v-if` e `v-for`.

Cada bloco rastreia quaisquer nós descendente (não apenas filhos diretos) que têm opções de remendo. Por exemplo:

```vue-html{3,5}
<div> <!-- bloco de raiz -->
  <div>...</div>         <!-- não rastreado -->
  <div :id="id"></div>   <!-- rastreado -->
  <div>                  <!-- não rastreado-->
    <div>{{ bar }}</div> <!-- rastreado -->
  </div>
</div>
```

O resultado é um arranjo aplanado que contém apenas os nós descendentes dinâmicos:

```
div (raiz do bloco)
- div com vínculo de :id
- div com vínculo de {{ bar }}
```

Quando este componente precisa de re-apresentar, apenas precisa de atravessar a árvore aplanada ao invés da árvore completa. Isto é chamado de **Aplainamento de Árvore**, e reduz grandemente o número de nós que precisa ser atravessado durante a reconciliação do DOM virtual. Quaisquer partes estáticas do modelo de marcação são efetivamente ignoradas.

As diretivas `v-if` e `v-for` criarão novos nós de bloco:

```vue-html
<div> <!-- bloco de raiz -->
  <div>
    <div v-if> <!-- bloco if -->
      ...
    <div>
  </div>
</div>
```

Um bloco filho é rastreado dentro do arranjo de descendentes dinâmicos do bloco pai. Isto conserva uma estrutura estável para o bloco pai.

### Impacto na Hidratação de SSR {#impact-on-ssr-hydration}

Tanto as opções de remendo quanto o aplainamento de árvore também melhoram grandemente o desempenho da [Hidratação de SSR](/guide/scaling-up/ssr#client-hydration) da Vue:

- A hidratação de um único elemento pode pegar caminhos rápidos baseado na opção de remendo do `vnode` correspondente.

- Apenas nós de bloco e seus descendentes dinâmicos precisam de ser atravessados durante a hidratação, alcançando efetivamente a hidratação parcial no nível do modelo de marcação.

---

---
url: /guide/components/v-model.md
---
# Modelo Virtual do Componente {#component-v-model}

## Uso Básico {#basic-usage}

A `v-model` pode ser usada num componente para implementar um vínculo bidirecional.

<div class="composition-api">

Desde a Vue 3.4, a abordagem recomendada para alcançar isto é usar a macro [`defineModel()`](/api/sfc-script-setup#definemodel):

```vue
<!-- Child.vue -->
<script setup>
const model = defineModel()

function update() {
  model.value++
}
</script>

<template>
  <div>Parent bound v-model is: {{ model }}</div>
</template>
```

O pai pode então vincular um valor com `v-model`:

```vue-html
<!-- Parent.vue -->
<Child v-model="countModel" />
```

O valor retornado por `defineModel()` é uma referência. Esta pode ser acessada e alterada como qualquer outra referência, exceto que comporta-se como um vínculo bidirecional entre um valor pai e um valor local:

- Seu `.value` é sincronizado com o valor vinculado pela `v-model` do pai;
- Quando é alterada pelo filho, faz com que o valor vinculado ao pai também seja atualizado.

Isto significa que também podemos vincular esta referência a um elemento de entrada nativo com `v-model`, simplificando o embrulhar de elementos de entrada nativos enquanto fornecemos o mesmo uso de `v-model`:

```vue
<script setup>
const model = defineModel()
</script>

<template>
  <input v-model="model" />
</template>
```

[Exemplo de Testes](https://play.vuejs.org/#eNqFUtFKwzAU/ZWYl06YLbK30Q10DFSYigq+5KW0t11mmoQknZPSf/cm3eqEsT0l555zuefmpKV3WsfbBuiUpjY3XDtiwTV6ziSvtTKOLNZcFKQ0qiZRnATkG6JB0BIDJen2kp5iMlfSOlLbisw8P4oeQAhFPpURxVV0zWSa9PNwEgIHtRaZA0SEpOvbeduG5q5LE0Sh2jvZ3tSqADFjFHlGSYJkmhz10zF1FseXvIo3VklcrfX9jOaq1lyAedGOoz1GpyQwnsvQ3fdTqDnTwPhQz9eQf52ob+zO1xh9NWDBbIHRgXOZqcD19PL9GXZ4H0h03whUnyHfwCrReI+97L6RBdo+0gW3j+H9uaw+7HLnQNrDUt6oV3ZBzyhmsjiz+p/dSTwJfUx2+IpD1ic+xz5enwQGXEDJJaw8Gl2I1upMzlc/hEvdOBR6SNKAjqP1J6P/o6XdL11L5h4=)


### Nos Bastidores {#under-the-hood}

A `defineModel` é uma macro de conveniência. O compilador expande-a ao seguinte:

- Uma propriedade com o nome de `modelValue`, com a qual o valor da referência local é sincronizado;
- Um evento com o nome de `update:modelValue`. que é emitido quando o valor da referência local é alterado.

É assim que implementaríamos o mesmo componente filho mostrado acima antes da versão 3.4:

```vue
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', $event.target.value)"
  />
</template>
```

Como podemos ver, é um pouco mais verboso. No entanto, é útil para compreender o que acontece nos bastidores.

Uma vez que `defineModel` declara uma propriedade, podemos então declarar as opções da propriedade subjacente passando-a a `defineModel`:

```js
// tornar o `v-model` obrigatório
const model = defineModel({ required: true })

// fornecer um valor padrão
const model = defineModel({ default: 0 })
```

:::warning AVISO
Se tivermos um valor `default` para a propriedade `defineModel` e não fornecermos nenhum valor para esta propriedade do componente pai, isto pode causar uma dessincronização entre os componentes pai e filho. No exemplo abaixo, a `myRef` do componente pai é `undefined`, mas `model` do componente filho é `1`:

```js
// componente filho:
const model = defineModel({ default: 1 })

// componente pai:
const myRef = ref()
```

```html
<Child v-model="myRef"></Child>
```

:::

</div>

<div class="options-api">

Primeiro, revisitaremos como a `v-model` é usada sobre um elemento nativo:

```vue-html
<input v-model="searchText" />
```

Nos bastidores, o compilador do modelo de marcação expande `v-model` ao equivalente mais verboso por nós: Então o código acima faz o mesmo que o seguinte:

```vue-html
<input
  :value="searchText"
  @input="searchText = $event.target.value"
/>
```

Quando usada sobre um componente, `v-model` expande-se para isto:

```vue-html
<CustomInput
  :model-value="searchText"
  @update:model-value="newValue => searchText = newValue"
/>
```

Para que isto realmente funcione, o componente `<CustomInput>`  deve fazer duas coisas:

1. Vincular o atributo `value` de um elemento nativo `<input>` à propriedade `modelValue`.
2. Quando um evento de `input` nativo é acionado, emitir um evento personalizado `update:modelValue` com o novo valor.

Eis o que se passa em ação:

```vue
<!-- CustomInput.vue -->
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue']
}
</script>

<template>
  <input
    :value="modelValue"
    @input="$emit('update:modelValue', $event.target.value)"
  />
</template>
```

Agora a `v-model` deve funcionar perfeitamente com este componente:

```vue-html
<CustomInput v-model="searchText" />
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkctqwzAQRX9lEAEn4Np744aWrvoD3URdiHiSGvRCHpmC8b93JDfGKYGCkJjXvTrSJF69r8aIohHtcA69p6O0vfEuELzFgZx5tz4SXIIzUFT1JpfGCmmlxe/c3uFFRU0wSQtwdqxh0dLQwHSnNJep3ilS+8PSCxCQYrC3CMDgMKgrNlB8odaOXVJ2TgdvvNp6vSwHhMZrRcgRQLs1G5+M61A/S/ErKQXUR5immwXMWW1VEKX4g3j3Mo9QfXCeKU9FtvpQmp/lM0Oi6RP/qYieebHZNvyL0acLLODNmGYSxCogxVJ6yW1c2iWz/QOnEnY48kdUpMIVGSllD8t8zVZb+PkHqPG4iw==)

Uma outra maneira de implementar a `v-model` dentro deste componente é usar uma propriedade `computed` gravável com um recuperador e um definidor. O método `get` deve retornar a propriedade `modelValue` e o método `set` deve emitir o evento correspondente:

```vue
<!-- CustomInput.vue -->
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  computed: {
    value: {
      get() {
        return this.modelValue
      },
      set(value) {
        this.$emit('update:modelValue', value)
      }
    }
  }
}
</script>

<template>
  <input v-model="value" />
</template>
```

</div>

## Argumentos da `v-model` {#v-model-arguments}

A `v-model` sobre um componente também pode aceitar um argumento:

```vue-html
<MyComponent v-model:title="bookTitle" />
```

<div class="composition-api">

No componente filho, podemos suportar o argumento correspondente passando uma sequência de caracteres à `defineModel()` como seu primeiro argumento:

```vue
<!-- MyComponent.vue -->
<script setup>
const title = defineModel('title')
</script>

<template>
  <input type="text" v-model="title" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkl9PwjAUxb9K05dhglsMb2SQqOFBE9Soj31Zxh0Uu7bpHxxZ9t29LWOiQXzaes7p2a+9a+mt1unOA53S3JaGa0csOK/nTPJaK+NISwxUpCOVUTVJMJoM1nJ/r/BNgnS9nWYnWujFMCFMlkpaRxx3AsgsFI6S3XWtViBIYda+Dg3QFLUWkFwxmWcHFqTAhQPUCwe4IiTf3Mzbtq/qujzDddRPYfruaUzNGI1PRkmG0Twb+uiY/sI9cw0/0VdQcQnL0D5KovgfL5fa4/69jiDQOOTo+S6SOYtfrvg63VolkauNN0lLxOUCzLN2HMkYnZLoBK8QQn0+Rs0ZD+OjXm6g/Dijb20TNEZfDFgwOwQZPIdzAWQN9uLtKXIPJtL7gH3BfAWrhA+Mh9idlyvEPslF2of4J3G5freLxoG0x0MF0JDsYp5RHE6Y1F9H/8adpJO4j8mOdl/Hw/nf)

Se as opções de propriedade também forem necessárias, devem ser passadas depois do nome do modelo:

```js
const title = defineModel('title', { required: true })
```

<details>
<summary>Uso antes da 3.4</summary>

```vue
<!-- MyComponent.vue -->
<script setup>
defineModel({
  title: {
    required: true
  }
})
defineEmits(['update:title'])
</script>

<template>
  <input
    type="text"
    :value="title"
    @input="$emit('update:title', $event.target.value)"
  />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9kE1rwzAMhv+KMIW00DXsGtKyMXYc7D7vEBplM8QfOHJoCfnvk+1QsjJ2svVKevRKk3h27jAGFJWoh7NXjmBACu4kjdLOeoIJPHYwQ+ethoJLi1vq7fpi+WfQ0JI+lCstcrkYQJqzNQMBKeoRjhG4LcYHbVvsofFfQUcCXhrteix20tRl9sIuOCBkvSHkCKD+fjxN04Ka57rkOOlrMwu7SlVHKdIrBZRcWpc3ntiLO7t/nKHFThl899YN248ikYpP9pj1V60o6sG1TMwDU/q/FZRxgeIPgK4uGcQLSZGlamz6sHKd1afUxOoGeeT298A9bHCMKxBfE3mTSNjl1vud5x8qNa76)

</details>
</div>
<div class="options-api">

Neste caso, ao invés da propriedade `modelValue` e evento `update:modelValue` padrão, o componente filho deve esperar uma propriedade `title` e emitir um evento `update:title` para atualizar o valor do pai:

```vue
<!-- MyComponent.vue -->
<script>
export default {
  props: ['title'],
  emits: ['update:title']
}
</script>

<template>
  <input
    type="text"
    :value="title"
    @input="$emit('update:title', $event.target.value)"
  />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFUNFqwzAM/BVhCm6ha9hryMrGnvcFdR9Mo26B2DGuHFJC/n2yvZakDAohtuTTne5G8eHcrg8oSlFdTr5xtFe2Ma7zBF/Xz45vFi3B2XcG5K6Y9eKYVFZZHBK8xrMOLcGoLMDphrqUMC6Ypm18rzXp9SZjATxS8PZWAVBDLZYg+xfT1diC9t/BxGEctHFtlI2wKR78468q7ttzQcgoTcgVQPXzuh/HzAnTVBVcp/58qz+lMqHelEinElAwtCrufGIrHhJYBPdfEs53jkM4yEQpj8k+miYmc5DBcRKYZeXxqZXGukDZPF1dWhQHUiK3yl63YbZ97r6nIe6uoup6KbmFFfbRCnHGyI4iwyaPPnqffgGMlsEM)

</div>

## Vários Vínculos de `v-model` {#multiple-v-model-bindings}

Com o aproveitamento da capacidade de mirar uma propriedade e um evento em particular, como aprendemos anteriormente com os argumentos da `v-model`, podemos agora criar vários vínculos de `v-model` numa única instância de componente.

Cada `v-model` sincronizar-se-á com uma propriedade diferente, sem a necessidade de opções adicionais no componente:

```vue-html
<UserName
  v-model:first-name="first"
  v-model:last-name="last"
/>
```

<div class="composition-api">

```vue
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>

<template>
  <input type="text" v-model="firstName" />
  <input type="text" v-model="lastName" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkstuwjAQRX/F8iZUAqKKHQpIfbAoUmnVx86bKEzANLEt26FUkf+9Y4MDSAg2UWbu9fjckVv6oNRw2wAd08wUmitLDNhGTZngtZLakpZoKIkjpZY1SdCadNK3Ab3IazhowzQ2/ES0MVFIYSwpucbvxA/qJXO5FsldlKr8qDxL8EKW7kEQAQsLtapyC1gRkq3vp217mOccwf8wwLksRSlYIoMvCNkOarmEahyODAT2J4yGgtFzhx8UDf5/r6c4NEs7CNqnpxkvbO0kcVjNhCyh5AJe/SW9pBPOV3DJGvu3dsKFaiyxf8qTW9gheQwVs4Z90BDm5oF47cF/Ht4aZC75argxUmD61g9ktJC14hXoN2U5ZmJ0TILitbyq5O889KxuoB/7xRqKnwv9jdn5HqPvGnDVWwTpNJvrFSCul2efi4DeiRigqdB9RfwAI6vGM+5tj41YIvaJL9C+hOfNxerLzHYWhImhPKh3uuBnFJ/A05XoR9zRcBTOMeGo+wcs+yse)

<details>
<summary>Uso antes da 3.4</summary>

```vue
<script setup>
defineProps({
  firstName: String,
  lastName: String
})

defineEmits(['update:firstName', 'update:lastName'])
</script>

<template>
  <input
    type="text"
    :value="firstName"
    @input="$emit('update:firstName', $event.target.value)"
  />
  <input
    type="text"
    :value="lastName"
    @input="$emit('update:lastName', $event.target.value)"
  />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNUc1qwzAMfhVjCk6hTdg1pGWD7bLDGIydlh1Cq7SGxDaOEjaC332yU6cdFNpLsPRJ348y8idj0qEHnvOi21lpkHWAvdmWSrZGW2Qjs1Azx2qrWyZoVMzQZwf2rWrhhKVZbHhGGivVTqsOWS0tfTeeKBGv+qjEMkJNdUaeNXigyCYjZIEKhNY0FQJVjBXHh+04nvicY/QOBM4VGUFhJHrwBWPDutV7aPKwslbU35Q8FCX/P+GJ4oB/T3hGpEU2m+ArfpnxytX2UEsF71abLhk9QxDzCzn7QCvVYeW7XuGyWSpH0eP6SyuxS75Eb/akOpn302LFYi8SiO8bJ5PK9DhFxV/j0yH8zOnzoWr6+SbhbifkMSwSsgByk1zzsoABFKZY2QNgGpiW57Pdrx2z3JCeI99Svvxh7g8muf2x)

</details>
</div>
<div class="options-api">

```vue
<script>
export default {
  props: {
    firstName: String,
    lastName: String
  },
  emits: ['update:firstName', 'update:lastName']
}
</script>

<template>
  <input
    type="text"
    :value="firstName"
    @input="$emit('update:firstName', $event.target.value)"
  />
  <input
    type="text"
    :value="lastName"
    @input="$emit('update:lastName', $event.target.value)"
  />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNkk1rg0AQhv/KIAETSJRexYYWeuqhl9JTt4clmSSC7i7rKCnif+/ObtYkELAiujPzztejQ/JqTNZ3mBRJ2e5sZWgrVNUYbQm+WrQfskE4WN1AmuXRwQmpUELh2Qv3eJBdTTAIBbDTLluhoraA4VpjXHNwL0kuV0EIYJE6q6IFcKhsSwWk7/qkUq/nq5be+aa5JztGfrmHu8t8GtoZhI2pJaGzAMrT03YYQk0YR3BnruSOZe5CXhKnC3X7TaP3WBc+ZaOc/1kk3hDJvYILRQGfQzx3Rct8GiJZJ7fA7gg/AmesNszMrUIXFpxbwCfZSh09D0Hc7tbN6sAWm4qZf6edcZgxrMHSdA3RF7PTn1l8lTIdhbXp1/CmhOeJRNHLupv4eIaXyItPdJEFD7R8NM0Ce/d/ZCTtESnzlVZXhP/vHbeZaT0tPdf59uONfx7mDVM=)

</div>

## Manipulação de Modificadores da `v-model` {#handling-v-model-modifiers}

Quando aprendemos sobre os vínculos de entrada de formulário, vimos que a `v-model` tem [modificadores embutidos](/guide/essentials/forms#modifiers) — `.trim`, `.number` e `.lazy`. Em alguns casos, também podemos querer que a `v-model` sobre o nosso componente de entrada personalizado suporte modificadores personalizados.

Criaremos um exemplo de modificador personalizado, `capitalize`, que transforma a primeira letra da sequência de caracteres fornecida pelo vínculo de `v-model` em maiúscula:

```vue-html
<MyComponent v-model.capitalize="myText" />
```

<div class="composition-api">

Os modificadores adicionados a `v-model` de um componente podem ser acessados no componente filho através da desestruturação do valor de retorno da `defineModel()` da seguinte maneira:

```vue{4}
<script setup>
const [model, modifiers] = defineModel()

console.log(modifiers) // { capitalize: true }
</script>

<template>
  <input type="text" v-model="model" />
</template>
```

Para ajustar condicionalmente como o valor de ser lido ou escrito baseado nos modificadores, podemos passar as opções `get` e `set` a `defineModel()`. Estas duas opções recebem o valor na recuperação ou definição da referência do modelo e devem retornar um valor transformado. É assim que podemos usar a opção `set` para implementar o modificador `capitalize`:

```vue{6-8}
<script setup>
const [model, modifiers] = defineModel({
  set(value) {
    if (modifiers.capitalize) {
      return value.charAt(0).toUpperCase() + value.slice(1)
    }
    return value
  }
})
</script>

<template>
  <input type="text" v-model="model" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9UsFu2zAM/RVClzhY5mzoLUgHdEUPG9Bt2LLTtIPh0Ik6WxIkyosb5N9LybFrFG1OkvgeyccnHsWNtXkbUKzE2pdOWQKPFOwnqVVjjSM4gsMKTlA508CMqbMRuu9uDd80ajrD+XISi3WZDCB1abQnaLoNHgiuY8VsNptLvV72TbkdPwgbWxeE/ALY7JUHpW0gKAurqKjVI3rAFl1He6V30JkA3AbdKvLXUzXt+8Zssc6fM6+l6NtLAUtusF6O3cRCvFB9yY2SiYFw+8KSYcY/qfEC+FCVQuf/8rxbrJTG+4hkxyiWq2ZtUQecQ3oDqAqyMWeieyQAu0bBaUh5ebkv3A1lH+Y5md/WorstPGZzeHfGfa1KzD6yxzH11B/TCjHC4dPlX1j3P0CdjQ5S79/Z3WhpPF91lDz7Uald/uCNZj/TFFJE91SN7rslxX5JsRrmk6Koa/P/a4qRC7gY4uUey3+vxB/8Icak+OHQo2tRihGjwu2QtUb47te3pHsEWXWomX0B/Ine1CFq7Gmfg96y7Akvqf2StoKXcePvDoTaD0NFocnhxJeClyRu2FujP8u9yq+GnxGnJxSEO+M=)

<details>
<summary>Uso antes da 3.4</summary>

```vue{11-13}
<script setup>
const props = defineProps({
  modelValue: String,
  modelModifiers: { default: () => ({}) }
})

const emit = defineEmits(['update:modelValue'])

function emitValue(e) {
  let value = e.target.value
  if (props.modelModifiers.capitalize) {
    value = value.charAt(0).toUpperCase() + value.slice(1)
  }
  emit('update:modelValue', value)
}
</script>

<template>
  <input type="text" :value="modelValue" @input="emitValue" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9Us1Og0AQfpUJF5ZYqV4JNTaNxyYmVi/igdCh3QR2N7tDIza8u7NLpdU0nmB+v5/ZY7Q0Jj10GGVR7iorDYFD6sxDoWRrtCU4gsUaBqitbiHm1ngqrfuV5j+Fik7ldH6R83u5GaBQlVaOoO03+Emw8BtFHCeFyucjKMNxQNiapiTkCGCzlw6kMh1BVRpJZSO/0AEe0Pa0l2oHve6AYdBmvj+/ZHO4bfUWm/Q8uSiiEb6IYM4A+XxCi2bRH9ZX3BgVGKuNYwFbrKXCZx+Jo0cPcG9l02EGL2SZ3mxKr/VW1hKty9hMniy7hjIQCSweQByHBIZCDWzGDwi20ps0Yjxx4MR73Jktc83OOPFHGKk7VZHUKkyFgsAEAqcG2Qif4WWYUml3yOp8wldlDSLISX+TvPDstAemLeGbVvvSLkncJSnpV2PQrkqHLOfmVHeNrFDcMz3w0iBQE1cUzMYBbuS2f55CPj4D6o0/I41HzMKsP+u0kLOPoZWzkx1X7j18A8s0DEY=)

</details>
</div>

<div class="options-api">

Os modificadores adicionados a uma `v-model` de um componente serão fornecidos ao componente através da propriedade `modelModifiers`. No exemplo abaixo, criamos um componente que contém uma propriedade `modelModifiers` que tem como padrão um objeto vazio:

```vue{11}
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  created() {
    console.log(this.modelModifiers) // { capitalize: true }
  }
}
</script>

<template>
  <input
    type="text"
    :value="modelValue"
    @input="$emit('update:modelValue', $event.target.value)"
  />
</template>
```

Observemos que a propriedade `modelModifiers` do componente contém `capitalize` e seu valor é `true` — devido ao fato de ter sido definida sobre o vínculo da `v-model` `v-model.capitalize="myText"`.

Agora temos a nossa propriedade configurada, podemos verificar as chaves do objeto `modelModifiers` e escrever um manipulador para alterar o valor emitido. No código abaixo, transformaremos a primeira letra da sequência de caracteres em maiúscula sempre que o elemento `<input />` disparar um evento `input`.

```vue{13-15}
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  methods: {
    emitValue(e) {
      let value = e.target.value
      if (this.modelModifiers.capitalize) {
        value = value.charAt(0).toUpperCase() + value.slice(1)
      }
      this.$emit('update:modelValue', value)
    }
  }
}
</script>

<template>
  <input type="text" :value="modelValue" @input="emitValue" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFks1qg0AQgF9lkIKGpqa9iikNOefUtJfaw6KTZEHdZR1DbPDdO7saf0qgIq47//PNXL2N1uG5Ri/y4io1UtNrUspCK0Owa7aK/0osCQ5GFeCHq4nMuvlJCZCUeHEOGR5EnRNcrTS92VURXGex2qXVZ4JEsOhsAQxSbcrbDaBo9nihCHyXAaC1B3/4jVdDoXwhLHQuCPkGsD/JCmSpa4JUaEkilz9YAZ7RNHSS5REaVQPXgCay9vG0rPNToTLMw9FznXhdHYkHK04Qr4Zs3tL7g2JG8B4QbZS2LLqGXK5PkdcYwTsZrs1R6RU7lcmDRDPaM7AuWARMbf0KwbVdTNk4dyyk5f3l15r5YjRm8b+dQYF0UtkY1jo4fYDDLAByZBxWCmvAkIQ5IvdoBTcLeYCAiVbhvNwJvEk4GIK5M0xPwmwoeF6EpD60RrMVFXJXj72+ymWKwUvfXt+gfVzGB1tzcKfDZec+o/LfxsTdtlCj7bSpm3Xk4tjpD8FZ+uZMWTowu7MW7S+CWR77)

</div>

### Modificadores para `v-model` com Argumentos {#modifiers-for-v-model-with-arguments}

<div class="options-api">

Para vínculos de `v-model` com ambos argumento e modificadores, o nome da propriedade gerada será `argumento + "Modificadores"`. Por exemplo:

```vue-html
<MyComponent v-model:title.capitalize="myText">
```

As declarações correspondentes devem ser:

```js
export default {
  props: ['title', 'titleModifiers'],
  emits: ['update:title'],
  created() {
    console.log(this.titleModifiers) // { capitalize: true }
  }
}
```

</div>

Eis um outro exemplo de uso de modificadores com várias `v-model` com diferentes argumentos:

```vue-html
<UserName
  v-model:first-name.capitalize="first"
  v-model:last-name.uppercase="last"
/>
```

<div class="composition-api">

```vue
<script setup>
const [firstName, firstNameModifiers] = defineModel('firstName')
const [lastName, lastNameModifiers] = defineModel('lastName')

console.log(firstNameModifiers) // { capitalize: true }
console.log(lastNameModifiers) // { uppercase: true}
</script>
```

<details>
<summary>Uso antes da 3.4</summary>

```vue{5,6,10,11}
<script setup>
const props = defineProps({
firstName: String,
lastName: String,
firstNameModifiers: { default: () => ({}) },
lastNameModifiers: { default: () => ({}) }
})
defineEmits(['update:firstName', 'update:lastName'])

console.log(props.firstNameModifiers) // { capitalize: true }
console.log(props.lastNameModifiers) // { uppercase: true}
</script>
```

</details>
</div>
<div class="options-api">

```vue{15,16}
<script>
export default {
  props: {
    firstName: String,
    lastName: String,
    firstNameModifiers: {
      default: () => ({})
    },
    lastNameModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:firstName', 'update:lastName'],
  created() {
    console.log(this.firstNameModifiers) // { capitalize: true }
    console.log(this.lastNameModifiers) // { uppercase: true}
  }
}
</script>
```

</div>

---

---
url: /guide/essentials/watchers.md
---
# Observadores {#watchers}

## Exemplo Básico {#basic-example}

As propriedades computadas permite-nos calcular declarativamente valores derivados. No entanto, existêm casos onde precisamos realizar "efeitos colaterais" em reação as mudanças de estado - por exemplo, alterando o DOM, ou mudando um outro pedaço do estado baseado no resultado de uma operação assíncrona.

<div class="options-api">

Com a API de Opções, podemos utilizar a [opção `watch`](/api/options-state#watch) para acionar uma função sempre que uma propriedade reativa mudar:

```js
export default {
  data() {
    return {
      question: '',
      answer: 'Questions usually contain a question mark. ;-)'
    }
  },
  watch: {
    // sempre que `question` mudar, esta função executará
    question(newQuestion, oldQuestion) {
      if (newQuestion.indexOf('?') > -1) {
        this.getAnswer()
      }
    }
  },
  methods: {
    async getAnswer() {
      this.answer = 'Thinking...'
      try {
        const res = await fetch('https://yesno.wtf/api')
        this.answer = (await res.json()).answer
      } catch (error) {
        this.answer = 'Error! Could not reach the API. ' + error
      }
    }
  }
}
```

```vue-html
<p>
  Ask a yes/no question:
  <input v-model="question" />
</p>
<p>{{ answer }}</p>
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNptUk2PmzAQ/SuvXAA1sdVrmt0qqnroqa3UIxcLhuCGjKk/wkYR/70OBJLuroRkPDPvzbznuSS7rhOnQMkm2brS6s4/F0wvnbEeFdUqtB6XgoFKeZXl0z9gyQfL8w34G8h5bXiDNF3NQcWuJxtDv25Zh+CCatszSsNeaYZakDgqexD4vM7TCT9cj2Ek65Uvm83cTUr0DTGdyN7RZaN4T24F32iHOnA5hnvdtrCBJ+RcnTH180wrmLaaL4s+QNd4LBOaK3r5UWfplzTHM9afHmoxdhV78rtRcpbPmVHEf1qO5BtTuUWNcmcu8QC9046kk4l4Qvq70XzQvBdC3CyKJfb8OEa01fn4OC7Wq15pj5qidVnaeN+5jZRncmxE72upOp0uY77ulU3gSCT+uOhXnt9yiy6U1zdBRtYa+9aK+9TfrgUf8NWEtgKbK6mKQN8Qdj+/C6T4iJHkXcsKjt9WLpsZL56OXas8xRuw7cYD2LlDXKYoT7K5b+OU22rugsdpfTQVtU9FMueLBHKikRNPpLtcbnuLYZjCW7m0TIZ/92UFiQ==))

A opção `watch` também suporta um caminho delimitado por ponto como chave:

```js
export default {
  watch: {
    // Nota: apenas caminhos simples. Expressões não são suportados.
    'some.nested.key'(newValue) {
      // ...
    }
  }
}
```

</div>

<div class="composition-api">

Com a API de Composição, podemos utilizar a [função `watch`](/api/reactivity-core#watch) para acionar uma resposta sempre que um pedaço do estado reativo mudar:

```vue
<script setup>
import { ref, watch } from 'vue'

const question = ref('')
const answer = ref('Questions usually contain a question mark. ;-)')

// `watch` trabalha diretamente sobre uma referência
watch(question, async (newQuestion, oldQuestion) => {
  if (newQuestion.indexOf('?') > -1) {
    answer.value = 'Thinking...'
    try {
      const res = await fetch('https://yesno.wtf/api')
      answer.value = (await res.json()).answer
    } catch (error) {
      answer.value = 'Error! Could not reach the API. ' + error
    }
  }
})
</script>

<template>
  <p>
    Ask a yes/no question:
    <input v-model="question" />
  </p>
  <p>{{ answer }}</p>
</template>
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNplkkGPmzAQhf/KKxdA3Rj1mpJUUdVDT22lHrlYxDRuYOzaJjRC/PcdxyGr3b2A7PfmmzcMc3awVlxGlW2z2rdO2wCvwmj3DenBGhcww6nuCZMM7QkLOmcG5FyRN9RQa8gH/BuVD9oQdtFb5Hm5KpL8pNx6/+vu8xj9KPv+CnYFqQnyhTFIdxb4vCkjpaFb32JVnyD9lVoUpKaVVmK3x9wQoLtXgtB0VP9/cOMveYk9Np/K5MM9l7jIflScLv990nTW9EcIwXNFR3DX1YwYk4dxyrNXTlIHdCrGyk8hWL+tqqvyZMQUukpaHYOnujdtilTLHPHXGyrKUiRH8i9obx+5UM4Z98j6Pu23qH/AVzP2R5CJRMl14aRw+PldIMdH3Bh3bnzxY+FcdZW2zPvlQ1CD7WVQfALquPToP/gzL4RHqsg89rJNWq3JjgGXzWCOqt812ao3GaqEqRKHcfO8/gDLkq7r6tEyW54Bf5TTlg==)

### Observar Tipos de Fonte {#watch-source-types}

O primeiro argumento do `watch` pode ser de diferentes tipos de "fontes" reativas: pode ser uma referência (incluindo referências computadas), um objeto reativo, uma função recuperada, ou um arranjo de várias fontes:

```js
const x = ref(0)
const y = ref(0)

// referência única
watch(x, (newX) => {
  console.log(`x is ${newX}`)
})

// recuperador
watch(
  () => x.value + y.value,
  (sum) => {
    console.log(`sum of x + y is: ${sum}`)
  }
)

// arranjo de várias fontes
watch([x, () => y.value], ([newX, newY]) => {
  console.log(`x is ${newX} and y is ${newY}`)
})
```

Tome nota de que não podes observar uma propriedade de um objeto reativo desta maneira:

```js
const obj = reactive({ count: 0 })

// isto não funcionará porque estamos passando um número para `watch()`
watch(obj.count, (count) => {
  console.log(`count is: ${count}`)
})
```

Ao invés daquilo, utilize um recuperador:

```js
// Ao invés daquilo, utilize um recuperador:
watch(
  () => obj.count,
  (count) => {
    console.log(`count is: ${count}`)
  }
)
```

</div>

## Observadores Profundos {#deep-watchers}

<div class="options-api">

A `watch` é superficial por padrão: a resposta só acionará quando a propriedade observada for atribuida um valor novo - ele não acionará sobre mudanças de propriedade encaixada.

```js
export default {
  watch: {
    someObject: {
      handler(newValue, oldValue) {
        // Nota: cá `newValue` será igual ao `oldValue`
        // sobre as mutações encaixadas enquanto o próprio objeto
        // não for substítuido.
      },
      deep: true
    }
  }
}
```

</div>

<div class="composition-api">

Quando chamares `watch()` diretamente sobre um objeto reativo, ela criará implicitamente um observador profundo - a resposta será acionada sobre todas as mutações encaixadas:

```js
const obj = reactive({ count: 0 })

watch(obj, (newValue, oldValue) => {
  // dispara sobre mutações de propriedade encaixada
  // Nota: cá `newValue` será igual ao `oldValue`
  // porque ambos eles apontam para o mesmo objeto!
})

obj.count++
```

Isto deve ser distinguido de um recuperador que retorna um objeto reativo - no recente caso, a resposta só disparará se o recuperador retornar um objeto diferente:

```js
watch(
  () => state.someObject,
  () => {
    // dispara só quando `state.someObject` for substituido
  }
)
```

Tu podes, no entanto, forçar o segundo caso para um observador profundo utilizando explicitamente a opção `deep`:

```js
watch(
  () => state.someObject,
  (newValue, oldValue) => {
    // Nota: cá `newValue` será igual ao `oldValue`
    // *a menos que* `state.someObject` tenha sido substituido
  },
  { deep: true }
)
```

</div>

:::warning USE COM CAUTELA
A observação profunda precisa percorrer todas propriedades encaixadas dentro do objeto observado, e pode ser caro quando utilizada sobre grandes estruturas de dados. Utilize-a só quando necessário e esteja ciente das implicações de desempenho.
:::

## Observadores Incansáveis {#eager-watchers}

O `watch` é preguiçoso por padrão: a resposta não será chamada até que a fonte observada tenha mudado. Mas em alguns casos podemos querer que a mesma lógica de resposta seja executada incansavelmente - por exemplo, podemos querer pedir alguns dados iniciais, e depois pedir novamente os dados sempre que o estado relevante mudar.

<div class="options-api">

Nós podemos forçar que uma resposta do observador seja executada imediatamente declarando-a utilizando um objeto com uma função `handler` e a opção `immediate: true`:

```js
export default {
  // ...
  watch: {
    question: {
      handler(newQuestion) {
        // isto será executado imediatamente sobre a criação do componente.
      },
      // forçar a execução incansável da resposta
      immediate: true
    }
  }
  // ...
}
```

</div>

<div class="composition-api">

Nós podemos forçar uma resposta do observador a ser executada imediatamente passando a opção `immediate: true`:

```js
watch(source, (newValue, oldValue) => {
  // executado imediatamente, depois novamente quando `source` mudar
}, { immediate: true })
```

</div>

<div class="composition-api">

## `watchEffect()` \*\* {#watcheffect}

É comum para a função de resposta do observador usar exatamente o mesmo estado reativo como fonte. Por exemplo, considere o seguinte código, que usa um observador para carregar um recurso remoto sempre que a referência `todoId` mudar:

```js
const todoId = ref(1)
const data = ref(null)

watch(todoId, async () => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
  )
  data.value = await response.json()
}, { immediate: true })
```

Em particular, repare em como o observador usa o `todoId` duas vezes, uma vez como fonte e depois novamente dentro da função de resposta.

Isto pode ser simplificado com [`watchEffect()`](/api/reactivity-core#watcheffect). A `watchEffect()` permite-nos rastrear as dependências reativas da função de resposta automaticamente. O observador acima pode ser reescrito como:

```js
watchEffect(async () => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
  )
  data.value = await response.json()
})
```

Aqui, a função de resposta executará imediatamente, não há necessidade de especificar `immediate: true`. Durante a sua execução, ela rastreará automaticamente o `todoId.value` como uma dependência (similar as propriedades computadas). Sempre que `todoId.value` mudar, a função de resposta será executada novamente. Com a `watchEffect()`, já não precisamos passar `todoId` explicitamente como valor de fonte.

Tu podes consultar [este exemplo](/examples/#fetching-data) de `watchEffect` e da requisição reativa de dados em ação.

Para exemplos como este, com apenas uma dependência, o benefício da `watchEffect()` é relativamente pequeno. Mas para os observadores que têm várias dependências, usar `watchEffect()` remove o fardo de ter que manter a lista de dependências manualmente. Além disto, se precisares observar várias propriedades em uma estrutura encaixada, a `watchEffect()` pode provar-se mais eficiente do que um observador profundo, já que ele apenas rastreará as propriedades que são usadas na função de resposta, em vez de rastrear recursivamente todos eles.

:::tip DICA
A `watchEffect` só rastreia dependências durante sua execução **síncrona**. Quando estiveres utilizando-a com uma resposta assíncrona, apenas as propriedades acessadas antes do primeiro visto `await` serão executadas.
:::

### `watch` vs. `watchEffect` {#watch-vs-watcheffect}

Ambos `watch` e `watchEffect` permitem-nos realizar efeitos colaterais de maneira reativa. A principal diferença entre elas está na maneira de como elas rasteiam as dependências reativas:

- `watch` só rastreia a fonte observada explicitamente. Ela não rastreiará nada acessado dentro da resposta. Além disto, a resposta só aciona quando a fonte tiver sido de fato mudada. `watch` separa rastreiamente de dependência do efeito colateral, dando-nos controlo mais preciso sobre quando a resposta deveria disparar.

- `watchEffect`, por outro lado, combina o rastreiamente de dependência e efeito colateral em uma fase. Ela rastreia automaticamente toda propriedade reativa acessada durante sua execução síncrona. Isto é mais conveniente e normalmente resulta em um código mais conciso, mas torna as suas dependências reativas menos explícitas.

</div>

## Tempo de Fluxo de Resposta {#callback-flush-timing}

Quando alterares o estado reativo, ele pode acionar tanto as atualizações de componente de Vue e respostas de observador criadados por ti.

Por padrão, respostas de observador criadas pelo utilizador são chamadas **antes** das atualização de componente de Vue. Isto significa que se tentares acessar o DOM de dentro de uma resposta de observador, o DOM estará no estado antes da Vue tiver aplicado quaisquer atualizações.

Se quiseres acessar o DOM em uma resposta de observador **depois** da Vue tiver atualizado-o, precisas especificar a opção `flush: 'post'`:

<div class="options-api">

```js
export default {
  // ...
  watch: {
    key: {
      handler() {},
      flush: 'post'
    }
  }
}
```

</div>

<div class="composition-api">

```js
watch(source, callback, {
  flush: 'post'
})

watchEffect(callback, {
  flush: 'post'
})
```

A `watchEffect()` pós-fluxo também tem um pseudónimo de conveniência, `watchPostEffect()`:

```js
import { watchPostEffect } from 'vue'

watchPostEffect(() => {
  /* executada depois das atualizações de Vue */
})
```

</div>

<div class="options-api">

## `this.$watch()` \* {#this-watch}

Também é possível criar observadores imperativamente utilizando o [método de instância `$watch()`](/api/component-instance#watch):

```js
export default {
  created() {
    this.$watch('question', (newQuestion) => {
      // ...
    })
  }
}
```

Isto é útil para quando precisares definir um observador condicionalmente, ou apenas observar algo em resposta à interação do utilizador. Ele também permite-te parar o observador de maneira prematura.

</div>

## Parando um Observador {#stopping-a-watcher}

<div class="options-api">

Os observadores declarados utilizando a opção `watch` ou o método de instância `$watch` são paradas automaticamente quando o componente proprietário for desmontado, assim na maioria dos casos não precisas te preocupares acerca de parar o observador por ti mesmo.

Em caso raro onde precisas parar um observador antes do componente proprietário ser desmontado, a API de `$watch()` retorna uma função para isto:

```js
const unwatch = this.$watch('foo', callback)

// ...quando o observador não é mais necessário:
unwatch()
```

</div>

<div class="composition-api">

Os observadores declarados sincronamente dentro de  `setup()` ou `<script setup>` estão vinculados a instância do componente proprietário, e serão paradas automaticamente quando o componente proprietário for desmontado. Na maioria dos casos, não precisas te preocupares acerca de parar o observador por ti mesmo.

A chave aqui é que o observador deve ser criado **sincronamente**: se o observador for criado em uma resposta assíncrona, ele não estará vinculado ao componente proprietário e deve ser parado manualmente para evitar fugas de memória. Cá está um exemplo:

```vue
<script setup>
import { watchEffect } from 'vue'

// este aqui será parado automaticamente
watchEffect(() => {})

// ...este aqui não será!
setTimeout(() => {
  watchEffect(() => {})
}, 100)
</script>
```

Para parar manualmente um observado, utilize a função retornada para lidar com isto. Isto funciona para ambos `watch` e `watchEffect`:

```js
const unwatch = watchEffect(() => {})

// ...mais tarde, quando for mais necessária
unwatch()
```

Nota que deve haver muito poucos casos onde precisas criar observadores assincronamente, e criação síncrona deve ser a preferida sempre que possível. Se precisares esperar por algum dado assíncrono, podes tornar a tua lógica de observação condicional:

```js
// dados a serem carregados assincronamente
const data = ref(null)

watchEffect(() => {
  if (data.value) {
    // faça algo quando os dados forem carregados
  }
})
```

</div>

---

---
url: /api/compile-time-flags.md
---

# Opções de Compilação {#compile-time-flags}

:::tip DICA
As opções de compilação apenas aplicam-se quando usamos a construção de `esm-bundler` da Vue (isto é, `vue/dist/vue.esm-bundler.js`).
:::

Quando usamos a Vue com uma etapa de construção, é possível configurar um número de opções de compilação para ativar ou desativar certas funcionalidades. O benefício de usar as opções de compilação é que as funcionalidades desativadas desta maneira podem ser removidas do pacote final através da agitação da árvore.

A Vue funcionará mesmo se estas opções não forem explicitamente configuradas. No entanto, é recomendado sempre configurá-las para que as funcionalidades relevantes podem ser removidas corretamente quando possível.

Consultar os [Guias de Configuração](#configuration-guides) sobre como configurá-las dependendo da nossa ferramenta de construção.

## `__VUE_OPTIONS_API__` {#VUE_OPTIONS_API}

- **Predefinida como:** `true`

  Ativa ou desativa o suporte da API de Opções. Desativar isto resultará em pacotes menores, mas pode afetar a compatibilidade com as bibliotecas de terceiros se estas dependerem da API de Opções.

## `__VUE_PROD_DEVTOOLS__` {#VUE_PROD_DEVTOOLS}

- **Predefinida como:** `false`

  Ativa ou desativa o suporta das ferramentas de programação nas construções de produção. Isto resultará em mais código incluído no pacote, então é recomendado ativar isto apenas para fins de depuração.

## `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__` <sup class="vt-badge" data-text="3.4+" /> {#VUE_PROD_HYDRATION_MISMATCH_DETAILS}

- **Predefinida como:** `false`

  Ativa ou desativa avisos detalhados para as disparidades de hidratação nas construções de produção. Isto resultará em mais código incluído no pacote, então é recomendado ativar isto apenas para fins de depuração.

## Guias de Configuração {#configuration-guides}

### Vite {#vite}

A `@vitejs/plugin-vue` fornece automaticamente valores padrão para estas opções. Para mudar os valores padrão, usamos a [opção de configuração `define`](https://pt.vitejs.dev/config/shared-options#define) da Vite:

```js
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    // ativar detalhes de disparidade de hidratação na
    // construção de produção
    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'true'
  }
})
```

### `vue-cli` {#vue-cli}

A `@vue/cli-service` fornece automaticamente os valores padrão para algumas destas opções. Para configurar ou mudar os valores:

```js
// vue.config.js
module.exports = {
  chainWebpack: (config) => {
    config.plugin('define').tap((definitions) => {
      Object.assign(definitions[0], {
        __VUE_OPTIONS_API__: 'true',
        __VUE_PROD_DEVTOOLS__: 'false',
        __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
      })
      return definitions
    })
  }
}
```

### `webpack` {#webpack}

As opções devem ser definidas usando a [`DefinePlugin`](https://webpack.js.org/plugins/define-plugin/) da Webpack:

```js
// webpack.config.js
module.exports = {
  // ...
  plugins: [
    new webpack.DefinePlugin({
      __VUE_OPTIONS_API__: 'true',
      __VUE_PROD_DEVTOOLS__: 'false',
      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
    })
  ]
}
```

### Rollup {#rollup}

As opções devem ser definidas usando [`@rollup/plugin-replace`](https://github.com/rollup/plugins/tree/master/packages/replace):

```js
// rollup.config.js
import replace from '@rollup/plugin-replace'

export default {
  plugins: [
    replace({
      __VUE_OPTIONS_API__: 'true',
      __VUE_PROD_DEVTOOLS__: 'false',
      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
    })
  ]
}
```

---

---
url: /api/options-lifecycle.md
---
# Opções: Ciclo de Vida {#options-lifecycle}

:::info Consulte também
Para uso partilhado dos gatilhos do ciclo de vida, consulte o [Guia - Gatilhos do Ciclo de Vida](/guide/essentials/lifecycle).
:::

## `beforeCreate` {#beforecreate}

Chamada quando a instância for inicializada.

- **Tipo**

  ```ts
  interface ComponentOptions {
    beforeCreate?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Chamada imediatamente quando a instância for inicializada e as propriedades forem resolvidas.

  Depois as propriedades serão definidas como propriedades reativas e o estado tais como `data()` ou `computed` serão configurados.

  Nota que o gatilho `setup()` da API de Composição é chamado antes de quaisquer gatilhos da API de Opções, até mesmo antes de `beforeCreate()`.

## `created` {#created}

Chamada depois da instância ter terminado de processar todas as opções relacionadas ao estado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    created?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Quando este gatilho é chamado, os seguintes foram configurados: dados reativos, propriedades computadas, métodos, e observadores. No entanto, a fase de montagem ainda não foi começada, e a propriedade `$el` ainda não estará disponível.

## `beforeMount` {#beforemount}

Chamada bem antes do componente ser montado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    beforeMount?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Quando este gatilho é chamado, o componente terminou de configurar o seu estado reativo, mas ainda nenhum dos nós de DOM foi criado. Está prestes a executar o seu efeito de interpretação de DOM pela primeira vez.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `mounted` {#mounted}

Chamado depois do componente ter sido montado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    mounted?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Um componente é considerado montado depois:

  - De todos os seus componentes filhos síncronos terem sido montados (isto não inclui componentes assíncronos ou componentes dentro das árvores do `<Suspense>`).

  - Da sua própria árvore do DOM ter sido criada e inserida no contentor pai. Nota que isto apenas garante que a árvore do DOM do componente está no documento se o contentor da raiz da aplicação também estiver no documento.

  Este gatilho é normalmente usado para executar os efeitos colaterais que precisam do acesso ao DOM interpretado do componente, ou para limitar o código relacionado ao DOM para o cliente numa [aplicação interpretada no servidor](/guide/scaling-up/ssr).

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `beforeUpdate` {#beforeupdate}

Chamada bem antes do componente estiver prestes a atualizar a sua árvore do DOM devido à uma mudança de estado reativo.

- **Tipo**

  ```ts
  interface ComponentOptions {
    beforeUpdate?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Este gatilho pode ser usado para acessar o estado do DOM antes da Vue atualizar o DOM. Também é seguro modificar o estado do componente dentro deste gatilho.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `updated` {#updated}

Chamada depois do componente ter atualizado a sua árvore do DOM devido à uma mudança de estado reativo.

- **Tipo**

  ```ts
  interface ComponentOptions {
    updated?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Uma gatilho `updated` dum componente pai é chamado depois do `updated` dos seus componentes filhos.

  Este gatilho é chamado depois de qualquer atualização do DOM do componente, que pode ser causada por diferentes mudanças de estado. Se precisarmos acessar o DOM atualizado depois duma mudança de estado específica, devemos usar [`nextTick()`](/api/general#nexttick).

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

  :::warning AVISO
  Não altere o estado do componente no gatilho `updated` - isto provavelmente conduzirá à um laço de atualização infinita!
  :::

## `beforeUnmount` {#beforeunmount}

Chamada bem antes duma instância de componente estiver a ser desmontada.

- **Tipo**

  ```ts
  interface ComponentOptions {
    beforeUnmount?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Quando este gatilho é chamado, a instância do componente permanece completamente funcional.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `unmounted` {#unmounted}

Chamada depois do componente ter sido desmontado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    unmounted?(this: ComponentPublicInstance): void
  }
  ```

- **Detalhes**

  Um componente é considerado desmontado depois:

  - De todos os seus componentes filhos terem sido desmontados.

  - De todos os seus efeitos reativos associados (efeito de interpretação e computado ou observadores criados durante a `setup()`) terem sido interrompidos.

  Use este gatilho para limpar os efeitos colaterais criados manualmente tais como temporizadores, ouvintes de eventos de DOM oou conexões de servidor.

  **Este gatilho não é chamado durante a interpretação no lado do servidor.**

## `errorCaptured` {#errorcaptured}

Chamada quando um erro propagando-se a partir dum componente descendente tiver sido capturado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    errorCaptured?(
      this: ComponentPublicInstance,
      err: unknown,
      instance: ComponentPublicInstance | null,
      info: string
    ): boolean | void
  }
  ```

- **Detalhes**

  Os erros podem ser capturados a partir das seguintes fontes:

  - Interpretadores de componente
  - Manipuladores de evento
  - Gatilhos do ciclo de vida
  - função `setup()`
  - Observadores
  - Gatilhos de diretiva personalizada
  - Gatilhos de transição

  O gatilho recebe três argumentos: o erro, a instância do componente que acionou o erro, e uma sequência de caracteres de informação especificando o tipo da fonte do erro.

  :::tip DICA
  Em produção, o terceiro argumento (`info`) será um código encurtado ao invés da sequência de caracteres da informação completa. Nós podemos encontrar o código ao mapeamento da sequência de caracteres na [Referência do Código de Erro de Produção](/error-reference/#runtime-errors).
  :::

  Nós podemos modificar o estado do componente na `errorCaptured()` para exibir um estado de erro ao utilizador. No entanto, é importante que o estado de erro não interprete o conteúdo original que causou o erro; de outro modo o componente será lançado para um laço de interpretação infinita.

  O gatilho pode retornar `false` para impedir o erro de propagar-se mais. Consulte os detalhes sobre a propagação de erro abaixo.

  **Regras de Propagação de Erros**

  - Por padrão, todos os erros ainda serão enviados para o nível de aplicação [`app.config.errorHandler`](/api/application#app-config-errorhandler) se for definido, para que estes erros possam ser relatados à um serviço de análises num único lugar.

  - Se vários gatilhos de `errorCaptured` existirem numa cadeia de herança de componentes ou em uma cadeia de pais, todos serão invocados com o mesmo erro, na ordem de baixo para cima. Isto é semelhante ao mecanismo borbulhante de eventos de DOM nativos.

  - Se o próprio gatilho `errorCaptured` lançar um erro, tanto este erro quanto o erro original capturado serão enviados à `app.config.errorHandler`.

  - Um gatilho `errorCaptured` pode retornar `false` para evitar que o erro continue a propagar-se. Isto significa essencialmente que "este erro já foi manipulado e deve ser ignorado". Ele evitará quaisquer gatilhos `errorCaptured` adicionais ou `app.config.errorHandler` de serem invocados por este erro.

## `renderTracked` <sup class="vt-badge dev-only" data-text="desenvolvimento" /> {#rendertracked}

Chamada quando uma dependência reativa tiver sido rastreada pelo efeito de interpretação do componente.

**Este gatilho é apenas para o modo de desenvolvimento e não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  interface ComponentOptions {
    renderTracked?(this: ComponentPublicInstance, e: DebuggerEvent): void
  }

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TrackOpTypes /* 'get' | 'has' | 'iterate' */
    key: any
  }
  ```

- **Consulte também** [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## `renderTriggered` <sup class="vt-badge dev-only" data-text="desenvolvimento" /> {#rendertriggered}

Chamada quando uma dependência reativa acionar o efeito de interpretação do componente a ser executado novamente.

**Este gatilho é apenas para o modo de desenvolvimento e não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  interface ComponentOptions {
    renderTriggered?(this: ComponentPublicInstance, e: DebuggerEvent): void
  }

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
    key: any
    newValue?: any
    oldValue?: any
    oldTarget?: Map<any, any> | Set<any>
  }
  ```

- **Consulte também** [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## `activated` {#activated}

Chamada depois da instância do componente for inserida no DOM como parte duma árvore armazenada para consulta imediata pelo [`<KeepAlive>`](/api/built-in-components#keepalive).

**Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  interface ComponentOptions {
    activated?(this: ComponentPublicInstance): void
  }
  ```

- **Consulte também** [Guia - Ciclo de Vida da Instância Armazenada para Consulta Imediata](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## `deactivated` {#deactivated}

Chamada depois da instância do componente ser removida do DOM como parte duma árvore armazenada para consulta imediata pelo [`<KeepAlive>`](/api/built-in-components#keepalive).

**Este gatilho não é chamado durante a interpretação no lado do servidor.**

- **Tipo**

  ```ts
  interface ComponentOptions {
    deactivated?(this: ComponentPublicInstance): void
  }
  ```

- **Consulte também** [Guia - Ciclo de Vida da Instância Armazenada para Consulta Imediata](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## `serverPrefetch` <sup class="vt-badge" data-text="servidor" /> {#serverprefetch}

Função assíncrona a ser resolvida antes da instância do componente estiver à ser interpretada no servidor.

- **Tipo**

  ```ts
  interface ComponentOptions {
    serverPrefetch?(this: ComponentPublicInstance): Promise<any>
  }
  ```

- **Detalhes**

  Se um gatilho retornar uma promessa, o interpretador do servidor aguardará até a promessa ser resolvida antes de interpretar o componente.

  Este gatilho é chamado apenas durante a interpretação no lado do servidor e pode ser usado para realizar requisição de dados apenas no servidor.

- **Exemplo**

  ```js
  export default {
    data() {
      return {
        data: null
      }
    },
    async serverPrefetch() {
      // componente é interpretado como parte da requisição inicial
      // pré-requisita dados no servidor pois é mais rápido do que no cliente
      this.data = await fetchOnServer(/* ... */)
    },
    async mounted() {
      if (!this.data) {
        // se data for null ao montar, significa que o componente
        // é interpretado dinamicamente no cliente.
        // Realizar uma requisição no lado do cliente.
        this.data = await fetchOnClient(/* ... */)
      }
    }
  }
  ```

- **Consulte também** [Interpretação no Lado do Servidor](/guide/scaling-up/ssr)

---

---
url: /api/options-composition.md
---
# Opções: Composição {#options-composition}

## `provide` {#provide}

Fornece valores que podem ser injetados pelos componentes descendentes.

- **Tipo**

  ```ts
  interface ComponentOptions {
    provide?: object | ((this: ComponentPublicInstance) => object)
  }
  ```

- **Detalhes**

  `provide` e [`inject`](#inject) são usadas ao mesmo tempo para permitir um componente ancestral servir como um injetor de dependência para todos os seus descendentes, independentemente de quão profunda é a hierarquia do componente, enquanto estiverem na mesma cadeia primaria.

  A opção `provide` deve ser ou um objeto ou uma função que retorna um objeto. Este objeto contém as propriedades que estão disponíveis para a injeção para os seus descendentes. Nós podemos usar símbolos como chaves neste objeto.

- **Exemplo**

  Uso básico:

  ```js
  const s = Symbol()

  export default {
    provide: {
      foo: 'foo',
      [s]: 'bar'
    }
  }
  ```

  Usando uma função para fornecer o estado por componente:

  ```js
  export default {
    data() {
      return {
        msg: 'foo'
      }
    }
    provide() {
      return {
        msg: this.msg
      }
    }
  }
  ```

  Nota que no exemplo acima, a `msg` fornecida NÃO será reativa. Consulte [Trabalhando com a Reatividade](/guide/components/provide-inject#working-with-reactivity) por mais detalhes.

- **Consulte também** [Fornecer ou Injetar](/guide/components/provide-inject)

## `inject` {#inject}

Declara as propriedades a injetar no componente atual localizando-as a partir dos fornecedores ancestrais.

- **Tipo**

  ```ts
  interface ComponentOptions {
    inject?: ArrayInjectOptions | ObjectInjectOptions
  }

  type ArrayInjectOptions = string[]

  type ObjectInjectOptions = {
    [key: string | symbol]:
      | string
      | symbol
      | { from?: string | symbol; default?: any }
  }
  ```

- **Detalhes**

  A opção `inject` deve ser:

  - Um vetor de sequências de caracteres, ou
  - Um objeto onde as chaves são o nome de vínculo local e o valor é ou:
    - A chave (sequência de caracteres ou símbolo) à procurar nas injeções disponíveis, ou
    - Um objeto onde:
      - A propriedade `from` é a chave (sequência de caracteres ou símbolo) à procurar nas injeções disponíveis, e
      - A propriedade `default` é usada como valor de retrocesso. Semelhante aos valores padrão das propriedades, uma função de fábrica é necessária para os tipos de objeto para impedir a partilha de valor entre várias instância do componente.

  Uma propriedade injetada será `undefined` se nenhuma propriedade correspondente e nem um valor padrão foi fornecido.

  Nota que os vínculos injetados NÃO são reativos. Isto é intencional. No entanto, se o valor injetado for um objeto reativo, as propriedades deste objeto permanecem reativas. Consulte [Trabalhando com a Reatividade](/guide/components/provide-inject#working-with-reactivity) por mais detalhes.

- **Exemplo**

  Uso básico:

  ```js
  export default {
    inject: ['foo'],
    created() {
      console.log(this.foo)
    }
  }
  ```

  Usando um valor injetado como padrão para uma propriedade:

  ```js
  const Child = {
    inject: ['foo'],
    props: {
      bar: {
        default() {
          return this.foo
        }
      }
    }
  }
  ```

  Usando um valor injetado como entrada de dados:

  ```js
  const Child = {
    inject: ['foo'],
    data() {
      return {
        bar: this.foo
      }
    }
  }
  ```

  As injeções podem ser opcionais com valor padrão:

  ```js
  const Child = {
    inject: {
      foo: { default: 'foo' }
    }
  }
  ```

  Se precisar ser injetado a partir duma propriedade com um nome diferente, use `from` para denotar a propriedade da fonte:

  ```js
  const Child = {
    inject: {
      foo: {
        from: 'bar',
        default: 'foo'
      }
    }
  }
  ```

  Semelhante aos padrões de propriedade, precisamos usar uma função de fábrica para os valores não primitivos:

  ```js
  const Child = {
    inject: {
      foo: {
        from: 'bar',
        default: () => [1, 2, 3]
      }
    }
  }
  ```

- **Consulte também** [Fornecer ou Injetar](/guide/components/provide-inject)

## `mixins` {#mixins}

Uma vetor de objetos opcionais a serem misturados no componente atual.

- **Tipo**

  ```ts
  interface ComponentOptions {
    mixins?: ComponentOptions[]
  }
  ```

- **Detalhes**

  A opção `mixins` aceita um vetor de objetos de mistura. Estes objetos de mistura podem conter opções de instância como objetos de instância normais, e serão combinadas contra as opções eventuais usando a lógica de combinação de opção certa. Por exemplo, se a nossa mistura contiver um gatilho `updated` e o próprio componente também tiver um, ambas funções serão chamadas.

  Os gatilhos da mistura são chamados na ordem que são fornecidos, e chamados bem antes dos gatilhos do próprio componente.

  :::warning NÃO É MAIS RECOMENDADO
  Na Vue 2, as misturas eram o mecanismo primário para criação de pedaços reutilizáveis da lógica do componente. Embora as misturas continuam a ser suportadas na Vue 3, as [Funções de Composição usando a API de Composição](/guide/reusability/composables) agora são a abordagem preferida para reutilização de código entre os componentes.
  :::

- **Exemplo**

  ```js
  const mixin = {
    created() {
      console.log(1)
    }
  }

  createApp({
    created() {
      console.log(2)
    },
    mixins: [mixin]
  })

  // => 1
  // => 2
  ```

## `extends` {#extends}

Um componente de "classe de base" a partir do qual estender.

- **Type:**

  ```ts
  interface ComponentOptions {
    extends?: ComponentOptions
  }
  ```

- **Detalhes**

  Permite que um componente estenda outro, herdando suas opções de componente.

  A partir duma perspetiva de implementação, `extends` é quase idêntico à `mixins`. O componente especificado pela `extends` será tratado como se fosse a primeira mistura.

  No entanto, `extends` e `mixins` expressam diferentes intenções. A opção `mixins` é primariamente usada para compor pedaços de funcionalidade, ao passo que `extends` está primariamente preocupada com a herança.

  Tal como acontece com a `mixins`, quaisquer opções (exceto para `setup()`) serão combinadas usando a estratégia de combinação relevante.

- **Exemplo**

  ```js
  const CompA = { ... }

  const CompB = {
    extends: CompA,
    ...
  }
  ```

  :::warning NÃO RECOMENDADA PARA API DE COMPOSIÇÃO
  `extends` está desenhada para a API de Opções e não lida com a combinação do gatilho `setup()`.

  Na API de Composição, o modelo mental preferido para reutilização da lógica é "composição" acima da "herança". Se tivermos lógica dum componente que precisa ser reutilizada num outro, consideramos extrair a lógica relevante para uma [Função de Composição](/guide/reusability/composables#composables).

  Se ainda tencionamos "estender" um componente usando a API de Composição, podemos chamar a `setup()` do componente de base na `setup()` do componente que se estende:

  ```js
  import Base from './Base.js'

  export default {
    extends: Base,
    setup(props, ctx) {
      return {
        ...Base.setup(props, ctx),
        // vínculos locais
      }
    }
  }
  ```
  :::

---

---
url: /api/options-state.md
---
# Opções: Estado {#options-state}

## `data` {#data}

Uma função que retorna o estado reativo inicial para a instância do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    data?(
      this: ComponentPublicInstance,
      vm: ComponentPublicInstance
    ): object
  }
  ```

- **Detalhes**

  Espera-se que a função retorne um objeto de JavaScript simples, que será tornado reativo pela Vue. Depois da instância ser criada, o objeto de dados reativo pode ser acessado com `this.$data`. A instância do componente também delega todas as propriedades encontradas no objeto de dados, então `this.a` será equivalente à `this.$data.a`.

  Todas as propriedades de dados de alto nível devem ser incluídas no objeto de dados retornado. A adição de novas propriedades à `this.$data` é possível, mas *não* é recomendada. Se o valor desejado duma propriedade ainda não estiver disponível, então um valor vazio tal como `undefined` ou `null` deveria ser incluído como preservador de lugar para garantir que a Vue saiba que a propriedade existe. 

  As propriedades que começam com `_` ou `$` **não** serão delegadas na instância do componente porque podem entrar em conflito com as propriedades internas e métodos da API da Vue. Nós teremos de acessá-las como `this.$data._property`. 

  **Não** é recomendado retornar objetos com os seus próprios comportamentos de estado, como objetos da API do navegador e propriedades do protótipo. O objeto retornado deveria ser idealmente um objeto simples que apenas representa o estado do componente.

- **Exemplo**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    created() {
      console.log(this.a) // 1
      console.log(this.$data) // { a: 1 }
    }
  }
  ```

  Nota que se usarmos uma função de seta com a propriedade `data`, o `this` não será a instância do componente, mas ainda podemos acessar a instância como o primeiro argumento da função:

  ```js
  data: (vm) => ({ a: vm.myProp })
  ```

- **Consulte também** a [Reatividade em Profundidade](/guide/extras/reactivity-in-depth)

## `props` {#props}

Declara as propriedades dum componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    props?: ArrayPropsOptions | ObjectPropsOptions
  }

  type ArrayPropsOptions = string[]

  type ObjectPropsOptions = { [key: string]: Prop }

  type Prop<T = any> = PropOptions<T> | PropType<T> | null

  interface PropOptions<T> {
    type?: PropType<T>
    required?: boolean
    default?: T | ((rawProps: object) => T)
    validator?: (value: unknown, rawProps: object) => boolean
  }

  type PropType<T> = { new (): T } | { new (): T }[]
  ```

  > Os tipos estão simplificados por questões de legibilidade.

- **Detalhes**

  Na Vue, todas as propriedades do componente precisam ser explicitamente declaradas. As propriedades podem ser declaradas de duas formas:

  - De forma simples usando um vetor de sequências de caracteres
  - De forma completa usando um objeto onde cada chave de propriedade é o nome da propriedade, e o valor é o tipo da propriedade (uma função construtura) ou opções avançadas.

  Com a sintaxe baseada em objetos, cada propriedade pode ainda definir as seguintes opções:

  - **`type`**: Pode ser um dos seguintes construtores nativos: `String`, `Number`, `Boolean`, `Array`, `Object`, `Date`, `Function`, `Symbol`, qualquer função construtora personalizada ou um vetor destes. No modo de desenvolvimento, a Vue verificará se o valor duma propriedade corresponde o tipo declarado, e lançará um aviso se não corresponder. Consulte a [Validação de Propriedade](/guide/components/props#prop-validation) por mais detalhes.

    Além disto nota que uma propriedade com o tipo `Boolean` afeta o seu comportamento de moldagem de valores em ambos desenvolvimento e produção. Consulte a [Moldagem Booleana](/guide/components/props#boolean-casting) por mais detalhes.

  - **`default`**: Especifica o valor padrão duma propriedade quando não é passada pelo pai ou quando tem o valor `undefined`. Os valores padrão de objeto ou vetor devem ser retornados usando uma função de fábrica. A função de fábrica também recebe o objeto de propriedades puro como argumento.

  - **`required`**: Define se a propriedade é obrigatória. Num ambiente que não é de produção, um aviso na consola será lançado se este valor for verdadeiro e a propriedade não for passada.

  - **`validator`**: Função de validação personalizada que recebe o valor da propriedade como o único argumento. No modo de desenvolvimento, um aviso da consola será lançado se esta função retornar um valor falso (por exemplo, se a validação falhar).

- **Exemplo**

  Declaração simples:

  ```js
  export default {
    props: ['size', 'myMessage']
  }
  ```

  Declaração de objeto com validações:

  ```js
  export default {
    props: {
      // verificação de tipo
      height: Number,
      // verificação de tipo mais outras validações
      age: {
        type: Number,
        default: 0,
        required: true,
        validator: (value) => {
          return value >= 0
        }
      }
    }
  }
  ```

- **Consulte também:**
  - [Guia - Propriedades](/guide/components/props)
  - [Guia - Tipos para as Propriedades dos Componentes](/guide/typescript/options-api#typing-component-props) <sup class="vt-badge ts" data-text="typescript" />

## `computed` {#computed}

Declara propriedades computadas a serem expostas na instância do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    computed?: {
      [key: string]: ComputedGetter<any> | WritableComputedOptions<any>
    }
  }

  type ComputedGetter<T> = (
    this: ComponentPublicInstance,
    vm: ComponentPublicInstance
  ) => T

  type ComputedSetter<T> = (
    this: ComponentPublicInstance,
    value: T
  ) => void

  type WritableComputedOptions<T> = {
    get: ComputedGetter<T>
    set: ComputedSetter<T>
  }
  ```

- **Detalhes**

  A opção aceita um objeto onde a chave é o nome da propriedade computada, e o valor é ou um recuperador computado, ou um objeto com métodos `get` e `set` (para as propriedades computadas graváveis).

  Todos os recuperadores e definidores têm o seu próprio contexto de `this` automaticamente vinculado à instância do componente.

  Nota que se estivermos a usar uma função de seta com uma propriedade computada, `this` não apontará para a instância do componente, mas ainda podemos acessar a instância como o primeiro argumento da função:

  ```js
  export default {
    computed: {
      aDouble: (vm) => vm.a * 2
    }
  }
  ```

- **Exemplo**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    computed: {
      // somente leitura
      aDouble() {
        return this.a * 2
      },
      // gravável
      aPlus: {
        get() {
          return this.a + 1
        },
        set(v) {
          this.a = v - 1
        }
      }
    },
    created() {
      console.log(this.aDouble) // => 2
      console.log(this.aPlus) // => 2

      this.aPlus = 3
      console.log(this.a) // => 2
      console.log(this.aDouble) // => 4
    }
  }
  ```

- **Consulte também**
  - [Guia - Propriedades Computadas](/guide/essentials/computed)
  - [Guia - Tipos para as Propriedades Computadas](/guide/typescript/options-api#typing-computed-properties) <sup class="vt-badge ts" data-text="typescript" />

## `methods` {#methods}

Declara métodos a serem misturados à instância do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    methods?: {
      [key: string]: (this: ComponentPublicInstance, ...args: any[]) => any
    }
  }
  ```

- **Detalhes**

  Os métodos declarados podem ser acessados diretamente na instância do componente, ou usados nas expressões do modelo de marcação. Todos os métodos têm o seu contexto de `this` automaticamente vinculado à instância do componente, mesmo quando passados.

  Devemos evitar funções de seta quando declaramos métodos, porque não terão acesso à instância do componente através de `this`.

- **Exemplo**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    methods: {
      plus() {
        this.a++
      }
    },
    created() {
      this.plus()
      console.log(this.a) // => 2
    }
  }
  ```

- **Consulte também** a [Manipulação de Evento](/guide/essentials/event-handling)

## `watch` {#watch}

Declara as funções de resposta de observação a serem invocadas sobre a mudança de dados.

- **Tipo**

  ```ts
  interface ComponentOptions {
    watch?: {
      [key: string]: WatchOptionItem | WatchOptionItem[]
    }
  }

  type WatchOptionItem = string | WatchCallback | ObjectWatchOptionItem

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  type ObjectWatchOptionItem = {
    handler: WatchCallback | string
    immediate?: boolean // predefinido como: false
    deep?: boolean // predefinido como: false
    flush?: 'pre' | 'post' | 'sync' // predefinido como: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }
  ```

  > Os tipos estão simplificados por questões de legibilidade.

- **Detalhes**

  A opção `watch` espera um objeto onde as chaves estão as propriedades reativas da instância do componente a serem observadas (por exemplo, as propriedades declaradas através da `data` ou `computed`) — e os seus valores são as funções de resposta correspondentes. A função de resposta recebe o novo valor e o valor antigo da fonte observada.

  Além das propriedades do nível da raiz, a chave também pode ser um caminho simples delimitado por pontos, por exemplo, `a.b.c`. Nota que este uso **não** suporta expressões complexas - apenas caminhos delimitados por ponto são suportados. Se precisarmos de observar fontes de dados complexas, devemos usar a API [`$watch()`](/api/component-instance#watch) imperativa.

  O valor também pode ser a sequência de caracteres dum nome de método (declarado através dos `methods`), ou um objeto que contém opções adicionais. Quando usamos a sintaxe de objeto, a função de resposta deve ser declarada sob o campo `handler`. As propriedades adicionais incluem:

  - **`immediate`**: aciona a função de resposta imediatamente sobre a criação do observador. O valor antigo será `undefined` na primeira chamada.  
  - **`deep`**: força a travessia profunda da fonte se for um objeto ou um vetor, para que a função de resposta dispare sobre as mutações profundas. Consulte os [Observadores Profundos](/guide/essentials/watchers#deep-watchers).
  - **`flush`**: ajusta o tempo de descarga da função de resposta. Consulte o [Tempo de Descarga da Função de Resposta](/guide/essentials/watchers#callback-flush-timing) e a [`watchEffect()`](/api/reactivity-core#watcheffect).
  - **`onTrack / onTrigger`**: depura as dependências do observador. Consulte a [Depuração do Observador](/guide/extras/reactivity-in-depth#watcher-debugging).

  Devemos evitar usar funções de seta quando declaramos funções de resposta de observação porque não terão acesso à instância do componente através de `this`.

- **Exemplo**

  ```js
  export default {
    data() {
      return {
        a: 1,
        b: 2,
        c: {
          d: 4
        },
        e: 5,
        f: 6
      }
    },
    watch: {
      // observando uma propriedade de alto nível
      a(val, oldVal) {
        console.log(`nova: ${val}, antiga: ${oldVal}`)
      },
      // sequência de caracteres do nome do método
      b: 'someMethod',
      // a função de resposta será chamada sempre que alguma
      // das propriedades do objeto observado mudar independente da
      // sua profundidade encaixada.
      c: {
        handler(val, oldVal) {
          console.log('c mudou')
        },
        deep: true
      },
      // observando uma única propriedade encaixada:
      'c.d': function (val, oldVal) {
        // fazer alguma coisa
      },
      // a função de resposta será chamada imediatamente
      // após o início da observação
      e: {
        handler(val, oldVal) {
          console.log('e mudou')
        },
        immediate: true
      },
      // podemos passar um vetor de funções de respostas,
      // serão chamados um atrás do outro
      f: [
        'handle1',
        function handle2(val, oldVal) {
          console.log('handle2 disparado')
        },
        {
          handler: function handle3(val, oldVal) {
            console.log('handle3 disparado')
          }
          /* ... */
        }
      ]
    },
    methods: {
      someMethod() {
        console.log('b mudou')
      },
      handle1() {
        console.log('handle 1 disparado')
      }
    },
    created() {
      this.a = 3 // => novo: 3, antigo: 1
    }
  }
  ```

- **Consulte também** [Observadores](/guide/essentials/watchers)

## `emits` {#emits}

Declara os eventos personalizados emitidos pelo componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    emits?: ArrayEmitsOptions | ObjectEmitsOptions
  }

  type ArrayEmitsOptions = string[]

  type ObjectEmitsOptions = { [key: string]: EmitValidator | null }

  type EmitValidator = (...args: unknown[]) => boolean
  ```

- **Detalhes**

  Os eventos emitidos podem ser declarados de duas formas:

  - De forma simples usando um vetor de sequências de caracteres
  - De forma completa usando um objeto onde cada chave de propriedade é o nome do evento, e o valor ou é `null` ou é uma função de validação.

  A função de validação receberá argumentos adicionais passados para a chamada de `$emit` do componente. Por exemplo, se `this.$emit('foo', 1)` for chamado, a função de validação correspondente para `foo` receberá o argumento `1`. A função de validação deve retornar um booleano para indicar se os argumentos do evento são válidos.

  Nota que a opção `emits` afeta os ouvintes de eventos que são considerados ouvintes de eventos do componente, em vez de ouvintes de eventos nativos do DOM. Os ouvintes para eventos declarados serão removidos do objeto `$attrs` do componente, assim não serão passados ao elemento raiz do componente. Consulte os [Atributos](/guide/components/attrs) por mais detalhes.

- **Exemplo**

  Sintaxe de vetor:

  ```js
  export default {
    emits: ['check'],
    created() {
      this.$emit('check')
    }
  }
  ```

  Sintaxe de objeto:

  ```js
  export default {
    emits: {
      // sem validação
      click: null,

      // com validação
      submit: (payload) => {
        if (payload.email && payload.password) {
          return true
        } else {
          console.warn(`Invalid submit event payload!`)
          return false
        }
      }
    }
  }
  ```

- **Consulte também**
  - [Guia - Atributos](/guide/components/attrs)
  - [Guia - Tipos para as Emissões do Componente](/guide/typescript/options-api#typing-component-emits) <sup class="vt-badge ts" data-text="typescript" />

## `expose` {#expose}

Declara as propriedades públicas expostas quando a instância do componente for acessada por um pai através das referências do modelo de marcação.

- **Tipo**

  ```ts
  interface ComponentOptions {
    expose?: string[]
  }
  ```

- **Detalhes**

  Por padrão, uma instância de componente expõe todas as propriedades da instância ao pai quando acessada através de `$parent`, `$root`, ou referências do modelo de marcação. Isto pode ser indesejável, visto que um componente provavelmente possui estado interno ou métodos que devem permanecer privados para evitar associação rigorosa.

  A opção `expose` espera uma lista de sequências de caracteres de nomes de propriedade. Quando `expose` for usada, apenas as propriedades explicitamente listadas serão expostas sobre a instância pública do componente.

  `expose` apenas afeta as propriedades definidas pelo utilizador - não filtra as propriedades da instância do componente embutido.

- **Exemplo**

  ```js
  export default {
    // apenas `publicMethod` estará disponível na instância pública
    expose: ['publicMethod'],
    methods: {
      publicMethod() {
        // ...
      },
      privateMethod() {
        // ...
      }
    }
  }
  ```

---

---
url: /api/options-rendering.md
---
# Opções: Interpretação {#options-rendering}

## `template` {#template}

Um modelo de marcação de sequência de caracteres para o componente.

- **Type**

  ```ts
  interface ComponentOptions {
    template?: string
  }
  ```

- **Detalhes**

  Um modelo de marcação fornecido através da opção `template` que será compilada instantaneamente em tempo de execução. É suportado apenas quando usamos uma construção de Vue que inclui o compilador de modelo de marcação. O compilador de modelo de marcação **NÃO** está incluído nas construções de Vue que têm a palavra `runtime` em seus nomes, por exemplo. `vue.runtime.esm-bundler.js`. Consulte o [guia de ficheiro de distribuição](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use) por mais detalhes sobre as diferentes construções.

  Se a sequência de caracteres começar com `#` será usada como uma `querySelector` e usará o `innerHTML` do elemento selecionado como modelo de marcação de sequência de caracteres. Isto permite o modelo de marcação da fonte ser escrito usando elementos `<template>` nativos.

  Se a opção `render` também estiver presente no mesmo componente, o `template` será ignorado.

  Se o componente de raiz da nossa aplicação não tiver uma opção `template` ou `render` especificada, a Vue tentará usar o `innerHTML` do elemento montado como modelo de marcação.

  :::warning Aviso de Segurança
  Só deveríamos usar modelos de marcação de fontes que possamos confiar. Não devemos usar conteúdo fornecido pelo utilizador como nosso modelo de marcação. Consulte o [Guia de Segurança](/guide/best-practices/security#rule-no-1-never-use-non-trusted-templates) por mais detalhes.
  :::

## `render` {#render}

Uma função que retorna programaticamente a árvore de DOM virtual do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    render?(this: ComponentPublicInstance) => VNodeChild
  }

  type VNodeChild = VNodeChildAtom | VNodeArrayChildren

  type VNodeChildAtom =
    | VNode
    | string
    | number
    | boolean
    | null
    | undefined
    | void

  type VNodeArrayChildren = (VNodeArrayChildren | VNodeChildAtom)[]
  ```

- **Detalhes:**

  `render` é uma alternativa aos modelos de marcação de sequência de caracteres que permite-nos influenciar todo o poder programático da JavaScript de declarar a saída da interpretação do componente.

  Os modelos de marcação pré-compilados, por exemplo aqueles nos Componentes de Ficheiro Único, são compilados para a opção `render` em tempo de construção. Se ambos `render` e `template` estiverem presentes num componente, `render` receberá prioridade mais alta.

- **Consulte também**
  - [Mecanismo de Interpretação](/guide/extras/rendering-mechanism)
  - [Funções de Interpretação](/guide/extras/render-function)

## `compilerOptions` {#compileroptions}

Configura as opções do compilador de tempo de execução para o modelo de marcação do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    compilerOptions?: {
      isCustomElement?: (tag: string) => boolean
      whitespace?: 'condense' | 'preserve' // predefinido como: 'condense'
      delimiters?: [string, string] // predefinido como: ['{{', '}}']
      comments?: boolean // predefinido como: false
    }
  }
  ```

- **Detalhes**

  Esta opção de configuração só é respeitada quando usamos a construção completa (por exemplo, o `.vue.js` autónomo que pode compilar modelos de marcação no navegador). Ela suporta as mesmas opções que o [`app.config.compilerOptions`](/api/application#app-config-compileroptions) do nível de aplicação, e tem prioridade mais alta para o componente atual.

- **Consulte também** [`app.config.compilerOptions`](/api/application#app-config-compileroptions)

## `slots`<sup class="vt-badge ts" data-text="typescript"/> {#slots}

Uma opção para ajudar com a inferência de tipo quando usamos ranhuras programaticamente nas funções de interpretação. Apenas suportado na 3.3+.

- **Detalhes**

  Este valor de tempo de execução da opção não é usado. Os tipos verdadeiros devem ser declarados através da moldagem de tipo usando o tipo auxiliar `SlotsType`:

  ```ts
  import { SlotsType } from 'vue'

  defineComponent({
    slots: Object as SlotsType<{
      default: { foo: string; bar: number }
      item: { data: number }
    }>,
    setup(props, { slots }) {
      expectType<
        undefined | ((scope: { foo: string; bar: number }) => any)
      >(slots.default)
      expectType<undefined | ((scope: { data: number }) => any)>(
        slots.item
      )
    }
  })
  ```

---

---
url: /api/options-misc.md
---
# Opções: Outros {#options-misc}

## `name` {#name}

Explicitamente declara um nome de exibição para o componente.
Declara explicitamente um nome de exibição para o componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    name?: string
  }
  ```

- **Detalhes**

  O nome dum componente é usado para o seguinte:

  - Auto-referência recursiva no modelo de marcação do próprio componente
  - Exibição na árvore de inspeção de componentes das ferramentas de programação da Vue
  - Exibição em traços de componentes de aviso

  Quando usamos os componentes de ficheiro único, o componente já infere o seu próprio nome a partir do nome do ficheiro. Por exemplo, um ficheiro chamado `MyComponent.vue` terá o nome de exibição inferido "MyComponent".

  Um outro caso é que quando um componente é registado globalmente com [`app.component`](/api/application#app-component), o identificador global é definido automaticamente como seu nome.

  A opção `name` permite-nos sobrepor o nome inferido, ou explicitamente fornecer um nome quando nenhum nome puder ser inferido (por exemplo, quando não estamos usando ferramentas de construção, ou um componente que não é de ficheiro único embutido).

  Existe um caso onde `name` é explicitamente necessário: quando correspondemos contra componentes passíveis de armazenamento de consulta imediata no [`<KeepAlive>`](/guide/built-ins/keep-alive) através das suas propriedades `include / exclude`.

  :::tip DICA
  Desde a versão 3.2.34, um componente de ficheiro único usando `<script setup>` inferirá automaticamente a sua opção `name` baseado no nome do ficheiro, removendo a necessidade de manualmente declarar o nome mesmo quando usado com `<KeepAlive>`.
  :::

## `inheritAttrs` {#inheritattrs}

Controla se o comportamento padrão de passagem de atributo do componente deveria ser ativado.

- **Tipo**

  ```ts
  interface ComponentOptions {
    inheritAttrs?: boolean // predefinido como: true
  }
  ```

- **Detalhes**

  Por padrão, os vínculos de atributos do âmbito de aplicação pai que não são reconhecidos como propriedades "cairão". Isto significa que quando tivermos um componente de única raiz, estes vínculos serão aplicados ao elemento raiz do componente filho como atributos de HTML normais. Quando escrevemos um componente que envolve um elemento alvo ou um outro componente, isto pode não ser sempre o comportamento desejado. Pela definição de `inheritAttrs` para `false`, este comportamento padrão pode ser desligado. Os atributos estão disponíveis através da propriedade de instância `$attrs` e podem ser explicitamente vinculadas à um elemento que é de raiz usando `v-bind`.

- **Exemplo**

  <div class="options-api">

  ```vue
  <script>
  export default {
    inheritAttrs: false,
    props: ['label', 'value'],
    emits: ['input']
  }
  </script>

  <template>
    <label>
      {{ label }}
      <input
        v-bind="$attrs"
        v-bind:value="value"
        v-on:input="$emit('input', $event.target.value)"
      />
    </label>
  </template>
  ```

  </div>
  <div class="composition-api">

  Ao declarar esta opção em um componente que usa `<script setup>`, um bloco separado `<script>` é necessário:
  Quando declaramos esta opção num componente que usa `<script setup>`, podemos usar a macro [`defineOptions`](/api/sfc-script-setup#defineoptions):

  ```vue
  <script setup>
  defineProps(['label', 'value'])
  defineEmits(['input'])
  defineOptions({ 
    inheritAttrs: false 
  })
  </script>

  <template>
    <label>
      {{ label }}
      <input
        v-bind="$attrs"
        v-bind:value="value"
        v-on:input="$emit('input', $event.target.value)"
      />
    </label>
  </template>
  ```

  </div>

- **Consultar também** [Atributos de Passagem](/guide/components/attrs)

## `components` {#components}

Um objeto que regista os componentes a serem disponibilizados à instância do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    components?: { [key: string]: Component }
  }
  ```

- **Exemplo**

  ```js
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'

  export default {
    components: {
      // abreviatura
      Foo,
      // registar sob um nome diferente
      RenamedBar: Bar
    }
  }
  ```

- **Consultar também** [Registo de Componente](/guide/components/registration)

## `directives` {#directives}

Um objeto que regista as diretivas a serem disponibilizadas à instância do componente.

- **Tipo**

  ```ts
  interface ComponentOptions {
    directives?: { [key: string]: Directive }
  }
  ```

- **Exemplo**

  ```js
  export default {
    directives: {
      // ativa `v-focus` no modelo de marcação
      focus: {
        mounted(el) {
          el.focus()
        }
      }
    }
  }
  ```

  ```vue-html
  <input v-focus>
  ```

  Um dicionário de diretivas a serem disponibilizadas à instância do componente.

- **Consultar também** [Diretivas Personalizadas](/guide/reusability/custom-directives)

---

---
url: /guide/built-ins/keep-alive.md
---
<script setup>
import SwitchComponent from './keep-alive-demos/SwitchComponent.vue'
</script>

# Preservação de Componente {#keepalive}

O `<KeepAlive>` é um componente embutido que permite-nos condicionalmente guardar para consulta imediata as instâncias de componente quando mudamos dinamicamente entre vários componentes.

## Utilização Básica {#basic-usage}

No capítulo de Fundamentos de Componente, introduzimos a sintaxe para [Componentes Dinâmicos](/guide/essentials/component-basics.html#componentes-dinâmicos), utilizando o elemento especial `<component>`:

```vue-html
<component :is="activeComponent" />
```

Por padrão, uma instância de componente ativa será desmontada quando mudamos para outra instância de componente. Isto causará que qualquer estado mudado que ele segura ser perdido.

No exemplo abaixo, temos dois componentes com conteúdo - (A) contém um contador, enquando (B) contém uma messagem síncronizada com uma entrada através `v-model`. Tente atualizar o estado de um deles, mude para outro, e então mude de volta para ele:

<SwitchComponent />

Notarás que quando mudado de volta, o anterior estado mudado teria sido reiniciado.

A criação de nova instância de componente na troca é um comportamente normalmente útil, mas neste caso, gostariamos muito que as duas instâncias de componente sejam preservadas mesmo quando estiverem inativas. Para solucionar este problema, podemos envolver o nosso componente dinâmico com o componente embutido `<KeepAlive>`:

```vue-html
<!-- Os componentes inativos serão cacheados! -->
<KeepAlive>
  <component :is="activeComponent" />
</KeepAlive>
```

Agora, o estado será persistido através das mudanças de componente:

<SwitchComponent use-KeepAlive />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqtUsFOwzAM/RWrl4IGC+cqq2h3RFw495K12YhIk6hJi1DVf8dJSllBaAJxi+2XZz8/j0lhzHboeZIl1NadMA4sd73JKyVaozsHI9hnJqV+feJHmODY6RZS/JEuiL1uTTEXtiREnnINKFeAcgZUqtbKOqj7ruPKwe6s2VVguq4UJXEynAkDx1sjmeMYAdBGDFBLZu2uShre6ioJeaxIduAyp0KZ3oF7MxwRHWsEQmC4bXXDJWbmxpjLBiZ7DwptMUFyKCiJNP/BWUbO8gvnA+emkGKIgkKqRrRWfh+Z8MIWwpySpfbxn6wJKMGV4IuSs0UlN1HVJae7bxYvBuk+2IOIq7sLnph8P9u5DJv5VfpWWLaGqTzwZTCOM/M0IaMvBMihd04ruK+lqF/8Ajxms8EFbCiJxR8khsP6ncQosLWnWV6a/kUf2nqu75Fby04chA0iPftaYryhz6NBRLjdtajpHZTWPio=)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqtU8tugzAQ/JUVl7RKWveMXFTIseofcHHAiawasPxArRD/3rVNSEhbpVUrIWB3x7PM7jAkuVL3veNJmlBTaaFsVraiUZ22sO0alcNedw2s7kmIPHS1ABQLQDEBAMqWvwVQzffMSQuDz1aI6VreWpPCEBtsJppx4wE1s+zmNoIBNLdOt8cIjzut8XAKq3A0NAIY/QNveFEyi8DA8kZJZjlGALQWPVSSGfNYJjVvujIJeaxItuMyo6JVzoJ9VxwRmtUCIdDfNV3NJWam5j7HpPOY8BEYkwxySiLLP1AWkbK4oHzmXOVS9FFOSM3jhFR4WTNfRslcO54nSwJKcCD4RsnZmJJNFPXJEl8t88quOuc39fCrHalsGyWcnJL62apYNoq12UQ8DLEFjCMy+kKA7Jy1XQtPlRTVqx+Jx6zXOJI1JbH4jejg3T+KbswBzXnFlz9Tjes/V/3CjWEHDsL/OYNvdCE8Wu3kLUQEhy+ljh+brFFu)

</div>

:::tip Dica
Quando utilizada nos [modelos de marcação de DOM](/guide/essentials/component-basics.html#advertências-de-analise-de-modelo-marcação-de-dom), ele deve ser referenciado como `<keep-alive>`.
:::

## Incluir / Excluir {#include-exclude}

Por padrão, `<KeepAlive>` cacheará qualquer instância de componente no lado de dentro. Nós podemos personalizar este comportamento através das propriedades `include` e `exclude`. Ambas propriedades podem ser uma sequência de caracteres delimitada por vírgula, uma `RegExp` (Expressão Regular), ou arranjo contendo quaisquer tipos:

```vue-html
<!-- sequência de caracteres delimitada por vírgula -->
<KeepAlive include="a,b">
  <component :is="view" />
</KeepAlive>

<!-- expressão regular (ou regex) (utilize `v-bind`) -->
<KeepAlive :include="/a|b/">
  <component :is="view" />
</KeepAlive>

<!-- arranjo (ou array) (utilize `v-bind`) -->
<KeepAlive :include="['a', 'b']">
  <component :is="view" />
</KeepAlive>
```

A correspondência é verificada contra a opção [name](/api/options-misc.html#name) do componente, assim os componentes que precisam ser cacheados condicionalmente pelo `KeepAlive` devem declarar de maneira explícita uma opção `name`.

## Máximo de Instâncias Cacheadas {#max-cached-instances}

Nós podemos limitar o número máximo de instâncias de componente que podem ser cacheadas através da propriedade `max`. Quando `max` é especificada, `<KeepAlive>` comporta-se como um [cache de LRU](<https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)>): se o número de instâncias cacheadas exceder a contagem máxima especidada, a menor instância cacheada acessada recentemente será destruída para arranjar espaço para uma nova.

```vue-html
<KeepAlive :max="10">
  <component :is="activeComponent" />
</KeepAlive>
```

## Ciclo de Vida da Instância Cacheada {#lifecycle-of-cached-instance}

Quando uma instância de componente for removida do DOM mas for parte de uma árvore de componente cacheada pelo  `<KeepAlive>`, ele entra em um estado **desativado** no lugar de ser desmontada. Quando uma instância de componente for inserida no DOM como parte de uma árvore cacheada, ele é **ativado**.

<div class="composition-api">

Um componente que é mantido vivo pode registar gatilhos de ciclo de vida para estes dois estados utilizando [`onActivated()`](/api/composition-api-lifecycle.html#onactivated) e [`onDeactivated()`](/api/composition-api-lifecycle.html#ondeactivated):

```vue
<script setup>
import { onActivated, onDeactivated } from 'vue'

onActivated(() => {
  // chamada na montagem inicial
  // e toda vez que ela for inserida novamente do cache
})

onDeactivated(() => {
  // chamada quando removida do DOM para o cache
  // e também quando desmontada
})
</script>
```

</div>
<div class="options-api">

Um componente que é mantido vivo pode registar gatilhos de ciclo de vida para estes dois estados utilizando os gatilhos [`activated`](/api/options-lifecycle.html#activated) e [`deactivated`](/api/options-lifecycle.html#deactivated):

```js
export default {
  activated() {
    // chamada na montagem inicial
    // e toda vez que ela for inserida novamente do cache
  },
  deactivated() {
    // chamada quando removida do DOM para o cache
    // e tamém quando desmontada
  }
}
```

</div>

Nota que:

- <span class="composition-api">`onActivated`</span><span class="options-api">`activated`</span> é também chamada na montagem, e <span class="composition-api">`onDeactivated`</span><span class="options-api">`deactivated`</span> na desmontagem.

- Ambos gatilhos funcionam para não apenas o componente de raiz cacheado pelo `<KeepAlive>`, mas também para componentes descendentes na árvore cacheada.

---

**Relacionado a**

- [Referência de API de `<KeepAlive>`](/api/built-in-components.html#keepalive)

---

---
url: /guide/components/props.md
---
# Propriedades {#props}

> Neste material assume-se conhecimento dos [Fundamentos dos Componentes](/guide/essentials/component-basics). Precisamos entender o básico de componentes para acompanhar este material.

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-3-reusable-components-with-props" title="Aula Gratuita de Propriedades de Vue.js"/>
</div>

## Declaração das Propriedades {#props-declaration}

Os componentes da Vue exigem a declaração explícita das propriedades para que a Vue saiba quais propriedades externas passadas ao componente deve ser tratadas como atributos de passagem (que serão discutidos na [sua secção dedicada](/guide/components/attrs)).

<div class="composition-api">

Nos componentes de ficheiro único que usam `<script setup>`, as propriedades podem ser declaradas com o uso da macro `defineProps()`:

```vue
<script setup>
const props = defineProps(['foo'])

console.log(props.foo)
</script>
```

Nos componentes que não usam `<script setup>`, as propriedades são declaradas com o uso da opção [`props`](/api/options-state#props):

```js
export default {
  props: ['foo'],
  setup(props) {
    // setup() recebe as propriedades como primeiro argumento.
    console.log(props.foo)
  }
}
```

Precisamos notar que o argumento passado à `defineProps()` é o mesmo valor fornecido às opções da `props`: a mesma API de opções é partilhada entre os dois estilos de declaração.

</div>

<div class="options-api">

As propriedades são declaradas com o uso da opção [`props`](/api/options-state#props):

```js
export default {
  props: ['foo'],
  created() {
    // as propriedades são expostas no `this`
    console.log(this.foo)
  }
}
```

</div>

Para além de declararmos as propriedades com o uso de um vetor de sequências de caracteres, também podemos usar a sintaxe de objeto:

<div class="options-api">

```js
export default {
  props: {
    title: String,
    likes: Number
  }
}
```

</div>
<div class="composition-api">

```js
// com <script setup>
defineProps({
  title: String,
  likes: Number
})
```

```js
// sem <script setup>
export default {
  props: {
    title: String,
    likes: Number
  }
}
```

</div>

Para cada propriedade na sintaxe de declaração de objeto, a chave é o nome da propriedade, enquanto o valor deve ser a função construtora do tipo esperado.

Isto não apenas documenta o nosso componente, mas também avisará outros programadores que usam o nosso componente na consola do navegador caso estes passarem o tipo errado. Nós discutiremos mais detalhes sobre [validação de propriedade](#prop-validation) mais adiante nesta página.

<div class="options-api">

Consultar também: [Tipificação das Propriedades do Componente](/guide/typescript/options-api#typing-component-props) <sup class="vt-badge ts" />

</div>

<div class="composition-api">

Se usarmos a TypeScript com `<script setup>`, é possível também declarar as propriedades com o uso de anotações de tipo puras:

```vue
<script setup lang="ts">
defineProps<{
  title?: string
  likes?: number
}>()
</script>
```

Mais detalhes: [Tipificação das Propriedades do Componente](/guide/typescript/composition-api#typing-component-props) <sup class="vt-badge ts" />

</div>

## Detalhes da Passagem de Propriedade {#prop-passing-details}

### Caixa do Nome de Propriedade {#prop-name-casing}

Nós declaramos nomes de propriedades longos usando a caixaDeCamelo porque isto evita ter de usar aspas quando os usamos como chaves de propriedade e permite-nos referenciá-los diretamente em expressões do modelo de marcação porque são identificadores de JavaScript válidos:

<div class="composition-api">

```js
defineProps({
  greetingMessage: String
})
```

</div>
<div class="options-api">

```js
export default {
  props: {
    greetingMessage: String
  }
}
```

</div>

```vue-html
<span>{{ greetingMessage }}</span>
```

Tecnicamente, também podemos usar a caixaDeCamelo ao passar propriedades a um componente filho, (exceto nos [modelos de marcação do modelo de objeto do documento incorporado](/guide/essentials/component-basics#in-dom-template-parsing-caveats)). No entanto, a convenção é usar a caixa-espetada em todos os casos para alinhar com os atributos de HTML:

```vue-html
<MyComponent greeting-message="hello" />
```

Nós usamos a [CaixaPascal para os marcadores de componente](/guide/components/registration#component-name-casing) quando possível porque melhora a legibilidade do modelo de marcação ao diferenciar os componentes de Vue dos elementos nativos. No entanto, não existe muito benefícios práticos em usar caixaDeCamelo ao passar propriedades, por isto optamos por seguir as seguintes convenções de cada linguagem.

### Propriedades Estáticas vs Propriedades Dinâmicas {#static-vs-dynamic-props}

Por enquanto, vimos propriedades passadas como valores estáticos, como em:

```vue-html
<BlogPost title="My journey with Vue" />
```

Também vimos propriedades atribuídas dinamicamente com a `v-bind` ou seu atalho `:`, como em:

```vue-html
<!-- Atribuir dinamicamente o valor duma variável -->
<BlogPost :title="post.title" />

<!-- Atribuir dinamicamente o valor duma expressão complexa -->
<BlogPost :title="post.title + ' by ' + post.author.name" />
```

### Passagem de Diferentes Tipos de Valores {#passing-different-value-types}

Nos dois exemplos acima, passamos valores de sequência de caracteres, mas _qualquer_ tipo de valor pode ser passado a uma propriedade.

#### `Number` (Número) {#number}

```vue-html
<!-- Embora `42` seja estático, precisamos de `v-bind` para dizer -->
<!-- a Vue que isto é uma expressão de JavaScript em vez duma -->
<!-- sequência de caracteres. -->
<BlogPost :likes="42" />

<!-- Atribuir dinamicamente ao valor duma variável. -->
<BlogPost :likes="post.likes" />
```

#### `Boolean` (Booleano) {#boolean}

```vue-html
<!-- A inclusão da propriedade sem valor implicará `true`. -->
<BlogPost is-published />

<!-- Embora `false` seja estático, precisamos de `v-bind` para dizer -->
<!-- a Vue que isto é uma expressão de JavaScript em vez duma -->
<!-- sequência de caracteres. -->
<BlogPost :is-published="false" />

<!-- Atribuir dinamicamente ao valor duma variável. -->
<BlogPost :is-published="post.isPublished" />
```

#### `Array` (Vetor) {#array}

```vue-html
<!-- Embora o vetor seja estático, precisamos de `v-bind` para dizer -->
<!-- a Vue que isto é uma expressão de JavaScript em vez duma -->
<!-- sequência de caracteres. -->
<BlogPost :comment-ids="[234, 266, 273]" />

<!-- Atribuir dinamicamente ao valor duma variável. -->
<BlogPost :comment-ids="post.commentIds" />
```

#### `Object` (Objeto) {#object}

```vue-html
<!-- Embora o objeto seja estático, precisamos de `v-bind` para dizer -->
<!-- a Vue que isto é uma expressão de JavaScript em vez duma -->
<!-- sequência de caracteres. -->
<BlogPost
  :author="{
    name: 'Veronica',
    company: 'Veridian Dynamics'
  }"
 />

<!-- Atribuir dinamicamente ao valor duma variável. -->
<BlogPost :author="post.author" />
```

### Vínculo de Várias Propriedades Usando um Objeto {#binding-multiple-properties-using-an-object}

Se quisermos passar todas as propriedades dum objeto como propriedades, podemos usar a [`v-bind` sem um argumento](/guide/essentials/template-syntax#dynamically-binding-multiple-attributes) (`v-bind` em vez de `:prop-name`). Por exemplo, dado um objeto `post`:

<div class="options-api">

```js
export default {
  data() {
    return {
      post: {
        id: 1,
        title: 'My Journey with Vue'
      }
    }
  }
}
```

</div>
<div class="composition-api">

```js
const post = {
  id: 1,
  title: 'My Journey with Vue'
}
```

</div>

O seguinte modelo de marcação:

```vue-html
<BlogPost v-bind="post" />
```

Será equivalente a:

```vue-html
<BlogPost :id="post.id" :title="post.title" />
```

## Fluxo de Dados Unidirecional {#one-way-data-flow}

Todas as propriedades formam um **vínculo unidirecional descendente** entre a propriedade filha e a propriedade pai: quando a propriedade pai é atualizada, esta passa à propriedade filha, mas não o contrário. Isto evita que os componentes filhos alterem acidentalmente o estado do pai, o que pode tornar o fluxo de dados da nossa aplicação mais difícil de compreender.

Para além disto, sempre que o componente pai for atualizado, todas as propriedades no componente filho serão atualizadas com valor mais recente. Isto significa que não devemos tentar alterar uma propriedade dentro dum componente filho. Se o fizermos, a Vue avisar-nos-á na consola:

<div class="composition-api">

```js
const props = defineProps(['foo'])

// ❌ aviso, "props" são só de leitura!
props.foo = 'bar'
```

</div>
<div class="options-api">

```js
export default {
  props: ['foo'],
  created() {
    // ❌ aviso, "props" são só de leitura!
    this.foo = 'bar'
  }
}
```

</div>

Normalmente, existem dois casos em que é tentar alterar uma propriedade:

1. **A propriedade é usada para passar um valor inicial; o componente filho pretende usá-la posteriormente como uma propriedade de dados local.** Neste caso, é melhor definir uma propriedade de dados local que usa uma propriedade como seu valor inicial: 

   <div class="composition-api">

   ```js
   const props = defineProps(['initialCounter'])

   // "counter" só usa "props.initialCounter" como valor inicial;
   // é desligada de futuras atualizações de propriedade.
   const counter = ref(props.initialCounter)
   ```

   </div>
   <div class="options-api">

   ```js
   export default {
     props: ['initialCounter'],
     data() {
       return {
         // "counter" só usa "props.initialCounter" como valor inicial;
         // é desligada de futuras atualizações de propriedade.
         counter: this.initialCounter
       }
     }
   }
   ```

   </div>

2. **A propriedade é passada como um valor bruto que precisa de ser transformado.** Neste caso,é melhor definir uma propriedade computada usando o valor da propriedade:

   <div class="composition-api">

   ```js
   const props = defineProps(['size'])

   // propriedade computada que se atualiza automaticamente
   // quando a propriedade for alterada
   const normalizedSize = computed(() => props.size.trim().toLowerCase())
   ```

   </div>
   <div class="options-api">

   ```js
   export default {
     props: ['size'],
     computed: {
       // propriedade computada que se atualiza automaticamente
       // quando a propriedade for alterada
       normalizedSize() {
         return this.size.trim().toLowerCase()
       }
     }
   }
   ```

   </div>

### Alteração de Propriedades de Objeto ou Vetor {#mutating-object-array-props}

Quando os objetos e os vetores são passados como propriedades, embora o componente filho não possa alterar o vínculo da propriedade, **será** capaz de alterar as propriedades encaixadas do objeto ou do vetor. Isto acontece porque na JavaScript os objetos e vetores são passados por referência, e é excessivamente dispendioso para a Vue evitar tais mutações.

A principal desvantagem de tais mutações é que permite que o componente filho afete o estado do componente pai duma maneira que não é óbvia para o componente pai, tornando potencialmente mais difícil raciocinar sobre o fluxo de dados no futuro. Como boa prática, devemos evitar essas mutações a menos que o pai e o filho estejam fortemente acoplados por natureza. Na maioria dos casos, o filho deve [emitir um evento](/guide/components/events) para permitir que o pai realize a mutação.

## Validação de Propriedade {#prop-validation}

Os componentes podem especificar requisitos para suas propriedades, como os tipos que já vimos. Se um requisito não for cumprido, a Vue avisar-nos-á na consola de JavaScript do navegador. Isto é especialmente útil quando desenvolvemos um componente que se destina a ser usado por outros.

Para especificar as validações de propriedade, podemos fornecer um objeto com os requisitos de validação a <span class="composition-api">macro `defineProps()`</span><span class="options-api">opção `props`</span>, no lugar dum vetor de sequências de caracteres. Por exemplo:

<div class="composition-api">

```js
defineProps({
  // Verificação de tipo básica
  //  (valores `null` e `undefined` permitirão qualquer tipo)
  propA: Number,
  // Vários tipos possíveis
  propB: [String, Number],
  // Sequência de caracteres obrigatória
  propC: {
    type: String,
    required: true
  },
  // Número com um valor predefinido
  propD: {
    type: Number,
    default: 100
  },
  // Objeto com um valor predefinido
  propE: {
    type: Object,
    // Os valores predefinidos de objeto ou vetor devem
    // ser retornados duma função de fábrica. A função
    // recebe as propriedades brutas recebidas pelo 
    // componente como argumento.
    default(rawProps) {
      return { message: 'hello' }
    }
  },
  // Função de validação personalizada
  // propriedades completas passadas como
  // segundo argumento na 3.4+
  propF: {
    validator(value, props) {
      // O valor deve corresponder uma destas
      // sequências de caracteres
      return ['success', 'warning', 'danger'].includes(value)
    }
  },
  // Função com um valor predefinido
  propG: {
    type: Function,
    // Ao contrário do objeto ou vetor predefinidos, 
    // não se trata duma função de fábrica - esta é uma
    // função que serve de valor predefinido.
    default() {
      return 'Default function'
    }
  }
})
```

:::tip DICA
O código dentro do argumento da `defineProps()` **não pode acessar outras variáveis declaradas no `<script setup>`**, porque a expressão inteira é movida para um contexto de função externa quando compilada.
:::

</div>
<div class="options-api">

```js
export default {
  props: {
    // Verificação de tipo básica
    //  (valores `null` e `undefined` permitirão qualquer tipo)
    propA: Number,
    // Vários tipos possíveis
    propB: [String, Number],
    // Sequência de caracteres obrigatória
    propC: {
      type: String,
      required: true
    },
    // Número com um valor predefinido
    propD: {
      type: Number,
      default: 100
    },
    // Objeto com um valor predefinido
    propE: {
      type: Object,
      // Os valores predefinidos de objeto ou vetor devem
      // ser retornados duma função de fábrica. A função
      // recebe as propriedades brutas recebidas pelo 
      // componente como argumento.
      default(rawProps) {
        return { message: 'hello' }
      }
    },
    // Função de validação personalizada
    // propriedades completas passadas como
    // segundo argumento na 3.4+
    propF: {
      validator(value) {
        // O valor deve corresponder uma destas
        // sequências de caracteres
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // Função com um valor predefinido
    propG: {
      type: Function,
      // Ao contrário do objeto ou vetor predefinidos, 
      // não se trata duma função de fábrica - esta é uma
      // função que serve de valor predefinido.
      default() {
        return 'Default function'
      }
    }
  }
}
```

</div>

Detalhes adicionais:

- Todas as propriedades são opcionais por padrão, a menos que `required: true` seja especificado.

- Uma propriedade opcional ausente que não seja `Boolean` terá o valor `undefined`.
  
- As propriedades ausentes de `Boolean` serão convertidas para `false`. Nós podemos mudar isto definindo um `default: undefined` a esta — isto é, `default: undefined` para comportar-se como uma propriedade não Booleana.

- Se um valor `default` for especificado, esta será usada se o valor da propriedade resolvida for `undefined` — isto inclui tanto quando a propriedade está ausente, ou quando um valor `undefined` explícito é passado.

Quando a validação da propriedade falhar, a Vue produzirá um aviso na consola (se estivermos usando a construção de desenvolvimento).

<div class="composition-api">

Se estivermos usando [declarações de propriedades baseadas em tipos](/api/sfc-script-setup#type-only-props-emit-declarations) <sup class="vt-badge ts" />, a Vue tentará o seu melhor para compilar as anotações de tipos em declarações de propriedades equivalentes em execução. Por exemplo, `defineProps<{ msg: string }>` será compilada para `{ msg: { type: String, required: true }}`.

</div>
<div class="options-api">

:::tip NOTA
É necessário notar que as propriedades são validadas **antes** da instância dum componente ser criada, portanto as propriedades da instância (por exemplo, `data`, `computed`, etc.) não estarão disponíveis dentro das funções `default` ou `validator`.
:::

</div>

### Verificações de Tipo da Execução {#runtime-type-checks}

O `type` pode ser um dos seguintes construtores nativos:

- `String`
- `Number`
- `Boolean`
- `Array`
- `Object`
- `Date`
- `Function`
- `Symbol`
- `Error`

Além disto, `type` também pode ser uma classe personalizada ou função construtora e a asserção será feita com uma verificação de `instanceof`. Por exemplo, dada a seguinte classe:

```js
class Person {
  constructor(firstName, lastName) {
    this.firstName = firstName
    this.lastName = lastName
  }
}
```

Nós poderíamos usá-la como um tipo de propriedade:

<div class="composition-api">

```js
defineProps({
  author: Person
})
```

</div>
<div class="options-api">

```js
export default {
  props: {
    author: Person
  }
}
```

</div>

A Vue usará `instanceof Person` para validar se o valor da propriedade `author` é de fato uma instância da classe `Person`.

## Conversão Booleana {#boolean-casting}

As propriedades do tipo `Boolean` possuem regras especiais de conversão para imitarem o comportamento dos atributos booleanos nativos. Dado um `<MyComponent>` com a seguinte declaração:

<div class="composition-api">

```js
defineProps({
  disabled: Boolean
})
```

</div>
<div class="options-api">

```js
export default {
  props: {
    disabled: Boolean
  }
}
```

</div>

O componente pode ser usado da seguinte maneira:

```vue-html
<!-- equivalente à passagem de :disabled="true" -->
<MyComponent disabled />

<!-- equivalente à passagem de :disabled="false" -->
<MyComponent />
```

Quando uma propriedade é declarada para permitir vários tipos, as regras de conversão para `Boolean` também serão aplicadas. No entanto, existe uma vantagem quando ambos `String` e `Boolean` são permitidos — a regra de conversão de `Boolean` só se aplica se `Boolean` aparecer antes de `String`:

<div class="composition-api">

```js
// `disabled` será convertido para `true`
defineProps({
  disabled: [Boolean, Number]
})
  
// `disabled` será convertido para `true`
defineProps({
  disabled: [Boolean, String]
})
  
// `disabled` será convertido para `true`
defineProps({
  disabled: [Number, Boolean]
})
  
// `disabled` será analisado sintaticamente como
// uma sequência de caracteres vazia (disabled="")
defineProps({
  disabled: [String, Boolean]
})
```

</div>
<div class="options-api">

```js
// `disabled` será convertido para `true`
export default {
  props: {
    disabled: [Boolean, Number]
  }
}
  
// `disabled` será convertido para `true`
export default {
  props: {
    disabled: [Boolean, String]
  }
}
  
// `disabled` será convertido para `true`
export default {
  props: {
    disabled: [Number, Boolean]
  }
}
  
// `disabled` será analisado sintaticamente como
// uma sequência de caracteres vazia (disabled="")
export default {
  props: {
    disabled: [String, Boolean]
  }
}
```

</div>

---

---
url: /guide/essentials/computed.md
---
# Propriedades Computadas {#computed-properties}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/computed-properties-in-vue-3" title="Aula Gratuita de Propriedades Computadas de Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-computed-properties-in-vue-with-the-composition-api" title="Aula Gratuita de Propriedades Computadas de Vue.js"/>
</div>

## Exemplo Básico {#basic-example}

As expressões no modelo de marcação são muito convenientes, porém estas estão destinadas às operações simples. Colocar muita lógica nos nossos modelos de marcação pode torná-los inchados e difíceis de manter. Por exemplo, se tivermos um objeto com um vetor encaixado:

<div class="options-api">

```js
export default {
  data() {
    return {
      author: {
        name: 'John Doe',
        books: [
          'Vue 2 - Advanced Guide',
          'Vue 3 - Basic Guide',
          'Vue 4 - The Mystery'
        ]
      }
    }
  }
}
```

</div>
<div class="composition-api">

```js
const author = reactive({
  name: 'John Doe',
  books: [
    'Vue 2 - Advanced Guide',
    'Vue 3 - Basic Guide',
    'Vue 4 - The Mystery'
  ]
})
```

</div>

E queremos exibir mensagens diferentes se o `author` já tiver alguns livros ou não:

```vue-html
<p>Has published books:</p>
<span>{{ author.books.length > 0 ? 'Yes' : 'No' }}</span>
```

Neste ponto, o modelo de marcação está ficando um pouco desarrumado. Nós temos que olhar neste por um segundo antes de percebermos que este realiza um cálculo dependendo da `author.books`. Acima de tudo, provavelmente não queremos ser repetitivos ao incluir este cálculo no modelo de marcação mais de uma vez.

É por isto que para lógica complexa que inclui dados reativos, é recomendado usar uma **propriedade computada**. Eis o mesmo exemplo, refeito:

<div class="options-api">

```js
export default {
  data() {
    return {
      author: {
        name: 'John Doe',
        books: [
          'Vue 2 - Advanced Guide',
          'Vue 3 - Basic Guide',
          'Vue 4 - The Mystery'
        ]
      }
    }
  },
  computed: {
    // um recuperador computado
    publishedBooksMessage() {
      // `this` aponta à instância do componente
      return this.author.books.length > 0 ? 'Yes' : 'No'
    }
  }
}
```

```vue-html
<p>Has published books:</p>
<span>{{ publishedBooksMessage }}</span>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkN1KxDAQhV/l0JsqaFfUq1IquwiKsF6JINaLbDNui20S8rO4lL676c82eCFCIDOZMzkzXxetlUoOjqI0ykypa2XzQtC3ktqC0ydzjUVXCIAzy87OpxjQZJ0WpwxgzlZSp+EBEKylFPGTrATuJcUXobST8sukeA8vQPzqCNe4xJofmCiJ48HV/FfbLLrxog0zdfmn4tYrXirC9mgs6WMcBB+nsJ+C8erHH0rZKmeJL0sot2tqUxHfDONuyRi2p4BggWCr2iQTgGTcLGlI7G2FHFe4Q/xGJoYn8SznQSbTQviTrRboPrHUqoZZ8hmQqfyRmTDFTC1bqalsFBN5183o/3NG33uvoWUwXYyi/gdTEpwK)

Eis que declaramos uma propriedade computada `publishedBooksMessage`.

Nós podemos experimentar mudar o valor do vetor `books` na `data` da aplicação e veremos como `publishedBookMessage` está mudando por consequência.

Nós podemos vincular os dados às propriedades computadas nos modelos de marcação tal como uma propriedade normal. A Vue está consciente de que `this.publishedBooksMessage` depende da `this.author.books`, então esta atualizará quaisquer vínculos que dependem da `this.publishedBooksMessage` quando `this.author.books` mudar.

Consultar também: [Tipificando as Propriedades Computadas](/guide/typescript/options-api#typing-computed-properties) <sup class="vt-badge ts" />

</div>

<div class="composition-api">

```vue
<script setup>
import { reactive, computed } from 'vue'

const author = reactive({
  name: 'John Doe',
  books: [
    'Vue 2 - Advanced Guide',
    'Vue 3 - Basic Guide',
    'Vue 4 - The Mystery'
  ]
})

// uma referência computada
const publishedBooksMessage = computed(() => {
  return author.books.length > 0 ? 'Yes' : 'No'
})
</script>

<template>
  <p>Has published books:</p>
  <span>{{ publishedBooksMessage }}</span>
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1kE9Lw0AQxb/KI5dtoTainkoaaREUoZ5EEONhm0ybYLO77J9CCfnuzta0vdjbzr6Zeb95XbIwZroPlMySzJW2MR6OfDB5oZrWaOvRwZIsfbOnCUrdmuCpQo+N1S0ET4pCFarUynnI4GttMT9PjLpCAUq2NIN41bXCkyYxiZ9rrX/cDF/xDYiPQLjDDRbVXqqSHZ5DUw2tg3zP8lK6pvxHe2DtvSasDs6TPTAT8F2ofhzh0hTygm5pc+I1Yb1rXE3VMsKsyDm5JcY/9Y5GY8xzHI+wnIpVw4nTI/10R2rra+S4xSPEJzkBvvNNs310ztK/RDlLLjy1Zic9cQVkJn+R7gIwxJGlMXiWnZEq77orhH3Pq2NH9DjvTfpfSBSbmA==)

Eis que declaramos uma propriedade computada `publishedBooksMessage`. A função `computed()` espera uma função recuperada ser passada, e o valor retornado ser uma **referência computada**. Semelhante às referências normais, podemos acessar o resultado computado como `publishedBooksMessage.value`. As referências computadas também são embrulhadas automaticamente nos modelos de marcação, assim podemos referenciá-las sem `.value` nas expressões do modelo de marcação.

Uma propriedade computada rastreia automaticamente suas dependências reativas. A Vue está consciente de que a computação de `publishedBooksMessage` depende da `author.books`, então esta atualizará quaisquer vínculos que dependem da `publishedBooksMessage` quando `author.books` mudar.

Consultar também: [Tipificando os Computados](/guide/typescript/composition-api#typing-computed) <sup class="vt-badge ts" />

</div>

## Armazenamento de Consulta Imediata de Computado vs Métodos {#computed-caching-vs-methods}

Nós podemos ter reparado que podemos alcançar o mesmo resultado invocando um método na expressão:

```vue-html
<p>{{ calculateBooksMessage() }}</p>
```

<div class="options-api">

```js
// no componente
methods: {
  calculateBooksMessage() {
    return this.author.books.length > 0 ? 'Yes' : 'No'
  }
}
```

</div>

<div class="composition-api">

```js
// no componente
function calculateBooksMessage() {
  return author.books.length > 0 ? 'Yes' : 'No'
}
```

</div>

No lugar duma propriedade computada, podemos definir a mesma função como um método. Para resultado final, as duas abordagens são de fato exatamente a mesma. No entanto, a diferença é que as **propriedades computadas são armazenadas para consulta imediata baseada nas suas dependências reativas**. Uma propriedade computada apenas reavaliará quando algumas das suas dependências reativas tiverem mudado. Isto significa que enquanto `author.books` não tiver mudado, vários acessos ao `publishedBooksMessage` retornarão imediatamente o resultado computado anteriormente sem precisar executar a função recuperadora novamente.

Isto também significa que a seguinte propriedade computada nunca atualizará, porque `Date.now()` não é uma dependência reativa:

<div class="options-api">

```js
computed: {
  now() {
    return Date.now()
  }
}
```

</div>

<div class="composition-api">

```js
const now = computed(() => Date.now())
```

</div>

Em comparação, uma invocação de método **sempre** executará a função sempre que um reinterpretação acontecer.

Por que precisamos do armazenamento de consulta imediata? Imaginemos que temos uma propriedade computada dispendiosa `list`, que exige percorrer um vetor enorme e fazer muitos cálculos. Depois podemos ter outras propriedades computadas que por sua vez dependem da `list`. Sem o armazenamento de consulta imediata, estaríamos executando o recuperador da `list` mais vezes do que necessário! Nos casos onde não queremos o armazenamento de consulta imediata, usamos uma chamada de método.

## Propriedades Computadas Graváveis {#writable-computed}

As propriedades computadas são por padrão apenas recuperadoras. Se tentarmos atribuir um novo valor a uma propriedade computada, receberemos um aviso de execução. Nos casos raros onde precisamos duma propriedade computada "gravável", podemos criar uma fornecendo ambos um recuperador e um definidor:

<div class="options-api">

```js
export default {
  data() {
    return {
      firstName: 'John',
      lastName: 'Doe'
    }
  },
  computed: {
    fullName: {
      // recuperador
      get() {
        return this.firstName + ' ' + this.lastName
      },
      // definidor
      set(newValue) {
        // Nota: estamos usando a sintaxe de atribuição desestruturada.
        [this.firstName, this.lastName] = newValue.split(' ')
      }
    }
  }
}
```

Agora quando executarmos `this.fullName = 'John Doe'`, o definidor será invocado e `this.firstName` e `this.lastName` serão atualizadas por consequência.

</div>

<div class="composition-api">

```vue
<script setup>
import { ref, computed } from 'vue'

const firstName = ref('John')
const lastName = ref('Doe')

const fullName = computed({
  // recuperador
  get() {
    return firstName.value + ' ' + lastName.value
  },
  // definidor
  set(newValue) {
    // Nota: estamos usando a sintaxe de atribuição desestruturada.
    [firstName.value, lastName.value] = newValue.split(' ')
  }
})
</script>
```

Agora quando executarmos `fullName.value = 'John Doe'`, o definidor será invocado e `firstName` e `lastName` serão atualizadas por consequência.

</div>

## Boas Práticas {#best-practices}

### Os recuperadores não deveriam ter efeitos colaterais {#getters-should-be-side-effect-free}

É importante lembrar que as funções recuperadoras computadas apenas deveriam realizar computação pura e ser livres de efeitos colaterais. Por exemplo, **não fazer requisições assíncronas ou alterar o DOM dentro dum recuperador computado!** Pensemos duma propriedade computada como declarativamente descrevendo como derivar um valor baseado em outros valores - sua única responsabilidade deveria ser computar e retornar este valor. Mais tarde no guia discutiremos como realizamos efeitos colaterais em reação às mudanças de estado com os [observadores](./watchers).

### Evitar alterar o valor computado {#avoid-mutating-computed-value}

O valor retornado duma propriedade computada é o estado derivado. Consideremos esta como uma fotografia temporária - toda vez que o estado de origem mudar, uma nova fotografia é criada. Não faz sentido alterar uma fotografia, então um valor de retorno computado deveria ser tratado como destinada apenas a leitura e nunca deveria ser alterada - ao invés disto, atualizamos o estado de origem do qual este depende para acionar novos cálculos.

---

---
url: /about/faq.md
---
# Questões Feitas Com Frequência {#frequently-asked-questions}

## Quem mantém a Vue? {#who-maintains-vue}

A Vue é um projeto independente, conduzido pela comunidade. Ela foi criada pelo [Evan You](https://twitter.com/youyuxi) em 2014 como um projeto paralelo pessoal. Hoje, a Vue é ativamente mantida por [uma equipa de tanto membros de tempo integral e voluntários de todo o mundo](/about/team), onde Evan serve como o líder do projeto. Tu podes saber mais sobre a história da Vue neste [documentário](https://www.youtube.com/watch?v=OrxmtDw4pVI).

O desenvolvimento da Vue é primariamente financiado através de patrocínios e temos estado financeiramente sustentáveis desde 2016. Se tu ou teu negócio beneficia-se da Vue, considere [patrocinar-nos](/sponsor/) para apoiar o desenvolvimento da Vue!

## Qual é a diferença entre a Vue 2 e Vue 3? {#what-s-the-difference-between-vue-2-and-vue-3}

A Vue 3 é a atual, versão principal mais recente da Vue. Ela contém novas funcionalidades que estavam presentes na Vue 2, tais como Teletransporte, Suspense, e vários elementos raiz por modelo de marcação. Ela também contém mudanças de ruturas que a tornam incompatível com a Vue 2. Os detalhes completos são documentados no [Guia de Migração da Vue 3](https://v3-migration.vuejs.org/).

Apesar das diferenças, a maioria das APIs da Vue são partilhadas entre as duas versões principais, então a maioria do teu conhecimento de Vue 2 continuará a funcionar na Vue 3. Notavelmente, a API de Composição era originalmente uma funcionalidade exclusiva da Vue 3, mas agora foi adicionada à Vue 2 e está disponível na [Vue 2.7](https://github.com/vuejs/vue/blob/main/CHANGELOG.md#270-2022-07-01).

Em geral, a Vue 3 fornece tamanhos de pacote mais pequenos, melhor desempenho, melhor escalabilidade, e melhor suporte de TypeScript ou IDE. Se estiveres a começar um novo projeto hoje, a Vue 3 é a escolha recomendada. Existem algumas poucas razões para considerares a Vue 2 a partir de agora:

- Tu precisas de suportar o IE11. A Vue influencia funcionalidades de JavaScript modernas e não suporta o IE11.

- Tu ainda estás a espera que os principais projetos do ecossistema como Nuxt ou Vuetify lancem versões estáveis para Vue 3. Isto é sensato se não desejas usar software em estágio beta. No entanto, nota que existem outras bibliotecas de componentes de Vue 3 que já estão estáveis tais como [Quasar](https://quasar.dev/), [Naive UI](https://www.naiveui.com/) e [Element Plus](https://element-plus.org/).

Se tencionas migrar uma aplicação de Vue 2 existente para a Vue 3, consulte o [guia de migração](https://v3-migration.vuejs.org/).

## A Vue 2 ainda é suportada? {#is-vue-2-still-supported}

A Vue 2.7, que foi entregada em Julho de 2022, é o último lançamento secundário do limite de versão da Vue 2. A Vue 2 agora entrou no modo de manutenção: não mais entregará novas funcionalidades, mas continuará a receber correções de erros de programação críticos e atualizações de segurança por 18 meses começando a partir da data de lançamento da Vue 2.7. Isto significa que a **Vue 2 alcançará o Fim da Vida em 31 de Dezembro de 2023**.

Nós acreditamos que isto deve fornecer tempo o suficiente para a maioria do ecossistema migrar para a Vue 3. No entanto, também entendemos que poderiam existir equipas ou projetos que não podem atualizar por esta linha de tempo enquanto precisarem de cumprir requisitos de segurança e compatibilidade. Nós estamos a fazer parceria com especialistas da industria para fornecer suporte estendido para Vue 2 para equipas com tais necessidades - se a tua equipa espera estar a usar a Vue 2 além do fim de 2023, certifica-te de planear para adiante e aprender mais sobre o [Suporte de Longo Prazo Estendido da Vue 2](https://v2.vuejs.org/lts/).

## Qual licença a Vue usa? {#what-license-does-vue-use}

A Vue é um projeto livre e de código-aberto lançado sob a [licença MIT](https://opensource.org/licenses/MIT).

## Quais navegadores suportam a Vue? {#what-browsers-does-vue-support}

A versão mais recente da Vue (3.x) apenas suporta [navegadores com suporte de ES2015 nativo](https://caniuse.com/es6). Isto exclui IE11. A Vue 3.x usa funcionalidades da ES2015 que não podem ser adicionadas por preenchimento de buracos em navegadores antigos, então se precisas de suportar navegadores antigos, precisarás de usar a Vue 2.x.

## A Vue é fiável? {#is-vue-reliable}

A Vue é uma abstração madura e testada em combate. Ela é uma das mais largamente usada abstrações de JavaScript em produção hoje, com mais de 1.5 milhões de utilizadores mundialmente, e é descarregada quase 10 milhões de vezes num mês na npm.

A Vue é usada em produção por organizações famosas em capacidades variáveis em todo o mundo, incluindo a Wikimedia Foundation, NASA, Apple, Google, Microsoft, GitLab, Zoom, Tencent, Weibo, Bilibili, Kuaishou, e muitos mais.

## A Vue é rápida? {#is-vue-fast}

A Vue 3 é uma das mais otimizadas abstrações de frontend dominante, e lida com a maioria dos casos de uso de aplicação de Web com facilidade, sem a necessidade de otimizações manuais.

Em cenários de testes de esforço, a Vue tem um desempenho superior da React e Angular por uma margem decente na [js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/current.html). Ela também segue pescoço-a-pescoço contra as mais rápidas abstrações que não usam DOM Virtual em nível de produção na analise comparativa.

Nota que analises comparativas sintéticas como as de cima focam em desempenho de interpretação puro com otimizações dedicadas e podem não ser completamente representantes de resultados de desempenho do mundo real. Se importas-te mais com o desempenho do carregamento da página, és bem-vindo para fazer uma auditoria desta página usando [WebPageTest](https://www.webpagetest.org/lighthouse) ou [PageSpeed Insights](https://pagespeed.web.dev/). Esta página é alimentada pela própria Vue, com pré-interpretação estática, hidratação de página completa e navegação do lado do cliente. Ela pontua 100 em desempenho num Moto G4 emulado com 4x CPU estrangulando sobre redes 4G lentas.

Tu podes saber mais sobre como a Vue otimiza automaticamente o desempenho do tempo de execução na seção do [Mecanismo de Interpretação](/guide/extras/rendering-mechanism), e como otimizar uma aplicação de Vue em casos particularmente exigentes no [Guia de Otimização do Desempenho](/guide/best-practices/performance).

## A Vue é leve? {#is-vue-lightweight}

Quando usas uma ferramenta de construção, muitas das APIs da Vue são passíveis a ["agitação de árvore"](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking). Por exemplo, se não usas o componente `<Transition>` embutido, este não será incluído no pacote de produção final.

Uma aplicação de "Olá Mundo" de Vue que apenas usa o absolutamente mínimo de APIs tem um tamanho de base de apenas em torno de **16kb**, com a minificação e compressão de brotli. O verdadeiro tamanho da aplicação dependerá de quantas funcionalidades opcionais da abstração usas. Em caso pouco provável onde uma aplicação usa todas as funcionalidades que a Vue oferece, o tamanho do executor total é em torno de **27kb**.

Quando usamos a Vue sem uma ferramenta de construção, não apenas perdemos a agitação de árvore, mas também temos de entregar o compilador de modelo de marcação para o navegador. Isto aumenta o tamanho para em torno de **41kb**. Portanto, se estiveres a usar a Vue particularmente para otimizações progressivas sem uma etapa de construção, considere usar a [petite-vue](https://github.com/vuejs/petite-vue) (apenas **6kb**).

Algumas abstrações, tais como a Svelte, usam uma estratégia de compilação que produz uma saída extremamente leve em cenários de único componente. No entanto, [nossa pesquisa](https://github.com/yyx990803/vue-svelte-size-analysis) mostra que a diferença de tamanho depende muito do número de componentes na aplicação. Enquanto a Vue tem um tamanho de base mais pesado, ela gera menos código por componente. Em cenários do mundo real, uma aplicação de Vue pode muito bem acabar sendo mais leve.

## A Vue escala? {#does-vue-scale}

Sim. Apesar duma ideia errada comum de que a Vue é apenas adequada para casos de uso mais simples, a Vue é perfeitamente capaz de lidar com aplicações de grande escala:

- [Componentes de Ficheiro Único](/guide/scaling-up/sfc) fornecem um modelo de desenvolvimento separado por módulos que permite partes diferentes duma aplicação possam ser desenvolvidas separadamente.

- [API de Composição](/guide/reusability/composables) fornece integração de TypeScript de primeira classe e permite padrões limpos para organizar, extrair e reutilizar lógica complexa.

- [Suporte de ferramental abrangente](/guide/scaling-up/tooling) garante uma experiência de desenvolvimento suave conforme a aplicação for crescer.

- Obstáculo muito menor para entrada e excelente documentação que traduz-se para integração e custos de treinamento muito menores para novos programadores.

## Como posso contribuir com a Vue? {#how-do-i-contribute-to-vue}

Nós apreciamos o teu interesse! Consulte o nosso [Guia da Comunidade](/about/community-guide).

## Deveria eu usar a API de Opções ou API de Composição? {#should-i-use-options-api-or-composition-api}

Se fores novo para Vue, fornecemos uma comparação de alto nível entre os dois estilos [nesta ligação](/guide/introduction#which-to-choose).

Se usaste anteriormente a API de Opções e estás atualmente a avaliar a API de Composição, consulte a seção [Questões Frequentes sobre API de Composição](/guide/extras/composition-api-faq).

## Deveria eu usar a JavaScript ou TypeScript com a Vue? {#should-i-use-javascript-or-typescript-with-vue}

Embora a própria Vue seja implementada em TypeScript e forneça suporte de TypeScript de primeira classe, não força uma opinião sobre se deverias usar TypeScript como um utilizador.

O suporte de TypeScript é uma consideração importante quando novas funcionalidades são adicionadas à Vue. As APIs que são desenhadas com a TypeScript em mente são normalmente mais fáceis para IDEs e analisadores de código entenderem, mesmo se não estiveres a usar a TypeScript. Todos ganham. As APIs de Vue também são desenhadas para funcionarem da mesma maneira em ambas JavaScript e TypeScript o máximo possível.

Adotar a TypeScript envolve um compromisso entre integrar complexidade e ganhos de capacidade de manutenção de longo prazo. Se tal compromisso pode ser justificado pode variar dependendo do fundo da tua equipa e escala do projeto, mas a Vue não é de fato um fator influente na tomada desta decisão.

## Como a Vue se compara aos Componentes da Web? {#how-does-vue-compare-to-web-components}

A Vue foi criada antes dos Componentes da Web estivessem disponíveis de maneira nativa, e alguns aspetos do desenho da Vue (por exemplo, ranhuras) foram inspirados pelo modelo de Componentes da Web.

As especificações dos Componentes da Web são relativamente de baixo nível, uma vez que estão centradas em torno da definição de elementos personalizados. Como abstração, a Vue aborda preocupações de alto nível adicionais tais como a eficiente interpretação do DOM, gestão de estado reativo, ferramental, roteamento do lado do cliente, e interpretação no lado do servidor.

A Vue também suporta completamente o consumo ou exportação para elementos personalizados nativos - consulte o [Guia da Vue e os Componentes da Web](/guide/extras/web-components) por mais detalhes.

<!-- ## TODO How does Vue compare to React? -->

<!-- ## TODO How does Vue compare to Angular? -->

---

---
url: /guide/extras/composition-api-faq.md
---

# Questões Frequentes sobre API de Composição {#composition-api-faq}

:::tip DICA
Esta seção de questões frequentes presume experiência prévia com a Vue - em particular, experiência com a Vue 2 ainda que primariamente usando a API de Opções.
:::

## O Que é a API de Composição? {#what-is-composition-api}

<VueSchoolLink href="https://vueschool.io/lessons/introduction-to-the-vue-js-3-composition-api" title="Aula Gratuita Sobre a API de Composição"/>

A API de Composição é um conjunto de APIs que permitem-nos escrever componentes de Vue usando funções importadas ao invés de declarar opções. É um termo abrangente que cobre as seguintes APIs:

- [API de Reatividade](/api/reactivity-core), por exemplo, `ref()` e `reactive()`, que permite-nos criar diretamente estado reativo, estado computado, e observadores.

- [Gatilhos do Ciclo de Vida](/api/composition-api-lifecycle), por exemplo, `onMounted()` e `onUnmounted()`, que permitem-nos ligar programaticamente no ciclo de vida do componente.

- [Injeção de Dependência](/api/composition-api-dependency-injection), por exemplo, `provide()` e `inject()`, que permitem-nos influenciar o sistema de injeção de dependência da Vue ainda que usando as APIs de Reatividade.

A API de Composição é uma funcionalidade embutida da Vue 3 e [Vue 2.7](https://blog.vuejs.org/posts/vue-2-7-naruto.html). Para versões mais antigas da Vue 2, use a extensão [`@vue/composition-api`](https://github.com/vuejs/composition-api) mantida oficialmente. Na Vue 3, é também primariamente usada juntamente com a sintaxe de [`<script setup>`](/api/sfc-script-setup) nos Componentes de Ficheiro Único. Cá está um exemplo básico de um componente usando a API de Composição:

```vue
<script setup>
import { ref, onMounted } from 'vue'

// estado reativo
const count = ref(0)

// funções que alteram o estado e acionam atualizações
function increment() {
  count.value++
}

// gatilhos do ciclo de vida
onMounted(() => {
  console.log(`The initial count is ${count.value}.`)
})
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

Apesar de um estilo de API baseado na composição de função, **API de Composição NÃO é programação funcional**. A API de Composição é baseada no mutável paradigma de reatividade finamente ajustado da Vue, ao passo que a programação funcional enfatiza a imutabilidade.

Se estiveres interessado em aprender como usar a Vue com a API de Composição, podes definir a preferência de API da documentação toda para API de Composição usando interruptor no cimo da barra lateral esquerda, e depois rever o guia desde o início.

## Porquê API de Composição {#why-composition-api}

### Melhor Reutilização da Lógica {#better-logic-reuse}

A primeira vantagem da API de Composição é que possibilita clara, eficiente reutilização da lógica na forma de [funções de Composição](/guide/reusability/composables). Isto soluciona [todas as desvantagens das misturas](/guide/reusability/composables#vs-mixins), o mecanismo primário de reutilização de lógica para API de Opções.

A capacidade de reutilização de lógica da API de Composição tem dado origem a impressionantes projetos de comunidade tais como [VueUse](https://vueuse.org/), uma coleção em constante crescimento de utilitários de funções de composição. Ela também serve como um mecanismo claro para integrar facilmente serviços ou bibliotecas de terceiros com estado no sistema de reatividade da Vue, por exemplo [dados imutáveis](/guide/extras/reactivity-in-depth#immutable-data), [máquinas de estado](/guide/extras/reactivity-in-depth#state-machines), e [RxJS](/guide/extras/reactivity-in-depth#rxjs).

### Organização de Código Mais Flexível {#more-flexible-code-organization}

Muitos utilizadores amam que escrevamos código organizados por padrão com API de Opções: tudo tem o seu lugar baseado na opção em que se insere. No entanto, a API de Opções coloca sérias limitações quando a lógica de um único componente cresce além de um certo limiar de complexidade. Esta limitação é particularmente proeminente nos componentes que precisam de lidar com vários **interesses lógicos**, o que temos testemunhado em primeira mão em muitas aplicações de Vue 2 de produção.

Tome o componente explorador de pasta da interface de utilizador gráfico da interface da linha de comando da Vue como um exemplo: este componente é responsável pelos seguintes interesses lógicos:

- Rastrear o estado da pasta atual e exibir o seu conteúdo
- Lidar com a navegação da pasta (abrir, fechar, atualizar...)
- Lidar com a criação de uma nova pasta
- Alternar para mostrar apenas as pastas favoritas
- Alternar para mostrar as pastas ocultas
- Lidar com as mudanças do diretório de trabalho atual

A [versão original](https://github.com/vuejs/vue-cli/blob/a09407dd5b9f18ace7501ddb603b95e31d6d93c0/packages/@vue/cli-ui/src/components/folder/FolderExplorer.vue#L198-L404) do componente foi escrita na API de Opções. Se dermos para cada linha de código uma cor baseada no interesse lógico com qual lida, isto é como se pareceria:

<img alt="componente de pasta antes" src="./images/options-api.png" width="129" height="500" style="margin: 1.2em auto">

Repara como o código lidando com o mesmo interesse lógico é forçado a ser separado sob diferentes opções, localizado em diferentes partes do ficheiro. Num componente com várias centenas de linhas, entender e navegar um único interesse lógico exige deslocar-se constantemente para cima e para baixo no ficheiro, tornando-o muito mais difícil do que deveria ser. Além disto, se alguma vez tencionamos extrair um interesse lógico para um utilitário reutilizável, daria um pouco mais de trabalho encontrar e extrair os pedaços de código corretos de diferentes partes do ficheiro.

Cá está o mesmo componente, antes e depois de ser [refeito com a API de Composição](https://gist.github.com/yyx990803/8854f8f6a97631576c14b63c8acd8f2e):

![componente de pasta depois](./images/composition-api-after.png)

Repara como o código relacionado ao mesmo interesse lógico pode agora ser agrupado junto: não precisamos mais de saltar entre blocos de opções diferentes enquanto trabalhamos num interesse lógico específico. Ainda por cima, agora podemos mover um grupo de código para um ficheiro externo com mínimo esforço, já que não precisamos mais de remexer o código à volta para extraí-los. Esta fricção reduzida para refazer é chave para sustentabilidade de longo prazo em bases de código grandes.

### Melhor Inferência de Tipo {#better-type-inference}

Nos anos recentes, mais e mais programadores de frontend estão a adotar a [TypeScript](https://www.typescriptlang.org/) visto que ajuda-nos a escrever código mais robusto, fazer mudanças com mais confiança, e fornece uma excelente experiência de desenvolvimento com suporte de IDE. No entanto, a API de Opções, concebida originalmente em 2013, foi desenhada sem inferência de tipo em mente. Nós tínhamos que implementar alguma [ginástica de tipo absurdamente complexa](https://github.com/vuejs/core/blob/44b95276f5c086e1d88fa3c686a5f39eb5bb7821/packages/runtime-core/src/componentPublicInstance.ts#L132-L165) para fazer inferência de tipo funcionar com a API de Opções. Mesmo com todo este esforço, a inferência de tipo para API de Opções pode continuar a avariar para injeção de misturas e dependência.

Isto tinha conduzido muitos programadores que queriam usar a Vue com a TypeScript a inclinarem-se para API de Classe alimentada pela `vue-class-component`. No entanto, uma API baseada em Classe depende profundamente de decoradores de ECMAScript, uma funcionalidade de linguagem que era apenas uma proposta de estágio 2 quando a Vue 3 começou a ser desenvolvida em 2019. Nós sentimos que era muito arriscado basear uma API oficial numa proposta instável. Desde então, o proposta de decoradores passou por uma outra revisão completa, e finalmente chegou aos estágio 3 em 2022. Além disto, API baseada em classe sofre de limitações de reutilização de lógica e organização parecidos com os da API de Opções.

Em comparação, a API de Composição utiliza na maior parte das vezes variáveis e funções simples, que são naturalmente amigáveis a tipo. O código escrita na API de Composição pode desfrutar da inferência de tipo completa com pouca necessidade para sugestões de tipo manual. A maior parte das vezes, o código da API de Composição parecerão em grade parte idênticas na TypeScript e JavaScript simples. Isto também torna possível para utilizadores de JavaScript simples beneficiarem-se da inferência de tipo parcial.

### Pacote de Produção Mais Pequeno e Menos Despesas Gerais {#smaller-production-bundle-and-less-overhead}

O código escrito na API de Composição e `<script setup>` é também mais eficiente e amigável a minificação do que o equivalente da API de Opções. Isto porque o modelo de marcação num componente de `<script setup>` é compilado como uma função embutida no mesmo âmbito do código de `<script setup>`. Ao contrário do acesso de propriedade de `this`, o código do modelo de marcação compilado pode acessar diretamente as variáveis declaradas dentro de `<script setup>`, sem uma delegação de instância no meio. Isto também conduz para melhor minificação porque todas os nomes de variável podem ser abreviados com segurança.

## Relação com a API de Opções {#relationship-with-options-api}

### Compromissos {#trade-offs}

Alguns utilizadores saindo da API de Opções acharam o seu código de API de Composição menos organizado, e concluíram que a API de Composição é "pior" em termos de organização de código. Nós recomendamos que os utilizadores com tais opiniões a olhar naquele problema a partir duma perspetiva diferente.

É verdade que a API de Composição não mais fornece as "barreiras de proteção" que orientam-te a colocar o teu código nos seus respetivos baldes. Em troca, começas a escrever o código do componente como escreverias JavaScript normal. Isto significa que **podes e deves aplicar quaisquer boas práticas de organização de código ao código da tua API de Composição como farias quando escreves JavaScript normal**. Se podes escrever código de JavaScript bem-organizado, deves também ser capaz de escrever código de API de Composição bem-organizado.

A API de Opções permite-te "pensar menos" quando escreves o código do componente, daí o porquê muitos utilizadores amá-la. No entanto, na redução de custos mental, também fecha-te num padrão de organização de código pré-escrito sem escotilha de fuga, o que tornar difícil refatorar ou melhorar a qualidade do código em projetos de grande porte. Nesta consideração, a API de Composição fornece melhor escalabilidade a longo prazo.

### A API de Composição sobre todos casos de uso? {#does-composition-api-cover-all-use-cases}

Sim em termos de lógica com estado. Quando usas a API de Composição, existem apenas algumas opções que podem ainda ser necessárias: `props`, `emits`, `name`, e `inheritAttrs`. Se usas `<script setup>`, então `inheritAttrs` é normalmente a única opção que pode exigir um bloco normal de `<script>` separado.

Se tencionas usar a exclusivamente a API de Composição (juntamente com as opções listadas acima), podes rapar alguns kbs do teu pacote de produção através duma [opção de tempo de compilação](https://github.com/vuejs/core/tree/main/packages/vue#bundler-build-feature-flags) que reduz o código relacionado a API de Opções da Vue. Nota que isto também afeta os componentes de Vue nas tuas dependências.

### Posso usar ambas APIs juntas? {#can-i-use-both-apis-together}

Sim. Tu podes usar a API de Composição através da opção [`setup()`](/api/composition-api-setup) num componente de API dde Opções.

No entanto, apenas recomendados fazer isto se tiveres uma base de código de API de Opções existente que precisa integrar com funcionalidades novas ou bibliotecas externas escritas com a API de Composição.

### A API de Opções será depreciada? {#will-options-api-be-deprecated}

Não, não temos qualquer plano de o fazer. A API de Opções é uma parte integral da Vue e a razão de muitos programadores a amar. Nós também apercebemos-nos de que muitos dos benefícios da API de Composição apenas manifestam-se em projetos de grande porte, e a API de Opções continua a ser uma escolha sólida para muitos cenários baixa ou média complexidade.

## Relação com a API de Classe {#relationship-with-class-api}

Nós não recomendamos mais usar a API de Classe com a Vue 3, dado que a API de Composição fornece uma excelente integração de TypeScript com benefícios de reutilização de lógica e organização de código adicionais.

## Comparação com os Gatilhos de React {#comparison-with-react-hooks}

A API de Composição fornece o mesmo nível de capacidades de composição lógica que os Gatilhos de React, mas com algumas diferenças importantes.

Os Gatilhos de React são invocados repetidamente toda vez que um componente for atualizado. Isto cria um número de advertências que podem confundir até mesmo programadores de React experientes. Também conduz a problemas de otimização do desempenho que podem severamente afetar a experiência de programação. Cá estão alguns exemplos:

- Os gatilhos são sensíveis a ordem de chamada e não podem ser condicionais.

- As variáveis declaradas num componente de React pode ser capturada por um encerramento de gatilho e tornar-se "ultrapassada" se o programador falhar em passar o arranjo de dependências correto. Isto leva os programadores de React a dependerem de regras de ESLint para garantir que as dependências corretas são passadas. No entanto, a regra não é muitas vezes inteligente o suficiente e sobrecompensa por exatidão, o que conduz a invalidação desnecessária e dores de cabeça quando casos extremos são encontrados.

- Cálculos dispendiosos exigem o uso de `useMemo`, o que novamente exige passar manualmente o arranjo de dependência correto.

- Os manipuladores de evento passados para os componentes filho causam atualizações filho desnecessárias por padrão, e exigem `useCallback` explícito como uma otimização. Isto é quase sempre necessário, e novamente exige um arranjo de dependências correto. Negligenciar isto conduz ao desenho excessivo de aplicações por padrão por padrão e pode causar problemas de desempenho sem aperceber-se disto.

- O problema de encerramento ultrapassado, combinado com funcionalidades simultâneas, torna difícil racionalizar sobre quando um pedaço de código do gatilho é executado, e torna o trabalho com estado mutável que deveria persistir através das interpretações (através de `useRef`) desconfortável.

Em comparação, a API de Composição da Vue:

- Invoca o código do `setup()` ou `<script setup>` apenas uma vez. Isto faz o código alinhar-se melhor com as intuições de uso da JavaScript idiomática visto que não existem fechos ultrapassados para preocupar-se. As chamadas da API de Composição também não são sensíveis a ordem de chamada e podem ser condicionais.

- O sistema de reatividade do executor da Vue reuni as dependências reativas usadas nas propriedades computadas e observadores, assim não existe necessidade de manualmente declarar as dependências.

- Não precisa de manualmente fazer o armazenamento de consulta imediata de funções de resposta para evitar atualizações filho desnecessárias. Em geral, o sistema de reatividade finamente ajustado da Vue garante que os componentes filho apenas atualizem quando precisarem. As otimizações da atualização de filho são raramente uma preocupação para os programadores de Vue.

Nós reconhecemos a criatividade dos Gatilhos de React, e é uma das principais fonte de inspiração para a API de Composição. No entanto, os problemas mencionados acima existem no desenho e notamos que o modelo de reatividade da Vue acontece para fornecer um caminho à volta deles.

---

---
url: /guide/components/slots.md
---
# Ranhuras {#slots}

> Neste material assume-se conhecimento dos [Fundamentos dos Componentes](/guide/essentials/component-basics). Precisamos entender o básico de componentes para acompanhar este material.

<VueSchoolLink href="https://vueschool.io/lessons/vue-3-component-slots" title="Aula Gratuita Sobre Ranhuras de Vue.js"/>

## Conteúdo da Ranhura e a Saída de Ranhura {#slot-content-and-outlet}

Nós temos aprendido que os componentes podem aceitar propriedades, as quais podem ser valores de JavaScript de qualquer tipo. Mas quanto ao conteúdo do modelo de marcação? Em alguns casos, podemos desejar passar um fragmento de modelo de marcação para um componente filho, e permitir que o componente filho interprete o fragmento dentro do seu próprio modelo de marcação.

Por exemplo, podemos ter um componente `<FancyButton>` que suporta este tratamento:

```vue-html{2}
<FancyButton>
  Click me! <!-- conteúdo da ranhura -->
</FancyButton>
```

O modelo de marcação do `<FancyButton>` se parece com isto:

```vue-html{2}
<button class="fancy-btn">
  <slot></slot> <!-- saída de ranhura -->
</button>
```

O elemento `<slot>` é uma **saída de ranhura** que indica onde o **conteúdo de ranhura** fornecido pelo componente deve ser interpretado.

![diagrama da ranhura](./images/slots.png)

<!-- https://www.figma.com/file/LjKTYVL97Ck6TEmBbstavX/slot -->

E o DOM interpretado final:

```html
<button class="fancy-btn">Click me!</button>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpdUdlqAyEU/ZVbQ0kLMdNsXabTQFvoV8yLcRkkjopLSQj596oTwqRvnuM9y9UT+rR2/hs5qlHjqZM2gOch2m2rZW+NC/BDND1+xRCMBuFMD9N5NeKyeNrqphrUSZdA4L1VJPCEAJrRdCEAvpWke+g5NHcYg1cmADU6cB0A4zzThmYckqimupqiGfpXILe/zdwNhaki3n+0SOR5vAu6ReU++efUajtqYGJQ/FIg5w8Wt9FlOx+OKh/nV1c4ZVNqlHE1TIQQ7xnvCN13zkTNalBSc+Jw5wiTac2H1WLDeDeDyXrJVm9LWG7uE3hev3AhHge1cYwnO200L4QljEnd1bCxB1g82UNhe+I6qQs5kuGcE30NrxeaRudzOWtkemeXuHP5tLIKOv8BN+mw3w==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpdUdlqAyEU/ZVbQ0kLMdNsXabTQFvoV8yLcRkkjopLSQj596oTwqRvnuM9y9UT+rR2/hs5qlHjqZM2gOch2m2rZW+NC/BDND1+xRCMBuFMD9N5NeKyeNrqphrUSZdA4L1VJPCEAJrRdCEAvpWke+g5NHcYg1cmADU6cB0A4zzThmYckqimupqiGfpXILe/zdwNhaki3n+0SOR5vAu6ReU++efUajtqYGJQ/FIg5w8Wt9FlOx+OKh/nV1c4ZVNqlHE1TIQQ7xnvCN13zkTNalBSc+Jw5wiTac2H1WLDeDeDyXrJVm9LWG7uE3hev3AhHge1cYwnO200L4QljEnd1bCxB1g82UNhe+I6qQs5kuGcE30NrxeaRudzOWtkemeXuHP5tLIKOv8BN+mw3w==)

</div>

Com as ranhuras, a `<FancyButton>` é responsável pela interpretação do `<button>` externo (e sua estilização fantástica), enquanto o conteúdo interno é fornecido pelo componente pai.

Um outro maneira de entender as ranhuras é comparando-os as funções de JavaScript:

```js
// componente pai passando o conteúdo de ranhura 
FancyButton('Click me!')

// "FancyButton" interpreta o conteúdo de ranhura no seu...
// próprio modelo de marcação
function FancyButton(slotContent) {
  return `<button class="fancy-btn">
      ${slotContent}
    </button>`
}
```

O conteúdo de ranhura não é apenas limitado ao texto. Ele pode ser qualquer conteúdo de modelo de marcação válido. Por exemplo, podemos passar vários elementos, ou mesmo outros componentes:

```vue-html
<FancyButton>
  <span style="color:red">Click me!</span>
  <AwesomeIcon name="plus" />
</FancyButton>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpdUdlqAyEU/ZVbQ0kLMdNsXabTQFvoV8yLcRkkjopLSQj596oTwqRvnuM9y9UT+rR2/hs5qlHjqZM2gOch2m2rZW+NC/BDND1+xRCMBuFMD9N5NeKyeNrqphrUSZdA4L1VJPCEAJrRdCEAvpWke+g5NHcYg1cmADU6cB0A4zzThmYckqimupqiGfpXILe/zdwNhaki3n+0SOR5vAu6ReU++efUajtqYGJQ/FIg5w8Wt9FlOx+OKh/nV1c4ZVNqlHE1TIQQ7xnvCN13zkTNalBSc+Jw5wiTac2H1WLDeDeDyXrJVm9LWG7uE3hev3AhHge1cYwnO200L4QljEnd1bCxB1g82UNhe+I6qQs5kuGcE30NrxeaRudzOWtkemeXuHP5tLIKOv8BN+mw3w==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpdUdlqAyEU/ZVbQ0kLMdNsXabTQFvoV8yLcRkkjopLSQj596oTwqRvnuM9y9UT+rR2/hs5qlHjqZM2gOch2m2rZW+NC/BDND1+xRCMBuFMD9N5NeKyeNrqphrUSZdA4L1VJPCEAJrRdCEAvpWke+g5NHcYg1cmADU6cB0A4zzThmYckqimupqiGfpXILe/zdwNhaki3n+0SOR5vAu6ReU++efUajtqYGJQ/FIg5w8Wt9FlOx+OKh/nV1c4ZVNqlHE1TIQQ7xnvCN13zkTNalBSc+Jw5wiTac2H1WLDeDeDyXrJVm9LWG7uE3hev3AhHge1cYwnO200L4QljEnd1bCxB1g82UNhe+I6qQs5kuGcE30NrxeaRudzOWtkemeXuHP5tLIKOv8BN+mw3w==)

</div>

Ao utilizar as ranhuras, o nosso `<FancyButton>` é mais flexível e reutilizável. Nós podemos agora utilizá-lo em diferentes lugares com conteúdo interno diferente, mas todos com a mesma estilização fantástica.

O mecanismo de ranhura dos componentes de Vue são inspirados pelo [elemento `<slot>` de Componente de Web nativo](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot), mas com capacidades adicionais que veremos mais tarde.

## Escopo de Interpretação {#render-scope}

O conteúdo de ranhura tem acesso ao escopo de dados do componente pai, porque é definido no componente pai. Por exemplo:

```vue-html
<span>{{ message }}</span>
<FancyButton>{{ message }}</FancyButton>
```

Aqui ambos interpolações de <span v-pre>`{{ message }}`</span> interpretarão o mesmo conteúdo.

O conteúdo de ranhura **não** tem acesso aos dados do componente filho. As expressões nos modelos de marcação de Vue podem apenas acessar o escopo em que são definidas, consistente com a possibilidade léxica da JavaScript. Em outras palavras:

> As expressões no modelo de marcação do componente pai apenas têm acesso ao escopo do componente pai; as expressões no modelo de marcação do componente filho apenas têm acesso ao escopo do componente filho.

## Conteúdo Retrocessivo {#fallback-content}

Existem casos onde é útil especificar conteúdo retrocessivo (por exemplo, padrão) para uma ranhura, para ser interpretado apenas quando nenhum conteúdo for fornecido. Por exemplo, em um componente `<SubmitButton>`:

```vue-html
<button type="submit">
  <slot></slot>
</button>
```

Nós podemos desejar que o texto "Submit" seja interpretado dentro do `<button>` se o componente pai não forneceu qualquer conteúdo de ranhura. Para tornar o "Submit" o conteúdo retrocessivo, podemos colocá-lo entre os marcadores `<slot>`:

```vue-html{3}
<button type="submit">
  <slot>
    Submit <!-- conteúdo retrocessivo -->
  </slot>
</button>
```

Agora quando utilizarmos `<SubmitButton>` em componente pai, sem nenhum conteúdo sendo fornecido para a ranhura:

```vue-html
<SubmitButton />
```

Isto interpretará o conteúdo retrocessivo, "Submit":

```html
<button type="submit">Submit</button>
```

Mas se fornecermos o conteúdo:

```vue-html
<SubmitButton>Save</SubmitButton>
```

Então o conteúdo fornecido será interpretado no lugar:

```html
<button type="submit">Save</button>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1kMsKwjAQRX9lzMaNbfcSC/oL3WbT1ikU8yKZFEX8d5MGgi2YVeZxZ86dN7taWy8B2ZlxP7rZEnikYFuhZ2WNI+jCoGa6BSKjYXJGwbFufpNJfhSaN1kflTEgVFb2hDEC4IeqguARpl7KoR8fQPgkqKpc3Wxo1lxRWWeW+Y4wBk9x9V9d2/UL8g1XbOJN4WAntodOnrecQ2agl8WLYH7tFyw5olj10iR3EJ+gPCxDFluj0YS6EAqKR8mi9M3Td1ifLxWShcU=)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1kMsKwjAQRX9lzMaNbfcSC/oL3WbT1ikU8yKZFEX8d5MGgi2YVeZxZ86dN7taWy8B2ZlxP7rZEnikYFuhZ2WNI+jCoGa6BSKjYXJGwbFufpNJfhSaN1kflTEgVFb2hDEC4IeqguARpl7KoR8fQPgkqKpc3Wxo1lxRWWeW+Y4wBk9x9V9d2/UL8g1XbOJN4WAntodOnrecQ2agl8WLYH7tFyw5olj10iR3EJ+gPCxDFluj0YS6EAqKR8mi9M3Td1ifLxWShcU=)

</div>

## Ranhuras Nomeadas {#named-slots}

Existem momentos quando é útil ter várias saídas de ranhura em um único componente. Por exemplo, em um componente `<BaseLayout>` com o seguinte modelo de marcação:

```vue-html
<div class="container">
  <header>
    <!-- Nós queremos o conteúdo de cabelo aqui -->
  </header>
  <main>
    <!-- Nós queremos o conteúdo principal aqui -->
  </main>
  <footer>
    <!-- Nós queremos o conteúdo de rodapé aqui -->
  </footer>
</div>
```

Para estes casos, o elemento `<slot>` tem um atributo especial, `name`, o qual pode ser utilizado para atribuir um identificador único para ranhuras diferentes assim podes determinar onde o conteúdo dever ser interpretado:

```vue-html
<div class="container">
  <header>
    <slot name="header"></slot>
  </header>
  <main>
    <slot></slot>
  </main>
  <footer>
    <slot name="footer"></slot>
  </footer>
</div>
```

Uma saída de `<slot>` sem `name` implicitamente tem o nome de "default".

Em um componente pai utilizando `<BaseLayout>`, precisamos de uma maneira de passar vários fragmentos de conteúdo de ranhura, cada mirando uma saída de ranhura diferente. Isto é onde **ranhuras nomeadas** entram.

Para passar uma ranhura nomeada, precisamos utilizar um elemento `<template>` com a diretiva `v-slot`, e depois passar o nome da ranhura como um argumento para `v-slot`:

```vue-html
<BaseLayout>
  <template v-slot:header>
    <!-- conteúdo para a ranhura de cabeçalho -->
  </template>
</BaseLayout>
```

A `v-slot` tem um abreviação dedicada `#`, assim  `<template v-slot:header>` pode ser abreviada para apenas `<template #header>`. Pense disto como "interpretar este fragmento de modelo de marcação na ranhura 'header' do componente filho".

![diagrama de ranhuras nomeada](./images/named-slots.png)

<!-- https://www.figma.com/file/2BhP8gVZevttBu9oUmUUyz/named-slot -->

Aqui está o código passando conteúdo para todas as três ranhuras para `<BaseLayout>` utilizando a sintaxe abreviada:

```vue-html
<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <template #default>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </template>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>
```

Quando um componente aceita ambos uma ranhura padrão e ranhuras nomeadas, todos os nós de alto nível que não são `<template>` são implicitamente tratados como conteúdo para a ranhura padrão. Assim o exemplo acima também pode ser escrito como:

```vue-html
<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <!-- ranhura padrão implícita -->
  <p>A paragraph for the main content.</p>
  <p>And another one.</p>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>
```

Agora tudo dentro dos elementos `<template>` será passado às ranhuras correspondente. O resultado de HTML interpretado será: 

```html
<div class="container">
  <header>
    <h1>Here might be a page title</h1>
  </header>
  <main>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </main>
  <footer>
    <p>Here's some contact info</p>
  </footer>
</div>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9UsFuwjAM/RWrHLgMOi5o6jIkdtphn9BLSF0aKU2ixEVjiH+fm8JoQdvRfu/5xS8+ZVvvl4cOsyITUQXtCSJS5zel1a13geBdRvyUR9cR1MG1MF/mt1YvnZdW5IOWVVwQtt5IQq4AxI2cau5ccZg1KCsMlz4jzWrzgQGh1fuGYIcgwcs9AmkyKHKGLyPykcfD1Apr2ZmrHUN+s+U5Qe6D9A3ULgA1bCK1BeUsoaWlyPuVb3xbgbSOaQGcxRH8v3XtHI0X8mmfeYToWkxmUhFoW7s/JvblJLERmj1l0+T7T5tqK30AZWSMb2WW3LTFUGZXp/u8o3EEVrbI9AFjLn8mt38fN9GIPrSp/p4/Yoj7OMZ+A/boN9KInPeZZpAOLNLRDAsPZDgN4p0L/NQFOV/Ayn9x6EZXMFNKvQ4E5YwLBczW6/WlU3NIi6i/sYDn5Qu2qX1OF51MsvMPkrIEHg==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9UkFuwjAQ/MoqHLiUpFxQlaZI9NRDn5CLSTbEkmNb9oKgiL934wRwQK3ky87O7njGPicba9PDHpM8KXzlpKV1qWVnjSP4FB6/xcnsCRpnOpin2R3qh+alBig1HgO9xkbsFcG5RyvDOzRq8vkAQLSury+l5lNkN1EuCDurBCFXAMWdH2pGrn2YtShqdCPOnXa5/kKH0MldS7BFEGDFDoEkKSwybo8rskjjaevo4L7Wrje8x4mdE7aFxjiglkWE1GxQE9tLi8xO+LoGoQ3THLD/qP2/dGMMxYZs8DP34E2HQUxUBFI35o+NfTlJLOomL8n04frXns7W8gCVEt5/lElQkxpdmVyVHvP2yhBo0SHThx5z+TEZvl1uMlP0oU3nH/kRo3iMI9Ybes960UyRsZ9pBuGDeTqpwfBAvn7NrXF81QUZm8PSHjl0JWuYVVX1PhAqo4zLYbZarUak4ZAWXv5gDq/pG3YBHn50EEkuv5irGBk=)

</div>

Além disso, isto pode ajudar-te a entender as ranhuras nomeadas melhor utilizando a analogia de função de JavaScript:

```js
// passando vários fragmentos de ranhura com diferentes nomes
BaseLayout({
  header: `...`,
  default: `...`,
  footer: `...`
})

// "<BaseLayout>" interpreta-os em diferentes lugares
function BaseLayout(slots) {
  return `<div class="container">
      <header>${slots.header}</header>
      <main>${slots.default}</main>
      <footer>${slots.footer}</footer>
    </div>`
}
```

## Nomes de Ranhura Dinâmicos {#dynamic-slot-names}

Os [argumentos de diretiva dinâmicos](/guide/essentials/template-syntax#argumentos-dinâmicos) também funcionam sobre a `v-slot`, permitindo a definição de nomes de ranhura dinâmicos:

```vue-html
<base-layout>
  <template v-slot:[dynamicSlotName]>
    ...
  </template>

  <!-- com a forma abreviada -->
  <template #[dynamicSlotName]>
    ...
  </template>
</base-layout>
```

Toma nota que a expressão está sujeita às [restrições de sintaxe](/guide/essentials/template-syntax#diretivas) dos argumentos de diretiva dinâmicos.

## Ranhuras Isoladas {#scoped-slots}

Conforme discutido no [Escopo de Interpretação](#escope-de-interpretação), o conteúdo de ranhura não tem acesso ao estado no componente filho.

No entanto, existem casos onde poderia ser útil se um conteúdo da ranhura poder fazer uso dos dados de ambos escopo do componente pai e escopo do componente filho. Para alcançar isto, precisamos de uma maneira para o componente filho passar dados para uma ranhura quando estiver interpretando-o.

De fato, podemos fazer exatamente isto - nós podemos passar atributos para uma ranhura de saída da mesma maneira que passamos propriedades para um componente.

```vue-html
<!-- modelo de marcação do <MyComponent> -->
<div>
  <slot :text="greetingMessage" :count="1"></slot>
</div>
```

O recebimento das propriedades de ranhura é um pouco diferente de quando estamos utilizando uma única ranhura padrão versus a utilização de ranhuras nomeadas. Nós mostraremos como receber as propriedades utilizando uma única ranhura padrão primeiro, utilizando `v-slot` diretamente no marcador do componente filho:

```vue-html
<MyComponent v-slot="slotProps">
  {{ slotProps.text }} {{ slotProps.count }}
</MyComponent>
```

![diagrama de ranhuras isoladas](./images/scoped-slots.svg)

<!-- https://www.figma.com/file/QRneoj8eIdL1kw3WQaaEyc/scoped-slot -->

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp9kMEKgzAMhl8l9OJlU3aVOhg7C3uAXsRlTtC2tFE2pO++dA5xMnZqk+b/8/2dxMnadBxQ5EL62rWWwCMN9qh021vjCMrn2fBNoya4OdNDkmarXhQnSstsVrOOC8LedhVhrEiuHca97wwVSsTj4oz1SvAUgKJpgqWZEj4IQoCvZm0Gtgghzss1BDvIbFkqdmID+CNdbbQnaBwitbop0fuqQSgguWPXmX+JePe1HT/QMtJBHnE51MZOCcjfzPx04JxsydPzp2Szxxo7vABY1I/p)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkNFqxCAQRX9l8CUttAl9DbZQ+rzQD/AlJLNpwKjoJGwJ/nvHpAnusrAg6FzHO567iE/nynlCUQsZWj84+lBmGJ31BKffL8sng4bg7O0IRVllWnpWKAOgDF7WBx2em0kTLElt975QbwLkhkmIyvCS1TGXC8LR6YYwVSTzH8yvQVt6VyJt3966oAR38XhaFjjEkvBCECNcia2d2CLyOACZQ7CDrI6h4kXcAF7lcg+za6h5et4JPdLkzV4B9B6RBtOfMISmxxqKH9TarrGtATxMgf/bDfM/qExEUCdEDuLGXAmoV06+euNs2JK7tyCrzSNHjX9aurQf)

</div>

As propriedades passadas para a ranhura pelo componente filho estão disponíveis como valor da diretiva `v-slot` correspondente, a qual pode ser acessada pelas expressões dentro da ranhura.

Tu podes pensar em uma ranhura isolada como uma função sendo passada para o componente filho. O componente filho então chama-a, passando propriedades como argumentos:

```js
MyComponent({
  // passando a ranhura padrão, mas como uma função
  default: (slotProps) => {
    return `${slotProps.text} ${slotProps.count}`
  }
})

function MyComponent(slots) {
  const greetingMessage = 'hello'
  return `<div>${
    // chamar a função da ranhura com as propriedades!
    slots.default({ text: greetingMessage, count: 1 })
  }</div>`
}
```

De fato, isto está muito próximo de como as ranhuras isoladas são compiladas, e de como usaríamos as ranhuras isoladas no manual de [funções de interpretação](/guide/extras/render-function).

Repare que as `v-slot="slotProps"` correspondem a assinatura da função de ranhura. Tal como com os argumentos de função, podemos utilizar a desestruturação na `v-slot`:

```vue-html
<MyComponent v-slot="{ text, count }">
  {{ text }} {{ count }}
</MyComponent>
```

### Ranhuras Isoladas Nomeadas {#named-scoped-slots}

As ranhuras isoladas nomeadas funcionam de maneira semelhante - propriedades de ranhura são acessíveis como valor da diretiva `v-slot`: `v-slot:name="slotProps"`. Quando estiveres utilizando a forma abreviada, se parece com isto:

```vue-html
<MyComponent>
  <template #header="headerProps">
    {{ headerProps }}
  </template>

  <template #default="defaultProps">
    {{ defaultProps }}
  </template>

  <template #footer="footerProps">
    {{ footerProps }}
  </template>
</MyComponent>
```

Passando as propriedades para uma ranhura nomeada:

```vue-html
<slot name="header" message="hello"></slot>
```

Nota que o `name` de uma ranhura não será incluído nas propriedades porque está reservado - então o `headerProps` resultante seria `{ message: 'hello' }`.

Se estiveres misturando as ranhuras nomeadas com a ranhura isolada padrão, precisas utilizar um marcador `<template>` explícito para a ranhura padrão. A tentativa de colocar a diretiva `v-slot` diretamente sobre o componente resultará em um erro de compilação. Isto é para evitar qualquer ambiguidade a respeito do escopo das propriedades da ranhura padrão. Por exemplo:

```vue-html
<!-- Este modelo de marcação não compilará -->
<template>
  <MyComponent v-slot="{ message }">
    <p>{{ message }}</p>
    <template #footer>
      <!-- "message" pertence à ranhura padrão, e não está disponível aqui -->
      <p>{{ message }}</p>
    </template>
  </MyComponent>
</template>
```

A utilização de um marcador `<template>` explícito para a ranhura padrão ajuda a tornar claro de que a propriedade `message` não está disponível dentro de outra ranhura:

```vue-html
<template>
  <MyComponent>
    <!-- Utilize ranhura padrão explícita -->
    <template #default="{ message }">
      <p>{{ message }}</p>
    </template>

    <template #footer>
      <p>Here's some contact info</p>
    </template>
  </MyComponent>
</template>
```

### Exemplo de Lista Fantástica {#fancy-list-example}

Tu podes estar perguntando a si mesmo o que seria um bom caso de uso para ranhuras isoladas. Aqui está um exemplo: imagine um componente `<FancyList>` que interpreta uma lista de itens - ele pode resumir a lógica para o carregamento de dados remoto, utilizando os dados para exibir uma lista, ou mesmo funcionalidades avançadas como paginação ou rolamento infinito. No entanto, queremos ser flexíveis a respeito da aparência de cada item e deixar a estilização de cada item para componente pai que está consumindo-o. Assim a utilização desejada se parece com isto:

```vue-html
<FancyList :api-url="url" :per-page="10">
  <template #item="{ body, username, likes }">
    <div class="item">
      <p>{{ body }}</p>
      <p>by {{ username }} | {{ likes }} likes</p>
    </div>
  </template>
</FancyList>
```

Dentro do `<FancyList>`, podemos interpretar o mesmo `<slot>` várias vezes com diferentes dados de item (repara que estamos utilizando a `v-bind` para passar um objeto como propriedades de ranhura):

```vue-html
<ul>
  <li v-for="item in items">
    <slot name="item" v-bind="item"></slot>
  </li>
</ul>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFU2Fv0zAQ/StHJtROapNuZTBCNwnQQKBpTGxCQss+uMml8+bYlu2UlZL/zjlp0lQa40sU3/nd3Xv3vA7eax0uSwziYGZTw7UDi67Up4nkhVbGwScm09U5tw5yowoYhFEX8cBBImdRgyQMHRwWWjCHdAKYbdFM83FpxEkS0DcJINZoxpotkCIHkySo7xOixcMep19KrmGustUISotGsgJHIPgDWqg6DKEyvoRUMGsJ4HG9HGX16bqpAlU1izy5baqDFegYweYroMttMwLAHx/Y9Kyan36RWUTN2+mjXfpbrei8k6SjdSuBYFOlMaNI6AeAtcflSrqx5b8xhkl4jMU7H0yVUCaGvVeH8+PjKYWqWnpf5DQYBTtb+fc612Awh2qzzGaBiUyVpBVpo7SFE8gw5xIv/Wl4M9gsbjCCQbuywe3+FuXl9iiqO7xpElEEhUofKFQo2mTGiFiOLr3jcpFImuiaF6hKNxzuw8lpw7kuEy6ZKJGK3TR6NluLYXBVqwRXQjkLn0ueIc3TLonyZ0sm4acqKVovKIbDCVQjGsb1qvyg2telU4Yzz6eHv6ARBWdwjVqUNCbbFjqgQn6aW1J8RKfJhDg+5/lStG4QHJZjnpO5XjT0BMqFu+uZ81yxjEQJw7A1kOA76FyZjaWBy0akvu8tCQKeQ+d7wsy5zLpz1FlzU3kW1QP+x40ApWgWAySEJTv6/NitNMkllcTakwCaZZ5ADEf6cROas/RhYVQps5igEpkZLwzRROmG04OjDBcj7+Js+vYQDo9e0uH1qzeY5/s1vtaaqG969+vTTrsmBTMLLv12nuy7l+d5W673SBzxkzlfhPdWSXokdZMkSFWhuUDzTTtOnk6CuG2fBEwI9etrHXOmRLJUE0/vMH14In5vH30sCS4Nkr+WmARdztHQ6Jr02dUFPtJ/lyxUVgq6/UzyO1olSj9jc+0DcaWxe/fqab/UT51Uu7Znjw6lbUn5QWtR6vtJQM//4zPUt+NOw+lGzCqo/gLm1QS8)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFU11r20AQ/CtbhWIHZMlxkjZVHUMf2r6EUkgolCgPZ2mlHDndHXcnU9fVf++evixDP16Md9cztzszPgQftI52NQZJsLaZ4dqBRVfrTSp5pZVx8InJbH/HrYPCqApmUTx2PHCWynXcIQlDhcNKC+aQKoD1EZ0wzRe1EbdpQJ9pAIlGs9CsROpcLNOgBRBkIIAzTl9peICtyvch1BaNZBWGIPgLWmhGDKFyvoNMMGsJ4HGTGU315tCxQNOsY3/dcTTCKnSMYNs90I+HxwgAv3yjf7PpvkxJ1jE9Pmwfn95/FIvqkyGV1u0Fgs2Uxpw6kV8ADh5XKOkWlv/EBJbRDVbvfTNTQpkEzq5W25ubS2o1rfaeZBOEwYktf/fzAAYLaHo3OwdTmSlJHmmjtIVbyLHgEr/6av44642bhTAbLJs9nR9RXm6PIt75YzeIY6hU9kKtSpGTOaPDCnTZM5dlKmmjB16hqt18fg63m+7mlibaMVEjkT12enauJTC7b1WCe6Gchc81z5H2GUyi+ccdk/Bd1dRtDUpgtYQmpGXchOUbcT/UThnO/D0T/BdaUXAGD6hFTWuyI9EFEfltnkjxkKrlkm78V+hrMaRBcNgteEHhetWdJ1CW7nkSzjvFchIliqIhQIKfoAtl+kgDl51I09xbEgT8DWPuCbPlMh/reIxmz7yO2wX/k0aAWnTGAAlhKY5+vnB7TXJJJbHNJIBmuT8ggWv9o29tWfZSGlXLPCGoRGYWpaEzUbr55cV1jmXoU5xfvlvB6vo1FW+u3mJRnLf4Vms6vX97yk+ejo9UzJRcenf++O5ZURQD3fgnaX4DS1Wb6Q==)

</div>

### Componentes Sem Interpretação {#renderless-components}

O caso de uso de `<FancyList>` que discutimos acima resume ambas a lógica reutilizável (requisição de dados, paginação etc) e a saída visual, enquanto está delegando parte da saída visual para o componente consumidor através das ranhuras isoladas.

Se empurrarmos este conceito um pouco adiante, podemos surgir com componentes que apenas resumem a lógica e não interpretam nada por si mesmos - a saída visual é completamente delegada ao componente consumidor com as ranhuras isoladas. Nós chamamos este tipo de componente um **Componentes Sem Interpretação**.

Um exemplo de componente sem interpretação poderia ser um que resume a lógica do rastreio da posição atual do rato:

```vue-html
<MouseTracker v-slot="{ x, y }">
  Mouse is at: {{ x }}, {{ y }}
</MouseTracker>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNUcFqhDAQ/ZUhF12w2rO4Cz301t5aaCEX0dki1SQko6uI/96J7i4qLPQQmHmZ9+Y9ZhQvxsRdiyIVmStsZQgcUmtOUlWN0ZbgXbcOP2xe/KKFs9UNBHGyBj09kCpLFj4zuSFsTJ0T+o6yjUb35GpNRylG6CMYYJKCpwAkzWNQOcgphZG/YZoiX/DQNAttFjMrS+6LRCT2rh6HGsHiOQKtmKIIS19+qmZpYLrmXIKxM1Vo5Yj9HD0vfD7ckGGF3LDWlOyHP/idYPQCfdzldTtjscl/8MuDww78lsqHVHdTYXjwCpdKlfoS52X52qGit8oRKrRhwHYdNrrDILouPbCNVZCtgJ1n/6Xx8JYAmT8epD3fr5cC0oGLQYpkd4zpD27R0vA=)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqVUU1rwzAM/SvCl7SQJTuHdLDDbttthw18MbW6hjW2seU0oeS/T0lounQfUDBGepaenvxO4tG5rIkoClGGra8cPUhT1c56ghcbA756tf1EDztva0iy/Ds4NCbSAEiD7diicafigeA0oFvLPAYNhWICYEE5IL00fMp8Hs0JYe0OinDIqFyIaO7CwdJGihO0KXTcLriK59NYBlUARTyMn6Hv0yHgIp7ARAvl3FXm8yCRiuu1Fv/x23JakVqtz3t5pOjNOQNoC7hPz0nHyRSzEr7Ghxppb/XlZ6JjRlzhTAlA+ypkLWwAM6c+8G2BdzP+/pPbRkOoL/KOldH2mCmtnxr247kKhAb9KuHKgLVtMEkn2knG+sIVzV9sfmy8hfB/swHKwV0oWja4lQKKjoNOivzKrf4L/JPqaQ==)

</div>

Embora um padrão interessante, a maioria do que pode ser alcançada com os Componentes Sem Interpretação pode ser alcançada de uma maneira mais eficiente com a API de Composição, sem ficar sujeito a despesas gerais do encaixamento de componente adicionais. Depois, veremos como podemos implementar a mesma funcionalidade de rastreio do rato com uma [Função de Composição](/guide/reusability/composables).

Com isto dito, ranhuras isoladas ainda são úteis nos casos onde precisamos de ambos resumir a lógica **e** compor a saída visual, tal como no exemplo de `<FancyList>`.

---

---
url: /guide/extras/reactivity-transform.md
---
# Reactivity Transform {#reactivity-transform}

:::danger Removed Experimental Feature
Reactivity Transform was an experimental feature, and has been removed in the latest 3.4 release. Please read about [the reasoning here](https://github.com/vuejs/rfcs/discussions/369#discussioncomment-5059028).

If you still intend to use it, it is now available via the [Vue Macros](https://vue-macros.sxzz.moe/features/reactivity-transform.html) plugin.
:::

:::tip Composition-API-specific
Reactivity Transform is a Composition-API-specific feature and requires a build step.
:::

## Refs vs. Reactive Variables {#refs-vs-reactive-variables}

Ever since the introduction of the Composition API, one of the primary unresolved questions is the use of refs vs. reactive objects. It's easy to lose reactivity when destructuring reactive objects, while it can be cumbersome to use `.value` everywhere when using refs. Also, `.value` is easy to miss if not using a type system.

[Vue Reactivity Transform](https://github.com/vuejs/core/tree/main/packages/reactivity-transform) is a compile-time transform that allows us to write code like this:

```vue
<script setup>
let count = $ref(0)

console.log(count)

function increment() {
  count++
}
</script>

<template>
  <button @click="increment">{{ count }}</button>
</template>
```

The `$ref()` method here is a **compile-time macro**: it is not an actual method that will be called at runtime. Instead, the Vue compiler uses it as a hint to treat the resulting `count` variable as a **reactive variable.**

Reactive variables can be accessed and re-assigned just like normal variables, but these operations are compiled into refs with `.value`. For example, the `<script>` part of the above component is compiled into:

```js{5,8}
import { ref } from 'vue'

let count = ref(0)

console.log(count.value)

function increment() {
  count.value++
}
```

Every reactivity API that returns refs will have a `$`-prefixed macro equivalent. These APIs include:

- [`ref`](/api/reactivity-core#ref) -> `$ref`
- [`computed`](/api/reactivity-core#computed) -> `$computed`
- [`shallowRef`](/api/reactivity-advanced#shallowref) -> `$shallowRef`
- [`customRef`](/api/reactivity-advanced#customref) -> `$customRef`
- [`toRef`](/api/reactivity-utilities#toref) -> `$toRef`

These macros are globally available and do not need to be imported when Reactivity Transform is enabled, but you can optionally import them from `vue/macros` if you want to be more explicit:

```js
import { $ref } from 'vue/macros'

let count = $ref(0)
```

## Destructuring with `$()` {#destructuring-with}

It is common for a composition function to return an object of refs, and use destructuring to retrieve these refs. For this purpose, reactivity transform provides the **`$()`** macro:

```js
import { useMouse } from '@vueuse/core'

const { x, y } = $(useMouse())

console.log(x, y)
```

Compiled output:

```js
import { toRef } from 'vue'
import { useMouse } from '@vueuse/core'

const __temp = useMouse(),
  x = toRef(__temp, 'x'),
  y = toRef(__temp, 'y')

console.log(x.value, y.value)
```

Note that if `x` is already a ref, `toRef(__temp, 'x')` will simply return it as-is and no additional ref will be created. If a destructured value is not a ref (e.g. a function), it will still work - the value will be wrapped in a ref so the rest of the code works as expected.

`$()` destructure works on both reactive objects **and** plain objects containing refs.

## Convert Existing Refs to Reactive Variables with `$()` {#convert-existing-refs-to-reactive-variables-with}

In some cases we may have wrapped functions that also return refs. However, the Vue compiler won't be able to know ahead of time that a function is going to return a ref. In such cases, the `$()` macro can also be used to convert any existing refs into reactive variables:

```js
function myCreateRef() {
  return ref(0)
}

let count = $(myCreateRef())
```

## Reactive Props Destructure {#reactive-props-destructure}

There are two pain points with the current `defineProps()` usage in `<script setup>`:

1. Similar to `.value`, you need to always access props as `props.x` in order to retain reactivity. This means you cannot destructure `defineProps` because the resulting destructured variables are not reactive and will not update.

2. When using the [type-only props declaration](/api/sfc-script-setup#type-only-props-emit-declarations), there is no easy way to declare default values for the props. We introduced the `withDefaults()` API for this exact purpose, but it's still clunky to use.

We can address these issues by applying a compile-time transform when `defineProps` is used with destructuring, similar to what we saw earlier with `$()`:

```html
<script setup lang="ts">
  interface Props {
    msg: string
    count?: number
    foo?: string
  }

  const {
    msg,
    // default value just works
    count = 1,
    // local aliasing also just works
    // here we are aliasing `props.foo` to `bar`
    foo: bar
  } = defineProps<Props>()

  watchEffect(() => {
    // will log whenever the props change
    console.log(msg, count, bar)
  })
</script>
```

The above will be compiled into the following runtime declaration equivalent:

```js
export default {
  props: {
    msg: { type: String, required: true },
    count: { type: Number, default: 1 },
    foo: String
  },
  setup(props) {
    watchEffect(() => {
      console.log(props.msg, props.count, props.foo)
    })
  }
}
```

## Retaining Reactivity Across Function Boundaries {#retaining-reactivity-across-function-boundaries}

While reactive variables relieve us from having to use `.value` everywhere, it creates an issue of "reactivity loss" when we pass reactive variables across function boundaries. This can happen in two cases:

### Passing into function as argument {#passing-into-function-as-argument}

Given a function that expects a ref as an argument, e.g.:

```ts
function trackChange(x: Ref<number>) {
  watch(x, (x) => {
    console.log('x changed!')
  })
}

let count = $ref(0)
trackChange(count) // doesn't work!
```

The above case will not work as expected because it compiles to:

```ts
let count = ref(0)
trackChange(count.value)
```

Here `count.value` is passed as a number, whereas `trackChange` expects an actual ref. This can be fixed by wrapping `count` with `$$()` before passing it:

```diff
let count = $ref(0)
- trackChange(count)
+ trackChange($$(count))
```

The above compiles to:

```js
import { ref } from 'vue'

let count = ref(0)
trackChange(count)
```

As we can see, `$$()` is a macro that serves as an **escape hint**: reactive variables inside `$$()` will not get `.value` appended.

### Returning inside function scope {#returning-inside-function-scope}

Reactivity can also be lost if reactive variables are used directly in a returned expression:

```ts
function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // listen to mousemove...

  // doesn't work!
  return {
    x,
    y
  }
}
```

The above return statement compiles to:

```ts
return {
  x: x.value,
  y: y.value
}
```

In order to retain reactivity, we should be returning the actual refs, not the current value at return time.

Again, we can use `$$()` to fix this. In this case, `$$()` can be used directly on the returned object - any reference to reactive variables inside the `$$()` call will retain the reference to their underlying refs:

```ts
function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // listen to mousemove...

  // fixed
  return $$({
    x,
    y
  })
}
```

### Using `$$()` on destructured props {#using-on-destructured-props}

`$$()` works on destructured props since they are reactive variables as well. The compiler will convert it with `toRef` for efficiency:

```ts
const { count } = defineProps<{ count: number }>()

passAsRef($$(count))
```

compiles to:

```js
setup(props) {
  const __props_count = toRef(props, 'count')
  passAsRef(__props_count)
}
```

## TypeScript Integration <sup class="vt-badge ts" /> {#typescript-integration}

Vue provides typings for these macros (available globally) and all types will work as expected. There are no incompatibilities with standard TypeScript semantics, so the syntax will work with all existing tooling.

This also means the macros can work in any files where valid JS / TS are allowed - not just inside Vue SFCs.

Since the macros are available globally, their types need to be explicitly referenced (e.g. in a `env.d.ts` file):

```ts
/// <reference types="vue/macros-global" />
```

When explicitly importing the macros from `vue/macros`, the type will work without declaring the globals.

## Explicit Opt-in {#explicit-opt-in}

:::danger No longer supported in core
The following only applies up to Vue version 3.3 and below. Support has been removed in Vue core 3.4 and above, and `@vitejs/plugin-vue` 5.0 and above. If you intend to continue using the transform, please migrate to [Vue Macros](https://vue-macros.sxzz.moe/features/reactivity-transform.html) instead.
:::

### Vite {#vite}

- Requires `@vitejs/plugin-vue@>=2.0.0`
- Applies to SFCs and js(x)/ts(x) files. A fast usage check is performed on files before applying the transform so there should be no performance cost for files not using the macros.
- Note `reactivityTransform` is now a plugin root-level option instead of nested as `script.refSugar`, since it affects not just SFCs.

```js
// vite.config.js
export default {
  plugins: [
    vue({
      reactivityTransform: true
    })
  ]
}
```

### `vue-cli` {#vue-cli}

- Currently only affects SFCs
- Requires `vue-loader@>=17.0.0`

```js
// vue.config.js
module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => {
        return {
          ...options,
          reactivityTransform: true
        }
      })
  }
}
```

### Plain `webpack` + `vue-loader` {#plain-webpack-vue-loader}

- Currently only affects SFCs
- Requires `vue-loader@>=17.0.0`

```js
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          reactivityTransform: true
        }
      }
    ]
  }
}
```

---

---
url: /guide/extras/reactivity-in-depth.md
---

<script setup>
import SpreadSheet from './demos/SpreadSheet.vue'
</script>

# Reatividade em Profundidade {#reactivity-in-depth}

Uma das funcionalidades mais distintas da Vue é o sistema de reatividade discreto. O estado do componente consiste de objetos de JavaScript reativos. Quando os modificas, a visão atualiza. Isto torna a gestão de estado simples e intuitiva, mas também é importante entender como isto funciona para evitar algumas surpresas nada agradáveis. Nesta seção, escavaremos alguns dos detalhes de baixo nível do sistema de reatividade da Vue.

## O Que é Reatividade? {#what-is-reactivity}

Este termo surge bastante na programação estes dias, mas o que as pessoas querem dizer quando dizem isto? Reatividade é um paradigma de programação que permite-nos ajustar às mudanças duma maneira declarativa. O exemplo canónico que as pessoas normalmente mostram, uma vez que é um excelente exemplo, é uma folha de cálculo de Excel:

<SpreadSheet />

Neste exemplo a célula A2 é definida através duma fórmula de `= A0 + A1` (podes clicar na A2 para inspecionar ou editar a fórmula), assim a folha de cálculo dá-nos 3. Nenhum surpresa lá. Mas se atualizares a `A0` ou `A1`, notarás que a `A2` também atualiza-se automaticamente.

A JavaScript normalmente não funciona desta maneira. Se fossemos escrever algo comparável em JavaScript:

```js
let A0 = 1
let A1 = 2
let A2 = A0 + A1

console.log(A2) // 3

A0 = 2
console.log(A2) // Continua 3
```

Quando mudamos `A0`, `A2` não muda automaticamente.

Então como faríamos isto em JavaScript? Primeiro, para re-executar o código que atualiza `A2`, vamos envolvê-lo numa função:

```js
let A2

function update() {
  A2 = A0 + A1
}
```

Depois, precisamos definir alguns termos:

- A função `update()` produz um **efeito colateral**, ou **efeito** para abreviar, porque modifica o estado do programa.

- `A0` e `A1` são considerados **dependências** do efeito, visto que os seus valores são usados para realizar o efeito. O efeito é dito ser um **subscritor** para as suas dependências.

O que precisamos é duma função mágica que pode invocar `update()` (o **efeito**) sempre `A0` ou `A1` (as **dependências**) mudarem:

```js
whenDepsChange(update)
```

Esta função `whenDepsChange()` tem as seguintes tarefas:

1. Rastrear quando uma variável é lida. Por exemplo, quando avalia a expressão `A0 + A1`, ambas `A0` e `A1` são lidas.

2. Se uma variável é lida quando existir um efeito atualmente em execução, fazer deste efeito um subscritor para esta variável. Por exemplo, porque `A0` e `A1` são lidas quando `update()` estiver sendo executada, `update()` torna-se uma subscritora para ambos `A0` e `A1` depois da primeira chamada.

3. Detetar quando uma variável é mudada. Por exemplo, quando `A0` for atribuída um novo valor, notifica todos os seus efeitos de subscritor para re-executar.

## Como a Reatividade Funciona na Vue? {#how-reactivity-works-in-vue}

Nós não podemos na realidade rastrear a leitura e escrita de variáveis locais como no exemplo. Só não existe nenhum mecanismo para fazer isto em JavaScript puro. Mesmo assim o que **podemos** fazer, é intercetar a leitura e escrita de **propriedades de objeto**

Existem duas maneiras de intercetar o acesso de propriedade na JavaScript: [recuperadores](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) / [definidores](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) e [delegações](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). A Vue 2 usava exclusivamente recuperadores / definidores devido as limitações de suporte do navegador. Na Vue 3, as delegações são usadas para objetos reativos e recuperadores / definidores são usados para referências. No seguinte bloco de código temos algum pseudo-código que ilustra como funcionam:

```js{4,9,17,22}
function reactive(obj) {
  return new Proxy(obj, {
    get(target, key) {
      track(target, key)
      return target[key]
    },
    set(target, key, value) {
      target[key] = value
      trigger(target, key)
    }
  })
}

function ref(value) {
  const refObject = {
    get value() {
      track(refObject, 'value')
      return value
    },
    set value(newValue) {
      value = newValue
      trigger(refObject, 'value')
    }
  }
  return refObject
}
```

:::tip
Os trechos de código mostrados são destinados à explicar os conceitos fundamentais da forma mais simples possível, então muitos detalhes são omitidos, e os casos extremos ignorados.
:::

Isto explica um pouco as [limitações dos objetos reativos](/guide/essentials/reactivity-fundamentals#limitations-of-reactive) que discutimos na seção de fundamentos:

- Quando atribuis ou desestruturas uma propriedade dum objeto reativo para uma variável local, a reatividade é "desconectada" porque o acesso à variável local já não aciona as armadilhas da delegação de recuperação ou definição.

- A delegação retornada a partir da `reactive()`, embora comportando-se tal como a original, tem uma identidade diferente se a compararmos com a original usando o operador `===`.

Dentro de `track()`, verificamos se existe um efeito em execução atualmente. Se existir um, nós procuramos os efeitos do subscritor (armazenado num conjunto) para a propriedade ser rastreada, e adicionamos o efeito ao conjunto:

```js
// Isto será definido exatamente antes dum efeito ser executado.
// Lidaremos com isto depois.
let activeEffect

function track(target, key) {
  if (activeEffect) {
    const effects = getSubscribersForProperty(target, key)
    effects.add(activeEffect)
  }
}
```

As subscrições do efeito são armazenadas numa estrutura de dados `WeakMap<target, Map<key, Set<effect>>>` global. Se nenhum conjunto de efeitos de subscrição foi encontrado para uma propriedade (rastreada pela primeira vez), será criado. Isto é o que a função `getSubscribersForProperty()` faz, em resumo. Por simplicidade, pularemos os seus detalhes.

Dentro de `trigger()`, novamente procuraremos os feitos do subscritor para a propriedade. Mas desta vez os invocamos:

```js
function trigger(target, key) {
  const effects = getSubscribersForProperty(target, key)
  effects.forEach((effect) => effect())
}
```

Agora vamos voltar atrás para a função `whenDepsChange()`:

```js
function whenDepsChange(update) {
  const effect = () => {
    activeEffect = effect
    update()
    activeEffect = null
  }
  effect()
}
```

Ela envolve a função `update` pura num efeito que define a si mesmo como o atual efeito ativo antes de executar a atualização de fato. Isto permite `track()` chamar durante a atualização para localizar o atual efeito ativo.

Neste ponto, criamos um efeito que rastreia automaticamente suas dependências, e re-executa sempre que uma dependência mudar. Nós chamamos isto um **Efeito Reativo**.

A Vue fornece uma API que permite-nos criar efeitos reativos: [`watchEffect()`](/api/reactivity-core#watcheffect). De fato, podes ter notado que funciona de maneira muito semelhante à `whenDepsChange()` mágica no exemplo. Nós podemos agora retrabalhar o exemplo original usando as verdadeiras APIs da Vue:

```js
import { ref, watchEffect } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = ref()

watchEffect(() => {
  // rastreia A0 e A1
  A2.value = A0.value + A1.value
})

// aciona o efeito
A0.value = 2
```

Usar um efeito reativo para mudar uma referência não é o caso de uso mais interessante - de fato, usar uma propriedade computada a torna mais declarativa:

```js
import { ref, computed } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = computed(() => A0.value + A1.value)

A0.value = 2
```

Internamente, `computed` gere sua invalidação e re-calculo usando um efeito reativo.

E o que é um exemplo dum efeito reativo comum e útil? Bem, atualizar o DOM! Nós podemos implementar uma "interpretação reativa" simples como esta:

```js
import { ref, watchEffect } from 'vue'

const count = ref(0)

watchEffect(() => {
  document.body.innerHTML = `count is: ${count.value}`
})

// atualiza o DOM
count.value++
```

De fato, isto é muito próximo de como um componente da Vue mantém o estado e o DOM em sincronia - cada instância de componente cria um efeito reativo para gerar e atualizar o DOM. Claro, os componentes da Vue usam maneiras muito mais eficientes para atualizar o DOM do que `innerHTML`. Isto é discutido no [Mecanismo de Interpretação](./rendering-mechanism).

<div class="options-api">

As APIs `ref()`, `computed()`, e `watchEffect()` são todas parte da API de Composição. Se apenas tens estado a usar a API de Opções com a Vue até aqui, notarás que API de Composição é mais próxima de como o sistema de reatividade da Vue funciona nos bastidores. De fato, na Vue 3 a API de Opções é implementada em cima da API de Composição. Todo acesso de propriedade na instância do componente (`this`) aciona os recuperadores / definidores para o rastreio da reatividade, e opções como `watch` e `computed` invocam suas equivalentes de API de Composição internamente.

</div>

## Reatividade de Tempo de Execução vs. de Tempo de Compilação {#runtime-vs-compile-time-reactivity}

O sistema de reatividade da Vue é essencialmente baseado em tempo de execução: o rastreio e acionamento são todos realizados enquanto o código está em execução diretamente no navegador. Os pós da reatividade de tempo de execução são que pode trabalhar sem uma etapa de construção, e existem muito poucos casos extremos. Por outro lado, isto torna-o restrito pelas limitações de sintaxe da JavaScript, conduzindo à necessidade de contentores de valor como referências de Vue.

Algumas abstrações, tais como a [Svelte](https://svelte.dev/), escolheram superar tais limitações implementando a reatividade durante a compilação. Ela analisa e transforma o código para simular reatividade. A etapa de compilação permite a abstração alterar as semânticas da própria JavaScript - por exemplo, injetar implicitamente código que realiza analises de dependência e acionamento de efeito em torno do acesso às variáveis definidas localmente. A desvantagem é que tais transformações exigem uma etapa de construção, e alterar as semânticas da JavaScript é essencialmente criar uma linguagem que parece-se com a JavaScript mas compila para outro coisa.

A equipa da Vue explorou esta direção através duma funcionalidade experimental chamada [Transformação de Reatividade](/guide/extras/reactivity-transform), mas no final decidimos que não seria muito atraente para o projeto devido à este [raciocínio](https://github.com/vuejs/rfcs/discussions/369#discussioncomment-5059028).

## Depuração da Reatividade {#reactivity-debugging}

É excelente que o sistema de reatividade da Vue rastreia automaticamente as dependências, mas em alguns casos podemos querer compreender exatamente o que está sendo rastreado, ou que está causando um componente para redesenhar.

### Gatilhos da Depuração do Componente {#component-debugging-hooks}

Nós podemos depurar quais dependências são usadas durante a interpretação dum componente e qual dependência está acionar uma atualização usando os gatilhos do ciclo de vida <span class="options-api">`renderTracked`</span><span class="composition-api">`onRenderTracked`</span> e <span class="options-api">`renderTriggered`</span><span class="composition-api">`onRenderTriggered`</span>. Ambos gatilhos receberão um evento depurador que contém informação sobre a dependência em questão. É recomendado colocar uma declaração `debugger` nas funções de resposta para inspecionar interativamente a dependência:

<div class="composition-api">

```vue
<script setup>
import { onRenderTracked, onRenderTriggered } from 'vue'

onRenderTracked((event) => {
  debugger
})

onRenderTriggered((event) => {
  debugger
})
</script>
```

</div>
<div class="options-api">

```js
export default {
  renderTracked(event) {
    debugger
  },
  renderTriggered(event) {
    debugger
  }
}
```

</div>

:::tip
Os gatilhos de depuração do componente apenas funcionam no modo de desenvolvimento.
:::

Os objetos do evento de depuração tem o seguinte tipo:

<span id="debugger-event"></span>

```ts
type DebuggerEvent = {
  effect: ReactiveEffect
  target: object
  type:
    | TrackOpTypes /* 'get' | 'has' | 'iterate' */
    | TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
  key: any
  newValue?: any
  oldValue?: any
  oldTarget?: Map<any, any> | Set<any>
}
```

### Depuração Computada {#computed-debugging}

<!-- TODO options API equivalent -->

Nós podemos depurar propriedades computadas passando a `computed()` um segundo objeto de opções com as funções de resposta `onTrack` e `onTrigger`:

- `onTrack` será chamada quando uma propriedade reativa ou referência é rastreada como uma dependência.
- `onTrigger` será chamada quando a função de resposta observadora for acionada pela mutação duma dependência.

Ambas funções de resposta receberão eventos depuradores no [mesmo formato](#debugger-event) como gatilhos de depuração do componente:

```js
const plusOne = computed(() => count.value + 1, {
  onTrack(e) {
    // acionada quando `count.value` for rastreado como uma dependência
    debugger
  },
  onTrigger(e) {
    // acionada quando `count.value` for mudada
    debugger
  }
})

// acesso ao `plusOne`, deve acionar `onTrack`
console.log(plusOne.value)

// mutação de `count.value`, deve acionar `onTrigger`
count.value++
```

:::tip
As opções computadas `onTrack` e `onTrigger` apenas funcionam em modo de desenvolvimento.
:::

### Depuração do Observador {#watcher-debugging}

<!-- TODO options API equivalent -->

Semelhante a `computed()`, os observadores também suportam as opções `onTrack` e `onTrigger`:

```js
watch(source, callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})

watchEffect(callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})
```

:::tip
As opções observadoras `onTrack` e `onTrigger` apenas funcionam em modo de desenvolvimento.
:::

## Integração com Sistemas de Estado Externos {#integration-with-external-state-systems}

O sistema de reatividade da Vue funciona convertendo profundamente opções de JavaScript simples em delegações reativas. A conversão profunda pode ser desnecessária ou algumas vezes indesejada quando integramos com sistemas de gestão de estado externos (por exemplo, se uma solução externa também usa delegações).

A ideia geral de integrar o sistema de reatividade da Vue com uma solução de gestão estado externa é segurar o estado externo numa [`shallowRef`](/api/reactivity-advanced#shallowref). Uma referência superficial é apenas reativa quando a sua propriedade `.value` for acessada - o valor interno é deixado intacto. Quando o estado externo muda, substitui o valor da referência para acionar atualizações.

### Dado Imutável {#immutable-data}

Se estiveres a implementar uma funcionalidade de desfazer / refazer, provavelmente queres tirar uma fotografia do estado da aplicação sobre cada edição do utilizador. No entanto, o sistema de reatividade mutável da Vue não é o mais adequado para isto se a árvore de estado for grande, porque seriar o objeto de estado inteiro em cada atualização pode ser dispendioso em termos de ambos custos de CPU e memória.

As [estruturas de dados imutáveis](https://en.wikipedia.org/wiki/Persistent_data_structure) resolvem isto nunca mudando os objetos de estado - ao invés disto, cria novos objetos que partilham as mesmas, partes não modificadas com aquelas antigas. Existem diferentes maneiras de usar dados imutáveis na JavaScript, mas recomendamos usar [Immer](https://immerjs.github.io/immer/) com a Vue porque permite-te usar dados imutáveis enquanto mantém a sintaxe mais ergonómica e mutável.

Nós podemos integrar `immer` com a Vue através duma simples função de composição:

```js
import produce from 'immer'
import { shallowRef } from 'vue'

export function useImmer(baseState) {
  const state = shallowRef(baseState)
  const update = (updater) => {
    state.value = produce(state.value, updater)
  }

  return [state, update]
}
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNplU8Fu2zAM/RXOlzpAYu82zEu67lhgpw3bJcrBs5VYqywJkpxmMPzvoyjZNRodbJF84iOppzH7ZkxxHXhWZXvXWGE8OO4H88iU6I22HkYYHH/ue25hgrPVPTwUpQh28dc9MAXAVKOV83AUnvduC4Npa8+fg3GCw3I8PwbwGD64vPCSV8Cy77y2Cn4PnGXbFGu1wpC36EPHRO67c78cD6fgVfgOiOB9gnMtXczA1GnDFFPnQTVeaAVeXy6SSsyFavltE/OvKs+pGTg8zsxkHwl9KgIBtvbhzkl0yIWU+zIOFEeJBgKNxORoAewHSX/cSQHX3VnbA8vyMXa3pfqxb0i1CRXZWZb6w1U1snYOT40JvQ4+NVI0Lxi865NliTisMRHChOVSNaUUscCSKtyXq7LRdP6fDNvYPw3G85vftbzRtg6TrUAKxXe+s3q4dF/mQdC5bJtFTe362qB4tELVURKWAthhNc87+OhSw2V33htXleWgzMulaHQfFfj0ufhYfCpb4XySJHc9Zv7a63aQqKh0+xNRR8kiZ1K2sYhqeBI1xVHPi+xdV0upX3/w8yJ8fCiIYIrfCLPIaZH4n9rxnx7nlQQVH4YLHpTLW8YV8A0W1Ye4PO7sZiU/ylFca4mSP8yl5yvv/O4sZcSmw8/iW8bXdSTcjDiFgUz/AcH6WZQ=)

### Maquinas de Estado {#state-machines}

A [Máquina de Estado](https://en.wikipedia.org/wiki/Finite-state_machine) é um modelo para descrever todos os possíveis estados em que uma aplicação pode estar, e todas as possíveis maneiras que pode transitar de um estado para um outro. Enquanto isto pode ser exagero para componentes simples, pode ajudar a tornar fluxos de estado complexo mais robustos e manejáveis.

Uma das implementações de máquina de estado mais popular em JavaScript é a [XState](https://xstate.js.org/). Neste exemplo mostramos uma função de composição que integra com ela:

```js
import { createMachine, interpret } from 'xstate'
import { shallowRef } from 'vue'

export function useMachine(options) {
  const machine = createMachine(options)
  const state = shallowRef(machine.initialState)
  const service = interpret(machine)
    .onTransition((newState) => (state.value = newState))
    .start()
  const send = (event) => service.send(event)

  return [state, send]
}
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNp1U81unDAQfpWRL7DSFqqqUiXEJumhyqVVpDa3ugcKZtcJjC1syEqId8/YBu/uIRcEM9/P/DGz71pn0yhYwUpTD1JbMMKO+o6j7LUaLMwwGvGrqk8SBSzQDqqHJMv7EMleTMIRgGOt0Fj4a2xlxZ5EsPkHhytuOjucbApIrDoeO5HsfQCllVVHUYlVbeW0xr2OKcCzHCwkKQAK3fP56fHx5w/irSyqbfFMgA+h0cKBHZYey45jmYfeqWv6sKLXHbnTF0D5f7RWITzUnaxfD5y5ztIkSCY7zjwKYJ5DyVlf2fokTMrZ5sbZDu6Bs6e25QwK94b0svgKyjwYkEyZR2e2Z2H8n/pK04wV0oL8KEjWJwxncTicnb23C3F2slabIs9H1K/HrFZ9HrIPX7Mv37LPuTC5xEacSfa+V83YEW+bBfleFkuW8QbqQZDEuso9rcOKQQ/CxosIHnQLkWJOVdept9+ijSA6NEJwFGePaUekAdFwr65EaRcxu9BbOKq1JDqnmzIi9oL0RRDu4p1u/ayH9schrhlimGTtOLGnjeJRAJnC56FCQ3SFaYriLWjA4Q7SsPOp6kYnEXMbldKDTW/ssCFgKiaB1kusBWT+rkLYjQiAKhkHvP2j3IqWd5iMQ+M=)

### RxJS {#rxjs}

A [RxJS](https://rxjs.dev/) é uma biblioteca para trabalhar com fluxos de evento assíncronos. A biblioteca [VueUse](https://vueuse.org/) fornece a extensão [`@vueuse/rxjs`](https://vueuse.org/rxjs/readme.html) para conectar os fluxos da RxJS com o sistema de reatividade da Vue.

## Conexão com os Sinais {#connection-to-signals}

Muitas outras abstrações têm introduzido reatividade primitivas semelhante as referências da API de Composição da Vue, sob o termo "sinais":

- [Sinais de Solid](https://www.solidjs.com/docs/latest/api#createsignal)
- [Sinais de Angular](https://github.com/angular/angular/discussions/49090)
- [Sinais de Preact](https://preactjs.com/guide/v10/signals/)
- [Sinais de Qwik](https://qwik.builder.io/docs/components/state/#usesignal)

Fundamentalmente, sinais são o mesmo tipo de reatividade primitiva como as referências da Vue. É um contentor de valor que fornece rastreio de dependência sobre o acesso, e acionamento de efeito colateral sobre a mutação. Este paradigma baseado na reatividade primitiva não é particularmente um conceito novo no mundo do frontend: data para trás para implementações como [observáveis de Knockout](https://knockoutjs.com/documentation/observables.html) e [Rastreador de Meteor](https://docs.meteor.com/api/tracker.html) de mais de uma década atrás. A API de Opções da Vue e a biblioteca de gestão de estado da React [MobX](https://mobx.js.org/) também são baseadas sobre os mesmos princípios, mas escondem os primitivos atrás de propriedades de objeto.

Embora não uma característica necessária para algo qualificar como sinais, hoje o conceito é discutido com frequência ao lado do modelo de interpretação onde as atualizações são realizadas através de subscrições finamente ajustados. Devido ao uso do DOM Virtual, a Vue atualmente [depende de compiladores para alcançar otimizações semelhantes](/guide/extras/rendering-mechanism#compiler-informed-virtual-dom). No entanto, também estamos a explorar uma nova estratégia de compilação inspirada na Solid (Modo de Vapor) que não dependo do DOM Virtual e tira mais partido do sistema de reatividade embutido da Vue.

### Compromissos de Desenho da API {#api-design-trade-offs}

O desenho dos sinais da Preact e Qwik são muito semelhantes a [`shallowRef`](/api/reactivity-advanced#shallowref) da Vue: Todos os três fornecem uma interface mutável através da propriedade `.value`. Nós focaremos a discussão sobre os sinais de Solid e Angular.

#### Sinais de Solid {#solid-signals}

O desenho da API `createSignal()` da Solid enfatiza a segregação da leitura e escrita. Os sinais são expostos como um recuperador de apenas leitura e definidor separado:

```js
const [count, setCount] = createSignal(0)

count() // acessar o valor
setCount(1) // atualizar o valor
```

Repara como o sinal `count` pode ser passado sem o definidor. Isto garante qua o estado nunca pode ser mudado a menos que o definidor seja também explicitamente exposto. Se esta garantia de segurança justifica a sintaxe mais verbosa poderia estar sujeita ao requisito do gosto do projeto e pessoal - mas no caso de preferires este estilo de API, podes facilmente replicá-lo na Vue:

```js
import { shallowRef, triggerRef } from 'vue'

export function createSignal(value, options) {
  const r = shallowRef(value)
  const get = () => r.value
  const set = (v) => {
    r.value = typeof v === 'function' ? v(r.value) : v
    if (options?.equals === false) triggerRef(r)
  }
  return [get, set]
}
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpdUk1TgzAQ/Ss7uQAjgr12oNXxH+ix9IAYaDQkMV/qMPx3N6G0Uy9Msu/tvn2PTORJqcI7SrakMp1myoKh1qldI9iopLYwQadpa+krG0TLYYZeyxGSojSSs/d7E8vFh0ka0YhOCmPh0EknbB4mPYfTEeqbIelD1oiqXPRQCS+WjoojAW8A1Wmzm1A39KYZzHNVYiUib85aKeCx46z7rBuySqQe6h14uINN1pDIBWACVUcqbGwtl17EqvIiR3LyzwcmcXFuTi3n8vuF9jlYzYaBajxfMsDcomv6E/m9E51luN2NV99yR3OQKkAmgykss+SkMZerxMLEZFZ4oBYJGAA600VEryAaD6CPaJwJKwnr9ldR2WMedV1Dsi6WwB58emZlsAV/zqmH9LzfvqBfruUmNvZ4QN7VearjenP4aHwmWsABt4x/+tiImcx/z27Jqw==)

#### Sinais de Angular {#angular-signals}

A Angular está a passar por algumas mudanças fundamentais renunciando a verificação suja e introduzindo sua própria implementação duma reatividade primitiva. A API de Sinal da Angular parece-se com isto:

```js
const count = signal(0)

count() // acessar o valor
count.set(1) // definir novo valor
count.update((v) => v + 1) // atualização baseada no valor anterior

// mudar objetos profundos com a mesma identidade
const state = signal({ count: 0 })
state.mutate((o) => {
  o.count++
})
```

Novamente, podemos facilmente replicar a API na Vue:

```js
import { shallowRef, triggerRef } from 'vue'

export function signal(initialValue) {
  const r = shallowRef(initialValue)
  const s = () => r.value
  s.set = (value) => {
    r.value = value
  }
  s.update = (updater) => {
    r.value = updater(r.value)
  }
  s.mutate = (mutator) => {
    mutator(r.value)
    triggerRef(r)
  }
  return s
}
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNp9UslOwzAQ/ZVRLiRQEsqxpBUIvoADp0goTd3U4DiWl4AU5d8ZL3E3iZtn5r1Z3vOYvAiRD4Ykq6RUjaRCgyLaiE3FaSd6qWEERVteswU0fSeMJjuYYC/7Dm7youatYbW895D8S91UvOJNz5VGuOEa1oGePmRzYdebLSNYmRumaQbrjSfg8xYeEVsWfh/cBANNOsFqTTACKA/LzavrTtUKxjEyp6kssDZj3vygAPJjL1Bbo3XP4blhtPleV4nrlBuxw1npYLca4A6WWZU4PADljSQd4drRC8//rxfKaW+f+ZJg4oJbFvG8ZJFcaYreHL041Iz1P+9kvwAtadsS6d7Rm1rB55VRaLAzhvy6NnvDG01x1WAN5VTTmn3UzJAMRrudd0pa++LEc9wRpRDlHZT5YGu2pOzhWHAJWxvnakxOHufFxqx/4MxzcEinIYP+eV5ntOe5Rx94IYjopxOZUhnIEr+4xPMrjuG1LPFftkTj5DNJGhwYBZ4BJz3DV56FmJLpD1DrKXU=)

Comparado as referências da Vue, o estilo de API baseado em recuperador da Solid e Angular fornece alguns compromissos interessantes quando usada nos componentes da Vue:

- `()` é ligeiramente menos verboso do que `.value`, mas a atualização do valor é mais verbosa.
- Não existe nenhum desembrulho de referência: acesso aos valores sempre `()`. Isto torna o acesso ao valor consistente em toda parte. Isto também significa que podes passar sinais puros como propriedades de componente.

Se estes estilos de API adequam-se a ti é até algum ponto subjetivo. O nosso objetivo acima é demonstrar a similaridade subjacente e os compromissos entre estes diferentes desenhos de API. Nós também queremos mostrar que a Vue é flexível: de fato não estás trancado nas APIs existentes. Se for necessário, podes criar a tua própria API de reatividade primitiva adequar-se mais as necessidades específicas.

---

---
url: /api/index.md
---

<script setup>
import ApiIndex from './ApiIndex.vue'
</script>

<ApiIndex />

---

---
url: /error-reference/index.md
---
<script setup>
import { ref, onMounted } from 'vue'
import { data } from './errors.data.ts'
import ErrorsTable from './ErrorsTable.vue'

const highlight = ref()
onMounted(() => {
  highlight.value = location.hash.slice(1)
})
</script>

# Referência do Código de Erro de Produção {#error-reference}

## Erros de Execução {#runtime-errors}

Nas construções de produção, o terceiro argumento passado às seguintes APIs do manipulador de erro serão um código curto ao invés da sequência de caracteres da informação completa:

- [`app.config.errorHandler`](/api/application#app-config-errorhandler)
- [`onErrorCaptured`](/api/composition-api-lifecycle#onerrorcaptured) (API de Composição)
- [`errorCaptured`](/api/options-lifecycle#errorcaptured) (API de Opções)

A seguinte tabela mapeia os códigos às suas sequências de caracteres da informação completa.

<ErrorsTable kind="runtime" :errors="data.runtime" :highlight="highlight" />

## Erros do Compilador {#compiler-errors}

A seguinte tabela fornece um mapeamento dos códigos de erro do compilador de produção às suas mensagens originais.

<ErrorsTable kind="compiler" :errors="data.compiler" :highlight="highlight" />

---

---
url: /guide/essentials/template-refs.md
---
# Referências do Modelo de Marcação {#template-refs}

Embora o modelo de interpretação declarativa da Vue abstraia a maior parte das operações diretas do DOM por ti, ainda existe casos onde precisamos de acesso direto aos elementos do DOM subjacentes. Para conseguir isto, podemos utilizar o atributo especial `ref`:

```vue-html
<input ref="input">
```

O `ref` é um atributo especial, similar ao atributo `key` discutido no capitulo `v-for`. Ele permite-nos obter uma referência direta para um elemento de DOM especifico ou instância de componente depois de ser montada. Isto pode ser útil quando quiseres, por exemplo, focar programaticamente uma entrada (`input`) na montagem do componente, ou inicializar uma biblioteca de terceiro sobre um elemento.

## Acessando as Referências {#accessing-the-refs}

<div class="composition-api">

Para obter a referência com a API de Composição, precisamos declarar uma `ref` com o mesmo nome:

```vue
<script setup>
import { ref, onMounted } from 'vue'

// declara uma `ref` para segurar a referência de elemento
// o nome deve corresponder ao valor de `ref` do modelo de marcação
const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>
```

Se não estiveres utilizando a `<script setup>`, certifica-te de também retornar a referência a partir de `setup()`:

```js{6}
export default {
  setup() {
    const input = ref(null)
    // ...
    return {
      input
    }
  }
}
```

</div>
<div class="options-api">

A referência resultante é exposta sobre `this.$refs`:

```vue
<script>
export default {
  mounted() {
    this.$refs.input.focus()
  }
}
</script>

<template>
  <input ref="input" />
</template>
```

</div>

Nota que só podes acessar a referência **depois do componente ser montado.** Se tentares acessar <span class="options-api">`$refs.input`</span><span class="composition-api">`input`</span> em uma expressão de modelo de marcação, será `null` na primeira interpretação. Isto porque o elemento não existe até depois da primeira interpretação!

<div class="composition-api">

Se estiveres tentando observar as mudanças de uma referência de modelo de marcação, certifica-te de representar o caso onde a referência tem o valor `null`:

```js
watchEffect(() => {
  if (input.value) {
    input.value.focus()
  } else {
    // ainda não está montado, ou o elemento foi desmontado (por exemplo, pelo v-if)
  }
})
```

Consulte também: [Atribuindo Tipos às Referências do Modelo de Marcação](/guide/typescript/composition-api.html#typing-template-refs) <sup class="vt-badge ts" />

</div>

## Referências dentro de `v-for` {#refs-inside-v-for}

> Exige a versão 3.2.25 em diante

<div class="composition-api">

Quando o `ref` é utilizado dentro de `v-for`, a referência correspondente deve conter uma valor de arranjo, que será povoada com os elementos depois de montar:

```vue
<script setup>
import { ref, onMounted } from 'vue'

const list = ref([
  /* ... */
])

const itemRefs = ref([])

onMounted(() => console.log(itemRefs.value))
</script>

<template>
  <ul>
    <li v-for="item in list" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpFjs1qwzAQhF9l0CU2uDZtb8UOlJ576bXqwaQyCGRJyCsTEHr3rGwnOehnd2e+nSQ+vW/XqMSH6JdL0J6wKIr+LK2evQuEhKCmBs5+u2hJ/SNjCm7GiV0naaW9OLsQjOZrKNrq97XBW4P3v/o51qTmHzUtd8k+e0CrqsZwRpIWGI0KVN0N7TqaqNp59JUuEt2SutKXY5elmimZT9/t2Tk1F+z0ZiTFFdBHs738Mxrry+TCIEWhQ9sttRQl0tEsK6U4HEBKW3LkfDA6o3dst3H77rFM5BtTfm/P)

</div>
<div class="options-api">

Quando o `ref` é utilizado dentro de `v-for`, o valor de referência resultante será um arranjo contendo os elementos correspondentes:

```vue
<script>
export default {
  data() {
    return {
      list: [
        /* ... */
      ]
    }
  },
  mounted() {
    console.log(this.$refs.items)
  }
}
</script>

<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>
```

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpFjk0KwjAQha/yCC4Uaou6kyp4DuOi2KkGYhKSiQildzdNa4WQmTc/37xeXJwr35HEUdTh7pXjszT0cdYzWuqaqBm9NEDbcLPeTDngiaM3PwVoFfiI667AvsDhNpWHMQzF+L9sNEztH3C3JlhNpbaPNT9VKFeeulAqplfY5D1p0qurxVQSqel0w5QUUEedY8q0wnvbWX+SYgRAmWxIiuSzm4tBinkc6HvkuSE7TIBKq4lZZWhdLZfE8AWp4l3T)

</div>

Deve ser notado que o arranjo de referência **não** garante a mesma ordem conforme o arranjo de origem.

## Referências de Função {#function-refs}

No lugar de uma chave de sequência de caracteres, o atributo `key` também pode ser atado a uma função, que será chamada em cada atualização do componente e dar-te-á completa flexibilidade sobre onde guardar a referência do elemento. A função recebe a referência do elemento como primeiro argumento:

```vue-html
<input :ref="(el) => { /* atribui `el` a uma propriedade ou referência */ }">
```

Nota que estamos utilizando uma vinculação de `:ref` dinâmica assim podemos passar nela uma função no lugar de uma sequência de caracteres de nome de referência. Quando o elemento é desmontado, o argumento será `null`. Tu podes, claro, utilizar um método no lugar de uma função em linha.

## Referência no Componente {#ref-on-component}

> Esta seção presume conhecimento de [Componentes](/guide/essentials/component-basics). Esteja a vontade para saltá-la e voltar mais tarde.

O `ref` também pode ser utilizado sobre um componente filho. Neste caso a referência será aquela de uma instância de componente:

<div class="composition-api">

```vue
<script setup>
import { ref, onMounted } from 'vue'
import Child from './Child.vue'

const child = ref(null)

onMounted(() => {
  // child.value segurará uma instância de <Child />
})
</script>

<template>
  <Child ref="child" />
</template>
```

</div>
<div class="options-api">

```vue
<script>
import Child from './Child.vue'

export default {
  components: {
    Child
  },
  mounted() {
    // this.$refs.child segurará uma instância de <Child />
  }
}
</script>

<template>
  <Child ref="child" />
</template>
```

</div>

<span class="composition-api">Se o componente filho estiver utilizando a API de Opções ou não utilizando `<script setup>`, a</span><span class="options-api">A</span> instância referenciada será idêntica ao `this` do componente filho, o que significa que o componente pai terá total acesso as todas propriedades e métodos do componente filho. Isto torna-o fácil de criar detalhes de implementação atrelados firmemente entre o pai e o filho, assim as referências do componente só deve ser utilizadas quando forem absolutamente necessários - na maioria dos casos, deves tentar implementar interações entre o pai e o filho utilizando as interfaces de propriedades e emissão padrão primeiro.

<div class="composition-api">

Uma exceção é que componentes utilizando `<script setup>` são **privados por padrão**: um componente pai referenciando um componente filho utilizando `<script setup>` não será capaz de acessar nada a menos que o componente filho escolha expor uma interface publica utilizando a macro `defineExpose`:

```vue
<script setup>
import { ref } from 'vue'

const a = 1
const b = ref(2)

// Macros do compilador, tais como `defineExpose`, não precisam ser importados.
defineExpose({
  a,
  b
})
</script>
```

Quando um pai recebe uma instância deste componente através de referências de modelo de marcação, a instância recuperada será da forma `{ a: number, b: number }` (referências são desembrulhadas automaticamente como instâncias normais).

Consulte também: [Atribuindo Tipos às Referências do Modelo de Marcação do Componente](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" />

</div>
<div class="options-api">

A opção `expose` pode ser utilizada para limitar o acesso a instância do filho:

```js
export default {
  expose: ['publicData', 'publicMethod'],
  data() {
    return {
      publicData: 'foo',
      privateData: 'bar'
    }
  },
  methods: {
    publicMethod() {
      /* ... */
    },
    privateMethod() {
      /* ... */
    }
  }
}
```

No exemplo acima, um pai referenciando este componente através de referência de modelo de marcação só será capaz de acessar `publicData` e `publicMethod`.

</div>

---

---
url: /guide/components/registration.md
---
# Registo de Componente {#component-registration}

> Esta página pressupõe conhecimento dos [Fundamentos dos Componentes](/guide/essentials/component-basics). Nós precisamos ler este artigo se os conceitos dos componentes forem novos para nós.

<VueSchoolLink href="https://vueschool.io/lessons/vue-3-global-vs-local-vue-components" title="Aula Grátis de Registo de Componente de Vue.js"/>

Um componente da Vue precisa ser "registado" para que a Vue saiba onde localizar a sua implementação quando for encontrado num modelo de marcação. Existem duas maneiras de registar os componentes: global e local.

## Registo Global {#global-registration}

Nós podemos disponibilizar os componentes globalmente na [aplicação atual de Vue](/guide/essentials/application) usando o método `app.component()`:

```js
import { createApp } from 'vue'

const app = createApp({})

app.component(
  // o nome registado
  'MyComponent',
  // a implementação
  {
    /* ... */
  }
)
```

Se usarmos os componentes compostos por um único ficheiro (SFCs), registaremos os ficheiros `.vue` importados:

```js
import MyComponent from './App.vue'

app.component('MyComponent', MyComponent)
```

O método `app.component()` pode ser encadeado:

```js
app
  .component('ComponentA', ComponentA)
  .component('ComponentB', ComponentB)
  .component('ComponentC', ComponentC)
```

Os componentes registados globalmente podem ser usados no modelo de marcação de qualquer componente dentro desta aplicação:

```vue-html
<!-- isto funcionará em qualquer componente dentro da aplicação -->
<ComponentA/>
<ComponentB/>
<ComponentC/>
```

Isto aplica-se a todos os subcomponentes, o que significa que todos estes três componentes também estarão disponíveis _dentro de uns dos outros_.

## Registo Local {#local-registration}

Embora conveniente, o registo global tem algumas desvantagens:

1. O registo global impede os sistemas de construção de remover os componentes que não são usados (mais conhecido como "agitação de árvore" (tree-shaking)). Se registarmos globalmente um componente, mas acabarmos não usando este em nenhum lugar na nossa aplicação, este ainda será incluído no pacote final.

2. O registo global torna o relacionamento de dependência menos explícito em grandes aplicações. Este dificulta a localização da implementação dum componente filho a partir dum componente pai que usa o componente filho. Isto pode afetar a sustentabilidade a longo prazo semelhante ao uso de muitas variáveis globais.

O registo local limita a disponibilidade dos componentes registados apenas ao componente atual. Este torna o relacionamento de dependências mais explícito, e é mais amigável a agitação da árvore de componentes.

<div class="composition-api">

Quando usamos o componente de um único ficheiro (SFC) com o `<script setup>`, os componentes importados podem ser usados localmente sem fazer-se o registo:

```vue
<script setup>
import ComponentA from './ComponentA.vue'
</script>

<template>
  <ComponentA />
</template>
```

No componente que não estivermos usando o `<script setup>`, precisaremos usar a opção `components`:

```js
import ComponentA from './ComponentA.js'

export default {
  components: {
    ComponentA
  },
  setup() {
    // ...
  }
}
```

</div>
<div class="options-api">

O registo local é feito usando a opção `components`:

```vue
<script>
import ComponentA from './ComponentA.vue'

export default {
  components: {
    ComponentA
  }
}
</script>

<template>
  <ComponentA />
</template>
```

</div>

Para cada propriedade no objeto `components`, a chave será o nome do componente registado, enquanto o valor conterá a implementação do componente. O exemplo acima usa a abreviação de propriedade da especificação da ECMAScript de 2015 e é equivalente a:

```js
export default {
  components: {
    ComponentA: ComponentA
  }
  // ...
}
```

Notemos que **os componentes registados localmente também não _estão_ disponíveis dentro dos componentes descendentes**. Neste caso, `ComponentA` será disponibilizado apenas ao componente atual, e não aos componentes filho ou descendente.

## Caixa do Nome do Componente {#component-name-casing}

Durante todo o guia, usaremos os nomes de CaixaPascal quando registarmos os componentes. Isto porque:

1. Os nomes de CaixaPascal são identificadores válidos de JavaScript. Isto facilita a importação e registo de componentes na JavaScript. Este também ajuda os ambientes de desenvolvimento integrado com a conclusão automática de código.

2. `<PascalCase />` torna mais óbvio de que isto é um componente de Vue ao invés dum elemento de HTML nativo dentro dos modelos de marcação. Este também diferencia os componentes da Vue dos elementos personalizados (componentes da Web).

Isto é um estilo recomendado quando trabalharmos com o componente de um único ficheiro ou modelos de marcação na forma de sequência de caracteres. No entanto, conforme discutido nas [Advertências da Analise do Modelo de Marcação no DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats), os marcadores de CaixaPascal não são utilizáveis nos modelos de marcação do DOM.

Felizmente, a Vue suporta a resolução de marcadores de caixa-espetada para os componentes registados usando a CaixaPascal. Isto significa que um componente registado como `MyComponent` pode ser referenciado no modelo de marcação como `<MyComponent>` ou `<my-component>`. Isto permite-nos usar o mesmo código de registo de componente de JavaScript independentemente da origem do modelo de marcação.

---

---
url: /style-guide/rules-essential.md
---
# Regras Prioridade A: Essencial {#priority-a-rules-essential}

Estas regras ajudam a prevenir erros, então aprenda e siga-as a qualquer custo. Exceções podem existir, mas devem ser muito raras e feitas somente por aqueles com conhecimento especializado em JavaScript e Vue. 

## Use nomes de componente com multipalavras {#use-multi-word-component-names}

Nomes de componentes do usuário devem sempre conter multipalavras, exceto componentes raiz `App`. User component names should always be multi-word, except for root `App` components. Isto [previne conflitos](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) com elementos HTML existentes e futuros, visto que todos os elementos HTML são formados por apenas uma palavra.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<!-- em modelos pré-compilados -->
<Item />

<!-- em modelos dentro do DOM -->
<item></item>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<!-- em modelos pré-compilados -->
<TodoItem />

<!-- em modelos dentro do DOM -->
<todo-item></todo-item>
```

</div>

## Use definições de propriedades detalhadas {#use-detailed-prop-definitions}

No código desenvolvido, definições de propriedades devem ser tão detalhadas quanto possível, especificando ao menos os seus tipos.

::: details Explicação Detalhada
[Definições de propriedades](/guide/components/props#prop-validation) detalhadas possuem duas vantagens:

- Elas documentam a API do componente, para que seja fácil ver como o componente deve ser usado.
- No desenvolvimento, Vue avisará se um componente receber propriedades com o formato incorreto, ajudando-o a capturar potenciais causas de erro.
  :::

<div class="options-api">
<div class="style-example style-example-bad">
<h3>Ruim</h3>

```js
// Isto é aceitável apenas ao prototipar
props: ['status']
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```js
props: {
  status: String
}
```

```js
// Ainda melhor!
props: {
  status: {
    type: String,
    required: true,

    validator: value => {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].includes(value)
    }
  }
}
```

</div>
</div>

<div class="composition-api">
<div class="style-example style-example-bad">
<h3>Ruim</h3>

```js
// Isto é aceitável apenas ao prototipar
const props = defineProps(['status'])
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```js
const props = defineProps({
  status: String
})
```

```js
// Ainda melhor!

const props = defineProps({
  status: {
    type: String,
    required: true,

    validator: (value) => {
      return ['syncing', 'synced', 'version-conflict', 'error'].includes(
        value
      )
    }
  }
})
```

</div>
</div>

## Use chaves de identificação no `v-for` {#use-keyed-v-for}

`key` com `v-for` é _sempre_ exigido em componentes, de forma a manter o estado do componente interno até a subárvore. E mesmo para elementos, é uma boa prática manter o comportamento previsível, como a [constância de objetos](https://bost.ocks.org/mike/constancy/) em animações.

::: details Explicação Detalhada
Digamos que você tenha uma lista de tarefas:

```js
data() {
  return {
    todos: [
      {
        id: 1,
        text: 'Aprenda a usar v-for'
      },
      {
        id: 2,
        text: 'Aprenda a usar key'
      }
    ]
  }
}
```

E então você as separa alfabeticamente. Ao atualizar o DOM, o Vue irá aperfeiçoar a renderização para desempenhar o menor número possível de mutações no DOM. Isto pode significar apagar o primeiro elemento de tarefa, e então adicioná-lo novamente ao final da lista.

O problema é que há casos em que é importante não apagar qualquer elemento que permanecerá no DOM. Por exemplo, você pode querer usar `<transition-group>` para animar a ordenação da lista, ou manter o foco se o elemento renderizado é um `<input>`. Nestes casos, adicionar uma chave única para cada item (ex.: `:key="todo.id"`) irá dizer ao Vue como se comportar de forma mais previsível.

Em nossa experiência, o melhor é _sempre_ adicionar uma chave única, para que você e seu time nunca precisem se preocupar com esses casos extremos. Então, em raros cenários com questões críticas de desempenho onde a constância de objetos não é necessária, você pode fazer uma exceção de forma consciente.
:::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<ul>
  <li v-for="todo in todos">
    {{ todo.text }}
  </li>
</ul>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<ul>
  <li
    v-for="todo in todos"
    :key="todo.id"
  >
    {{ todo.text }}
  </li>
</ul>
```

</div>

## Evite `v-if` com `v-for` {#avoid-v-if-with-v-for}

**Nunca use `v-if` com `v-for` no mesmo elemento.**

Geralmente existem dois casos onde isso pode ser tentador:

- Para filtrar itens em uma lista (ex.: `v-for="user in users" v-if="user.isActive"`). Nestes casos, substitua `users` com um novo dado computado que retorne a sua lista filtrada (ex.: `activeUsers`).

- Para evitar renderizar uma lista se ela deverá ser escondida (ex.: `v-for="user in users" v-if="shouldShowUsers"`). Nestes casos, mova o `v-if` para o elemento pai. (ex.: `ul`, `ol`).

::: details Explicação Detalhada
Quando Vue processa diretrizes, o `v-if` tem uma prioridade maior do que o `v-for`, então para este modelo:

```vue-html
<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

Acontecerá um erro, porque a diretriz `v-if` deve ser examinada primeiro e a variável de iteração `user` não existe neste momento.

Isto pode ser arrumado ao se iterar sobre um dado computado, assim:

```js
computed: {
  activeUsers() {
    return this.users.filter(user => user.isActive)
  }
}
```

```vue-html
<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

Alternativamente, podemos usar uma tag `<template>` com `v-for` para envolver o elemento `<li>`:

```vue-html
<ul>
  <template v-for="user in users" :key="user.id">
    <li v-if="user.isActive">
      {{ user.name }}
    </li>
  </template>
</ul>
```

:::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

```vue-html
<ul>
  <template v-for="user in users" :key="user.id">
    <li v-if="user.isActive">
      {{ user.name }}
    </li>
  </template>
</ul>
```

</div>

## Use estilos de componente em escopo {#use-component-scoped-styling}

Para aplicações, estilos em um componente de nível maior `App` e em componentes de layout podem ser globais, mas todos os outros componentes devem utilizar estilo em escopo.

Isto é relevante apenas para [componentes de arquivo único](/guide/scaling-up/sfc). _Não_ é exigido que o [atributo `scoped`](https://vue-loader.vuejs.org/en/features/scoped-css.html) seja usado. O escopo pode ser realizado através de [módulos CSS](https://vue-loader.vuejs.org/en/features/css-modules), uma estratégia baseada em classes como [BEM](http://getbem.com/), ou outra biblioteca/convenção.

**Bibliotecas de componente, entretanto, devem preferir uma estratégia baseada em classes ao invés de usar o atributo `scoped`.**

Isto torna mais fácil a sobreposição de estilos internos, com nomes de classes de fácil leitura que não possuem especificidade alta, mas que muito improvavelmente resultarão em um conflito.

::: details Explicação Detalhada
Se você está desenvolvendo um projeto grande, trabalhando com outros desenvolvedores, ou às vezes incluindo algum HTML/CSS de terceiros (ex.: do Auth0), um escopo consistente irá garantir que seus estilos se apliquem somente aos componentes para que foram designados.

Além do atributo `scoped`, usar nomes de classe únicos podem ajudar a garantir que o CSS de terceiros não se apliquem em seu próprio HTML. Por exemplo, muitos projetos usam nomes de classe `button`, `btn`, ou `icon`, então mesmo ao não usar uma estratégia como o BEM, adicionar um prefixo específico do app e/ou específico do componente (ex.: `ButtonClose-Icon`) pode fornecer alguma proteção.
:::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<template>
  <button class="btn btn-close">×</button>
</template>

<style>
.btn-close {
  background-color: red;
}
</style>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<template>
  <button class="button button-close">×</button>
</template>

<!-- Usando o atributo `scoped` -->
<style scoped>
.button {
  border: none;
  border-radius: 2px;
}

.button-close {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button :class="[$style.button, $style.buttonClose]">×</button>
</template>

<!-- Usando módulos CSS -->
<style module>
.button {
  border: none;
  border-radius: 2px;
}

.buttonClose {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button class="c-Button c-Button--close">×</button>
</template>

<!-- Usando a convenção BEM -->
<style>
.c-Button {
  border: none;
  border-radius: 2px;
}

.c-Button--close {
  background-color: red;
}
</style>
```

</div>

---

---
url: /style-guide/rules-strongly-recommended.md
---
# Regras Prioridade B: Fortemente Recomendado {#priority-b-rules-strongly-recommended}

Estas regras foram verificadas para melhorar a legibilidade e/ou a experiência do desenvolvedor na maioria dos projetos. Seu código ainda funcionará se você violá-las, mas as violações devem ser raras e bem justificadas.

## Arquivos de componente {#component-files}

**Quando houver um sistema de compilação disponível para concatenar arquivos, cada componente deve estar em seu próprio arquivo.**

Isto ajuda você a encontrar mais rapidamente um componente quando precisar editá-lo ou verificar como usá-lo.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```js
app.component('TodoList', {
  // ...
})

app.component('TodoItem', {
  // ...
})
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- TodoList.js
|- TodoItem.js
```

```
components/
|- TodoList.vue
|- TodoItem.vue
```

</div>

## Notação de nomes de Componentes de Arquivo Único {#single-file-component-filename-casing}

**Nomes de arquivo de [Componentes de Arquivo Único](/guide/scaling-up/sfc) devem ser sempre PascalCase ou kebab-case.**

A notação com PascalCase funciona melhor com o preenchimento automático de editores de código, pois é consistente com a forma que referenciamos componentes em JS(X) e modelos, onde possível. Entretanto, diferentes tipos de nomes de arquivo podem às vezes causar problemas em sistemas de arquivo insensíveis a maiúsculas e minúsculas, é a razão de o kebab-case ser perfeitamente aceitável.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- mycomponent.vue
```

```
components/
|- myComponent.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- MyComponent.vue
```

```
components/
|- my-component.vue
```

</div>

## Nomes de componentes base {#base-component-names}

**Componentes base (também conhecidos como componentes de apresentação, burros, ou puros) que aplicam estilos e convenções específicos da aplicação devem começar com um prefixo específico, como `Base`, `App` ou `V`.**

::: details Explicação Detalhada
Estes componentes estabelecem a base para o estilo e o comportamento consistentes na sua aplicação. Eles podem conter **somente**:

- Elementos HTML,
- outros componentes base, e
- componentes UI de terceiros.

Mas eles **nunca** irão conter um estado global (ex.: de uma store [Pinia](https://pinia.vuejs.org/)).

Seus nomes frequentemente incluem o nome do elemento que eles envolvem (ex.: `BaseButton`, `BaseTable`), a não ser que nenhum elemento exista para seu propósito específico (ex.: `BaseIcon`). Se você construir componentes similares para um contexto mais específico, eles quase sempre consumirão estes componentes (ex.: `BaseButton` será usado em `ButtonSubmit`)..

Algumas vantagens desta convenção:

- Quando organizado alfabeticamente em editores, os componentes base da aplicação serão listados em conjunto, tornando-os mais fáceis de identificar.

- Como nomes de componente sempre possuem multipalavras, esta convenção previne que você tenha que escolher um prefixo arbitrário para simples componentes envoltórios (ex.: `MyButton`, `VueButton`).

- Como estes componentes são frequentemente usados, você pode simplesmente torná-los globais ao invés de importá-los em todos os lugares. Um prefixo torna isto possível com o Webpack:

  ```js
  const requireComponent = require.context(
    './src',
    true,
    /Base[A-Z]\w+\.(vue|js)$/
  )
  requireComponent.keys().forEach(function (fileName) {
    let baseComponentConfig = requireComponent(fileName)
    baseComponentConfig =
      baseComponentConfig.default || baseComponentConfig
    const baseComponentName =
      baseComponentConfig.name ||
      fileName.replace(/^.+\//, '').replace(/\.\w+$/, '')
    app.component(baseComponentName, baseComponentConfig)
  })
  ```

  :::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue
```

```
components/
|- AppButton.vue
|- AppTable.vue
|- AppIcon.vue
```

```
components/
|- VButton.vue
|- VTable.vue
|- VIcon.vue
```

</div>

## Nomes de componentes de instância única {#single-instance-component-names}

**Componentes que devem ter somente uma única instância ativa devem começar com o prefixo `The`, para denotar que poderá existir somente um.**

Isto não significa que o componente é usado apenas em uma única página, mas que será usado uma vez _por página_. Estes componentes nunca aceitam quaisquer propriedades, pois são específicos à sua aplicação, e não ao contexto dentro da sua aplicação. Se você encontrar a necessidade de adicionar propriedades, é uma boa indicação de que este na verdade é um componente reutilizável que é usado uma vez por página _por ora_.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- Heading.vue
|- MySidebar.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- TheHeading.vue
|- TheSidebar.vue
```

</div>

## Nomes de componentes estreitamente acoplados {#tightly-coupled-component-names}

**Componentes filho que são estreitamente acoplados com seus pais devem incluir o nome do componente pai como prefixo.**

Se um componente fizer sentido apenas no contexto de um único componente pai, este relacionamento deve ser evidente em seu nome. Como editores tipicamente organizam os arquivos alfabeticamente, isto irá ajudar a manter estes arquivos relacionados próximos uns dos outros.

::: details Explicação Detalhada
Você pode ser tentado a resolver este problema aninhando componentes filho em diretórios nomeados com base em seu pai. Por exemplo:

```
components/
|- TodoList/
   |- Item/
      |- index.vue
      |- Button.vue
   |- index.vue
```

ou:

```
components/
|- TodoList/
   |- Item/
      |- Button.vue
   |- Item.vue
|- TodoList.vue
```

Isto não é recomendado, pois resulta em:

- Muitos arquivos com nomes similares, fazendo com que trocas de arquivos rápidas em editores de código tornem-se mais difíceis.
- Muitos subdiretórios aninhados, o que aumenta o tempo para procurar componentes na barra lateral do editor.
  :::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
```

```
components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
```

```
components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue
```

</div>

## Ordem das palavras em nomes de componente {#order-of-words-in-component-names}

**Nomes de componente devem começar com palavras de nível mais alto (muitas vezes a mais geral) e terminar com palavras modificadoras descritivas.**

::: details Explicação Detalhada
Você pode estar se perguntando:

> "Por que forçamos nomes de componentes a usar uma linguagem menos natural?"

No inglês natural, adjetivos e outros descritores aparecem geralmente antes dos substantivos, enquanto exceções exigem palavras conectoras. Por exemplo:

- Café _com_ leite
- Sopa _do_ dia
- Visitante _do_ museu

Você definitivamente pode incluir estas palavras conectoras no nome dos componentes se quiser, mas a ordem ainda é importante.

Também note que **o que é considerado "nível mais alto" será contextual à sua aplicação**. Por exemplo, imagine uma aplicação com um formulário de busca. Ele pode incluir componentes como este:

```
components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue
```

Como você pode perceber, é difícil ver quais componentes são específicos da busca. Agora vamos renomear os componentes de acordo com a regra:

```
components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputExcludeGlob.vue
|- SearchInputQuery.vue
|- SettingsCheckboxLaunchOnStartup.vue
|- SettingsCheckboxTerms.vue
```

Como editores tipicamente organizam os arquivos alfabeticamente, todas as relações importantes entre componentes agora estão evidentes à vista.

Você pode ser tentado a resolver este problema diferentemente, aninhando todos os componentes de busca em um diretório "search", e todos os componentes de configuração em um diretório "settings". Recomendamos considerar esta abordagem apenas em aplicações muito grandes (ex.: mais de 100 componentes), pelas seguintes razões:

- Geralmente leva mais tempo navegar por subdiretórios aninhados, do que percorrer um único diretório `components`.
- Conflitos com nomes (ex.: múltiplos componentes `ButtonDelete.vue`) tornam mais difícil navegar rapidamente para um componente específico no editor de código.
- Refatorar torna-se mais difícil, já que buscar-e-substituir nem sempre será suficiente para alterar as referências relativas para um componente deslocado.
  :::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue
```

</div>

## Componentes com autofechamento {#self-closing-components}

**Componentes sem conteúdo devem se autofechar em [Componentes de Arquivo Único](/guide/scaling-up/sfc), modelos string, e [JSX](/guide/extras/render-function#jsx-tsx) - mas nunca em modelos DOM.**

Componentes que se fecham automaticamente informam não apenas que não possuem conteúdo, mas são **feitos** para não terem conteúdo. É a diferença entre uma página em branco em um livro e uma rotulada "Esta página foi intencionalmente deixada em branco". Seu código também é mais limpo sem a etiqueta de fechamento desnecessária.

Infelizmente, HTML não permite que elementos customizados tenham fechamento próprio - somente [elementos "void" oficiais](https://www.w3.org/TR/html/syntax.html#void-elements). É por isso que a estratégia só é possível quando o compilador de modelos do Vue pode alcançar o modelo antes do DOM, e então servir o HTML conforme especificado ao DOM.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<!-- Em Componentes de Arquivo Único, modelos string, e JSX -->
<MyComponent></MyComponent>
```

```vue-html
<!-- Em modelos DOM -->
<my-component/>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<!-- Em Componentes de Arquivo Único, modelos string, e JSX -->
<MyComponent/>
```

```vue-html
<!-- Em modelos DOM -->
<my-component></my-component>
```

</div>

## Notação de nomes de componente em modelos {#component-name-casing-in-templates}

**Na maioria dos projetos, os nomes de componente devem ser sempre PascalCase em [Componentes de Arquivo Único](/guide/scaling-up/sfc) e modelos em string - e kebab-case em templates DOM.**

PascalCase possui algumas vantagens sobre kebab-case:

- Editores podem autocompletar nomes de componentes em modelos, pois o PascalCase também é utilizado no JavaScript.
- `<MyComponent>` é mais distintivo visualmente do que um simples elemento HTML de palavra única como `<my-component>`, pois há duas diferenças em caracteres (duas maiúsculas), ao invés de só uma (um hífen).
- Se você usar qualquer elemento personalizado em seus modelos que não do Vue, como um Web Component, PascalCase garante que seus componentes Vue permaneçam distintamente visíveis.

Infelizmente, devido à insensibilidade do HTML em relação a maiúsculas e minúsculas, modelos DOM ainda precisam utilizar kebab-case.

Também note que se você já investiu bastante em kebab-case, a consistência de convenções HTML e ser capaz de usar o mesmo padrão pelos seus projetos pode ser mais importante do que as vantagens listadas acima. Nestes casos, **utilizar kebab-case em todo lugar também é aceitável.**

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<!-- Em Componentes de Arquivo Único e modelos string -->
<mycomponent/>
```

```vue-html
<!-- Em Componentes de Arquivo Único e modelos string -->
<myComponent/>
```

```vue-html
<!-- Em modelos DOM -->
<MyComponent></MyComponent>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<!-- Em Componentes de Arquivo Único e modelos string -->
<MyComponent/>
```

```vue-html
<!-- Em modelos DOM -->
<my-component></my-component>
```

OU

```vue-html
<!-- Em todo lugar -->
<my-component></my-component>
```

</div>

## Notação de nomes de componentes em JS/JSX {#component-name-casing-in-js-jsx}

**Nomes de componentes em JS/[JSX](/guide/extras/render-function#jsx-tsx) devem ser sempre PascalCase, apesar de que podem ser kebab-case dentro de strings para aplicações mais simples, que usam apenas registros globais de componentes  através de `app.component`.**

::: details Explicação Detalhada
No JavaScript, PascalCase é a convenção para classes e construtores - essencialmente, qualquer coisa que possa ter instâncias diferentes. Componentes Vue também possuem instâncias, então faz sentido também usar PascalCase. Como um benefício extra, usar PascalCase com JSX (e modelos) permite que os leitores do código consigam distinguir mais facilmente entre componentes e elementos HTML. 

Entretanto, para aplicações que usam **apenas** definições globais de componente via `app.component`, recomendamos que kebab-case seja usado. Os motivos são:

- É raro que componentes globais sejam referenciados no JavaScript, então seguir a convenção para o JavaScript faz menos sentido.
- Essas aplicações sempre incluem muito modelos dentro do DOM, onde [kebab-case **deve** ser usado](#component-name-casing-in-templates).
  :::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```js
app.component('myComponent', {
  // ...
})
```

```js
import myComponent from './MyComponent.vue'
```

```js
export default {
  name: 'myComponent'
  // ...
}
```

```js
export default {
  name: 'my-component'
  // ...
}
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```js
app.component('MyComponent', {
  // ...
})
```

```js
app.component('my-component', {
  // ...
})
```

```js
import MyComponent from './MyComponent.vue'
```

```js
export default {
  name: 'MyComponent'
  // ...
}
```

</div>

## Palavras completas em nomes de componente {#full-word-component-names}

**Nomes de componente devem preferir palavras completas ao invés de abreviações.**

O preenchimento automático em editores torna o custo de escrever nomes maiores muito baixo, enquanto a clareza que eles fornecem é inestimável. Abreviações incomuns, em particular, devem sempre ser evitadas.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```
components/
|- SdSettings.vue
|- UProfOpts.vue
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```
components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue
```

</div>

## Notação do nome de propriedades {#prop-name-casing}

**Nomes de propriedade devem sempre usar camelCase durante a declaração. Quando usadas dentro de modelos DOM, propriedades devem utilizar kebab-case. Modelos em Componentes de Arquivo Único e [JSX](/guide/extras/render-function#jsx-tsx) podem usar props tanto kebab-case ou camelCase. A notação deve ser consistente - se você escolher props com camelCase, certifique-se de não usar outras com kebab-case em sua aplicação**

<div class="style-example style-example-bad">
<h3>Ruim</h3>

<div class="options-api">

```js
props: {
  'greeting-text': String
}
```

</div>

<div class="composition-api">

```js
const props = defineProps({
  'greeting-text': String
})
```

</div>

```vue-html
// para modelos DOM
<welcome-message greetingText="hi"></welcome-message>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

<div class="options-api">

```js
props: {
  greetingText: String
}
```

</div>

<div class="composition-api">

```js
const props = defineProps({
  greetingText: String
})
```

</div>

```vue-html
// para SFC - por favor certifique-se de que sua notação é consistente em seu projeto
// você pode usar qualquer convenção mas não recomendamos misturar os dois estilos diferentes de notação
<WelcomeMessage greeting-text="hi"/>
// ou
<WelcomeMessage greetingText="hi"/>
```

```vue-html
// para modelos DOM
<welcome-message greeting-text="hi"></welcome-message>
```

</div>

## Elementos com múltiplos atributos {#multi-attribute-elements}

**Elementos com múltiplos atributos devem sempre ocupar múltiplas linhas, com um atributo por linha.**

No JavaScript, dividir objetos com múltiplas propriedades por múltiplas linhas é considerada uma boa convenção, pois é muito mais fácil de se ler. Nossos modelos e [JSX](/guide/extras/render-function#jsx-tsx) merecem a mesma consideração.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
```

```vue-html
<MyComponent foo="a" bar="b" baz="c"/>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>
```

```vue-html
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>
```

</div>

## Expressões simples em modelos {#simple-expressions-in-templates}

**Modelos de componentes devem incluir apenas expressões simples, com expressões mais complexas sendo refatoradas em propriedades computadas ou métodos.**

Expressões complexas em seus templates os tornam menos declarativos. Devemos nos esforçar para descrever _o quê_ deve aparecer, não _como_ estamos computando aquele valor. Propriedades computadas e métodos também permitem que o código seja reutilizado.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
{{
  fullName.split(' ').map((word) => {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<!-- In a template -->
{{ normalizedFullName }}
```

<div class="options-api">

```js
// A expressão complexa foi movida para uma propriedade computada
computed: {
  normalizedFullName() {
    return this.fullName.split(' ')
      .map(word => word[0].toUpperCase() + word.slice(1))
      .join(' ')
  }
}
```

</div>

<div class="composition-api">

```js
// A expressão complexa foi movida para uma propriedade computada
const normalizedFullName = computed(() =>
  fullName.value
    .split(' ')
    .map((word) => word[0].toUpperCase() + word.slice(1))
    .join(' ')
)
```

</div>

</div>

## Propriedades computadas simples {#simple-computed-properties}

**Propriedades computadas complexas devem ser divididas em propriedades computadas mais simples sempre que possível.**

::: details Explicação Detalhada
Propriedades computadas mais simples e bem nomeadas são:

- **Mais fáceis de testar**

  Quando cada propriedade computada contém somente uma expressão muito simples, com poucas dependências, é muito mais fácil escrever testes confirmando que elas funcionam corretamente.

- **Mais fáceis de ler**

  Simplificar propriedades computadas força você a dar a cada valor um nome descritivo, mesmo que não seja reutilizado. Isso torna mais fácil para outros desenvolvedores (e você no futuro) a focarem no código que manipulam e no que está acontecendo.

- **Mais adaptáveis a novas exigências**

  Qualquer valor que possa ser nomeado pode ser útil para a visualização. Por exemplo, podemos decidir mostrar a mensagem informando ao usuário quanto dinheiro ele economizou. Também podemos decidir como calcular taxas das vendas, mas talvez mostrá-los separadamente, ao invés de uma parte do preço final.

  Propriedades computadas pequenas e focadas fazem menos pressuposições sobre como a informação será usada, e portanto exigem menos refatoramento conforme as exigências mudam.
  :::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

<div class="options-api">

```js
computed: {
  price() {
    const basePrice = this.manufactureCost / (1 - this.profitMargin)
    return (
      basePrice -
      basePrice * (this.discountPercent || 0)
    )
  }
}
```

</div>

<div class="composition-api">

```js
const price = computed(() => {
  const basePrice = manufactureCost.value / (1 - profitMargin.value)
  return basePrice - basePrice * (discountPercent.value || 0)
})
```

</div>

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

<div class="options-api">

```js
computed: {
  basePrice() {
    return this.manufactureCost / (1 - this.profitMargin)
  },

  discount() {
    return this.basePrice * (this.discountPercent || 0)
  },

  finalPrice() {
    return this.basePrice - this.discount
  }
}
```

</div>

<div class="composition-api">

```js
const basePrice = computed(
  () => manufactureCost.value / (1 - profitMargin.value)
)

const discount = computed(
  () => basePrice.value * (discountPercent.value || 0)
)

const finalPrice = computed(() => basePrice.value - discount.value)
```

</div>

</div>

## Aspas em valores de atributos {#quoted-attribute-values}

**Valores de atributos HTML não vazios devem sempre estar dentro de aspas (simples ou duplas, a qual não for usada no JS).**

Enquanto valores de atributo sem qualquer espaço não exigem aspas no HTML, esta prática frequentemente leva a _evitar_ espaços, tornando os valores dos atributos menos legíveis.

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<input type=text>
```

```vue-html
<AppSidebar :style={width:sidebarWidth+'px'}>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<input type="text">
```

```vue-html
<AppSidebar :style="{ width: sidebarWidth + 'px' }">
```

</div>

## Abreviação de diretrizes {#directive-shorthands}

**Abreviações de diretrizes (`:` para `v-bind:`, `@` para `v-on:` e `#` para `v-slot`) devem ser usadas sempre ou nunca.**

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<input
  v-bind:value="newTodoText"
  :placeholder="newTodoInstructions"
>
```

```vue-html
<input
  v-on:input="onInput"
  @focus="onFocus"
>
```

```vue-html
<template v-slot:header>
  <h1>Here might be a page title</h1>
</template>

<template #footer>
  <p>Here's some contact info</p>
</template>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<input
  :value="newTodoText"
  :placeholder="newTodoInstructions"
>
```

```vue-html
<input
  v-bind:value="newTodoText"
  v-bind:placeholder="newTodoInstructions"
>
```

```vue-html
<input
  @input="onInput"
  @focus="onFocus"
>
```

```vue-html
<input
  v-on:input="onInput"
  v-on:focus="onFocus"
>
```

```vue-html
<template v-slot:header>
  <h1>Aqui pode ser um título de página</h1>
</template>

<template v-slot:footer>
  <p>Aqui alguma informação de contato</p>
</template>
```

```vue-html
<template #header>
  <h1>Aqui pode ser um título de página</h1>
</template>

<template #footer>
  <p>Aqui alguma informação de contato</p>
</template>
```

</div>

---

---
url: /style-guide/rules-recommended.md
---
# Regras Prioridade C: Recomendado {#priority-c-rules-recommended}

Onde múltiplas opções igualmente boas existem, uma escolha arbitrária pode ser feita para garantir consistência. Nestas regras, descrevemos cada opção aceitável e sugerimos uma escolha padrão. Isso significa que você pode ficar à vontade para realizar uma escolha diferente em sua própria base de código, desde que você seja consistente e tenha um bom motivo. Mas por favor, tenha um bom motivo! Ao adotar o padrão da comunidade, você irá:

1. Treinar seu cérebro para analisar mais facilmente a maior parte do código da comunidade que encontrar
2. Ser capaz de copiar e colar a maior parte dos exemplos de código da comunidade sem modificações
3. Frequentemente encontrar novos parceiros que já estão acostumados ao seu estilo de código preferido, ao menos no âmbito Vue

## Ordem das opções de componente/instância {#component-instance-options-order}

**Opções de componente/instância devem ser ordenadas consistentemente.**

Esta é a ordem padrão que recomendamos para opções de componente. Elas são divididas em categorias, então você saberá onde adicionar novas propriedades de plugins.

1. **Conscientização Global** (exige conhecimento além do componente)

   - `name`

2. **Opções do Compilador de Modelo** (mudam a maneira que modelos são compilados)

   - `compilerOptions`

3. **Dependências de Modelo** (recursos usados no modelo)

   - `components`
   - `directives`

4. **Composição** (mescla propriedades nas opções)

   - `extends`
   - `mixins`
   - `provide`/`inject`

5. **Interface** (a interface para o componente)

   - `inheritAttrs`
   - `props`
   - `emits`

6. **API de Composição** (ponto de entrada para usar a API de Composição)

   - `setup`

7. **Estado Local** (propriedades locais reativas)

   - `data`
   - `computed`

8. **Eventos** (_callbacks_ acionados por eventos reativos)

   - `watch`
   - Eventos do Ciclo de Vida (na ordem em que são chamados)
     - `beforeCreate`
     - `created`
     - `beforeMount`
     - `mounted`
     - `beforeUpdate`
     - `updated`
     - `activated`
     - `deactivated`
     - `beforeUnmount`
     - `unmounted`
     - `errorCaptured`
     - `renderTracked`
     - `renderTriggered`

9. **Propriedades não reativas** (propriedades da instância independentes da reatividade do sistema)

   - `methods`

10. **Interpretação** (a descrição declarativa da saída do componente)
    - `template`/`render`

## Ordem dos atributos de elementos {#element-attribute-order}

**Os atributos dos elementos (incluindo componentes) devem ser ordenados consistentemente.**

Esta é a ordenação padrão que recomendamos para opções do componente. Elas estão divididas em categorias, então você saberá onde adicionar atributos e diretivas personalizadas.

1. **Definição** (fornece as opções do componente)

   - `is`

2. **Interpretação de Listas** (cria múltiplas variações do mesmo elemento)

   - `v-for`

3. **Condicionais** (se o elemento é interpretado/mostrado)

   - `v-if`
   - `v-else-if`
   - `v-else`
   - `v-show`
   - `v-cloak`

4. **Modificadores de Interpetação** (mudam a forma que o elemento é interpretado)

   - `v-pre`
   - `v-once`

5. **Conscientização Global** (exige conhecimento além do componente)

   - `id`

6. **Atributos Únicos** (atributos que exigem valores únicos)

   - `ref`
   - `key`

7. **Vinculação Bidirecional** (combina vinculações e eventos)

   - `v-model`

8. **Outros Atributos** (todos os atributos não especificados vinculados ou não vinculados)

9. **Eventos** (ouvintes de evento dos componentes)

   - `v-on`

10. **Conteúdo** (substituem o conteúdo do elemento)
    - `v-html`
    - `v-text`

## Linhas vazias em opções de componente/instância {#empty-lines-in-component-instance-options}

**Você pode querer adicionar uma linha vazia entre propriedades de várias linhas, especialmente se as opções não couberem mais na sua tela sem rolagem.**

Quando os componentes começam a parecer abarrotados ou difíceis de se ler, adicionar espaços entre propriedades com múltiplas linhas pode torná-lo fácil de se ler novamente. Em alguns editores, como o Vim, opções de formatação como essa podem também tornar mais fácil de se navegar com o teclado.

<div class="style-example style-example-good">
<h3>Bom</h3>

```js
props: {
  value: {
    type: String,
    required: true
  },

  focused: {
    type: Boolean,
    default: false
  },

  label: String,
  icon: String
},

computed: {
  formattedValue() {
    // ...
  },

  inputClasses() {
    // ...
  }
}
```

```js
// Não ter espaços também é bom, desde que o componente
// seja fácil de ler e de navegar.
props: {
  value: {
    type: String,
    required: true
  },
  focused: {
    type: Boolean,
    default: false
  },
  label: String,
  icon: String
},
computed: {
  formattedValue() {
    // ...
  },
  inputClasses() {
    // ...
  }
}
```

</div>

## Ordem de elementos de nível superior de Componentes de Arquivo Único {#single-file-component-top-level-element-order}

**[Componentes de Arquivo Único](/guide/scaling-up/sfc) devem sempre ordenar os identificadores `<script>`, `<template>`, e `<style>` consistentemente, com o `<style>` por último, porque ao menos uma das outras duas é sempre necessária.**

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<style>/* ... */</style>
<script>/* ... */</script>
<template>...</template>
```

```vue-html
<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>
```

```vue-html
<!-- ComponentA.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>
```

</div>

---

---
url: /style-guide/rules-use-with-caution.md
---
# Regras Prioridade D: Use com Cautela {#priority-d-rules-use-with-caution}

Algumas funcionalidades do Vue existem para acomodar casos extremos raros ou suavizar migrações de uma base de código legado. Entretanto, ao serem utilizadas excessivamente, elas podem tornar o seu código mais difícil de manter ou até mesmo se tornarem uma fonte de bugs. Estas regras demonstram funcionalidades possivelmente arriscadas, descrevendo quando e porquê elas devem ser evitadas.

## Seletores de elemento com `scoped` {#element-selectors-with-scoped}

**Seletores de elemento devem ser evitados com `scoped`.**

Prefira seletores de classe em vez de seletores de elemento nos estilos `scoped`, porque um grande número de seletores de elemento diminuem a velocidade.

::: details Explicação Detalhada
Para definir estilos em escopo, o Vue adiciona um atributo único aos elementos componentes, algo como `data-v-f3f3eg9`. Então os seletores são modificados para que apenas elementos correspondentes com este atributo sejam selecionados (e.g. `button[data-v-f3f3eg9]`).

O problema é que um grande número de seletores elemento-atributo (e.g. `button[data-v-f3f3eg9]`) serão consideravelmente mais lentos do que seletores classe-atributo (e.g. `.btn-close[data-v-f3f3eg9]`), então seletores de classe devem ser escolhidos sempre quando possível.
:::

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```vue-html
<template>
  <button>×</button>
</template>

<style scoped>
button {
  background-color: red;
}
</style>
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```vue-html
<template>
  <button class="btn btn-close">×</button>
</template>

<style scoped>
.btn-close {
  background-color: red;
}
</style>
```

</div>

## Comunicação pai-filho implícita {#implicit-parent-child-communication}

**Props e eventos devem ser preferíveis para a comunicação entre componentes pai-filho, ao invés de `this.$parent` ou de realizar mutações em props.**

Uma aplicação Vue ideal segue props para baixo, eventos para cima. Manter-se a esta convenção tornará os seus componentes mais fáceis de se entender. Entretanto, existem casos extremos em que a mutação de props ou `this.$parent` pode simplificar dois componentes já profudamente acoplados.

O problema é, há muitos outros casos _simples_ onde esses padrões podem ser convenientes. Cuidado: não fique tentando a trocar simplicidade (estar apto a entender o fluxo do seu estado) por conveniência a curto-prazo (escrever menos código).

<div class="style-example style-example-bad">
<h3>Ruim</h3>

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  template: '<input v-model="todo.text">'
})
```

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  methods: {
    removeTodo() {
      this.$parent.todos = this.$parent.todos.filter(
        (todo) => todo.id !== vm.todo.id
      )
    }
  },

  template: `
    <span>
      {{ todo.text }}
      <button @click="removeTodo">
        ×
      </button>
    </span>
  `
})
```

</div>

<div class="style-example style-example-good">
<h3>Bom</h3>

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  emits: ['input'],

  template: `
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})
```

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  emits: ['delete'],

  template: `
    <span>
      {{ todo.text }}
      <button @click="$emit('delete')">
        ×
      </button>
    </span>
  `
})
```

</div>

---

---
url: /guide/scaling-up/routing.md
---
# Roteamento {#routing}

## Roteamento do Lado do Cliente vs Lado do Servidor {#client-side-vs-server-side-routing}

Rotear no lado do servidor significa que o servidor envia uma resposta baseada no caminho da URL que o utilizador visita. Quando clicamos sobre uma ligação numa aplicação da Web interpretada do lado do servidor tradicional, o navegador recebe uma resposta de HTML a partir do servidor e recarrega a página inteira com o novo HTML.

Numa [Aplicação de Página Única](https://developer.mozilla.org/en-US/docs/Glossary/SPA) (SPA, sigla em Inglês), no entanto, a JavaScript do lado do cliente pode intercetar a navegação, pedir dinamicamente novos dados, e atualizar a página atual sem recarregamento completo da página. Isto normalmente resulta numa experiência de uso mais elegante, especialmente para os casos de uso que são mais como "aplicações" de verdade, onde o utilizador é esperado realizar muitas interações sobre um longo período de tempo.

Em tais aplicações de página única, o "roteamento" é feito sobre o lado do cliente, no navegador. Um roteador do lado do cliente é responsável por gerir a visão interpretada da aplicação usando as APIs do navegador tais como [API de História](https://developer.mozilla.org/en-US/docs/Web/API/History) ou o [evento `hashchange`](https://developer.mozilla.org/en-US/docs/Web/API/Window/hashchange_event).

## Roteador Oficial {#official-router}

<!-- TODO update links -->
<div>
  <VueSchoolLink href="https://vueschool.io/courses/vue-router-4-for-everyone" title="Curso Grátis de Vue Router">
    Assistir um curso gratuito na Vue School
  </VueSchoolLink>
</div>

A Vue está bem adaptada para construir aplicações de página única. Para a maioria das aplicações de página única, é recomendado usar a [biblioteca Vue Router](https://github.com/vuejs/router) suportada oficialmente. Para mais detalhes, consultar a [documentação](https://vue-router-docs-pt.netlify.app/) da Vue Router.

## Roteamento Simples do Zero {#simple-routing-from-scratch}

Se apenas precisarmos dum roteamento muito simples e não desejarmos envolver uma biblioteca roteadora completa, podemos fazer isto com os [Componentes Dinâmicos](/guide/essentials/component-basics#dynamic-components) e atualizar o estado do componente atual ouvindo os [eventos de `hashcache`](https://developer.mozilla.org/en-US/docs/Web/API/Window/hashchange_event) do navegador ou usando a [API de História](https://developer.mozilla.org/en-US/docs/Web/API/History).

Eis um exemplo simples:

<div class="composition-api">

```vue
<script setup>
import { ref, computed } from 'vue'
import Home from './Home.vue'
import About from './About.vue'
import NotFound from './NotFound.vue'

const routes = {
  '/': Home,
  '/about': About
}

const currentPath = ref(window.location.hash)

window.addEventListener('hashchange', () => {
  currentPath.value = window.location.hash
})

const currentView = computed(() => {
  return routes[currentPath.value.slice(1) || '/'] || NotFound
})
</script>

<template>
  <a href="#/">Home</a> |
  <a href="#/about">About</a> |
  <a href="#/non-existent-path">Broken Link</a>
  <component :is="currentView" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNptUk1vgkAQ/SsTegAThZp4MmhikzY9mKanXkoPWxjLRpgly6JN1P/eWb5Eywlm572ZN2/m5GyKwj9U6CydsIy1LAyUaKpiHZHMC6UNnEDjbgqxyovKYAIX2GmVg8sktwe9qhzbdz+wga15TW++VWX6fB3dAt6UeVEVJT2me2hhEcWKSgOamVjCCk4RAbiBu6xbT5tI2ML8VDeI6HLlxZXWSOZdmJTJPJB3lJSoo5+pWBipyE9FmU4soU2IJHk+MGUrS4OE2nMtIk4F/aA7BW8Cq3WjYlDbP4isQu4wVp0F1Q1uFH1IPDK+c9cb1NW8B03tyJ//uvhlJmP05hM4n60TX/bb2db0CoNmpbxMDgzmRSYMcgQQCkjZhlXkPASRs7YmhoFYw/k+WXvKiNrTcQgpmuFv7ZOZFSyQ4U9a7ZFgK2lvSTXFDqmIQbCUJTMHFkQOBAwKg16kM3W6O7K3eSs+nbeK+eee1V/XKK0dY4Q3vLhR6uJxMUK8/AFKaB6k)

</div>

<div class="options-api">

```vue
<script>
import Home from './Home.vue'
import About from './About.vue'
import NotFound from './NotFound.vue'

const routes = {
  '/': Home,
  '/about': About
}

export default {
  data() {
    return {
      currentPath: window.location.hash
    }
  },
  computed: {
    currentView() {
      return routes[this.currentPath.slice(1) || '/'] || NotFound
    }
  },
  mounted() {
    window.addEventListener('hashchange', () => {
		  this.currentPath = window.location.hash
		})
  }
}
</script>

<template>
  <a href="#/">Home</a> |
  <a href="#/about">About</a> |
  <a href="#/non-existent-path">Broken Link</a>
  <component :is="currentView" />
</template>
```

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNptUstO6zAQ/ZVR7iKtVJKLxCpKK3Gli1ggxIoNZmGSKbFoxpEzoUi0/87YeVBKNonHPmfOmcdndN00yXuHURblbeFMwxtFpm6sY7i1NcLW2RriJPWBB8bT8/WL7Xh6D9FPwL3lG9tROWHGiwGmqLDUMjhhYgtr+FQEEKdxFqRXfaR9YrkKAoqOnocfQaDEre523PNKzXqx7M8ADrlzNEYAReccEj9orjLYGyrtPtnZQrOxlFS6rXqgZJdPUC5s3YivMhuTDCkeDe6/dSalvognrkybnIgl7c4UuLhcwuHgS3v2/7EPvzRruRXJ7/SDU12W/98l451pGQndIvaWi0rTK8YrEPx64ymKFQOce5DOzlfs4cdlkA+NzdNpBSRgrJudZpQIINdQOdyuVfQnVdHGzydP9QYO549hXIII45qHkKUL/Ail8EUjBgX+z9k3JLgz9OZJgeInYElAkJlWmCcDUBGkAsrTyWS0isYV9bv803x1OTiWwzlrWtxZ2lDGDO90mWepV3+vZojHL3QQKQE=)

</div>

---

---
url: /guide/best-practices/security.md
---
# Segurança {#security}

## Relatório de Vulnerabilidades {#reporting-vulnerabilities}

Quando uma vulnerabilidade é reportada, ela imediatamente se torna nossa principal preocupação, com um colaborar em tempo integral largando tudo para trabalhar nela. Para relatar uma vulnerabilidade, envie um e-mail para [security@vuejs.org](mailto:security@vuejs.org).

Embora a descoberta de novas vulnerabilidades seja rara, também recomendamos sempre usar as versões mais recentes do Vue e suas bibliotecas oficiais para garatinr que sua aplicação permaneça a mais segura possível.

## Regra Nº1: Nunca Usar Modelos de Marcação Duvidosos {#rule-no-1-never-use-non-trusted-templates}

A regra de segurança mais fundamental ao usar o Vue é **nunca usar conteúdo não confiável como modelo de marcação do componente**. Fazer isso equivale a permitir a execução arbitrária de JavaScript na sua aplicação - e pior, pode levar a violações se o código for executado durante a renderização no lado do servidor. Um exemplo desse uso:

```js
Vue.createApp({
  template: `<div>` + userProvidedString + `</div>` // NUNCA FAÇA ISTO
}).mount('#app')
```

Os modelos de marcação Vue são compilados em JavaScript, e as expressões dentro dos modelos de marcação serão executadas como parte do processo de renderização. Embora as expressões sejam avaliadas em relação a um contexto de renderização específico, devido à complexidade dos potenciais ambientes de execução global, é inviável para uma estrutura como o Vue protegê-lo completamente da possível execução de código malicioso sem sofrer com as despesas gerais de desempenho irrealistas. A maneira mais direta de evitar essa categoria de problemas é garantir que o conteúdo dos seus modelos Vue seja sempre confiável e totalmente controlado por você.

## O Que Vue Faz Para Proteger-te {#what-vue-does-to-protect-you}

### Conteúdo HTML {#html-content}

Seja usando os modelos de marcação ou funções de renderização, o conteúdo é escapado automaticamente. Isto significa que neste modelo:

```vue-html
<h1>{{ userProvidedString }}</h1>
```

Se `userProvidedString` continha:

```js
'<script>alert("hi")</script>'
```

Então seria escapado para o seguinte HTML:

```vue-html
&lt;script&gt;alert(&quot;hi&quot;)&lt;/script&gt;
```

Assim evitando a injeção de script. Este escapamento é feito usando as APIs nativas do navegador, como `textContent`, assim uma vulnerabilidade apenas pode existir se o próprio navegador estiver vulnerável.

### Vínculação de Atributos {#attribute-bindings}

Similarmente, os vínculos de atributos dinâmicos também são escapados automaticamente. Isto significa que neste modelo de marcação:

```vue-html
<h1 :title="userProvidedString">
  hello
</h1>
```

Se `userProvidedString` continha:

```js
'" onclick="alert(\'hi\')'
```

Então seria escapado para o seguinte HTML:

```vue-html
&quot; onclick=&quot;alert('hi')
```

Assim evitando o fechamento do atributo `title` para injetar HTML novo e arbitrário. Este escapamento é feito usando as APIs nativas do navegador, como `setAttribute`, assim uma vulnerabilidade apenas pode existir se o próprio navegador estiver vulnerável.

## Perigos Potenciais {#potential-dangers}

Em qualquer aplicação web, permitir conteúdo não desinfetado, fornecido pelo usuário ser executado como HTML, CSS, ou JavaScript é potencialmente perigoso, então deve ser evitado onde quer que for possível. Há momentos em que algum risco pode ser aceitável.

Por exemplo, serviços como CodePen e JSFiddle permitem que o conteúdo fornecido pelo usuário seja executado, mas está em um contexto onde este é esperado e isolado em uma área restrita até certo ponto dentro de `iframe`. Nestes casos onde uma funcionalidade importante exige inerentemente algum nível de vulnerabilidade, está sobre o seu time avaliar a importância do recurso em relação aos piores cenários que a vulnerabilidade permite.

### Injeção de HTML {#html-injection}

Conforme foi aprendido anteriormente, no Vue escapa automaticamente o conteúdo HTML, evitando de acidentalmente injetar HTML executável para dentro da sua aplicação. No entanto, **em casos onde é sabido que o HTML é seguro**, pode explicitamente renderizar o conteúdo HTML:

- Usando um modelo de marcação:

  ```vue-html
  <div v-html="userProvidedHtml"></div>
  ```

- Usando uma função de renderização:

  ```js
  h('div', {
    innerHTML: this.userProvidedHtml
  })
  ```

- Usando uma função de renderização com JSX:

  ```jsx
  <div innerHTML={this.userProvidedHtml}></div>
  ```

:::warning AVISO
O HTML fornecido pelo usuário nunca pode ser considerado 100% seguro a menos que seja um `iframe` isolado em uma área restrita ou em uma parte da aplicação onde apenas o usuário que escreveu aquele HTML pode sempre ser exposto à ele. Adicionalmente, permitir que os usuárioes escrevam seus próprios modelos de marcação de Vue atrai perigos parecidos.
:::

### Injeção de URL {#url-injection}

Em uma URL como esta:

```vue-html
<a :href="userProvidedUrl">
  click me
</a>
```

Há um possível problema de segurança se a URL não tiver sido "desinfetada" para evitar a execução de JavaScript usando `javascript:`. Existem bibliotecas como [`sanitize-url`](https://www.npmjs.com/package/@braintree/sanitize-url) para ajudar com isto, mas observe: se estiver fazendo a desinfeção de URL no frontend, já existe um problema de segurança. **URLs fornecidas pelo usuário devem sempre ser desinfetadas no seu backend antes mesmo de serem salvas em uma base de dados.** Portanto o problema é evitado para _todos_ os clientes conectados à sua API, incluindo aplicações móveis nativas. Observe também que mesmo com URLs desinfetadas, o Vue não pode ajudar a garantir que eles levem para destinos seguros.

### Injeção de Estilo {#style-injection}

Olhando para este exemplo:

```vue-html
<a
  :href="sanitizedUrl"
  :style="userProvidedStyles"
>
  click me
</a>
```

Suponhamos que `sanitizedUrl` tenha sido desinfetada, para que seja definitivamente uma URL verdadeira e não JavaScript. Com a `userProvidedStyles`, usuárioes maliciosos poderiam continuar a fornecer CSS para "sequestrar o clique", por exemplo estilizando a ligação para um caixa transparente sobre o botão "Log In" (iniciar em Português). Então se `https://user-controlled-website.com/` for criado para se parecer com a página de login do seu aplicativo, eles poderão ter capturado apenas as informações reais de login de um usuário.

Imagine como permitir que o conteúdo fornecido pelo usuário para um elemento `<style>` criaria uma vulnerabilidade ainda maior, dando este controle completo ao usuário sobre como estilizar a página inteira. É por isto que Vue evita a renderização de marcadores de `style` dentro dos modelos de marcação, como:

```vue-html
<style>{{ userProvidedStyles }}</style>
```

Para manter seus usuários totalmente seguros de 'sequestro de clique', recomendados permitir apenas o controle completo sobre CSS dentro de um `iframe` isolado em uma àrea restritta. Alternativamente, ao fornecer controle ao usuário por meio de um vínculo de estilo, recomendamos usar a [sintaxe de objeto](/guide/essentials/class-and-style#binding-to-objects-1) e permitir que os usuários forneçam apenas valores para propriedades específicas que sejam seguros para eles controlarem, como este:

```vue-html
<a
  :href="sanitizedUrl"
  :style="{
    color: userProvidedColor,
    background: userProvidedBackground
  }"
>
  click me
</a>
```

### Injeção de JavaScript {#javascript-injection}

Nós sempre discordamos fortemente de interpretar um elemento `<script>` com Vue, já que os modelos de marcação e funções de renderização nunca devem ter efeitos colaterais. No entanto, está não é a única maneira de incluir sequências de caracteres que seriam avaliadas como JavaScript em tempo de execução.

Todo elemento HTML tem atributos com valores aceitando sequências de caracteres de JavaScript, como `onclick`, `onfocus`, e `onmouseenter`. Vincular o JavaScript fornecido pelo usuário a qualquer um destes atributos de eventos é um potencial risco de segurança, então deve ser evitado.

:::warning AVISO
O JavaScript fornecido pelo usuário nunca pode ser considerado 100% seguro a menos que esteja em um `iframe` isolado em uma área restrita ou em uma parte da aplicação onde apenas o usuário que escreveu aquele JavaScript possa ser exposto a ele.
:::

Algumas vezes recebemos relatórios de vulnerabilidade sobre como é possível fazer programação cruzada de aplicação (XSS, sigla em Inglês) nos modelos de marcação de Vue. Em geral, não consideramos esses casos como vulnerabilidades reais porque não há uma maneira prática de proteger os programadores dos dois cenários que permitiriam o XSS:

1. O programador está explicitamente pedindo para o Vue interpretar conteúdo não desinfetado fornecido pelo usuário como modelos de marcação de Vue. Isto é inerentemente inseguro, e não existe nenhuma maneira do Vue saber a origem.

2. O programador está montando a Vue à uma página de HTML inteira que parece conter conteúdo fornecido pelo usuário gerado pelo servidor. Isto é fundamentalmente o mesmo problema da \#1, mas algumas vezes os programadores podem fazer isto sem darem-se conta disto. Isto pode conduzir a possíveis vulnerabilidades onde o atacante fornece o HTML que é seguro como HTML simples mas inseguro como um modelo de marcação Vue. A boa prática é **nunca montar a Vue em nós que possam conter conteúdo fornecido pelo usuário e gerado pelo servidor**.

## Boas Práticas {#best-practices}

A regra geral é que se permitires que conteúdo não desinfetado fornecido pelo usuário seja executado (como ou HTML, JavaScript, ou mesmo CSS), podes estar se expondo. Este conselho é realmente verdadeiro seja usando Vue, ou uma outra abstração, ou mesmo nenhuma abstração.

Além das recomendações feitas acima para os [Perigos Potenciais](#potential-dangers), também recomendamos familiarizar-se com estes recursos:

- [HTML5 Security Cheat Sheet](https://html5sec.org/)
- [OWASP's Cross Site Scripting (XSS) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)

Depois use o que aprendeu para revisar também o código-fonte de suas dependências em busca de padrões potencialmente perigosos, se um deles incluir componentes de terceiros ou de outro modo influenciar o que é renderizado mo DOM.

## Coordenação do Backend {#backend-coordination}

As vulnerabilidades de segurança HTTP, como a falsificação de requisição de página cruzada (CSRF ou XSRF, siglas em Inglês) e inclusão de scripts de página cruzada (XSSI, sigla em Inglês), são abordadas principalmente no backend, portanto não são uma preocupação do Vue. No entanto, continua a ser uma boa ideia comunicar com o seu time backend para saber como interagir melhor com as suas APIs, por exemplo, eviando fichas de CSRF com envios de formulário.

## Renderização no Lado do Servidor (SSR) {#server-side-rendering-ssr}

Existem algumas preocupações adicionais de segurança ao usar o SSR, portanto, siga as práticas recomendadas descritas em nossa [nossa documentação da SSR](/guide/scaling-up/ssr) para evitar vulnerabilidades.

---

---
url: /guide/essentials/template-syntax.md
---
# Sintaxe do Modelo de Marcação {#template-syntax}

A Vue usa uma sintaxe de modelo de marcação baseada na HTML que permite-nos vincular declarativamente o DOM interpretado aos dados da instância do componente subjacente. Todos os modelos de marcação da Vue são HTML sintaticamente válidas que podem ser analisados sintaticamente por navegadores e analisadores sintáticos de HTML compatíveis com a especificação.

Nos bastidores, a Vue compila os modelos de marcação para um código de JavaScript altamente otimizado. Aliada ao sistema de reatividade, a Vue é capaz de descobrir inteligentemente o número mínimo de componentes a reinterpretar e aplicar a quantidade mínima de manipulações do DOM quando o estado da aplicação mudar. 

Se estivermos familiarizados com os conceitos do DOM virtual e preferirmos o poder puro da JavaScript, também podemos [escrever diretamente funções de interpretação](/guide/extras/render-function) ao invés dos modelos de marcação, com suporte opcional de JSX. No entanto, nota que estas não gozam do mesmo nível de otimizações no momento da compilação como os modelos de marcação.

## Interpolação de Texto {#text-interpolation}

A forma mais básica de vinculação de dados é a interpolação de texto usando a sintaxe de "Bigodes" (chaves duplas):

```vue-html
<span>Message: {{ msg }}</span>
```

O marcador do bigode será substituído pelo valor da propriedade `msg` [da instância do componente correspondente](/guide/essentials/reactivity-fundamentals#declaring-reactive-state). Este também será atualizado sempre que a propriedade `msg` mudar.

## HTML Puro {#raw-html}

Os bigodes duplos interpretam os dados como texto simples, e não como HTML. No sentido de produzirmos HTML de verdade, precisaremos de usar a [diretiva `v-html`](/api/built-in-directives#v-html):

```vue-html
<p>Using text interpolation: {{ rawHtml }}</p>
<p>Using v-html directive: <span v-html="rawHtml"></span></p>
```

<script setup>
  const rawHtml = '<span style="color: red">This should be red.</span>'
</script>

<div class="demo">
  <p>Using text interpolation: {{ rawHtml }}</p>
  <p>Using v-html directive: <span v-html="rawHtml"></span></p>
</div>

Eis que encontramos algo novo. O atributo `v-html` que vemos é chamado de **diretiva**. As diretivas são prefixadas com `v-` para indicar que são atributos especiais fornecidos pela Vue, como podemos ter imaginado, estas aplicam comportamento especial reativo ao DOM interpretado. Eis, que estamos basicamente dizendo para "manter este HTML interno do elemento atualizado com a propriedade `rawHtml` sobre a atual instância ativa".

Os conteúdos do `span` serão substituídos pelo valor da propriedade `rawHtml`, interpretados como HTML simples - os vínculos de dados são ignorados. Nota que não podemos usar `v-html` para compor os parciais do modelo de marcação, porque a Vue não é um motor de modelagem de marcação de hipertexto baseado em sequência de caracteres. No lugar disto, os componentes são preferenciais como unidade fundamental para reutilização e composição da interface.

:::warning AVISO DE SEGURANÇA
Interpretar dinamicamente HTML arbitrário na nossa aplicação pode ser muito perigoso porque pode facilmente conduzir à [vulnerabilidades de XSS](https://en.wikipedia.org/wiki/Cross-site_scripting). Apenas usamos `v-html` em conteúdo de confiança e **nunca** no conteúdo fornecido pelo utilizador.
:::

## Vínculos de Atributo {#attribute-bindings}

Os bigodes não podem ser usados dentro dos atributos de HTML. No lugar destes, usamos a [diretiva `v-bind`](/api/built-in-directives#v-bind):

```vue-html
<div v-bind:id="dynamicId"></div>
```

A diretiva `v-bind` instrui a Vue para manter o atributo `id` do elemento em sincronia com a propriedade `dynamicId` do componente. Se o valor vinculado for `null` ou `undefined`, então o atributo será removido do elemento interpretado.

### Abreviação {#shorthand}

Uma vez que a `v-bind` é comummente usa, esta tem uma sintaxe abreviada dedicada:

```vue-html
<div :id="dynamicId"></div>
```

Os atributos que começa com os `:` podem parecer um pouco diferentes da HTML normal, mas é de fato um carácter válido para nomes de atributo e todos os navegadores suportados pela Vue podem analisá-lo sintaticamente corretamente. Além disto, estes não aparecerem na marcação desenhada final. A sintaxe abreviada é opcional, mas possivelmente a apreciaremos quando aprendermos mais sobre o seu uso mais tarde.

> Para o resto do guia, estaremos usando a sintaxe abreviada nos exemplos de código, já que é o uso mais comum para os programadores de Vue.

### Atalho de Mesmo Nome <sup class="vt-badge" data-text="3.4+" /> {#same-name-shorthand}

Se o atributo tiver o mesmo nome que o valor de JavaScript sendo vinculado, a sintaxe pode ser muito mais abreviada para omitir o valor do atributo:

```vue-html
<!-- o mesmo que `:id="id"` -->
<div :id></div>

<!-- isto também funciona -->
<div v-bind:id></div>
```

Isto é semelhante a sintaxe de abreviação de propriedade quando declaramos objetos na JavaScript. Nota que esta é uma funcionalidade que está disponível apenas na Vue 3.4+ e superior.

### Atributos Booleanos {#boolean-attributes}

Os [atributos booleanos](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes) são atributos que podem indicar valores verdadeiros ou falsos com sua presença sobre um elemento. Por exemplo, [`disabled`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) é um dos atributos booleanos mais comummente usados.

A `v-bind` funciona de maneira um pouco diferente neste caso:

```vue-html
<button :disabled="isButtonDisabled">Button</button>
```

O atributo `disabled` será incluído se `isButtonDisabled` tiver um [valor verdadeiro](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). Este também será incluído se o valor for uma sequência de caracteres vazia, mantendo a consistência com `<button disabled="">`. Para os outros [valores falsos](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) o atributo será omitido.

### Vinculando Dinamicamente Vários Atributos {#dynamically-binding-multiple-attributes}

Se tivermos um objeto de JavaScript representando vários atributos que se parece com este:

<div class="composition-api">

```js
const objectOfAttrs = {
  id: 'container',
  class: 'wrapper'
}
```

</div>
<div class="options-api">

```js
data() {
  return {
    objectOfAttrs: {
      id: 'container',
      class: 'wrapper'
    }
  }
}
```

</div>

Nós podemos vinculá-los (os atributos) a um único elemento usando a `v-bind` sem um argumento:

```vue-html
<div v-bind="objectOfAttrs"></div>
```

## Usando as Expressões da JavaScript {#using-javascript-expressions}

De momento apenas estivemos vinculando às chaves de propriedade simples nos nossos modelos de marcação. Mas a Vue de fato suporta o poder total das expressões de JavaScript dentro de todos os vínculos de dados:

```vue-html
{{ number + 1 }}

{{ ok ? 'YES' : 'NO' }}

{{ message.split('').reverse().join('') }}

<div :id="`list-${id}`"></div>
```

Estas expressões serão avaliadas como JavaScript no âmbito da aplicação dos dados da instância do componente atual.

Nos modelos de marcação da Vue, as expressões de JavaScript podem ser usadas nas seguintes posições:

- Dentro das interpolações de texto (bigodes)
- No valor do atributo de quaisquer diretivas da Vue (atributos especiais que começam com `v-`)

### Somente Expressões {#expressions-only}

Cada vínculo apenas pode conter **uma única expressão**. Uma expressão é um pedaço de código que pode ser avaliada para um valor. Uma verificação simples é se pode ser usada depois de `return`.

Portanto, as seguintes **não** funcionarão:

```vue-html
<!-- isto é uma declaração, e não uma expressão: -->
{{ var a = 1 }}

<!-- controlo de fluxo também não funcionará, use expressões ternárias -->
{{ if (ok) { return message } }}
```

### Chamando Funções {#calling-functions}

É possível chamar um método exposto pelo componente dentro duma expressão de vínculo:

```vue-html
<time :title="toTitleDate(date)" :datetime="date">
  {{ formatDate(date) }}
</time>
```

:::tip NOTA
As funções chamadas dentro das expressões de vínculo serão chamadas todas as vezes que o componente atualizar, então estas **não** devem possuir quaisquer efeitos colaterais, tais como alterar dados ou acionar operações assíncronas.
:::

### Acesso Global Restrito {#restricted-globals-access}

As expressões do modelo de marcação são isoladas e apenas têm acesso a uma [lista restrita de globais](https://github.com/vuejs/core/blob/main/packages/shared/src/globalsAllowList.ts#L3). A lista expõe os globais embutidos comummente usados tais como `Math` e `Date`.

Os globais que não são explicitamente incluídos na lista, por exemplo, propriedades anexadas pelo utilizador sobre `window`, não estarão acessíveis nas expressões do modelo de marcação. Nós podemos, no entanto, definir explicitamente os globais adicionais para todas as expressões da Vue adicionado-os à [`app.config.globalProperties`](/api/application#app-config-globalproperties).

## Diretivas {#directives}

As diretivas são atributos especiais com o prefixo `v-`. A Vue fornece um número de [diretivas embutidas](/api/built-in-directives), incluindo `v-html` e `v-bind` que introduzimos acima.

Os valores do atributo da diretiva são esperados serem expressões de JavaScript únicas (com a exceção de `v-for`, `v-on`, e `v-slot`, as quais serão discutidas nas suas respetivas seções adiante). O trabalho duma diretiva é aplicar atualizações de maneira reativa ao DOM quando o valor da sua expressão mudar. Consideremos [`v-if`](/api/built-in-directives#v-if) como um exemplo:

```vue-html
<p v-if="seen">Now you see me</p>
```

Neste exemplo, a diretiva `v-if` removeria ou inseriria o elemento `<p>` baseada na veracidade do valor da expressão `seen`.

### Argumentos {#arguments}

Algumas diretivas podem receber um "argumento", denotado por um sinal de dois-pontos depois do nome da diretiva. Por exemplo, a diretiva `v-bind` é usada para atualizar um atributo de HTML de maneira reativa:

```vue-html
<a v-bind:href="url"> ... </a>

<!-- abreviação -->
<a :href="url"> ... </a>
```

Neste exemplo, `href` é o argumento, o qual diz à diretiva `v-bind` para vincular o atributo `href` do elemento ao valor da expressão `url`. Em resumo, tudo que estiver antes do argumento (isto é, `v-bind`) é condensado a um único carácter, `:`.

Um outro exemplo é a diretiva `v-on`, a qual ouve os eventos do DOM:

```vue-html
<a v-on:click="doSomething"> ... </a>

<!-- abreviação -->
<a @click="doSomething"> ... </a>
```

Neste exemplo, o argumento é o nome do evento a ouvir: `click`. A `v-on` tem uma abreviação correspondente, nomeadamente o carácter `@`. Nós também falaremos sobre a manipulação de evento em mais detalhes.

### Argumentos Dinâmicos {#dynamic-arguments}

Também é possível usar uma expressão de JavaScript num argumento de diretiva envolvendo-a entre colchetes:

```vue-html
<!--
Nota que existem algumas restrições à expressão de argumento,
como explicado nas seções "restrições do valor de argumento dinâmico"
e "restrições da sintaxe do argumento dinâmico" abaixo.
-->
<a v-bind:[attributeName]="url"> ... </a>

<!-- abreviação -->
<a :[attributeName]="url"> ... </a>
```

Neste exemplo, o `attributeName` será avaliado dinamicamente como uma expressão de JavaScript, e o seu valor avaliado será usado como valor final para o argumento. Por exemplo, se a instância do nosso componente tiver uma propriedade de dados `attributeName`, cujo valor é `"href"`, então este vínculo será equivalente à `v-bind:href`.

De maneira semelhante, podemos usar os argumentos dinâmicos para vincular um manipulador a um nome de evento dinâmico:

```vue-html
<a v-on:[eventName]="doSomething"> ... </a>

<!-- abreviação -->
<a @[eventName]="doSomething">
```

Neste exemplo, quando o valor do `eventName` for `"focus"`, `v-on:[eventName]` será equivalente à `v-on:focus`.

#### Restrições do Valor do Argumento Dinâmico {#dynamic-argument-value-constraints}

Os argumentos dinâmicos são esperados serem avaliados a uma sequência de caracteres, com a exceção de `null`. O valor especial `null` pode ser usado para remover explicitamente o vínculo. Qualquer outro valor que não for sequência de caracteres acionará um aviso.

#### Restrições da Sintaxe do Argumento Dinâmico {#dynamic-argument-syntax-constraints}

As expressões de argumento dinâmico têm algumas restrições de sintaxe porque certos caracteres, tais como espaços e aspas, são inválidos dentro dos nomes de atributo de HTML. Por exemplo, o seguinte é inválido:

```vue-html
<!-- Isto acionará um aviso de compilação. -->
<a :['foo' + bar]="value"> ... </a>
```

Se precisarmos de passar um argumento dinâmico complexo, é possivelmente melhor usar uma [propriedade computada](./computed), a qual cobriremos brevemente.

Quando usamos os modelos de marcação no DOM (modelos de marcação escritos diretamente num ficheiro de HTML), também devemos evitar nomear as chaves com caracteres maiúsculos, já que os navegadores coagirão os nomes de atributo para minúsculas:

```vue-html
<a :[someAttr]="value"> ... </a>
```

O exemplo acima será convertido à `:[someattr]` nos modelos de marcação no DOM. Se o nosso componente tiver uma propriedade `someAttr` ao invés de `someattr`, o nosso código não funcionará. Os modelos de marcação dentro dos componentes de ficheiro único **não** estão sujeitos a esta restrição. 

### Modificadores {#modifiers}

Os modificadores são sufixos especiais denotados por um ponto, os quais indicam que uma diretiva deve ser vinculada duma maneira especial. Por exemplo, o modificador `.prevent` diz a diretiva `v-on` para chamar `event.preventDefault()` sobre o evento acionado:

```vue-html
<form @submit.prevent="onSubmit">...</form>
```

Depois veremos outros exemplos de modificadores, [para a `v-on`](./event-handling#event-modifiers) e [para a `v-model`](./forms#modifiers), quando explorarmos estas funcionalidades.

E finalmente, eis a sintaxe completa da diretiva visualizada:

![gráfico da sintaxe de diretiva](./images/directive.png)

<!-- https://www.figma.com/file/BGWUknIrtY9HOmbmad0vFr/Directive -->

---

---
url: /guide/built-ins/suspense.md
---

# Suspense {#suspense}

:::warning Funcionalidade Experimental
`<Suspense>` é uma funcionalidade experimental. Não é garantido de que chegue a estado estável e a API pode mudar antes disso acontecer.
:::

`<Suspense>` é um componente embutido para orquestração de dependências assíncronas em uma árvore de componente. Ele pode interpretar um estado de carregamento enquanto espera por várias dependências assíncronas encaixadas em baixo da árvore de componente ser resolvida.

## Dependências Assíncronas {#async-dependencies}

Para explicar o problema que `<Suspense>` está tentando solucionar e como ele interage com estas dependências assíncronas, vamos imaginar uma hierarquia de componente como a seguinte:

```
<Suspense>
└─ <Dashboard>
   ├─ <Profile>
   │  └─ <FriendStatus> (componente com setup() assíncrono)
   └─ <Content>
      ├─ <ActivityFeed> (componente assíncrono)
      └─ <Stats> (componente assíncrono)
```

Na árvore de componente existem vários componentes encaixados dos quais a interpretação depende de algum recurso assíncrono para ser resolvida primeiro. Sem `<Suspense>`, cada um deles precisará lidar com o seus próprios estados "carregando" (loading, em Inglês), "erro" (error, em Inglês) e "carregado" (loaded, em Inglês). No pior cenário, podemos ver três giradores de carregamento na página, com o conteúdo exibindo em momentos diferentes.

O componente `<Suspense>` dá-nos a habilidade de exibir os estados de erro e carregamento enquanto servimos estas dependências assíncronas encaixadas para serem resolvidas.

Existem dois tipos das dependências assíncronas que `<Suspense>` pode servir:

1. Os componentes com um gatilho `setup()` assíncrono. Isto inclui componentes utilizando `<script setup>` com expressões `await` de alto nível.

2. [Componentes Assíncronos](/guide/components/async.html).

### `async setup()` {#async-setup}

Um gatilho de `setup()` do componente da API de Composição pode ser assíncrono:

```js
export default {
  async setup() {
    const res = await fetch(...)
    const posts = await res.json()
    return {
      posts
    }
  }
}
```

Se estiver a utilizar `<script setup>`, a presença de expressões `await` de alto nível automaticamente faz do componente uma dependência assíncrona:

```vue
<script setup>
const res = await fetch(...)
const posts = await res.json()
</script>

<template>
  {{ posts }}
</template>
```

### Componentes Assíncronos {#async-components}

Os componentes assíncronos são **"suspensivos"** por padrão. Isto significa que se ele tiver um `<Suspense>` na cadeia do componente pai, ele será tratado como uma dependência assíncrona daquele `<Suspense>`. Neste caso, o estado de carregamento será controlado pelo `<Suspense>`, e as opções de carregamento (loading, em Inglês), erro (error, em Inglês), atraso (delay, em Inglês), e pausa (timeout, em Inglês) do próprio componente serão ignorados.

O componente assíncrono pode sair do controlo do `Suspense` e permitir que o componente sempre controle o seu próprio estado de carregamento especificando `suspensible: false` nas suas opções.

## Estado de Carregamento {#loading-state}

O componente `<Suspense>` tem duas ranhuras: `#default` e `#fallback`. Ambas ranhuras apenas têm em conta **um** nó filho imediato. O nó na ranhura padrão é mostrado se possível. Se não, o nó na ranhura retrocessiva (fallback, em Inglês) será mostrada.

```vue-html
<Suspense>
  <!-- componente com dependências assíncronas encaixada -->
  <Dashboard />

  <!-- estado de carregamento através da ranhura #fallback -->
  <template #fallback>
    Loading...
  </template>
</Suspense>
```

Na interpretação inicial, `<Suspense>` interpretará o conteúdo da sua ranhura padrão na memória. Se quaisquer dependências assíncronas forem encontradas durante o processo, ele entrará um estado **pendente (pending, em Inglês)**. Durante o estado pendente, o conteúdo retrocessivo será exibido. Quando todas dependências assíncronas encontradas tiver sido resolvidas, `<Suspense>` entre em um estado **resolvido (resolved, em Inglês)** e o conteúdo da ranhura padrão resolvida é exibido.

Se nenhuma das dependências assíncronas foi encontra durante a interpretação, `<Suspense>` irá diretamente para um estado resolvido.

Uma vez em um estado resolvido, `<Suspense>` apenas reverterá para um estado pendente se nó de raiz da ranhura `#default` é substituída. As novas dependências assíncronas encaixadas no fundo da árvore **não** causarão o `<Suspense>` a reverter para um estado pendente.

Quanto uma reversão acontece, conteúdo retrocessivo não será imediatamente exibido. Ao invés do, `<Suspense>` exibirá conteúdo `#default` anterior enquanto espera que o novo conteúdo e suas dependências assíncronas sejam resolvidas. Este comportamento pode ser configurado com a propriedade `timeout`: `<Suspense>` mudará para conteúdo retrocessivo se demorar mais que o `timeout` para interpretar o novo conteúdo padrão. Um valor de `timeout` de `0` causará o conteúdo retrocessivo ser exibido imediatamente quando o conteúdo for substituído.

## Eventos {#events}

O componente `<Suspense>` emite 3 eventos: `pending`, `resolve` e `fallback`. O evento `pending` ocorre quando estiveres entrando em um estado pendente. O evento `resolve` é emitido quando o novo conteúdo termina a resolução na ranhura `default`. O evento `fallback` é disparado quando os conteúdos da ranhura `fallback` são exibidos.

Os eventos poderiam ser utilizado, por exemplo, para mostrar o indicador de carregamento na frente do DOM antigo enquanto os novos componentes estavam carregando.

## Manipulação de Erro {#error-handling}

`<Suspense>` atualmente não fornece manipulação de erro através do próprio componente - no entanto, podes utilizar a opção [`errorCaptured`](/api/options-lifecycle.html#errorcaptured) ou o gatilho [`onErrorCaptured()`](/api/composition-api-lifecycle.html#onerrorcaptured) para capturar e manipular erros assíncronos no componente pai de `<Suspense>`.

## Combinando com Outros Componentes {#combining-with-other-components}

É comum querer utilizar `<Suspense>` em conjunto com os componentes [`<Transition>`](./transition) e [`<KeepAlive>`](./keep-alive). A ordem de encaixamento destes componentes é importante para conseguir que todos eles funcionem corretamente.

Além disto, estes componentes são frequentemente utilizados em conjunto com o componente `<RouterView>` do [Roteador de Vue (Vue Router, em Inglês)](https://router.vuejs.org/).

O seguinte exemplo mostra como encaixar estes componentes para que todos eles se comportem como o esperado. Para combinações mais simples podes remover os componentes que não precisas:

```vue-html
<RouterView v-slot="{ Component }">
  <template v-if="Component">
    <Transition mode="out-in">
      <KeepAlive>
        <Suspense>
          <!-- conteúdo principal -->
          <component :is="Component"></component>

          <!-- estado de carregamento -->
          <template #fallback>
            Loading...
          </template>
        </Suspense>
      </KeepAlive>
    </Transition>
  </template>
</RouterView>
```

O Roteador de Vue (Vue Router, em Inglês) tem suporte embutido para [componentes carregados preguiçosamente](https://router.vuejs.org/guide/advanced/lazy-loading.html) utilizando importações dinâmicas. Estes são distintos dos componentes assíncronos e atualmente não acionarão `<Suspense>`. No entanto, podem ainda ter componentes assíncronos como descendentes e estes podem acionar `<Suspense>` de maneira normal.

---

---
url: /guide/extras/animation.md
---
<script setup>
import ElasticHeader from './demos/ElasticHeader.vue'
import DisabledButton from './demos/DisabledButton.vue'
import Colors from './demos/Colors.vue'
import AnimateWatcher from './demos/AnimateWatcher.vue'
</script>

# Técnicas de Animação {#animation-techniques}

A Vue fornece os componentes [`<Transition>`](/guide/built-ins/transition) e [`<TransitionGroup>`](/guide/built-ins/transition-group) para manipular a transição de entrada / saída e lista de transições. No entanto, existem muitas outras maneiras de usar animações na Web, até mesmo em uma aplicação de Vue. Abaixo discutiremos algumas técnicas adicionais.

## Animações Baseadas em Classe {#class-based-animations}

Para os elementos que não estão a entrar / sair do DOM, podemos acionar animações ao dinamicamente adicionar uma classe de CSS:

<div class="composition-api">

```js
const disabled = ref(false)

function warnDisabled() {
  disabled.value = true
  setTimeout(() => {
    disabled.value = false
  }, 1500)
}
```

</div>

<div class="options-api">

```js
export default {
  data() {
    return {
      disabled: false
    }
  },
  methods: {
    warnDisabled() {
      this.disabled = true
      setTimeout(() => {
        this.disabled = false
      }, 1500)
    }
  }
}
```

</div>

```vue-html
<div :class="{ shake: disabled }">
  <button @click="warnDisabled">Click me</button>
  <span v-if="disabled">This feature is disabled!</span>
</div>
```

```css
.shake {
  animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
  transform: translate3d(0, 0, 0);
}

@keyframes shake {
  10%,
  90% {
    transform: translate3d(-1px, 0, 0);
  }

  20%,
  80% {
    transform: translate3d(2px, 0, 0);
  }

  30%,
  50%,
  70% {
    transform: translate3d(-4px, 0, 0);
  }

  40%,
  60% {
    transform: translate3d(4px, 0, 0);
  }
}
```

<DisabledButton />

## Animações Orientadas a Estado {#state-driven-animations}

Alguns efeitos de transição podem ser aplicados com a interpolação de valores, por exemplo ao vincular um estilo à um elemento enquanto uma interação ocorre. Considere o seguinte exemplo:

<div class="composition-api">

```js
const x = ref(0)

function onMousemove(e) {
  x.value = e.clientX
}
```

</div>

<div class="options-api">

```js
export default {
  data() {
    return {
      x: 0
    }
  },
  methods: {
    onMousemove(e) {
      this.x = e.clientX
    }
  }
}
```

</div>

```vue-html
<div
  @mousemove="onMousemove"
  :style="{ backgroundColor: `hsl(${x}, 80%, 50%)` }"
  class="movearea"
>
  <p>Move your mouse across this div...</p>
  <p>x: {{ x }}</p>
</div>
```

```css
.movearea {
  transition: 0.3s background-color ease;
}
```

<Colors />

Além da cor, também podes usar as vinculações de estilo para animar a transformação com `transform`, a largura com `width` ou altura com `height`. Tu até podes animar os caminhos de SVG usando a física de salto - afinal de contas, são todos atributos de vinculações de dados:

<ElasticHeader />

## Animar com os Observadores {#animating-with-watchers}

Com alguma criatividade, podemos usar os observadores para animar qualquer coisa baseada em algum estado numérico. Por exemplo, podemos animar o próprio número:

<div class="composition-api">

```js
import { ref, reactive, watch } from 'vue'
import gsap from 'gsap'

const number = ref(0)
const tweened = reactive({
  number: 0
})

watch(number, (n) => {
  gsap.to(tweened, { duration: 0.5, number: Number(n) || 0 })
})
```

```vue-html
Type a number: <input v-model.number="number" />
<p>{{ tweened.number.toFixed(0) }}</p>
```

</div>

<div class="options-api">

```js
import gsap from 'gsap'

export default {
  data() {
    return {
      number: 0,
      tweened: 0
    }
  },
  watch: {
    number(n) {
      gsap.to(this, { duration: 0.5, tweened: Number(n) || 0 })
    }
  }
}
```

```vue-html
Type a number: <input v-model.number="number" />
<p>{{ tweened.toFixed(0) }}</p>
```

</div>

<AnimateWatcher />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpNUstygzAM/BWNLyEzBDKd6YWSdHrpsacefSGgJG7xY7BImhL+vTKv9ILllXYlr+jEm3PJpUWRidyXjXIEHql1e2mUdrYh6KDBY8yfoiR1wRiuBZVn6OHYWA0r5q6W2pMv3ISHkBPSlNZ4AtPqAzawC2LRdj3DdEU0WA34qB910sBUnsFWmp6LpRmaRo9UHMLIrGG3h4EBQ/OEbDRpxjx51TYFKWtYKHmOF9WP4Qzs+x22EDoA9NLwmaejC/x+vhBqVxeEfAPIK3WBsi6830lRobZSDDjA580hFIt8roxrCS4bbSuskxFmzhhIAenEy92id1CnzZzfd91szETmZ72rH6zYOej7PA3rYXrKE3GUp//m5KunWx3C5CE6enS0hjZXVKczZXCwdfWyoF79YgZPqBliJ9iGSUTEYlzuRrO9X94a/lUGNTklvBTZvAMpwhYCIMWZyPksTVvjvk9JaXUacq9sSlujFJPnvej/AElH3FQ=)

</div>

<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpNUctugzAQ/JWVLyESj6hSL5Sm6qXHnnr0xYENuAXbwus8Svj3GlxIJEvendHMvgb2bkx6cshyVtiyl4b2XMnO6J6gtsLAsdcdbKZwwxVXeJmpCo/CtQQDVwCVIBFtQwzQI7leLRmAct0B+xx28YLQGVFh5aGAjNM3zvRZUNnkizhII7V6w9xTSjqiRtoYBqhcL0hq5c3S5/hu/blKbzfYwbh9LMWVf0W2zusTws60gnDK6OtqEMTaeSGVcQSnpNMVtmmAXzkLAWeQzarCQNkKaz1zkHWysPthWNryjX/IC1bRbgvjWGTG64rssbQqLF3bKUzvHmH6o1aUnFHWDeVw0G31sqJW/mIOT9h5KEw2m7CYhUsmnV/at9XKX3n24v+E5WxdNmfTbieAs4bI2DzLnDI/dVrqLpu4Nz+/a5GzZYls/AM3dcFx)

</div>

---

---
url: /guide/built-ins/teleport.md
---
# Teletransporte {#teleport}

<VueSchoolLink href="https://vueschool.io/lessons/vue-3-teleport" title="Aula Gratuita sobre Teleport de Vue.js"/>

`<Teleport>` é um componente embutido que permite-nos "teletransportar" uma parte de um modelo de marcação do componente para um nó de DOM que existe fora da hierarquia do DOM deste componente.

## Uso Básico {#basic-usage}


Algumas vezes podemos correr para os seguintes cenários: uma parte de um modelo de marcação do componente pertence a ele logicamente, mas a partir de um ponto de vista visual, ele deve ser exibido noutro lugar no DOM, fora da aplicação de Vue.

O exemplo mais comum disto é quando construimos um modal de tela cheia. Idealmente, queremos que o botão do modal e o próprio modal vivam dentro do mesmo componente, já que estão ambos relacionados ao estado abertura e fechamento do modal. Mas isto significa que o modal será interpretado junto do botão, profundamente encaixado na hierarquia do DOM da aplicação. Isto pode criar algumas questões complicadas quando posicionamos o modal através de CSS.

Considere a seguinte estrutura de HTML:

```vue-html
<div class="outer">
  <h3>Vue Teleport Example</h3>
  <div>
    <MyModal />
  </div>
</div>
```

E cá está a implementação do `<MyModal>`:

<div class="composition-api">

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <button @click="open = true">Open Modal</button>

  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</template>

<style scoped>
.modal {
  position: fixed;
  z-index: 999;
  top: 20%;
  left: 50%;
  width: 300px;
  margin-left: -150px;
}
</style>
```

</div>
<div class="options-api">

```vue
<script>
export default {
  data() {
    return {
      open: false
    }
  }
}
</script>

<template>
  <button @click="open = true">Open Modal</button>

  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</template>

<style scoped>
.modal {
  position: fixed;
  z-index: 999;
  top: 20%;
  left: 50%;
  width: 300px;
  margin-left: -150px;
}
</style>
```

</div>

O componente contém um `<button>` para acionar a abertura do modal, e a `<div>` uma classe `.modal`, a qual conterá o conteúdo do modal e um botão que se fecha a si mesmo.

Quando usamos este componente dentro da estrutura inicial de HTML, existe um número de potenciais questões:

- `position: fixed` apenas coloca o elemento relativo a janela de exibição quando nenhum elemento ancestral tiver a propriedade `transform`, `perspective` ou `filter` definida. Se, por exemplo, tencionamos animar o ancestral `<div class="outer">` com a transformação de CSS, quebraria a disposição do modal!

- O `z-index` do modal é restrito pelos seus elementos que o contém. Se houver um outro elemento que sobrepõem-se ao `<div class="outer">` e tiver um `z-index` superior, ele cobriria o nosso modal.

`<Teleport>` fornece um maneira clara de os contornar, permitindo-nos fugir da estrutura de DOM encaixada. Vamos modificar `<MyModal>` para usar `<Teleport>`:

```vue-html{3,8}
<button @click="open = true">Open Modal</button>

<Teleport to="body">
  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</Teleport>
```

O alvo do `to` de `<Teleport>` espera uma sequência de caracteres de seletor de CSS ou um nó de DOM real. Aqui, estamos essencialmente dizendo a Vue para "**teletransportar** este fragmento de modelo de marcação **para** o marcador **`body`**".

Tu podes clicar no botão abaixo e inspecionar o marcador `<body>` através da ferramenta de programação do navegador:

<script setup>
import { ref } from 'vue'

let open = ref(false)
</script>

<div class="demo">
  <button @click="open = true">Open Modal</button>
  <ClientOnly>
    <Teleport to="body">
      <div v-if="open" class="demo modal-demo">
        <p style="margin-bottom:20px">Hello from the modal!</p>
        <button @click="open = false">Close</button>
      </div>
    </Teleport>
  </ClientOnly>
</div>

<style>
.modal-demo {
  position: fixed;
  z-index: 999;
  top: 20%;
  left: 50%;
  width: 300px;
  margin-left: -150px;
  background-color: var(--vt-c-bg);
  padding: 30px;
  border-radius: 8px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
}
</style>

Tu podes combinar `<Teleport>` com [`<Transition>`](./transition) para criar modais animados - consulte o [exemplo](/examples/#modal).

:::tip Dica
O alvo `to` da teletransportação já deve estar no DOM quando o componente `<Teleport>` for montado. Idealmente, isto deve ser um elemento fora da aplicação de Vue inteira. Se virando um outro elemento interpretado pela Vue, precisas certificar-te de que o elemento seja montado antes do `<Teleport>`.
:::

## Usando com Componentes {#using-with-components}

`<Teleport>` apenas altera a estrutura do DOM interpretada - ele não afeta a hierarquia lógica dos componentes. Isto é, se `<Teleport>` contiver um componente, este componente continuará a ser um filho lógico do componente pai contendo o `<Teleport>`. A passagem de propriedades e emissão de evento continuarão a funcionar da mesma maneira.

Isto também significa que as injeções de um componente pai funcionam como esperado, e que o componente filho será encaixado abaixo do componente pai na Ferramenta de Programação de Vue, ao invés de ser colocado para onde o conteúdo real foi movido.

## Desativando o Teletransporte {#disabling-teleport}

Em alguns casos, podemos querer desativar condicionalmente `<Teleport>`. Por exemplo, podemos interpretar um componente como uma sobreposição para a área de trabalho, mas em linha no telemóvel. `<Teleport>` suporta a propriedade `disabled` que pode ser alternada dinamicamente:

```vue-html
<Teleport :disabled="isMobile">
  ...
</Teleport>
```

Onde o estado `isMobile` pode ser atualizado dinamicamente detetando mudanças de consulta de media.

## Vários Teletransporte sobre o Mesmo Alvo {#multiple-teleports-on-the-same-target}


Um caso de uso comum seria um componente `<Modal>` reutilizável, com o potencial para várias instâncias a serem ativadas ao mesmo tempo. Para este tipo de cenário, vários componentes `<Teleport>` podem montar seus conteúdos para o mesmo elemento de alvo. A ordem será um simples adição - depois as montagens serão localizadas depois dos anteriores dentro do elemento de alvo.

Dada o seguinte uso:

```vue-html
<Teleport to="#modals">
  <div>A</div>
</Teleport>
<Teleport to="#modals">
  <div>B</div>
</Teleport>
```

O resultado interpretado seria:

```html
<div id="modals">
  <div>A</div>
  <div>B</div>
</div>
```

---

**Relacionado ao**

- [Referência de API de `<Teleport>`](/api/built-in-components#teleport)
- [Manipulando Teletransportações na SSR](/guide/scaling-up/ssr#teleports)

---

---
url: /guide/scaling-up/testing.md
---
<script setup>
import { VTCodeGroup, VTCodeGroupTab } from '@vue/theme'
</script>

# Testes {#testing}

## Por que Testar? {#why-test}

Os testes automatizados ajudam-nos e a nossa equipa a construirmos aplicações complexas de Vue rapidamente e confiantemente evitando regressões e encorajando-nos a separar a nossa aplicação em funções, módulos, classes, e componentes testáveis. Tal como acontece com qualquer aplicação, a nossa nova aplicação de Vue pode quebrar de várias maneiras, e é importante que possamos capturar estes problemas e os corrigir antes do lançamento. 

Neste guia, cobriremos a terminologia básica e forneceremos as nossas recomendações sobre quais ferramentas escolher para a nossa aplicação de Vue 3.

Existe uma seção específica da Vue cobrindo as funções de composição. Consultar [Testando as Funções de Composição](#testing-composables) por mais detalhes.

## Quando Testar? {#when-to-test}

Começamos testando no princípio! Nós recomendamos começar escrevendo testes o mais cedo possível. Quanto mais esperamos para adicionar os testes à nossa aplicação, mais dependências a nossa aplicação terá, e mais difícil será começar.

## Tipos de Testes {#testing-types}

Quando desenharmos a estratégia de testes da nossa aplicação de Vue, devemos influenciar os seguintes tipos de testes:

- **Unitário**: Verifica se as entradas à uma dada função, classe, função de composição estão produzindo a saída esperada ou efeitos colaterais.
- **Componente**: Verifica se o nosso componente monta, interpreta, pode ser interagido com, e comporta-se como esperado. Estes testes importam mais código do que os testes unitários, são mais complexos, e exigem mais tempo para executarem.
- **Ponta-a-Ponta**: Verifica se as funcionalidades que abrangem várias páginas e faz requisições de rede reais contra a nossa aplicação de Vue construída para produção. Estes testes frequentemente envolvem levantar um base de dados ou outro backend.

Cada tipo de teste desempenha um papel na estratégia de testes da nossa aplicação, e cada um nos protegerá contra diferentes tipos de problemas.

## Visão Geral {#overview}

Nós discutiremos brevemente sobre cada tipo de teste, como estes podem ser implementados às nossas aplicações de Vue, e forneceremos algumas recomendações gerais.

## Teste Unitário {#unit-testing}

Os testes unitários são escritos para verificar se as pequenas e isoladas unidades de código estão funcionando como esperado. Um teste unitário normalmente cobre uma única função, classe, função de composição, ou módulo. Os testes unitários focam-se na exatidão lógica e os mesmos apenas preocupam-se com uma pequena porção da funcionalidade geral da aplicação. Estes podem simular grandes partes do ambiente da nossa aplicação (por exemplo, estado inicial, classes complexas, módulos de terceiros, e requisições de rede).

No geral, os testes unitários capturarão os problemas com a lógica de negócio da função e com a exatidão lógica.

Consideremos como exemplo esta função `increment`:

```js
// helpers.js
export function increment (current, max = 10) {
  if (current < max) {
    return current + 1
  }
  return current
}
```

Uma vez que é muito autónoma, será fácil invocar a função `increment` e asserir que esta retorna o que é suposto retornar, então escreveremos um Teste Unitário.

Se quaisquer uma destas asserções falhar, está claro que o problema está contido dentro da função `increment`:

```js{4-16}
// helpers.spec.js
import { increment } from './helpers'

describe('increment', () => {
  test('increments the current number by 1', () => {
    expect(increment(0, 10)).toBe(1)
  })

  test('does not increment the current number over the max', () => {
    expect(increment(10, 10)).toBe(10)
  })

  test('has a default max of 10', () => {
    expect(increment(10)).toBe(10)
  })
})
```

Conforme mencionado anteriormente, o teste unitário é normalmente aplicado à lógica de negócio, componentes, classes, módulos ou funções autónomas que não envolvem a interpretação da interface gráfica da aplicação, requisições de rede, ou outras preocupações ambientais.

Estes são normalmente módulos simples de JavaScript ou TypeScript que não estão relacionados com a Vue. No geral, escrever testes unitários para lógica de negócio em aplicações de Vue não difere significativamente das aplicações usando outras abstrações.

Existem duas casos onde REALIZAMOS teste unitários de funcionalidades específicas da Vue:

1. Funções de Composição
2. Componentes

### Funções de Composição {#composables}

Uma categoria de funções específicas às aplicações de Vue são as [Funções de Composição](/guide/reusability/composables), que podem exigir manipulação especial durante os testes. Consultar a seção [Testando as Funções de Composição](#testing-composables) abaixo por mais detalhes.

### Teste Unitário dos Componentes {#unit-testing-components}

Um componente pode ser testado de duas maneiras:

1. Caixa Branca: Teste Unitário

   Os testes que são "testes de Caixa Branca" estão conscientes dos detalhes da implementação e dependências dum componente. Estes estão focados em **isolar** o componente sob teste. Estes testes normalmente envolverão simular algumas, se não todos os filhos do nosso componente, bem como configurar o estado da extensão ou dependências (por exemplo, a Pinia).

2. Caixa Preta: Teste de Componente

   Os testes que são "testes de Caixa Preta" não estão conscientes dos detalhes da implementação dum componente. Estes testes simulam apenas o possível para testar a integração do nosso componente e do nosso sistema inteiro. Estes normalmente interpretam todos os componentes filhos e são considerados mais dum "teste de integração". Consultar as [recomendações de Teste de Componente](#component-testing) abaixo.

### Recomendação {#recommendation}

- [Vitest](https://vitest.dev/)

  Uma vez que a configuração oficial criada pela `create-vue` está baseada na [Vite](https://pt.vitejs.dev/), recomendamos usar uma abstração de teste unitário que pode influenciar diretamente a mesma conduta de configuração e transformação a partir da Vite. A [Vitest](https://vitest.dev/) é uma abstração de teste unitário desenhada especificamente para este propósito, criada e mantida pelos membros da equipa da Vue e Vite. Esta integra-se com os projetos baseados na Vite com o mínimo esforço, e é extremamente rápida.

### Outras Opções {#other-options}

- [Jest](https://jestjs.io/) é uma abstração de teste unitário popular. No entanto, apenas recomendamos a Jest se houver um conjunto de teste de Jest que precisa ser migrado a um projeto baseado na Vite, uma que a Vitest oferece uma integração mais transparente e um desempenho melhor.

## Teste de Componente {#component-testing}

Nas aplicações de Vue, os componentes são os principais blocos de construção da interface do utilizador. Os componentes são, portanto, a unidade natural da isolação quando se trata de validar o comportamento da nossa aplicação. Do ponto de vista da granularidade, os testes de componentes situam-se algures acima dos testes unitários e podem ser considerados uma forma de testes de integração. Grande parte da nossa aplicação de Vue deve ser coberta por um teste de componente e recomendamos que cada componente da Vue tenha o seu próprio ficheiro de especificações.

Os testes de componentes devem detetar problemas relacionados com as propriedades, eventos, ranhuras que o componente fornece, estilos, classes, funções gatilhos do ciclo de vida e muito mais.

Os testes de componentes não devem simular componentes filhos, mas sim testar as interações entre o nosso componente e seus filhos, interagindo com os componentes como um utilizador faria. Por exemplo, um teste de componente deve clicar num elemento como um utilizador faria, em vez de interagir programaticamente com o componente.

Os testes de componentes devem centrar-se nas interfaces públicas do componente e não nos detalhes de implementação interna. Para a maioria dos componentes, a interface pública é limitada a: eventos emitidos, propriedades e ranhuras. Quando testarmos, lembremos-nos de **testar o que um componente faz, e não como este faz**.

**FAZER**

- Para lógica **Visual**: asserir a saída correta da interpretação baseada nas propriedades e ranhuras introduzidas.
- Para lógica **Comportamental**: asserir atualizações corretas da interpretação ou eventos emitidos em resposta aos eventos de entrada do utilizador.

  No exemplo abaixo, demonstramos um componente `Stepper` que tem um elemento de DOM rotulado "increment" e pode ser clicado. Nós passamos uma propriedade chamada `max` que impede o `Stepper` de ser incrementado além de `2`, então se clicarmos no botão 3 vezes, a interface do utilizador ainda deve dizer `2`.

  Nós não sabemos nada sobre a implementação do `Stepper`, apenas que a "entrada" é a propriedade `max` e a "saída" é o estado do DOM como o utilizador o verá.

<VTCodeGroup>
  <VTCodeGroupTab label="Vue Test Utils">
  
  ```js
  const valueSelector = '[data-testid=stepper-value]'
  const buttonSelector = '[data-testid=increment]'

  const wrapper = mount(Stepper, {
    props: {
      max: 1
    }
  })

  expect(wrapper.find(valueSelector).text()).toContain('0')

  await wrapper.find(buttonSelector).trigger('click')

  expect(wrapper.find(valueSelector).text()).toContain('1')
  ```

</VTCodeGroupTab>

<VTCodeGroupTab label="Cypress">

  ```js
  const valueSelector = '[data-testid=stepper-value]'
  const buttonSelector = '[data-testid=increment]'

  mount(Stepper, {
    props: {
      max: 1
    }
  })

  cy.get(valueSelector).should('be.visible').and('contain.text', '0')
    .get(buttonSelector).click()
    .get(valueSelector).should('contain.text', '1')
  ```

</VTCodeGroupTab>

<VTCodeGroupTab label="Testing Library">
  
  ```js
  const { getByText } = render(Stepper, {
    props: {
      max: 1
    }
  })

  // Asserir implicitamente que "0" está dentro do componente
  getByText('0')

  const button = getByRole('button', { name: /increment/i })

  // Despachar um evento de clique ao nosso botão de incremento.
  await fireEvent.click(button)

  getByText('1')

  await fireEvent.click(button)
  ```

  </VTCodeGroupTab>
</VTCodeGroup>

**NÃO FAZER**

- Não asserir o estado privado da instância dum componente ou testar métodos privados dum componente. Testar detalhes de implementação fragiliza os testes, uma vez que estes estão sujeitos a quebrarem ou exigem atualizações quando a implementação mudar.

  O trabalho definitivo do componente é interpretar a saída correta do DOM, então os testes que focam-se na saída do DOM fornecem o mesmo nível de garantia de exatidão (se não mais) enquanto é mais robusto e resiliente à mudança.

  Não depender exclusivamente dos testes instantâneos. Asserir as sequências de caracteres de HTML não descreve exatidão. Precisamos escrever os testes intencionalidade.

  Se um método precisar ser testado meticulosamente, devemos considerar extraí-lo para uma função utilitária autónoma e escrever um teste unitário dedicado a esta. Se não poder ser extraída claramente, pode ser testada como uma parte dum teste de componente, integração, ou de ponta-a-ponta que a cobre.

### Recomendação {#recommendation-1}

- [Vitest](https://vitest.dev/) para componentes ou funções de composição que interpretam-se de maneira desgovernada (por exemplo, a função [`useFavicon`](https://vueuse.org/core/useFavicon/#usefavicon) na VueUse). Os componentes e o DOM podem ser testados usando a [`@vue/test-utils`](https://github.com/vuejs/test-utils).

- [Teste de Componente da Cypress](https://on.cypress.io/component) para os componentes cujo comportamento esperado depende da interpretação correta dos estilos ou acionam eventos nativos do DOM. Esta pode ser usada com a Testing Library através da [`@testing-library/cypress`](https://testing-library.com/docs/cypress-testing-library/intro).

As principais diferenças entre a Vitest e outras ferramentas que executam testes com a assistência do navegador são a velocidade e o contexto da execução. Em resumo, as ferramentas que executam testes com a assistência do navegador, como a Cypress, conseguem capturar problemas que ferramentas que executam testes sem a assistência do navegador, como a Vitest, não consegue (por exemplo, problemas de estilo, eventos nativos do DOM, biscoitos (cookies), armazenamento local, falhas de rede), mas as ferramentas que executam testes com a assistência do navegador são _muito mais lentas do que a Vitest_ porque estas precisam abrir um navegador, compilar as nossas folhas de estilo, e muito mais. A Cypress é uma ferramenta de execução de testes com assistência do navegador que suporta testes de componente. Nós podemos consultar a [página de comparação da Vitest](https://vitest.dev/guide/comparisons#cypress) por informação mais atualizada comparando a Vitest e a Cypress.

### Bibliotecas de Montagem {#mounting-libraries}

O teste de componente muitas vezes envolve a montagem isolada do componente a ser testado, acionar eventos de entrada do utilizador de maneira simulada, e asserir sobre a saída do DOM apresentado. Existem bibliotecas utilitárias dedicadas que simplificam estas tarefas.

- [`@vue/test-utils`](https://github.com/vuejs/test-utils) é a biblioteca oficial de testes de componente de baixo nível escrita para oferecer aos utilizadores acesso às APIs específicas da Vue. É também a biblioteca de baixo nível sobre qual a `@testing-library/vue` foi construída.

- [`@testing-library/vue`](https://github.com/testing-library/vue-testing-library) é uma biblioteca de testes de Vue focada em testar componentes sem depender dos detalhes de implementação. A sua diretriz é que quanto mais os testes refletirem a maneira que o software é usado, mais confiáveis são.

Nós recomendamos usar a `@vue/test-utils` para testar os componentes nas aplicações. A `@testing-library/vue` tem problemas com testes de componente assíncrono com Suspense, por isto deve ser usada com cautela.

### Outras Opções {#other-options-1}

- [Nightwatch](https://nightwatchjs.org/) é uma ferramenta de execução de teste de ponto-a-ponta com suporte a Testes de Componente de Vue. ([Projeto de Exemplo](https://github.com/nightwatchjs-community/todo-vue))

- [WebdriverIO](https://webdriver.io/docs/component-testing/vue) para testes de componentes entre os navegadores que dependem da interação nativa do utilizador baseado na automatização padronizada. Esta também pode ser usada com a Testing Library.

## Testes de Ponta-a-Ponta {#e2e-testing}

Embora os testes unitários ofereçam aos programadores um certo grau de confiança, os testes unitários e de componentes são limitados na sua capacidade de fornecer uma cobertura holística duma aplicação quando implantada em produção. Consequentemente, os testes de ponta-a-ponta fornecem cobertura sobre o que é, sem dúvida, o aspeto mais importante duma aplicação: o que acontece quando os utilizadores usam efetivamente as nossas aplicações.

Os testes de ponta-a-ponta concentram-se no comportamento da aplicação de várias páginas que faz requisições de rede contra a nossa aplicação de Vue construída para produção. Estes envolvem frequentemente a criação duma base de dados ou outro backend e podem até ser executadas num ambiente de teste em tempo real.

Os testes de ponta-a-ponta detetam frequentemente problemas com o nosso roteador, biblioteca de gestão de estados, componentes de alto nível (por exemplo, uma aplicação ou um esquema), recursos públicos ou qualquer tratamento de requisições. Como já foi referido, estes detetam problemas críticos que podem ser impossíveis de detetar com os testes unitários ou testes de componentes.

Os testes de ponta-a-ponta não importam nenhum código da nossa aplicação de Vue, mas dependem completamente de testar a nossa aplicação navegando por páginas inteiras num navegador de verdade.

Os testes de ponta-a-ponta validam muitas das camadas da nossa aplicação. Estes podem ser direcionados a nossa aplicação criada localmente ou mesmo a um ambiente de teste em tempo real. Os testes efetuados no nosso ambiente de teste incluem não só o nosso código de frontend e o servidor estático, mas também todos os serviços e infraestruturas de backend associados.

> Quanto mais os testes refletirem a maneira que o nosso software é usado, mas confiáveis serão - [Kent C. Dodds](https://twitter.com/kentcdodds/status/977018512689455106) - Autor da Testing Library

Ao testar como o impacto das ações do utilizador na nossa aplicação, os testes de ponta-a-ponta são muitas vezes a chave para uma maior confiança no bom funcionamento duma aplicação.

### Escolhendo uma Solução de Testes de Ponta-a-Ponta {#choosing-an-e2e-testing-solution}

Embora os testes de ponta-a-ponta na Web tenham ganho uma reputação negativa de testes não fiáveis e de atrasarem os processos de desenvolvimento, as ferramentas modernas de testes de ponta-a-ponta deram passos adiante para criar testes mais fiáveis, interativos e úteis. Ao escolher uma abstração de testes de ponta-a-ponta, as secções seguintes fornecem algumas orientações sobre os aspetos a ter em conta ao escolher uma abstração de testes para a nossa aplicação.

#### Testes entre Navegadores {#cross-browser-testing}

Um dos principais benefícios pelos quais os testes de ponta-a-ponta são conhecidos é a sua capacidade de testar a nossa aplicação em vários navegadores. Embora possa parecer desejável ter 100% de cobertura entre os navegadores, é importante notar que os testes entre navegadores têm um retorno decrescente nos recursos duma equipa devido ao tempo adicional e à potência da máquina necessários para os executar consistentemente. Como resultado, é importante ter em conta este compromisso ao escolher a quantidade de testes entre navegadores de que a nossa aplicação necessita.

#### Ciclos de Reações Mais Rápidos {#faster-feedback-loops}

Um dos principais problemas dos testes e do desenvolvimento de ponta-a-ponta é que a execução de todo o conjunto demora muito tempo. Normalmente, isto só é feito em condutas de integração e implantação contínuas. As abstrações modernas de testes de ponta-a-ponta ajudaram a resolver isto adicionando recursos como paralelismo, que permite que a integração contínua e as condutas de implantação contínua sejam executadas com mais rapidez do que antes. Além disto, ao desenvolver localmente, a capacidade de executar seletivamente um único teste para a página em que trabalhamos, ao mesmo tempo que fornece a recarga a quente de testes, podem ajudar a impulsionar o fluxo de trabalho e a produtividade dum programador.

#### Experiência de Depuração de Primeira Classe {#first-class-debugging-experience}

Embora os programadores tenham tradicionalmente dependido da analise de registos numa janela de terminal para determinar o que correu mal num teste, as abstrações modernas de teste de ponta-a-ponta permitem que os programadores influenciem ferramentas com as quais já estão familiarizados, por exemplo, as ferramentas de programação do navegador.

#### Visibilidade no Modo Desgovernado {#visibility-in-headless-mode}

Quando os testes de ponta-a-ponta são executados nas condutas de integração ou implantação contínuas, são frequentemente executados nos navegadores desgovernado (ou seja, não é aberto nenhum navegador visível para o utilizador assistir). Uma funcionalidade crítica das modernas abstrações de teste de ponta-a-ponta é a capacidade de ver fotografias e/ou vídeos da aplicação durante o teste, fornecendo alguma informação sobre a razão pela qual os erros acontecem. Historicamente, era tedioso manter estas integrações.

### Recomendação {#recommendation-2}

- [Cypress](https://www.cypress.io/)

  Geralmente, acreditamos que o Cypress fornece a solução mais completa de ponta-a-ponta com recursos como uma interface gráfica informativa, excelente capacidade de depuração, asserções e esboços integrados, resistência a falhas, paralelismo e fotografias. Tal como já foi referido, este também suporta o [teste de componentes](https://docs.cypress.io/guides/component-testing/introduction). Esta suporta navegadores baseados no Chromium, Firefox, Electron. O suporte de Webkit está disponível, mas marcado como experimental.

### Outras Opções {#other-options-2}

- [Playwright](https://playwright.dev/) é também uma excelente solução de teste de ponta-a-ponta que suporta todos os motores de apresentação modernos incluindo Chromium, Webkit, e Firefox. Podemos testar no Windows, Linux, e macOS, localmente ou sobre integração contínua, desgovernado ou governado com emulação móvel nativa do Google Chrome para Android e Mobile Safari.

- [Nightwatch](https://nightwatchjs.org/) é uma solução de teste ponta-a-ponta baseada no [Selenium WebDriver](https://www.npmjs.com/package/selenium-webdriver). Isto dá-lhe a mais ampla gama de suporte de navegadores, incluindo teste móvel nativo. As soluções baseadas na Selenium serão mais lentas do que a Playwright ou Cypress.

- [WebdriverIO](https://webdriver.io/) é uma abstração de automatização de testes para Web e móveis baseada no protocolo WebDriver.

## Receitas {#recipes}

### Adicionando a Vitest a um Projeto {#adding-vitest-to-a-project}

Num projeto de Vue baseado na Vite, executamos:

```sh
> npm install -D vitest happy-dom @testing-library/vue
```

Em seguida, atualizamos a configuração da Vite para adicionar o bloco de opções `test`:

```js{6-12}
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
  test: {
    // ativar as APIs de teste globais semelhantes a jest
    globals: true,
    // simular o DOM com happy-dom
    // (exige a instalação do happy-dom como uma dependência de pares)
    environment: 'happy-dom'
  }
})
```

:::tip DICA
Se nós usarmos a TypeScript, adicionamos `vitest/globals` ao campo `types` no nosso `tsconfig.json`:

```json
// tsconfig.json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}
```

:::

Depois, criamos um ficheiro terminado em `*.test.js` em nosso projeto. Nós podemos colocar todos os ficheiros de teste num diretório de teste na raiz do projeto ou em diretórios de teste junto aos nossos ficheiros de origem. A Vitest procurá-los-á utilizando automaticamente a convenção de nomes:

```js
// MyComponent.test.js
import { render } from '@testing-library/vue'
import MyComponent from './MyComponent.vue'

test('it should work', () => {
  const { getByText } = render(MyComponent, {
    props: {
      /* ... */
    }
  })

  // asserir a saída
  getByText('...')
})
```

Finalmente, atualizamos o `package.json` para adicionar o programa de teste e executá-lo:

```json{4}
{
  // ...
  "scripts": {
    "test": "vitest"
  }
}
```

```sh
> npm test
```

### Testes de Funções de Composição {#testing-composables}

> Esta secção parte pressupõe a leitura da secção [Funções de Composição](/guide/reusability/composables).

Quando se trata de testar as funções de composição, podemos dividi-los em duas categorias: funções de composição que dependem duma instância de componente hospedeiro e funções de composição que dependem.

Uma função de composição que depende duma instância de componente hospedeiro quando usa as seguintes APIS:

- Funções Gatilhos do Ciclo de Vida
- Fornecer / Injetar

Se uma função de composição apenas usar as APIs de reatividade, pode ser testado invocando-o diretamente e asserindo o seu estado ou métodos retornados:

```js
// counter.js
import { ref } from 'vue'

export function useCounter() {
  const count = ref(0)
  const increment = () => count.value++

  return {
    count,
    increment
  }
}
```

```js
// counter.test.js
import { useCounter } from './counter.js'

test('useCounter', () => {
  const { count, increment } = useCounter()
  expect(count.value).toBe(0)

  increment()
  expect(count.value).toBe(1)
})
```

Uma função de composição que depende das funções gatilhos do ciclo de vida ou de fornecer e injetar precisa ser envolvida num componente hospedeiro para ser testada. Nós podemos criar um auxiliar como o seguinte:

```js
// test-utils.js
import { createApp } from 'vue'

export function withSetup(composable) {
  let result
  const app = createApp({
    setup() {
      result = composable()
      // suprimir aviso de modelo de marcação em falta
      return () => {}
    }
  })
  app.mount(document.createElement('div'))
  // retornar o resultado e a instância da aplicação
  // para testar o fornecer ou desmontar
  return [result, app]
}
```

```js
import { withSetup } from './test-utils'
import { useFoo } from './foo'

test('useFoo', () => {
  const [result, app] = withSetup(() => useFoo(123))
  // simular o fornecer para testar as injeções
  app.provide(...)
  // executar as asserções
  expect(result.foo.value).toBe(1)
  // acionar a função gatilho de desmontagem se necessário
  app.unmount()
})
```

No caso de funções de composição mais complexas, também pode ser mais fácil testá-las escrevendo testes para o componente envolvente usando técnicas de [teste de componentes](#component-testing).

<!--
TODO more testing recipes can be added in the future e.g.
- How to set up CI via GitHub actions
- How to do mocking in component testing
-->

---

---
url: /api/utility-types.md
---
# Tipos de Utilitários de TypeScript {#utility-types}

:::info INFORMAÇÃO
Esta página lista apenas alguns tipos de utilitários comummente usados que podem precisar de explicação para o seu uso. Para uma lista completa de tipos exportados, consulte o [código-fonte](https://github.com/vuejs/core/blob/main/packages/runtime-core/src/index.ts#L131).
:::

## `PropType<T>` {#proptype-t}

Usado para anotar uma propriedade com tipos mais avançados quando usamos as declarações de propriedades de execução.

- **Exemplo**

  ```ts
  import type { PropType } from 'vue'

  interface Book {
    title: string
    author: string
    year: number
  }

  export default {
    props: {
      book: {
        // fornecer tipo mais específico ao `Object`
        type: Object as PropType<Book>,
        required: true
      }
    }
  }
  ```

- **Consulte também:** [Guia - Tipos para as Propriedades do Componente](/guide/typescript/options-api#typing-component-props)

## `MaybeRef<T>` {#mayberef}

Pseudónimo para `T | Ref<T>`. Útil para anotar argumentos de [Funções de Composição](/guide/reusability/composables).

- Apenas suportado na 3.3+.

## `MaybeRefOrGetter<T>` {#maybereforgetter}

Pseudónimo para `T | Ref<T> | (() => T)`. Útil para anotar argumentos de [Funções de Composição](/guide/reusability/composables).

- Apenas suportado na 3.3+.

## `ExtractPropTypes<T>` {#extractproptypes}

Extrai tipos de propriedades a partir dum objeto de opções de propriedades de tempo de execução. Os tipos extraídos são rosto interno - isto é, as propriedades resolvidas recebidas pelo componente. Isto significa que propriedades booleanas e propriedades com os valores padrão são sempre definidas, mesmo se não forem obrigatórias.

Para extrair propriedades de rosto público, isto é, propriedades que o pai é permitido passar, usamos [`ExtractPublicPropTypes`](#extractpublicproptypes).

- **Exemplo**

  ```ts
  const propsOptions = {
    foo: String,
    bar: Boolean,
    baz: {
      type: Number,
      required: true
    },
    qux: {
      type: Number,
      default: 1
    }
  } as const

  type Props = ExtractPropTypes<typeof propsOptions>
  // {
  //   foo?: string,
  //   bar: boolean,
  //   baz: number,
  //   qux: number
  // }
  ```

## `ExtractPublicPropTypes<T>` {#extractpublicproptypes}

Extrai tipos de propriedade a partir dum objeto de opções de propriedades de tempo de execução. Os tipos extraídos são rosto público - isto é, as propriedades que o pai é permitido passar.

- Suportado apenas na 3.3+.

- **Exemplo**

  ```ts
  const propsOptions = {
    foo: String,
    bar: Boolean,
    baz: {
      type: Number,
      required: true
    },
    qux: {
      type: Number,
      default: 1
    }
  } as const

  type Props = ExtractPublicPropTypes<typeof propsOptions>
  // {
  //   foo?: string,
  //   bar?: boolean,
  //   baz: number,
  //   qux?: number
  // }
  ```

## `ComponentCustomProperties` {#componentcustomproperties}

Usado para aumentar o tipo da instância do componente para suportar as propriedades globais personalizadas.

- **Exemplo**

  ```ts
  import axios from 'axios'

  declare module 'vue' {
    interface ComponentCustomProperties {
      $http: typeof axios
      $translate: (key: string) => string
    }
  }
  ```

:::tip DICA
Os aumentos devem ser colocados num ficheiro `.ts` ou `.d.ts` de módulo. Consulte [Colocação do Aumento de Tipo](/guide/typescript/options-api#augmenting-global-properties) por mais detalhes.
:::

- **Consulte também:** [Guia - Aumentando Propriedades Globais](/guide/typescript/options-api#augmenting-global-properties)

## `ComponentCustomOptions` {#componentcustomoptions}

Usado para aumentar os tipos das opções do componente para suportar opções personalizadas.

- **Exemplo**

  ```ts
  import { Route } from 'vue-router'

  declare module 'vue' {
    interface ComponentCustomOptions {
      beforeRouteEnter?(to: any, from: any, next: () => void): void
    }
  }
  ```

:::tip DICA
Os aumentos devem ser colocados num ficheiro `.ts` ou `.d.ts` de módulo. Consulte [Colocação do Aumento de Tipo](/guide/typescript/options-api#augmenting-global-properties) por mais detalhes.
:::

- **Consulte também:** [Guia - Aumentando Propriedades Globais](/guide/typescript/options-api#augmenting-global-properties)

## `ComponentCustomProps` {#componentcustomprops}

Usado para aumentar as propriedades de TSX permitidas no sentido de usar propriedades não declaradas sobre os elementos de TSX.

- **Exemplo**

  ```ts
  declare module 'vue' {
    interface ComponentCustomProps {
      hello?: string
    }
  }

  export {}
  ```

  ```tsx
  // agora funciona mesmo se `hello` não for uma propriedade declara
  <MyComponent hello="world" />
  ```

:::tip DICA
Os aumentos devem ser colocados num ficheiro `.ts` ou `.d.ts` de módulo. Consulte [Colocação do Aumento de Tipo](/guide/typescript/options-api#augmenting-global-properties) por mais detalhes.
:::

## `CSSProperties` {#cssproperties}

Usado para aumentar os valores permitidos nos vínculos da propriedade de estilo.

- **Exemplo**

  Permitir qualquer propriedade de CSS personalizada

  ```ts
  declare module 'vue' {
    interface CSSProperties {
      [key: `--${string}`]: string
    }
  }
  ```

  ```tsx
  <div style={ { '--bg-color': 'blue' } }>
  ```
  ```html
  <div :style="{ '--bg-color': 'blue' }"></div>
  ```

:::tip DICA
Os aumentos devem ser colocados num ficheiro `.ts` ou `.d.ts` de módulo. Consulte [Colocação do Aumento de Tipo](/guide/typescript/options-api#augmenting-global-properties) por mais detalhes.
:::
  
:::info CONSULTE TAMBÉM
Os marcadores `<style>` de componente de ficheiro único suportam ligação de valores de CSS ao estado do componente dinâmico usando a função de CSS `v-bind`. Isto permite propriedades personalizadas sem aumento de tipo.

- [`v-bind()` na CSS](/api/sfc-css-features#v-bind-in-css)
:::

---

---
url: /translations/index.md
---

# Traduções {#translations}

## Idiomas Disponíveis {#available-languages}

- [English](https://vuejs.org/) [[código-fonte](https://github.com/vuejs/docs)]
- [简体中文 / Simplified Chinese](https://cn.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-zh-cn)]
- [日本語 / Japanese](https://ja.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-ja)]
- [Українська / Ukrainian](https://ua.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-uk)]
- [Français / French](https://fr.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-fr)]
- [한국어 / Korean](https://ko.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-ko)]
- [Português / Portuguese](https://pt.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-pt)]
- [বাংলা / Bengali](https://bn.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-bn)]
- [Italiano / Italian](https://it.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-it)]
- [فارسی / Persian](https://fa.vuejs.org) [[código-fonte](https://github.com/vuejs-translations/docs-fa)]
- [Русский / Russian](https://ru.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-ru)]
- [Čeština / Czech](https://cs.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-cs)]
- [繁體中文 / Traditional Chinese](https://zh-hk.vuejs.org/) [[source](https://github.com/vuejs-translations/docs-zh-hk)]

## Idiomas com Traduções em Progresso {#work-in-progress-languages}

- [العربية / Arabic](https://ar.vuejs.org/) [[código-fonte](https://github.com/vuejs-translations/docs-ar)]

- [Español / Spanish](https://vue3-spanish-docs.netlify.app/) [[código-fonte](https://github.com/icarusgk/vuejs-spanish-docs)]

## Começando uma nova Tradução {#starting-a-new-translation}

A documentação da Vue foi recentemente submetida a uma grande revisão, então as traduções noutros idiomas continuam em falta ou com trabalho em curso.

Nós acolhemos bem os esforços da comunidade no sentido de fornecer mais traduções. Os esforços de tradução são geridos na organização [vuejs-translations](https://github.com/vuejs-translations/) da GitHub. Se estiveres interessado em contribuir, consulte as [Diretrizes de Tradução](https://github.com/vuejs-translations/guidelines/blob/main/README.md) para começares.

---

---
url: /guide/built-ins/transition.md
---
<script setup>
import Basic from './transition-demos/Basic.vue'
import SlideFade from './transition-demos/SlideFade.vue'
import CssAnimation from './transition-demos/CssAnimation.vue'
import NestedTransitions from './transition-demos/NestedTransitions.vue'
import JsHooks from './transition-demos/JsHooks.vue'
import BetweenElements from './transition-demos/BetweenElements.vue'
import BetweenComponents from './transition-demos/BetweenComponents.vue'
</script>

# Transição {#transition}

A Vue oferece dois componentes embutidos que podem ajudar a trabalhar com as transições e animações em resposta as mudanças de estado:

- `<Transition>` para aplicação de animações quando um elemento ou componente está entrando ou saindo do DOM. Isto é abordado nesta página.

- `<TransitionGroup>` para aplicação de animações quando um elemento ou componente é inserido, removido, movido de dentro de uma lista de `v-for`. Isto é abordado [no próximo capítulo](/guide/built-ins/transition-group.html).

Além destes dois componentes, podemos também aplicar animações na Vue usando outras técnicas tais como alternância de classes de CSS ou animações orientadas a estado através vinculações de estilo. Estas técnicas adicionais são abordadas no capítulo [Técnicas de Animação](/guide/extras/animation.html).

## O Componente `<Transition>` {#the-transition-component}

`<Transition>` é um componente embutido: isto significa que está disponível em qualquer modelo de marcação do componente sem ter que registá-lo. Isto pode ser utilizado para aplicar animações de entrada e saída sobre os elementos ou componentes passados para ele através da sua ranhura padrão. A entrada e saída pode ser acionada por um dos seguintes:

- Interpretação condicional através de `v-if`
- Exibição condicional através de `v-show`
- Alternância de componentes dinâmicos através do elemento especial `<component>`

Isto é um exemplo de uso mais básico:

```vue-html
<button @click="show = !show">Toggle</button>
<Transition>
  <p v-if="show">hello</p>
</Transition>
```

```css
/* nós explicaremos o que são estas classes fazem a seguir! */
.v-enter-active,
.v-leave-active {
  transition: opacity 0.5s ease;
}

.v-enter-from,
.v-leave-to {
  opacity: 0;
}
```

<Basic />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpVkEFuwyAQRa8yZZNWqu1sunFJ1N4hSzYUjRNUDAjGVJHluxcCipIV/OG/pxEr+/a+TwuykfGogvYEEWnxR2H17F0gWCHgBBtMwc2wy9WdsMIqZ2OuXtwfHErhlcKCb8LyoVoynwPh7I0kzAmA/yxEzsKXMlr9HgRr9Es5BTue3PlskA+1VpFTkDZq0i3niYfU6anRmbqgMY4PZeH8OjwBfHhYIMdIV1OuferQEoZOKtIJ328TgzJhm8BabHR3jeC8VJqusO8/IqCM+CnsVqR3V/mfRxO5amnkCPuK5B+6rcG2fydshks=)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpVkMFuAiEQhl9lyqlNuouXXrZo2nfwuBeKs0qKQGBAjfHdZZfVrAmB+f/M/2WGK/v1vs0JWcdEVEF72vQWz94Fgh0OMhmCa28BdpLk+0etAQJSCvahAOLBnTqgkLA6t/EpVzmCP7lFEB69kYRFAYi/ROQs/Cij1f+6ZyMG1vA2vj3bbN1+b1Dw2lYj2yBt1KRnXRwPudHDnC6pAxrjBPe1n78EBF8MUGSkixnLNjdoCUMjFemMn5NjUGacnboqPVkdOC+Vpgus2q8IKCN+T+suWENwxyWJXKXMyQ5WNVJ+aBqD3e6VSYoi)

</div>

:::tip Dica
`<Transition>` apenas suporta um único elemento ou componente como seu conteúdo de ranhura. Se o conteúdo é um componente, o componente deve também ter apenas um único elemento de raiz.
:::

Quando um elemento em um componente `<Transition>` é inserido ou removido, isto é o que acontece:

1. A Vue automaticamente farejará se elemento alvo tiver transições de CSS ou animações aplicadas. Se tiver, um número de [classes de transições de CSS](#classes-de-transição) serão adicionadas ou removidas no momento apropriado.

2. Se houverem ouvintes para [gatilhos de JavaScript](#gatilhos-de-javascript), estes gatilhos serão chamados no momento apropriado.

3. Se nenhuma transição ou animação de CSS for detetada e nenhum gatilho de JavaScript for fornecido, as operações do DOM para inserção e ou remoção serão executadas sobre o próximo quadro de animação do navegador.

## Transições Baseadas em CSS {#css-based-transitions}

### Classes de Transição {#transition-classes}

Existem seis classes aplicadas para as transições de entrada e saída.

![Diagrama de Transição](./images/transition-classes.png)

<!-- https://www.figma.com/file/rlOv0ZKJFFNA9hYmzdZv3S/Transition-Classes -->

1. `v-enter-from`: Estado inicial para entrada. Adicionado antes do elemento ser inserido, removido um quadro depois do elemento ser inserido.

2. `v-enter-active`: estado ativo para entrada. Aplciado durante a fase de entrada inteira. Adicionado antes do elemento ser inserido, removido quando a transição ou animação terminar. Esta calsse pode ser usada para definir a duração, o atraso e a curva de flexão para a transição de entrada.

3. `v-enter-to`: Estado final para entrada. Adicionado um quadro depois do elemento ser inserido (no mesmo momento que `v-enter-from` for removido), removido quando a transição ou animação terminar.

4. `v-leave-from`: Estado inicial para saída. Adicionada imediatamente quando a transição de saída for acionada, removida depois de um quadro.

5. `v-leave-active`: Estado ativo para saída. Aplicada durante a fase de saída inteira. Adicionada imediatamente quando um transição de saída é acionada, removida quando a transição ou animação termina. Esta classe pode ser usada para definir a duração, atraso e a curva de flexão para a transição de saída.

6. `v-leave-to`: Estado final para saída. Adicionada um quadro depois de uma transição de saída ser acionada (ao mesmo tempo que `v-leave-from` é removida), removida quando a transição ou animação termina.

`v-enter-active` e `v-leave-active` dão-nos a habilidade de especificar curvas de flexão diferentes para as transições de entrada ou saída, as quais veremos exemplos nas seguintes secções.

### Transições Nomeadas {#named-transitions}

Um transição pode ser nomeada através da propriedade `name`:

```vue-html
<Transition name="fade">
  ...
</Transition>
```

Para uma transição nomeada, suas classes de transição serão prefixadas com seu nome no lugar de `v`. Por exemplo, a classe aplicada para a transição de cima será `fade-enter-active` no lugar de `v-enter-active`. A CSS para a transição de desaparecimento (`fade`, em Inglês) deve parecer-se com isto:

```css
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.5s ease;
}

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}
```

### Transições de CSS {#css-transitions}

`<Transition>` é comummente usado em conjunto com [transições de CSS nativa](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions), conforme visto no exemplo básico de cima. A propriedade de CSS `transition` é uma forma abreviada que permite-nos especificar vários aspetos de uma transição, incluindo propriedades que devem ser animadas, duração da transição, e [curvas de flexão](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function).

Abaixo está mais um exemplo avançado que realiza transição de várias propriedades, com diferentes durações e curvas de flexão para entrada e saída:

```vue-html
<Transition name="slide-fade">
  <p v-if="show">hello</p>
</Transition>
```

```css
/*

  Animações de entrada e saída podem usar diferentes
  duranções e funções de tempo.
*/
.slide-fade-enter-active {
  transition: all 0.3s ease-out;
}

.slide-fade-leave-active {
  transition: all 0.8s cubic-bezier(1, 0.5, 0.8, 1);
}

.slide-fade-enter-from,
.slide-fade-leave-to {
  transform: translateX(20px);
  opacity: 0;
}
```

<SlideFade />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNpVkMFuAiEQhl9lyqlNuouXXrZo2nfwuBeKs0qKQGBAjfHdZZfVrAmB+f/M/2WGK/v1vs0JWcdEVEF72vQWz94Fgh0OMhmCa28BdpLk+0etAQJSCvahAOLBnTqgkLA6t/EpVzmCP7lFEB69kYRFAYi/ROQs/Cij1f+6ZyMG1vA2vj3bbN1+b1Dw2lYj2yBt1KRnXRwPudHDnC6pAxrjBPe1n78EBF8MUGSkixnLNjdoCUMjFemMn5NjUGacnboqPVkdOC+Vpgus2q8IKCN+T+suWENwxyWJXKXMyQ5WNVJ+aBqD3e6VSYoi)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqFkc1uwjAMgF/F6wk0SmHTJNQFtF32AuOwQy+hdSFamkSJ08EQ776EbMAkJKTIf7I/O/Y+ezVm3HvMyoy52gpDi0rh1mhL0GDLvSTYVwqg4cQHw2QDWCRv1Z8H4Db6qwSyHlPkEFUQ4bHixA0OYWckJ4wesZUn0gpeainqz3mVRQzM4S7qKlss9XotEd6laBDu4Y03yIpUE+oB2NJy5QSJwFC8w0iIuXkbMkN9moUZ6HPR/uJDeINSalaYxCjOkBBgxeWEijnayWiOz+AcFaHNeU2ix7QCOiFK4FLCZPzoALnDXHt6Pq7hP0Ii7/EGYuag9itR5yv8FmgH01EIPkUxG8F0eA2bJmut7kbX+pG+6NVq28WTBTN+92PwMDHbSAXQhteCdiVMUpNwwuMassMP8kfAJQ==)

</div>

### Animações de CSS {#css-animations}

As [animações de CSS nativa](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations) são aplicadas da mesma maneira que as transições de CSS com a diferença de que `*-enter-from` não é removida imediatamente depois do elemento ser inserido, mas sobre um evento de `animationend`.

Para a maior parte das animações de CSS, podemos simplesmente declará-las sob as classes `*-enter-active` e `*-leave-active`. Abaixo encontra-se o exemplo disto:

```vue-html
<Transition name="bounce">
  <p v-if="show" style="text-align: center;">
    Hello here is some bouncy text!
  </p>
</Transition>
```

```css
.bounce-enter-active {
  animation: bounce-in 0.5s;
}
.bounce-leave-active {
  animation: bounce-in 0.5s reverse;
}
@keyframes bounce-in {
  0% {
    transform: scale(0);
  }
  50% {
    transform: scale(1.25);
  }
  100% {
    transform: scale(1);
  }
}
```

<CssAnimation />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNksGOgjAQhl9lJNmoBwRNvCAa97YP4JFLbQZsLG3TDqzG+O47BaOezCYkpfB9/0wHbsm3c4u+w6RIyiC9cgQBqXO7yqjWWU9wA4813KH2toUpo9PKVEZaExg92V/YRmBGvsN5ZcpsTGGfN4St04Iw7qg8dkTWwF5qJc/bKnnYk7hWye5gm0ZjmY0YKwDlwQsTFCnWjGiRpaPtjETG43smHPSpqh9pVQKBrjpyrfCNMilZV8Aqd5cNEF4oFVo1pgCJhtBvnjEAP6i1hRN6BBUg2BZhKHUdvMmjWhYHE9dXY/ygzN4PasqhB75djM2mQ7FUSFI9wi0GCJ6uiHYxVsFUGcgX67CpzP0lahQ9/k/kj9CjDzgG7M94rT1PLLxhQ0D+Na4AFI9QW98WEKTQOMvnLAOwDrD+wC0Xq/Ubusw/sU+QL/45hskk9z8Bddbn)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNUs2OwiAQfpWxySZ66I8mXioa97YP4LEXrNNKpEBg2tUY330pqOvJmBBgyPczP1yTb2OyocekTJirrTC0qRSejbYEB2x4LwmulQI4cOLTWbwDWKTeqkcE4I76twSyPcaX23j4zS+WP3V9QNgZyQnHiNi+J9IKtrUU9WldJaMMrGEynlWy2em2lcjyCPMUALazXDlBwtMU79CT9rpXNXp4tGYGhlQ0d7UqAUcXOeI6bluhUtKmhEVhzisgPFPKpWhVCTUqQrt6ygD8oJQajmgRhAOnO4RgdQm8yd0tNzGv/D8x/8Dy10IVCzn4axaTTYNZymsSA8YuciU6PrLL6IKpUFBkS7cKXXwQJfIBPyP6IQ1oHUaB7QkvjfUdcy+wIFB8PeZIYwmNtl0JruYSp8XMk+/TXL7BzbPF8gU6L95hn8D4OUJnktsfM1vavg==)

</div>

### Classes de Transição Personalizadas {#custom-transition-classes}

Tu podes também especificar classes de transição personalizadas passando as seguintes propriedades para o `<Transition>`:

- `enter-from-class`
- `enter-active-class`
- `enter-to-class`
- `leave-from-class`
- `leave-active-class`
- `leave-to-class`

Estas irão sobrepor-se aos nomes convencionais das classes. Isto é especialmente útil quando queres combinar o sistema de transição da Vue com uma biblioteca de animação de CSS existente, tal como [Animate.css](https://daneden.github.io/animate.css/):

```vue-html
<!-- assumindo que Animate.css está incluída na página -->
<Transition
  name="custom-classes"
  enter-active-class="animate__animated animate__tada"
  leave-active-class="animate__animated animate__bounceOutRight"
>
  <p v-if="show">hello</p>
</Transition>
```

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNUctuwjAQ/BXXF9oDsZB6ogbRL6hUcbSEjLMhpn7JXtNWiH/vhqS0R3zxPmbWM+szf02pOVXgSy6LyTYhK4A1rVWwPsWM7MwydOzCuhw9mxF0poIKJoZC0D5+stUAeMRc4UkFKcYpxKcEwSenEYYM5b4ixsA2xlnzsVJ8Yj8Mt+LrbTwcHEgxwojCmNxmHYpFG2kaoxO0B2KaWjD6uXG6FCiKj00ICHmuDdoTjD2CavJBCna7KWjZrYK61b9cB5pI93P3sQYDbxXf7aHHccpVMolO7DS33WSQjPXgXJRi2Cl1xZ8nKkjxf0dBFvx2Q7iZtq94j5jKUgjThmNpjIu17ZzO0JjohT7qL+HsvohJWWNKEc/NolncKt6Goar4y/V7rg/wyw9zrLOy)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNUcFuwjAM/RUvp+1Ao0k7sYDYF0yaOFZCJjU0LE2ixGFMiH9f2gDbcVKU2M9+tl98Fm8hNMdMYi5U0tEEXraOTsFHho52mC3DuXUAHTI+PlUbIBLn6G4eQOr91xw4ZqrIZXzKVY6S97rFYRqCRabRY7XNzN7BSlujPxetGMvAAh7GtxXLtd/vLSlZ0woFQK0jumTY+FJt7ORwoMLUObEfZtpiSpRaUYPkmOIMNZsj1VhJRWeGMsFmczU6uCOMHd64lrCQ/s/d+uw0vWf+MPuea5Vp5DJ0gOPM7K4Ci7CerPVKhipJ/moqgJJ//8ipxN92NFdmmLbSip45pLmUunOH1Gjrc7ezGKnRfpB4wJO0ZpvkdbJGpyRfmufm+Y4Mxo1oK16n9UwNxOUHwaK3iQ==)

</div>

### Usando Juntas Transições e Animações {#using-transitions-and-animations-together}

A Vue precisa atribuir ouvintes de evento para saber quando uma transição termina. Isto pode ser tanto `transitionend` ou `animationend`, dependendo do tipo de regras de CSS aplicada. Se estás apenas a usar um ou o outro, a Vue pode automaticamente detetar o tipo correto.

No entanto, em alguns casos podes desejar ter ambos no mesmo elemento, por exemplo, ter uma animação de CSS acionada pela Vue, juntamente com um efeito de transição de CSS sobre pairar do ponteiro do rato. Nestes casos, terás que declarar explicitamente o tipo que quiseres que a Vue preocupe-se passando a propriedade `type`, com o valor de ou `animation` ou `transition`:

```vue-html
<Transition type="animation">...</Transition>
```

### Transições Encaixadas e Durações de Transição Explícita {#nested-transitions-and-explicit-transition-durations}

Apesar das classes de transição serem apenas aplicadas ao elemento filho direto no `<Transition>`, podemos aplicar a transição aos elementos encaixados usando seletores de CSS encaixado:

```vue-html
<Transition name="nested">
  <div v-if="show" class="outer">
    <div class="inner">
      Hello
    </div>
  </div>
</Transition>
```

```css
/* regras que miram os elementos encaixados */
.nested-enter-active .inner,
.nested-leave-active .inner {
  transition: all 0.3s ease-in-out;
}

.nested-enter-from .inner,
.nested-leave-to .inner {
  transform: translateX(30px);
  opacity: 0;
}

/* ... outras CSS necessárias omitidas */
```

Nós podemos até mesmo adicionar um atraso de transição para o elemento encaixado na entrada, o que cria uma sequência de animação de entrada escalonada:

```css{3}
/* atrasar a entrada do elemento encaixado para o efeito escalonado */
.nested-enter-active .inner {
  transition-delay: 0.25s;
}
```

No entanto, isto cria um pequeno problema. Por padrão, o componente `<Transition>` tenta automaticamente saber quando a transição terminou ouvindo o **primeiro** evento `transitionend` ou `animationend` sobre o elemento de transição de raiz. Com uma transição encaixada, o comportamento desejado deve ser esperar até as transições de todos elementos internos estiverem termidas.

Nestes casos podes especificar uma duração de transição explícita (em milissegundos) usando a propriedade `duration` no componente `<transition>`. A duração total deve corresponder ao atraso mais a duração da transição do elemento interno:

```vue-html
<Transition :duration="550">...</Transition>
```

<NestedTransitions />

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNUcFuwjAM/RUvp+1Ao0k7sYDYF0yaOFZCJjU0LE2ixGFMiH9f2gDbcVKU2M9+tl98Fm8hNMdMYi5U0tEEXraOTsFHho52mC3DuXUAHTI+PlUbIBLn6G4eQOr91xw4ZqrIZXzKVY6S97rFYRqCRabRY7XNzN7BSlujPxetGMvAAh7GtxXLtd/vLSlZ0woFQK0jumTY+FJt7ORwoMLUObEfZtpiSpRaUYPkmOIMNZsj1VhJRWeGMsFmczU6uCOMHd64lrCQ/s/d+uw0vWf+MPuea5Vp5DJ0gOPM7K4Ci7CerPVKhipJ/moqgJJ//8ipxN92NFdmmLbSip45pLmUunOH1Gjrc7ezGKnRfpB4wJO0ZpvkdbJGpyRfmufm+Y4Mxo1oK16n9UwNxOUHwaK3iQ==)

Se necessário, podes também especificar valores separados para as durações de entrada e saída usando um objeto:

```vue-html
<Transition :duration="{ enter: 500, leave: 800 }">...</Transition>
```

### Considerações de Desempenho {#performance-considerations}


Tu podes reparar que as animações mostradas acima estão na maior parte das vezes usando propriedades como `transform` e `opacity`. Estas propriedades são eficiantes ao animar porque:


1. Elas não afetam a disposição do documento durante a animação, então elas não acionam cálculos de disposição de CSS dispendiosos em cada quadro da animação.

2. A maior parte dos navegadores podem influenciar a aceleração de hardware da GPU quando estão animando a `transform`.

Em comparação, propriedades como `height` ou `margin` acionarão a disposição de CSS, então são muito mais dispensiosas para animar, e devem ser usadas com cautela. Nós podemos consultas recursos como [CSS-Triggers](https://csstriggers.com/) para saber quais propriedades acionarão a disposição se as animarmos.

## Gatilhos de JavaScript {#javascript-hooks}

Tu podes ligar-te ao processo de transição com a JavaScript ouvindo os eventos sobre o componente `<Transition>`:

```html
<Transition
  @before-enter="onBeforeEnter"
  @enter="onEnter"
  @after-enter="onAfterEnter"
  @enter-cancelled="onEnterCancelled"
  @before-leave="onBeforeLeave"
  @leave="onLeave"
  @after-leave="onAfterLeave"
  @leave-cancelled="onLeaveCancelled"
>
  <!-- ... -->
</Transition>
```

<div class="composition-api">

```js
// chamada antes do elemento ser inserido no DOM.
// usa isto para definir o estado "enter-from" do elemento
function onBeforeEnter(el) {}

// chamada um quadro depois do elemento ser inserido.
// usa isto para iniciar a animação de entrada.
function onEnter(el, done) {
  // chama a resposta "done" para indicar o fim da transição
  // opcional se usada em conjunto com a CSS
  done()
}

// chamada quando a transição de entrada termina.
function onAfterEnter(el) {}
function onEnterCancelled(el) {}

// chamada antes do gatilho de saída.
// A maior parte das vezes, deves apenas usar o gatilho de saída
function onBeforeLeave(el) {}

// chamada quando a transição de saída começa.
// usa isto para iniciar a animação de saída.
function onLeave(el, done) {
  // chama a resposta "done" para indicar o fim da transição
  // opcional se usada em conjunto com a CSS
  done()
}

// chamda quando a transição de saída termina e o
// elemento foi removido do DOM.
function onAfterLeave(el) {}

// apenas disponível com as transições de "v-show"
function onLeaveCancelled(el) {}
```

</div>
<div class="options-api">

```js
export default {
  // ...
  methods: {
    // chamada antes do elemento ser inserido no DOM.
    // usa isto para definir o estado "enter-from" do elemento
    onBeforeEnter(el) {},

    // chamada um quadro depois do elemento ser inserido.
    // usa isto para iniciar a animação de entrada.
    onEnter(el, done) {
      // chama a resposta "done" para indicar o fim da transição
      // opcional se usada em conjunto com a CSS
      done()
    },

    // chamada quando a transição de entrada termina.
    onAfterEnter(el) {},
    onEnterCancelled(el) {},

    // chamada antes do gatilho de saída.
    // A maior parte das vezes, deves apenas usar o gatilho de saída
    onBeforeLeave(el) {},

    // chamada quando a transição de saída começa.
    // usa isto para iniciar a animação de saída.
    onLeave(el, done) {
      // chama a resposta "done" para indicar o fim da transição
      // opcional se usada em conjunto com a CSS
      done()
    },

    // chamda quando a transição de saída termina e o
    // elemento foi removido do DOM.
    onAfterLeave(el) {},

    // apenas disponível com as transições de "v-show"
    onLeaveCancelled(el) {}
  }
}
```

</div>

Estes gatilhos podem ser usados em conjunto com as transições ou animações de CSS ou por conta própria.

Quando usamos transições em JavaScript apenas, é usualmente uma boa ideia adicionar a propriedade `:css="false"`. Isto diz explicitamente a Vue para ignorar a deteção automática de transição de CSS. Além de ter ligeiramente um desempenho melhor, isto também impedi as regras de CSS de acidentalmente interferirem com a transição:

```vue-html{3}
<Transition
  ...
  :css="false"
>
  ...
</Transition>
```

Com `:css="false"`, somos também completamente responsáveis pelo controle de quando a transição termina. Neste caso, as respostas `done` são obrigatórias para os gatilhos `@enter` e `@leave`. De outro modo, os gatilhos serão chamados de maneira síncrona e a transição terminará imediatamente.

Cá está uma demonstração usando a [biblioteca GreenSock](https://greensock.com/) para realizar as animações. Tu podes, com certeza, usar qualquer outra biblioteca de animação que quiseres, por exemplo [Anime.js](https://animejs.com/) ou [Motion One](https://motion.dev/).

<JsHooks />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNVMtu2zAQ/JUti8I2YD3i1GigKmnaorcCveTQArpQFCWzlkiCpBwHhv+9Sz1qKYckJ3FnlzvD2YVO5KvW4aHlJCGpZUZoB5a7Vt9lUjRaGQcnMLyEM5RGNbDA0sX/VGWpHnB/xEQmmZIWe+zUI9z6m0tnWr7ymbKVzAklQclvvFSG/5COmyWvV3DKJHTdQiRHZN0jAJbRmv9OIA432/UE+jODlKZMuKcErnx8RrazP8woR7I1FEryKaVTU8aiNdRfwWZTQtQwi1HAGF/YB4BTyxNY8JpaJ1go5K/WLTfhdg1Xq8V4SX5Xja65w0ovaCJ8Jvsnpwc+l525F2XH4ac3Cj8mcB3HbxE9qnvFMRzJ0K3APuhIjPefmTTyvWBAGvWbiDuIgeNYRh3HCCDNW+fQmHtWC7a/zciwaO/8NyN3D6qqap5GfVnXAC89GCqt8Bp77vu827+A+53AJrOFzMhQdMnO8dqPpMO74Yx4wqxFtKS1HbBOMdIX4gAMffVp71+Qq2NG4BCIcngBKk8jLOvfGF30IpBGEwcwtO6p9sdwbNXPIadsXxnVyiKB9x83+c3N9WePN9RUQgZO6QQ2sT524KMo3M5Pf4h3XFQ7NwFyZQpuAkML0doEtvEHhPvRDPRkTfq/QNDgRvy1SuIvpFOSDQmbkWTckf7hHsjIzjltkyhqpd5XIVNN5HNfGlW09eAcMp3J+R+pEn7L)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNVFFvmzAQ/is3pimNlABNF61iaddt2tukvfRhk/xiwIAXsJF9pKmq/PedDTSwh7ZSFLjvzvd9/nz4KfjatuGhE0ES7GxmZIu3TMmm1QahtLyFwugGFu51wRQAU+Lok7koeFcjPDk058gvlv07gBHYGTVGALbSDwmg6USPnNzjtHL/jcBK5zZxxQwZavVNFNqIHwqF8RUAWs2jn4IffCfqQz+mik5lKLWi3GT1hagHRU58aAUSshpV2YzX4ncCcbjZDp099GcG6ZZnEh8TuPR8S0/oTJhQjmQryLUSU0rUU8a8M9wtoWZTQtIwi0nAGJ/ZB0BwKxJYiJpblFko1a8OLzbhdgWXy8WzP99109YCqdIJmgifyfYuzmUzfFF2HH56o/BjAldx/BbRo7pXHKMjGbrl1IcciWn9fyaNfC8YsIueR5wCFFTGUVAEsEs7pOmDu6yW2f6GBW5o4QbeuScLbu91WdZiF/VlvgEtujdcWek09tx3qZ+/tXAzQU1mA8mCoeicneO1OxKP9yM+4ElmLaEFr+2AecVEn8sDZOSrSzv/1qk+sgAOa1kMOyDlu4jK+j1GZ70E7KKJAxRafKzdazi26s8h5dm+NLpTeQLvP27S6+urz/7T5aaUao26TWATt0cPPsgcK3f6Q1wJWVY4AVJtcmHWhueyo89+G38guD+agT5YBf39s25oIv5arehu8krYkLAs8BeG86DfuANYUCG2NomiTrX7Msx0E7ncl0bnXT04566M4PQPykWaWw==)

</div>

## Transições Reutilizáveis {#reusable-transitions}

As transições podem ser reutilizadas através do sistema de componente da Vue. Para criar uma transição reutilizável, podemos criar um componente que envolve o componente `<Transition>` e passar o conteúdo da ranhura:

```vue{5}
<!-- MyTransition.vue -->
<script>
// Lógica dos gatilhos de JavaScript...
</script>

<template>
  <!-- envolve o componente Transition embutido -->
  <Transition
    name="my-transition"
    @enter="onEnter"
    @leave="onLeave">
    <slot></slot> <!-- passa o conteúdo da ranhura -->
  </Transition>
</template>

<style>
/*
  CSS necessária...
  Nota: evite usar <style scoped> aqui já que não
  se aplica ao conteúdo da ranhura.
*/
</style>
```

Agora `MyTransition` pode ser importada e usada tal como a versão embutida:

```vue-html
<MyTransition>
  <div v-if="show">Hello</div>
</MyTransition>
```

## Transição sobre o Aparecimento {#transition-on-appear}

Se quiseres também aplicar uma transição sobre a interpretação inicial de um nó, podes adicionar o atributo `appear`:

```vue-html
<Transition appear>
  ...
</Transition>
```

## Transição Entre Elementos {#transition-between-elements}

Além de alternar um elemento com `v-if` ou `v-show`, podemos também realizar a transição entre dois elementos usando `v-if`, `v-else` ou `v-else-if`:

```vue-html
<Transition>
  <button v-if="docState === 'saved'">Edit</button>
  <button v-else-if="docState === 'edited'">Save</button>
  <button v-else-if="docState === 'editing'">Cancel</button>
</Transition>
```

<BetweenElements />

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqNVFFvmzAQ/is3pimNlABNF61iaddt2tukvfRhk/xiwIAXsJF9pKmq/PedDTSwh7ZSFLjvzvd9/nz4KfjatuGhE0ES7GxmZIu3TMmm1QahtLyFwugGFu51wRQAU+Lok7koeFcjPDk058gvlv07gBHYGTVGALbSDwmg6USPnNzjtHL/jcBK5zZxxQwZavVNFNqIHwqF8RUAWs2jn4IffCfqQz+mik5lKLWi3GT1hagHRU58aAUSshpV2YzX4ncCcbjZDp099GcG6ZZnEh8TuPR8S0/oTJhQjmQryLUSU0rUU8a8M9wtoWZTQtIwi0nAGJ/ZB0BwKxJYiJpblFko1a8OLzbhdgWXy8WzP99109YCqdIJmgifyfYuzmUzfFF2HH56o/BjAldx/BbRo7pXHKMjGbrl1IcciWn9fyaNfC8YsIueR5wCFFTGUVAEsEs7pOmDu6yW2f6GBW5o4QbeuScLbu91WdZiF/VlvgEtujdcWek09tx3qZ+/tXAzQU1mA8mCoeicneO1OxKP9yM+4ElmLaEFr+2AecVEn8sDZOSrSzv/1qk+sgAOa1kMOyDlu4jK+j1GZ70E7KKJAxRafKzdazi26s8h5dm+NLpTeQLvP27S6+urz/7T5aaUao26TWATt0cPPsgcK3f6Q1wJWVY4AVJtcmHWhueyo89+G38guD+agT5YBf39s25oIv5arehu8krYkLAs8BeG86DfuANYUCG2NomiTrX7Msx0E7ncl0bnXT04566M4PQPykWaWw==)

## Modos de Transição {#transition-modes}

No exemplo anterior, as entradas e saídas dos elementos são animadas ao mesmo tempo, e tinhamos que torná-las `position: absolute` para evitar o problema de disposição quando ambos elementos estiverem presentes no DOM.

No entanto, em alguns casos isto não é uma opção, ou simplesmente não é o comportamento desejado. Nós podemos desejar deixar o elemento ser animado primeiro, e para entrada o elemento ser apenas inserido **depois** de terminada a animação de saída. Orquestrar tais animações manualmente seria muito complicado - felizmente, podemos ativar este comportamento passando para `<Transition>` uma propriedade `mode`:

```vue-html
<Transition mode="out-in">
  ...
</Transition>
```

Cá está a demonstração anterior com `mode="out-in"`:

<BetweenElements mode="out-in" />

`<Transition>` também suporta `mode="in-out"`, embora que seja muito menos usada com frequência.

## Transição Entre Componentes {#transition-between-components}

`<Transition>` também pode ser usada em torno dos [componentes dinâmicos](/guide/essentials/component-basics.html#componentes-dinâmicos):

```vue-html
<Transition name="fade" mode="out-in">
  <component :is="activeComponent"></component>
</Transition>
```

<BetweenComponents />

<div class="composition-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqtksFugzAMhl/F4tJNKtDLLoxWKnuDacdcUnC3SCGJiMmEqr77EkgLbXfYYZyI8/v77dinZG9M5npMiqS0dScMgUXqzY4p0RrdEZzAfnEp9fc7HuEMx063sPIZq6viTbdmHy+yfDwF5K2guhFUUcBUnkNvcelBGrjTooHaC7VCRXBAoT6hQTRyAH2w2DlsmKq1sgS8JuEwUCfxdgF7Gqt5ZqrMp+58X/5A2BrJCcOJSskPKP0v+K8UyvQENBjcsqTjjdAsAZe2ukHpI3dm/q5wXPZBPFqxZAf7gCrzGfufDlVwqB4cPjqurCChFSjeBvGRN+iTA9afdE+pUD43FjG/bSHsb667Mr9qJot89vCBMl8+oiotDTL8ZsE39UnYpRN0fQlK5A5jEE6BSVdiAdrwWtAAm+zFAnKLr0ydA3pJDDt0x/PrMrJifgGbKdFPfCwpWU+TuWz5omzfVCNcfJJ5geL8pqtFn5E07u7fSHFOj6TzDyUDNEM=)

</div>
<div class="options-api">

[Experimente-o na Zona de Testes](https://play.vuejs.org/#eNqtksFugzAMhl/F4tJNKtDLLoxWKnuDacdcUnC3SCGJiMmEqr77EkgLbXfYYZyI8/v77dinZG9M5npMiqS0dScMgUXqzY4p0RrdEZzAfnEp9fc7HuEMx063sPIZq6viTbdmHy+yfDwF5K2guhFUUcBUnkNvcelBGrjTooHaC7VCRXBAoT6hQTRyAH2w2DlsmKq1sgS8JuEwUCfxdgF7Gqt5ZqrMp+58X/5A2BrJCcOJSskPKP0v+K8UyvQENBjcsqTjjdAsAZe2ukHpI3dm/q5wXPZBPFqxZAf7gCrzGfufDlVwqB4cPjqurCChFSjeBvGRN+iTA9afdE+pUD43FjG/bSHsb667Mr9qJot89vCBMl8+oiotDTL8ZsE39UnYpRN0fQlK5A5jEE6BSVdiAdrwWtAAm+zFAnKLr0ydA3pJDDt0x/PrMrJifgGbKdFPfCwpWU+TuWz5omzfVCNcfJJ5geL8pqtFn5E07u7fSHFOj6TzDyUDNEM=)

</div>

## Transições Dinâmicas {#dynamic-transitions}

As propriedades de `<Transition>` como `name` também podem ser dinâmicas! Ela permite-nos aplicar dinamicamente transições diferentes baseadas na mudança de estado:

```vue-html
<Transition :name="transitionName">
  <!-- ... -->
</Transition>
```

Isto pode ser útil quando tiveres definido transições ou animações de CSS usando as convenções de classe de transição da Vue e quiseres alternar entre elas.

Tu também podes aplicar comportamento diferente nos gatilhos de transição de JavaScript baseado no estado atual do teu componente. Finalmente, a maneira fundamental de criar transições dinâmicas é através de [componentes de transição reutilizáveis](#transições-reutilizáveis) que aceitam propriedades para mudar a natureza da transição ou transições a ser usadas. Isto pode soar foleiro, mas o único limite é realmente a tua imaginação.

---

**Relacionado ao**

- [Referência da API de `<Transition>`](/api/built-in-components.html#transition)

---

---
url: /tutorial/index.md
---

<script>
import { defineAsyncComponent } from 'vue'
import ReplLoading from '@theme/components/ReplLoading.vue'

export default {
  components: {
    TutorialRepl: defineAsyncComponent({
      loader: () => import('./TutorialRepl.vue'),
      loadingComponent: ReplLoading
    })
  }
}
</script>

<ClientOnly>
  <TutorialRepl />
</ClientOnly>

---

---
url: /guide/typescript/composition-api.md
---
# TypeScript com a API de Composição {#typescript-with-composition-api}

> Esta página presume que já leste a visão geral no [Usando a Vue com a TypeScript](./overview).

## Tipos para as Propriedades do Componente {#typing-component-props}

### Usando `<script setup>` {#using-script-setup}

Quando estivermos a usar o `<script setup>`, a macro `defineProps()` suporta a inferência de tipos de propriedades baseado no seu argumento:

```vue
<script setup lang="ts">
const props = defineProps({
  foo: { type: String, required: true },
  bar: Number
})

props.foo // string
props.bar // number | undefined
</script>
```

Isto é chamado de "declaração de tempo de execução", porque o argumento passado para `defineProps()` será utilizado como opção `props` de tempo de execução.

No entanto, é normalmente mais direto definir as propriedades com os tipos puros através de um argumento de tipo genérico:

```vue
<script setup lang="ts">
const props = defineProps<{
  foo: string
  bar?: number
}>()
</script>
```

Isto é chamado "declaração baseada em tipo". O compilador tentará fazer o seu melhor para inferir as opções de tempo de execução equivalente baseado no argumento de tipo. Neste caso, o nosso segundo exemplo compila para as exatas mesmas opções de tempo de execução que as do primeiro exemplo.

Nós podemos usar ou a declaração baseada em tipo OU a declaração de tempo de execução, mas não podemos usar ambas ao mesmo tempo.

Nós podemos também mover os tipos das propriedades para uma interface separada:

```vue
<script setup lang="ts">
interface Props {
  foo: string
  bar?: number
}

const props = defineProps<Props>()
</script>
```

#### Limitações de Sintaxe {#syntax-limitations}

Na versão 3.2 e abaixo, o parâmetro de tipo genérico para `defineProps()` estavam limitados à um literal de tipo ou uma referência à uma inferência local.

Esta limitação tinha sido resolvida na 3.3, A versão mais recente da Vue suporta a referência dum conjunto importado e limitado de tipos complexos na posição do parâmetro de tipo. No entanto, uma vez que o tipo para conversão de tempo de execução ainda é baseado na Árvore de Sintaxe Abstrata, alguns tipos complexos que exigem a analise do tipo verdadeiro, por exemplo, tipos condicionais, não são suportados. Nós podemos usar os tipos condicionais para o tipo duma única propriedade, mas não para objeto de propriedades inteira.

### Valores Padrão das Propriedades {#props-default-values}

Quando estamos a usar a declaração baseada no tipo, perdemos a habilidade de declarar valores padrão para as propriedades. Isto pode ser resolvido pela macro `withDefaults` do compilador:

```ts
export interface Props {
  msg?: string
  labels?: string[]
}

const props = withDefaults(defineProps<Props>(), {
  msg: 'hello',
  labels: () => ['one', 'two']
})
```

Isto será compilado para as opções `default` das propriedades de tempo de execução equivalentes. Além disto, a auxiliar `withDefaults` fornece verificação de tipo para os valores padrão, e garante que os tipo de `props` retornado tenha opções opcionais removidas para as propriedades que tiverem valores padrão declarados.

### Sem `<script setup>` {#without-script-setup}

Se não estivermos a usar `<script setup>`, é necessário usar `defineComponent()` para ativar a inferência de tipo das propriedades. O tipo do objeto das propriedades passadas para `setup()` é inferida a partir da opção `props`.

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  props: {
    message: String
  },
  setup(props) {
    props.message // <-- type: string
  }
})
```

### Tipos de Propriedades Complexas {#complex-prop-types}

Com a declaração baseada no tipo, uma propriedade pode usar um tipo complexo tal como qualquer outro tipo:

```vue
<script setup lang="ts">
interface Book {
  title: string
  author: string
  year: number
}

const props = defineProps<{
  book: Book
}>()
</script>
```

Para a declaração de tempo de execução, podemos usar o tipo utilitário `PropType`:

```ts
import type { PropType } from 'vue'

const props = defineProps({
  book: Object as PropType<Book>
})
```

Isto funciona exatamente da mesma maneira se estivéssemos a especificar a opção `props` diretamente:

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

export default defineComponent({
  props: {
    book: Object as PropType<Book>
  }
})
```

A opção `props` é mais comummente usada com a API de Opções, então encontrarás exemplos mais detalhados no guia para [TypeScript com a API de Opções](/guide/typescript/options-api#typing-component-props). As técnicas mostradas nestes exemplos também aplicam-se as declarações de tempo de execução usando `defineProps()`.

## Tipos para as Emissões do Componente {#typing-component-emits}

No `<script setup>`, o tipo da função `emit` também pode ser atribuído usando ou a declaração de tempo de execução OU a declaração de tipo:

```vue
<script setup lang="ts">
// tempo de execução (runtime)
const emit = defineEmits(['change', 'update'])

// baseada em tipo (type-based)
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>
```

O argumento de tipo deve ser um literal de tipo com [Assinaturas de Chamada](https://www.typescriptlang.org/docs/handbook/2/functions.html#call-signatures). O literal de tipo será usado como tipo da função `emit` retornada. Conforme podemos ver, a declaração de tipo dá-nos o controlo mais refinado sobre as restrições do tipo dos eventos emitidos.

Quando não se está utilizando `<script setup>`, a `defineComponent()` é capaz de inferir os eventos permitidos para a função `emit` exposta sobre o contexto da configuração:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  emits: ['change'],
  setup(props, { emit }) {
    emit('change') // <-- verificação de tipo / conclusão automática
  }
})
```

## Tipos para a `ref()` {#typing-ref}

As referências inferem o tipo a partir do valor inicial:

```ts
import { ref } from 'vue'

// tipo inferido: Ref<number>
const year = ref(2020)

// => Erro de TypeScript: tipo 'string' não é atribuível ao tipo 'number'.
year.value = '2020'
```

Algumas vezes podemos precisar de especificar os tipos complexos para um valor interno da referência. Nós podemos fazer isto usando o tipo `Ref`:

```ts
import { ref } from 'vue'
import type { Ref } from 'vue'

const year: Ref<string | number> = ref('2020')

year.value = 2020 // ok!
```

Ou, passando um argumento genérico quando estivermos chamando a `ref()` para sobrepor a inferência padrão:

```ts
// tipo resultante: Ref<string | number>
const year = ref<string | number>('2020')

year.value = 2020 // ok!
```

Se especificarmos um argumento de tipo genérico mas omitirmos o valor inicial, o tipo resultante será um tipo de união que inclui `undefined`:

```ts
// tipo inferido: Ref<number | undefined>
const n = ref<number>()
```

## Tipos para a `reactive()` {#typing-reactive}

A `reactive()` também infere implicitamente o tipo a partir do seu argumento:

```ts
import { reactive } from 'vue'

// tipo inferido: { title: string }
const book = reactive({ title: 'Vue 3 Guide' })
```

Para atribuir tipos explicitamente para uma propriedade de `reactive`, podemos usar as inferências:

```ts
import { reactive } from 'vue'

interface Book {
  title: string
  year?: number
}

const book: Book = reactive({ title: 'Vue 3 Guide' })
```

:::tip DICA
Não é recomendado usar o argumento genérico da `reactive()` porque o tipo retornado, o qual manipula o desembrulhar da referência encaixada, é diferente do tipo do argumento genérico.
:::

## Tipos para a `computed()` {#typing-computed}

A `computed()` infere o seu tipo baseado no valor de retorno do recuperador:

```ts
import { ref, computed } from 'vue'

const count = ref(0)

// tipo inferido: ComputedRef<number>
const double = computed(() => count.value * 2)

// => Erro de TypeScript: A propriedade 'split' não existe no tipo 'number'
const result = double.value.split('')
```

Nós podemos também especificar um tipo explícito através de um argumento genérico:

```ts
const double = computed<number>(() => {
  // erro de tipo se isto não retornar um número
})
```

## Tipos para os Manipuladores de Evento {#typing-event-handlers}

Quando estivermos a lidar com eventos de DOM nativo, pode ser útil definir o tipo para o argumento que passamos para o manipulador corretamente. Daremos uma vista de olhos neste exemplo:

```vue
<script setup lang="ts">
function handleChange(event) {
  // `event` tem implicitamente o tipo `any`
  console.log(event.target.value)
}
</script>

<template>
  <input type="text" @change="handleChange" />
</template>
```

Sem a anotação de tipo, o argumento `event` terá implicitamente um tipo de `any`. Isto também resultará num erro de TypeScript se `"strict": true` ou `"noImplicitAny": true` forem utilizados no `tsconfig.json`. É portanto recomendado anotar explicitamente o argumento dos manipuladores de evento. Além disto, podemos precisar de usar as asserções de tipo quando acessamos as propriedades de  `event`:

```ts
function handleChange(event: Event) {
  console.log((event.target as HTMLInputElement).value)
}
```

## Tipos para `provide()` / `inject()` {#typing-provide-inject}

O fornecimento e a injeção são normalmente realizadas em componentes separados. Para corretamente definir os tipos dos valores injetados, a Vue fornece uma interface `InjectionKey`, que é um tipo genérico que estende o `Symbol`. Este pode ser usado para sincronizar o tipo do valor injetado entre o fornecedor e o consumidor:

```ts
import { provide, inject } from 'vue'
import type { InjectionKey } from 'vue'

const key = Symbol() as InjectionKey<string>

// fornecer valor que não é uma sequência de caracteres resultará em erro
provide(key, 'foo')

const foo = inject(key) // tipo de foo: string | undefined
```

É recomendado colocar a chave de injeção num ficheiro separado para que possa ser importada em vários componentes.

Quando estivermos usando as chaves de injeção de sequência de caracteres, o tipo do valor injetado será `unknown`, e precisará ser explicitamente declarados através dum argumento de tipo genérico:

```ts
const foo = inject<string>('foo') // type: string | undefined
```

Repara que o valor injetado ainda pode ser `undefined`, porque não existe garantia de que um fornecedor fornecerá este valor no tempo de execução.

Os tipos `undefined` podem ser removidos fornecendo um valor padrão:

```ts
const foo = inject<string>('foo', 'bar') // type: string
```

Se estivermos certos de que o valor é sempre fornecido, podemos também forçar o lançamento do valor:

```ts
const foo = inject('foo') as string
```

## Tipos para as Referências do Modelo de Marcação {#typing-template-refs}

As referências de modelo de marcação devem ser criadas com um argumento de tipo genérico explícito e um valor inicial de `null`:

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue'

const el = ref<HTMLInputElement | null>(null)

onMounted(() => {
  el.value?.focus()
})
</script>

<template>
  <input ref="el" />
</template>
```

Nota que para a segurança de tipo restrito, é necessário usar o encadeamento opcional ou guardas de tipo quando estivermos acessando `el.value`. Isto é porque o valor da referência inicial é `null` até o componente ser montado, e também pode ser definido para `null` se o elemento referenciado for desmontado pelo `v-if`.

## Tipos para Referências do Modelo de Marcação do Componente {#typing-component-template-refs}

Algumas vezes podemos precisar anotar uma referência de modelo de marcação para um componente filho para chamar o seu método público. Por exemplo, temos um componente filho `MyModal` com um método que abre o modal:

```vue
<!-- MyModal.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const isContentShown = ref(false)
const open = () => (isContentShown.value = true)

defineExpose({
  open
})
</script>
```

Para receber o tipo da instância de `MyModal`, precisamos primeiro recuperar o seu tipo através de `typeof`, depois usar o utilitário `InstanceType` embutido da TypeScript para extrair o tipo da sua instância:

```vue{5}
<!-- App.vue -->
<script setup lang="ts">
import MyModal from './MyModal.vue'

const modal = ref<InstanceType<typeof MyModal> | null>(null)

const openModal = () => {
  modal.value?.open()
}
</script>
```

Nota que se quiseres utilizar esta técnica nos ficheiros de TypeScript dos Componentes de Ficheiro Único de Vue, precisamos ativar o [Modo de Aquisição](./overview.html#volar-takeover-mode) da Volar.

Nos casos onde o tipo exato do componente não estiver disponível ou não for importante, `ComponentPublicInstance` pode ser usado. Isto apenas incluirá as propriedades que são partilhadas por todos os componentes, tais como `$el`:

```ts
import { ref } from 'vue'
import type { ComponentPublicInstance } from 'vue'

const child = ref<ComponentPublicInstance | null>(null)
```

---

---
url: /guide/typescript/options-api.md
---
# TypeScript com a API de Opções {#typescript-with-options-api}

> Esta página presume que já leste a visão geral no [Utilizando a Vue com a TypeScript](./overview).

:::tip DICA
Embora a Vue suporte o uso da TypeScript com a API de Opções, é recomendado usar a Vue com a TypeScript através da API de Composição visto que oferece a mais simples, mais eficiente e mais robusta inferência de tipo.
:::

## Tipos para as Propriedades do Componente {#typing-component-props}

A inferência de tipo para as propriedades na API de Opções exige o envolvimento do componente com `defineComponent()`. Com isto, a Vue é capaz de inferir os tipos para as propriedades baseada na opção `props`, levando opções adicionais tais como `required: true` e `default` em conta:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inferência de tipo ativada
  props: {
    name: String,
    id: [Number, String],
    msg: { type: String, required: true },
    metadata: null
  },
  mounted() {
    this.name // type: string | undefined
    this.id // type: number | string | undefined
    this.msg // type: string
    this.metadata // type: any
  }
})
```

No entanto, as opções `props` de tempo de execução apenas suportam a utilização de funções construtoras como um tipo da propriedade - não existe maneira de especificar tipos complexos tais como objetos com propriedades encaixadas ou assinaturas de chamada de função.

Para anotar tipos de propriedades complexas, podemos utilizar o tipo utilitário `PropType`:

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

interface Book {
  title: string
  author: string
  year: number
}

export default defineComponent({
  props: {
    book: {
      // fornece tipo mais específico para `Object`
      type: Object as PropType<Book>,
      required: true
    },
    // também pode anotar funções
    callback: Function as PropType<(id: number) => void>
  },
  mounted() {
    this.book.title // string
    this.book.year // number

    // Erro de TS: argumento de tipo 'string' não é
    // atribuível ao parâmetro de tipo 'number'
    this.callback?.('123')
  }
})
```

### Advertências {#caveats}

Se a tua versão de TypeScript for menor do que `4.7`, tens que ser cuidadoso quando estiveres a usar os valores de função para as opções das propriedades `validator` e `default` - certifica-te de que utilizar funções em flecha:

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

interface Book {
  title: string
  year?: number
}

export default defineComponent({
  props: {
    bookA: {
      type: Object as PropType<Book>,
      // Certifica-te de que utilizas funções em flecha
      default: () => ({
        title: 'Arrow Function Expression'
      }),
      validator: (book: Book) => !!book.title
    }
  }
})
```

Isto impedi a TypeScript de ter que inferir o tipo do `this` dentro destas funções, o que, infelizmente, pode causar a inferência de tipo falhar na realização do seu trabalho. Isto era uma anterior [limitação do desenho](https://github.com/microsoft/TypeScript/issues/38845), e agora foi melhorada na [TypeScript 4.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#improved-function-inference-in-objects-and-methods).

## Tipos para as Emissões do Componente {#typing-component-emits}

Nós podemos declarar o tipo da carga esperada para um evento emitido utilizando a sintaxe de objeto da opção `emits`. Além disto, todos os eventos emitidos não declarados lançarão um erro de tipo quando chamados:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  emits: {
    addBook(payload: { bookName: string }) {
      // realiza a validação em tempo de execução
      return payload.bookName.length > 0
    }
  },
  methods: {
    onSubmit() {
      this.$emit('addBook', {
        bookName: 123 // Erro de tipo!
      })

      this.$emit('non-declared-event') // Erro de tipo!
    }
  }
})
```

## Tipos para as Propriedades Computadas {#typing-computed-properties}

Uma propriedade computada infere o seu tipo baseado no seu valor de retorno:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      message: 'Hello!'
    }
  },
  computed: {
    greeting() {
      return this.message + '!'
    }
  },
  mounted() {
    this.greeting // type: string
  }
})
```

Em alguns casos, podes querer explicitamente anotar o tipo de uma propriedade computada para garantir que sua implementação esteja correta:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      message: 'Hello!'
    }
  },
  computed: {
    // anotar explicitamente o tipo de retorno
    greeting(): string {
      return this.message + '!'
    },

    // anotando uma propriedade computada gravável
    greetingUppercased: {
      get(): string {
        return this.greeting.toUpperCase()
      },
      set(newValue: string) {
        this.message = newValue.toUpperCase()
      }
    }
  }
})
```

As anotações explícitas também podem ser exigidas em alguns casos extremos onde a TypeScript falha em inferir o tipo de uma propriedade computada por causa de laços de inferência circular.

## Tipos para os Manipuladores de Evento {#typing-event-handlers}

Quando estiveres lidando com eventos de DOM nativos, pode ser útil definir um tipo para o argumento que passamos para o manipulador corretamente. Vamos dar uma vista de olhos neste exemplo:

```vue
<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    handleChange(event) {
      // `event` tem implicitamente o tipo `any`
      console.log(event.target.value)
    }
  }
})
</script>

<template>
  <input type="text" @change="handleChange" />
</template>
```

Sem a anotação de tipo, o argumento `event` terá implicitamente um tipo de `any`. Isto também resultará em um erro de TypeScript se `"strict": true` ou `"noImplicitAny": true` forem utilizadas no `tsconfig.json`. É portanto recomendado anotar explicitamente o argumento dos manipuladores de eventos. Além disto, podes precisar de explicitamente usar as asserções de tipo quando estiveres a acessar as propriedades do `event`:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    handleChange(event: Event) {
      console.log((event.target as HTMLInputElement).value)
    }
  }
})
```

## Aumentando as Propriedades Globais {#augmenting-global-properties}

Algumas extensões são instaladas globalmente e suas propriedades estão disponíveis para todas instâncias de componente através de [`app.config.globalProperties`](/api/application.html#app-config-globalproperties). Por exemplo, podemos instalar `this.$http` para requisição de dados ou `this.$translate` para internacionalização. Para fazer isto funcionar bem com a TypeScript, a Vue expõe uma interface `ComponentCustomProperties` desenhada para ser aumentada através da [aumentação de módulo de TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation):

```ts
import axios from 'axios'

declare module 'vue' {
  interface ComponentCustomProperties {
    $http: typeof axios
    $translate: (key: string) => string
  }
}
```

Consulte também:

- [Testes unitários de TypeScript para as extensões de tipo de componente](https://github.com/vuejs/core/blob/main/test-dts/componentTypeExtensions.test-d.tsx)

### Colocação de Aumentação de Tipo {#type-augmentation-placement}

Nós podemos colocar esta aumentação de tipo em um ficheiro `.ts`, ou em um ficheiro `*.d.ts` de largura de projeto. De um modo ou outro, certifica-te de que é incluída no `tsconfig.json`. Para autores de extensão ou biblioteca, este ficheiro deve ser especificado na propriedade `types` no `package.json`.

Para tirar vantagem da aumentação de módulo, precisarás garantir que a aumentação é colocada em um [módulo de TypeScript](https://www.typescriptlang.org/docs/handbook/modules.html). Isto é, o ficheiro precisa conter ao menos um `import` ou `export` de alto nível, mesmo se for apenas `export {}`. Se a aumentação for colocada fora de um módulo, ela sobrescreverá os tipos originais no lugar de aumentá-los!

```ts
// Não funciona, sobrescreve os tipos originais.
declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}
```

```ts
// Funciona corretamente
export {}

declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}
```

## Aumentando Opções Personalizadas {#augmenting-custom-options}

Algumas extensões, por exemplo `vue-router`, fornecem suporta para opções de componente personalizadas tais como `beforeRouterEnter`:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  beforeRouteEnter(to, from, next) {
    // ...
  }
})
```

Sem a aumentação de tipo adequada, os argumentos deste gatilho terão implicitamente o tipo `any`. Nós podemos aumentar a interface `ComponentCustomOptions` para suportar estas opções personalizadas:

```ts
import { Route } from 'vue-router'

declare module 'vue' {
  interface ComponentCustomOptions {
    beforeRouteEnter?(to: Route, from: Route, next: () => void): void
  }
}
```

Agora a opção `beforeRouteEnter` terá o seu tipo apropriadamente definido. Nota que isto é apenas um exemplo - bibliotecas com os tipos corretamente definidos como `vue-router` devem automaticamente realizar estas aumentações em suas próprias definições de tipo.

A colocação desta aumentação está sujeita as [mesmas restrições](#type-augmentation-placement) que as aumentações de propriedade globais.

Consulte também:

- [Testes Unitário de TypeScript para Extensões de Tipo de Componente](https://github.com/vuejs/core/blob/main/test-dts/componentTypeExtensions.test-d.tsx)

---

---
url: /guide/reusability/plugins.md
---
# Extensões {#plugins}

## Introdução {#introduction}

As extensões são códigos auto-contidos que normalmente adicionam funcionalidade de nível de aplicação para a Vue. Isto é como instalamos uma extensão:

```js
import { createApp } from 'vue'

const app = createApp({})

app.use(myPlugin, {
  /* opções opcionais */
})
```

Uma extensão é definida tanto como um objeto que expõe um método `install()`, ou simplesmente como uma função que atua como a própria função de instalação. A função de instalação recebe a [instância de aplicação](/api/application) juntamente com as opções adicionais passadas para `app.use()`, se houverem:

```js
const myPlugin = {
  install(app, options) {
    // configura a aplicação
  }
}
```

Não existe escopo definido estritamente para uma extensão, mas os cenários comuns onde as extensões são úteis incluem:

1. Registar um ou mais componentes globais ou diretivas personalizas com [`app.component()`](/api/application#app-component) e [`app.directive()`](/api/application#app-directive).

2. Tornar um recurso [injetável](/guide/components/provide-inject) em toda a aplicação chamando [`app.provide()`](/api/application#app-provide).

3. Adicionar propriedades de instância global ou métodos atribuindo-os à [`app.config.globalProperties`](/api/application#app-config-globalproperties).

4. Uma biblioteca que precisa realizar alguma combinação do que está acima (por exemplo [vue-router](https://github.com/vuejs/vue-router-next)).

## Escrevendo uma Extensão {#writing-a-plugin}

Para melhor entender como criar as tuas próprias extensões de Vue.js, criaremos uma versão muito simplificada de uma extensão que exibe sequências de caracteres de `i18n` (forma abreviada para [Internacionalização](https://en.wikipedia.org/wiki/Internationalization_and_localization)).

Vamos começar definindo o objeto da extensão. É recomendado criá-lo em um ficheiro separado e exportá-lo, como mostrado abaixo para manter a lógica contida e separada.

```js
// plugins/i18n.js
export default {
  install: (app, options) => {
    // O código da extensão vai cá
  }
}
```

Nós queremos criar uma função de tradução. Esta função receberá uma sequência de caracteres `key` delimitada por ponto, a qual utilizaremos para procurar a sequência de caracteres traduzida nas opções fornecidas pelo utilizador. Isto é a utilização tencionada nos modelos de marcação:

```vue-html
<h1>{{ $translate('greetings.hello') }}</h1>
```

Já que esta função deve estar disponível globalmente em todos os modelos de marcação, faremos isto atribuindo-a ao `app.config.globalProperties` na nossa extensão:

```js{4-11}
// plugins/i18n.js
export default {
  install: (app, options) => {
    // injeta um método "$translate()" disponível globalmente
    app.config.globalProperties.$translate = (key) => {
      // recupera uma propriedade encaixada nas `options`
      // utilizando `key` como caminho
      return key.split('.').reduce((o, i) => {
        if (o) return o[i]
      }, options)
    }
  }
}
```

A nossa função `$translate()` receberá uma sequência de caracteres tal como `greetings.hello`, procura dentro da configuração fornecida pelo utilizar e retorna o valor traduzido.

O objeto contendo as chaves traduzidas devem ser passados para extensão durante a instalação através de parâmetros adicionais para `app.use()`:

```js
import i18nPlugin from './plugins/i18n'

app.use(i18nPlugin, {
  greetings: {
    hello: 'Bonjour!'
  }
})
```

Agora, a nossa expressão inicial `$translate('greetings.hello')` será substituído pelo `Bonjour!` em tempo de execução.

Consulte também: [Aumentando Propriedades Globais](/guide/typescript/options-api#augmenting-global-properties) <sup class="vt-badge ts" />

:::tip DICA
Utilize as propriedades globais cuidadosamente, já que pode rapidamente tornar-se as coisas confusas se muitas propriedades globais injetadas por extensões diferentes forem utilizadas em toda uma aplicação.
:::

### Fornecer / Injetar com as Extensões {#provide-inject-with-plugins}

As extensões também permitem-nos utilizar `inject` para fornecer uma função ou atributo aos utilizadores da extensão. Por exemplo, podemos permitir que a aplicação tenha acesso ao parâmetro `options` para ser capaz de utilizar o objeto de traduções.

```js{10}
// plugins/i18n.js
export default {
  install: (app, options) => {
    app.provide('i18n', options)
  }
}
```

Os utilizadores da extensão agora serão capazes de injetar as opções da extensão em seus componentes utilizando a chave `i18n`:

<div class="composition-api">

```vue
<script setup>
import { inject } from 'vue'

const i18n = inject('i18n')

console.log(i18n.greetings.hello)
</script>
```

</div>
<div class="options-api">

```js
export default {
  inject: ['i18n'],
  created() {
    console.log(this.i18n.greetings.hello)
  }
}
```

</div>

---

---
url: /guide/typescript/overview.md
---

# Utilizando a Vue com TypeScript {#using-vue-with-typescript}

Um sistema de tipo como TypeScript pode detetar muitos erros comuns através da analise estática em tempo de execução. Isto reduz a risco de erros de tempo de execução na produção, e também permite-nos refatorar o código com mais confiança em aplicações de grande escala. A TypeScript também melhora a ergonomia do programador através da conclusão automática baseada em tipo nas IDEs.

A Vue está escrita ele própria em TypeScript e fornece suporte de TypeScript de primeira classe. Todos os pacotes de Vue oficiais vêm com as declarações de tipo empacotada que deve funcionar fora da caixa.

## Configuração de Projeto {#project-setup}

A [`create-vue`](https://github.com/vuejs/create-vue), a ferramenta de estruturante de projeto oficial, oferece as opções para estruturar um projeto de Vue preparado com TypeScript e alimentado com a [Vite](https://pt.vitejs.dev/).

### Visão Geral {#overview}

Com uma configuração baseada na Vite, o servidor de desenvolvimento e o empacotador são apenas para tradução de código e realizam qualquer verificação de tipo. Isto garante que o servidor de desenvolvimento da Vite permaneça extremamente rápido mesmo quando estiveres utilizando a TypeScript.

- Durante o desenvolvimento, recomendamos a confiança sobre uma boa [configuração de IDE](#suporte-de-ide) para obter reações imediatas sobre os erros de tipo.

- Se estiveres utilizando Componentes de Ficheiro Único, utilize o utilitário [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) para verificação de tipo na linha de comando e para geração de declaração de tipo. O `vue-tsc` é um embrulhador em torno de `tsc`, a interface de linha de comando do próprio TypeScript. Ele funciona em grande parte da mesma maneira que a `tsc` exceto que suporta Componentes de Ficheiro Único de Vue além de ficheiros de TypeScript. Tu podes executar `vue-tsc` no modo observador em paralelo ao servidor de desenvolvimento da Vite.

- A Interface de Linha de Comando da Vue também fornece suporte a TypeScript, mas não é mais recomendado. Consulte as [notas abaixo](#nota-sobre-a-linha-de-comando-de-vue-e-o-ts-loader)

### Suporte de IDE {#ide-support}

- O [Visual Studio Code](https://code.visualstudio.com/) é fortemente recomendado para o seu excelente suporte fora da caixa para TypeScript.

  - A [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) é a extensão do Visual Studio Code oficial que oferece suporte de TypeScript dentro do Componentes de Ficheiro Único de Vue, com muitas outras excelente funcionalidades.

    :::tip
    A Volar substitui o [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur), nossa extensão Visual Studio Code oficial anterior para Vue 2. Se tiveres a Vetur atualmente instalada, certifica-te de a desativar em projetos de Vue 3.
    :::

  - [Extensão de Vue de TypeScript](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) é também necessário receber suporte de tipo para importações de `*.vue` em ficheiros de TypeScript.

- O [WebStorm](https://www.jetbrains.com/webstorm/) também fornece suporte fora da caixa para ambos TypeScript e Vue. Os outros ambientes de desenvolvimento integrado da JetBrains também os suportam, ou fora da caixa ou através [duma extensão gratuita](https://plugins.jetbrains.com/plugin/9442-vue-js). Desde a versão 2023.2, o WebStorm e a Extensão de Vue vêm com suporte embutido para o Servidor de Linguagem da Vue. Nós podemos definir o serviço da Vue para usar a integração Volar sobre todas as versões da TypeScript, sob `Settings > Languages & Frameworks > TypeScript > Vue`. Por padrão, a Volar será usada para as versões de TypeScript 5.0 e superior.

### Configurando o `tsconfig.json` {#configuring-tsconfig-json}

Os projetos estruturados através da `create-vue` inclui o `tsconfig.json` pré-configurado. A configuração de base é abstraída no pacote [`@vue/tsconfig`](https://github.com/vuejs/tsconfig). Dentro do projeto, utilizamos [Referências de Projeto](https://www.typescriptlang.org/docs/handbook/project-references.html) para garantir os tipos correto para execução de código em ambientes diferentes (por exemplo, aplicação versus teste).

Quando estiveres configurando o `tsconfig.json` manualmente, algumas opções notáveis incluem:

- [`compilerOptions.isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) está definido para `true` porque a Vite utiliza a [esbuild](https://esbuild.github.io/) para tradução de código TypeScript e está sujeito as limitações para tradução de código de ficheiro código.

- Se estiveres utilizando a API de Opções, precisas definir [`compilerOptions.strict`](https://www.typescriptlang.org/tsconfig#strict) para `true` (ou pelo menos ativa a parte [`compilerOptions.noImplicitThis`](https://www.typescriptlang.org/tsconfig#noImplicitThis) da bandeira `strict`) para influenciar a verificação de tipo do `this` nas opções de componente. De outro modo `this` será tratado como `any`.

- Se tiveres configurado os pseudónimos resolvedores na tua ferramenta de construção, por exemplo o pseudónimo `@/*` configurado por padrão em um projeto `create-vue`, também precisas configurá-lo pelo TypeScript através [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths).

Consulte também:

- [Documentação das opções do compilador de TypeScript oficial](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
- [Advertências de compilação de TypeScript da esbuild](https://esbuild.github.io/content-types/#typescript-caveats)

### Modo de Aquisição da Volar {#volar-takeover-mode}

> Esta secção apenas aplica-se para VS Code + Volar.

Para conseguir colocar os Componentes de Ficheiro Único de Vue e TypeScript funcionando juntos, a Volar cria uma instância de serviço da linguagem TypScript separada conciliadas com suporte especifico de Vue, e utiliza-o nos Componentes de Ficheiro Único de Vue. Ao mesmo tempo, ficheiros de TypeScript simples ainda continuam manipulado pelo serviço da linguagem TypeScript embutido do VS Code, o qual é o porque precisamos da [Extensão de Vue de TypeScript](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) para suportar as importações de Componente de Ficheiro Único nas instâncias de serviço da linguagem TypeScript: uma da Volar, um do serviço embutido do VS Code. Isto é um pouco ineficiente e pode levar a problemas de desempenho em projetos grandes.

A Volar fornece uma funcionalidade chamada "Modo de Aquisição" (ou "Takeover Mode") para melhorar o desempenho. No modo de aquisição, a Volar fornece suporte para ambos de ficheiros de Vue e TypeScript utilizando uma única instância de serviço da linguagem TypeScript.

Para ativar o Modo de Aquisição, precisas desativar o serviço da linguagem TypeScript embutido do VS Code no **espaço de trabalho do teu projeto apenas** seguindo estas etapas:

1. No teu espaço de trabalho, coloque a paleta de comando com `Ctrl + Shift + P` (macOS: `Cmd + Shift + P`).
2. Digite `built` e selecione "Extensions: Show Built-in Extensions" ou "Extensões: Mostrar Extensões Embutidas" (Português)
3. Digite `typescript` na caixa de pesquisa de extensão (não remova o prefixo `@builtin`).
4. Clique no pequeno ícone de engrenagem da "TypeScript and JavaScript Language Features" ou "Funcionalidades da Linguagem JavaScript e TypeScript" (Português), e selecione "Disable (Workspace)" ou "Desativar (Espaço de Trabalho)" (Português).
5. Recarregue o espaço de trabalho. O modo de aquisição será ativado quando abrires um ficheiro de Vue ou TypeScript.

<img src="./images/takeover-mode.png" width="590" height="426" style="margin:0px auto;border-radius:8px">

### Nota sobre a Linha de Comando de Vue e o `ts-loader` {#note-on-vue-cli-and-ts-loader}

Em configurações baseadas em Webpack tais como Linha de Comando de Vue, é comum se realizar verificação de tipo como parte da conduta de transformação de módulo, por exemplo com `ts-loader`. Isto, no entanto, não é uma solução decente porque o sistema de tipo precisa ter conhecimento do gráfico de módulo inteiro para realizar as verificações de tipo. A etapa de transformação de módulo individual simplesmente não é o lugar correto para a tarefa. Isto leva aos seguintes problemas:

- O `ts-loader` pode apenas verificar o tipo pós-transformação do código. Isto não se alinha com os erros que vemos em IDEs ou a partir de `vue-tsc`, que mapeia diretamente de volta para o código-fonte.

- A verificação de tipo pode ser lenta. Quando é realizada na mesma linha ou processo com as transformações de código, ele afeta significativamente a velocidade da construção do aplicação inteira.

- Nós já temos a verificação de tipo executando diretamente no nossa IDE em um processo separado, assim o custo da experiência de programação a abrandar o ritmo simplesmente não é uma bom acordo.

Se estiveres atualmente utilizando a Vue 3 + TypeScript através da Linha de Comando de Vue, recomendamos fortemente a migração para a Vite. Nós também estamos trabalhando sobre opções de Linha de Comando para possibilitar o suporte de TypeScript de tradução de código apenas, para que possas mudar para `vue-tsc` pela verificação de tipo.

## Notas de Utilização Geral {#general-usage-notes}

### `defineComponent()` {#definecomponent}

Para permitir que a TypeScript infira os tipos apropriadamente dentro das opções do componente, precisamos definir componentes com [`defineComponent()`](/api/general.html#definecomponent):

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inferência de tipo ativada
  props: {
    name: String,
    msg: { type: String, required: true }
  },
  data() {
    return {
      count: 1
    }
  },
  mounted() {
    this.name // type: string | undefined
    this.msg // type: string
    this.count // type: number
  }
})
```

A `defineComponent()` também suporta inferência de propriedades passadas para `setup()` quando estiveres utilizando a API de Composição sem o `<script setup>`:

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inferência de tipo ativada
  props: {
    message: String
  },
  setup(props) {
    props.message // type: string | undefined
  }
})
```

Consulte também:
- [Nota sobre a Sacudidura de Árvore de Webpack](/api/general.html#note-on-webpack-treeshaking)
- [Testes de Tipo para `defineComponent`](https://github.com/vuejs/core/blob/main/test-dts/defineComponent.test-d.tsx)

:::tip
A `defineComponent()` também ativa a inferência de tipo para os componentes definidos em JavaScript simples.
:::

### Utilização em Componentes de Ficheiro Único {#usage-in-single-file-components}

Para utilizar a TypeScript nos Componentes de Ficheiro Único, adicione o atributo `lang="ts"` aos marcadores de `<script>`. Quando `lang="ts"` estiver presente, todas as expressões de modelo de marcação também gozam de verificação de tipo rigorosa.

```vue
<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      count: 1
    }
  }
})
</script>

<template>
  <!-- verificação de tipo e conclusão automática ativada -->
  {{ count.toFixed(2) }}
</template>
```

O `lang="ts"` também pode ser utilizado com `<script setup>`:

```vue
<script setup lang="ts">
// TypeScript ativado
import { ref } from 'vue'

const count = ref(1)
</script>

<template>
  <!-- verificação de tipo e conclusão automática ativada -->
  {{ count.toFixed(2) }}
</template>
```

### TypeScript nos Modelos de Marcação {#typescript-in-templates}

O `<template>` também suporta a TypeScript nas expressões de vinculação quando `<script lang="ts">` ou `<script setup lang="ts">` serem utilizado. Isto é útil nos casos onde precisas realizar fusão de tipo nas expressões de modelo de marcação.

Cá está um exemplo artificial:

```vue
<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  <!-- erro porque "x" poderia ser uma sequência de caracteres -->
  {{ x.toFixed(2) }}
</template>
```

Isto pode ser solucionado com uma molde de tipo em linha:

```vue{6}
<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  {{ (x as number).toFixed(2) }}
</template>
```

:::tip Dica
Se estiveres utilizando a Linha de Comando de Vue ou uma configuração baseada em Webpack, a TypeScript nas expressões de modelo de marcação exigem `vue-loader@^16.8.0`.
:::

## Receitas Especificas da API {#api-specific-recipes}

- [TypeScript com a API de Composição](./composition-api)
- [TypeScript com a API de Opções](./options-api)

---

---
url: /guide/essentials/forms.md
---

<script setup>
import { ref } from 'vue'
const message = ref('')
const multilineText = ref('')
const checked = ref(false)
const checkedNames = ref([])
const picked = ref('')
const selected = ref('')
const multiSelected = ref([])
</script>

# Vinculações de Entrada de Formulário {#form-input-bindings}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/user-inputs-vue-devtools-in-vue-3" title="Aula Gratuita sobre Entradas do Utilizador com a Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-user-inputs-in-vue" title="Aula Gratuita sobre Entradas do Utilizador com a Vue.js"/>
</div>

Quando estamos lidando com formulários no frontend, com frequência precisamos sincronizar o estado do elementos de entrada do formulário com estado correspondente em JavaScript. Pode ser desconfortável prender manualmente as vinculações de valor e mudar os ouvintes de evento:

```vue-html
<input
  :value="text"
  @input="event => text = event.target.value">
```

A diretiva `v-model` ajuda-nos a simplificar o que está acima para:

```vue-html
<input v-model="text">
```

Além disto, a `v-model` pode ser utilizada nas entradas de tipos diferentes, `<textarea>`, e o elemento `<select>`. Ela expande automaticamente para propriedade de DOM diferente e pares de eventos baseados no elemento sobre o qual é utilizado:

- `<input>` com tipos de texto e elementos `<textarea>` utilizam a propriedade `value` e o evento `input`;
- `<input type="checkbox">` e `<input type="radio">` utilizam a propriedade `checked` e o evento `change`;
- `<select>` utiliza `value` como uma propriedade e `change` como um evento.

:::tip NOTA
A `v-model` ignorará o valor inicial dos atributos `value`, `checked`, ou `selected` encontrados em quaisquer elementos de formulário. Ela sempre tratará o atual estado de JavaScript vinculado como a fonte de verdade. Tu podes declarar o valor inicial no lado da JavaScript, utilizando <span class="options-api">a opção [`data`](/api/options-state#data)</span><span class="composition-api">as [APIs de reatividade](/api/reactivity-core#reactivity-api-core)</span>.
:::

## Uso Básico {#basic-usage}

### Texto (`<input type="text" />`) {#text}

```vue-html
<p>Message is: {{ message }}</p>
<input v-model="message" placeholder="edit me" />
```

<div class="demo">
  <p>Message is: {{ message }}</p>
  <input v-model="message" placeholder="edit me" />
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNo9jUEOgyAQRa8yYUO7aNkbNOkBegM2RseWRGACoxvC3TumxuX/+f+9ql5Ez31D1SlbpuyJoSBvNLjoA6XMUCHjAg2WnAJomWoXXZxSLAwBSxk/CP2xuWl9d9GaP0YAEhgDrSOjJABLw/s8+NJBrde/NWsOpWPrI20M+yOkGdfeqXPiFAhowm9aZ8zS4+wPv/RGjtZcJtV+YpNK1g==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNo9jdEKwjAMRX8l9EV90L2POvAD/IO+lDVqoetCmw6h9N/NmBuEJPeSc1PVg+i2FFS90nlMnngwEb80JwaHL1sCQzURwFm258u2AyTkkuKuACbM2b6xh9Nps9o6pEnp7ggWwThRsIyiADQNz40En3uodQ+C1nRHK8HaRyoMy3WaHYa7Uf8To0CCRvzMwWESH51n4cXvBNTd8Um1H0FuTq0=)

</div>

<span id="vmodel-ime-tip"></span>
:::tip NOTA
Para as linguagens que exigem um [IME](https://en.wikipedia.org/wiki/Input_method) (Chinês, Japonês, Coreano etc.), notarás que a `v-model` não é atualizada durante a composição da IME. Se também quiseres responder a estas atualizações, utilize o teu próprio ouvinte de evento `input` e vinculação de `value` ao invés de utilizar `v-model`.
:::

### Texto de Várias Linhas (`<textarea></textarea>`) {#multiline-text}

```vue-html
<span>Multiline message is:</span>
<p style="white-space: pre-line;">{{ message }}</p>
<textarea v-model="message" placeholder="add multiple lines"></textarea>
```

<div class="demo">
  <span>Multiline message is:</span>
  <p style="white-space: pre-line;">{{ message }}</p>
  <textarea v-model="message" placeholder="add multiple lines"></textarea>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNo9jktuwzAMRK9CaON24XrvKgZ6gN5AG8FmGgH6ECKdJjB891D5LYec9zCb+SH6Oq9oRmN5roEEGGWlyeWQqFSBDSoeYYdjLQk6rXYuuzyXzAIJmf0fwqF1Prru02U7PDQq0CCYKHrBlsQy+Tz9rlFCDBnfdOBRqfa7twhYrhEPzvyfgmCvnxlHoIp9w76dmbbtDe+7HdpaBQUv4it6OPepLBjV8Gw5AzpjxlOJC1a9+2WB1IZQRGhWVqsdXgb1tfDcbvYbJDRqLQ==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNo9jk2OwyAMha9isenMIpN9hok0B+gN2FjBbZEIscDpj6LcvaZpKiHg2X6f32L+mX+uM5nO2DLkwNK7RHeesoCnE85RYHEJwKPg1/f2B8gkc067AhipFDxTB4fDVlrro5ce237AKoRGjihUldjCmPqjLgkxJNoxEEqnrtp7TTEUeUT6c+Z2CUKNdgbdxZmaavt1pl+Wj3ldbcubUegumAnh2oyTp6iE95QzoDEGukzRU9Y6eg9jDcKRoFKLUm27E5RXxTu7WZ89/G4E)

</div>

Nota que a interpolação dentro de `<textarea>` não funcionará. Utilize `v-model`.

```vue-html
<!-- bad -->
<textarea>{{ text }}</textarea>

<!-- good -->
<textarea v-model="text"></textarea>
```

### Caixa de Confirmação (`<input type="checkbox" />`) {#checkbox}

Caixa de confirmação única, valor booleano:

```vue-html
<input type="checkbox" id="checkbox" v-model="checked" />
<label for="checkbox">{{ checked }}</label>
```

<div class="demo">
  <input type="checkbox" id="checkbox-demo" v-model="checked" />
  <label for="checkbox-demo">{{ checked }}</label>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpVjssKgzAURH/lko3tonVfotD/yEaTKw3Ni3gjLSH/3qhUcDnDnMNk9gzhviRkD8ZnGXUgmJFS6IXTNvhIkCHiBAWm6C00ddoIJ5z0biaQL5RvVNCtmwvFhFfheLuLqqIGQhvMQLgm4tqFREDfgJ1gGz36j2Cg1TkvN+sVmn+JqnbtrjDDiAYmH09En/PxphTebqsK8PY4wMoPslBUxQ==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNpVjtEKgzAMRX8l9Gl72Po+OmH/0ZdqI5PVNnSpOEr/fVVREEKSc0kuN4sX0X1KKB5Cfbs4EDfa40whMljsTXIMWXsAa9hcrtsOEJFT9DsBdG/sPmgfwDHhJpZl1FZLycO6AuNIzjAuxGrwlBj4R/jUYrVpw6wFDPbM020MFt0uoq2a3CycadFBH+Lpo8l5jwWlKLle1QcljwCi/AH7gFic)

</div>

Nós também podemos vincular várias caixas de confirmação ao mesmo valor de arranjo ou [conjunto](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set):

<div class="composition-api">

```js
const checkedNames = ref([])
```

</div>
<div class="options-api">

```js
export default {
  data() {
    return {
      checkedNames: []
    }
  }
}
```

</div>

```vue-html
<div>Checked names: {{ checkedNames }}</div>

<input type="checkbox" id="jack" value="Jack" v-model="checkedNames">
<label for="jack">Jack</label>

<input type="checkbox" id="john" value="John" v-model="checkedNames">
<label for="john">John</label>

<input type="checkbox" id="mike" value="Mike" v-model="checkedNames">
<label for="mike">Mike</label>
```

<div class="demo">
  <div>Checked names: {{ checkedNames }}</div>

  <input type="checkbox" id="demo-jack" value="Jack" v-model="checkedNames">
  <label for="demo-jack">Jack</label>

  <input type="checkbox" id="demo-john" value="John" v-model="checkedNames">
  <label for="demo-john">John</label>

  <input type="checkbox" id="demo-mike" value="Mike" v-model="checkedNames">
  <label for="demo-mike">Mike</label>
</div>

Neste caso, o arranjo `checkedNames` sempre conterá os valores das caixas confirmadas atualmente.

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqVkUtqwzAURbfy0CTtoNU8KILSWaHdQNWBIj8T1fohyybBeO+RbOc3i2e+vHvuMWggHyG89x2SLWGtijokaDF1gQunbfAxwQARaxihjt7CJlc3wgmnvGsTqAOqBqsfabGFXSm+/P69CsfovJVXckhog5EJcwJgle7558yBK+AWhuFxaRwZLbVCZ0K70CVIp4A7Qabi3h8FAV3l/C9Vk797abpy/lrim/UVmkt/Gc4HOv+EkXs0UPt4XeCFZHQ6lM4TZn9w9+YlrjFPCC/kKrPVDd6Zv5e4wjwv8ELezIxeX4qMZwHduAs=)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqVUc1qxCAQfpXBU3tovS9WKL0V2hdoenDjLGtjVNwxbAl592rMpru3DYjO5/cnOLLXEJ6HhGzHxKmNJpBsHJ6DjwQaDypZgrFxAFqRenisM0BEStFdEEB7xLZD/al6PO3g67veT+XIW16Cr+kZEPbBKsKMAIQ2g3yrAeBqwjjeRMI0CV5kxZ0dxoVEQL8BXxo2C/f+3DAwOuMf1XZ5HpRNhX5f4FPvNdqLfgnOBK+PsGqPFg4+rgmyOAWfiaK5o9kf3XXzArc0zxZZnJuae9PhVfPHAjc01wRZnP/Ngq8/xaY/yMW74g==)

</div>

### Rádio (`<input type="radio" />`) {#radio}

```vue-html
<div>Picked: {{ picked }}</div>

<input type="radio" id="one" value="One" v-model="picked" />
<label for="one">One</label>

<input type="radio" id="two" value="Two" v-model="picked" />
<label for="two">Two</label>
```

<div class="demo">
  <div>Picked: {{ picked }}</div>

  <input type="radio" id="one" value="One" v-model="picked" />
  <label for="one">One</label>

  <input type="radio" id="two" value="Two" v-model="picked" />
  <label for="two">Two</label>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqFkDFuwzAMRa9CaHE7tNoDxUBP0A4dtTgWDQiRJUKmHQSG7x7KhpMMAbLxk3z/g5zVD9H3NKI6KDO02RPDgDxSbaPvKWWGGTJ2sECXUw+VrFY22timODCQb8/o4FhWPqrfiNWnjUZvRmIhgrGn0DCKAjDOT/XfCh1gnnd+WYwukwJYNj7SyMBXwqNVuXE+WQXeiUgRpZyaMJaR5BX11SeHQfTmJi1dnNiE5oQBupR3shbC6LX9Posvpdyz/jf1OksOe85ayVqIR5bR9z+o5Qbc6oCk)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNqNkEEOAiEMRa/SsFEXyt7gJJ5AFy5ng1ITIgLBMmomc3eLOONSEwJ9Lf//pL3YxrjqMoq1ULdTspGa1uMjhkRg8KyzI+hbD2A06fmi1gAJKSc/EkC0pwuaNcx2Hme1OZSHLz5KTtYMhNfoNGEhUsZ2zf6j7vuPEQyDkmVSBPzJ+pgJ6Blx04qkjQ2tAGsYgkcuO+1yGXF6oeU1GHTM1Y1bsoY5fUQH55BGZcMKJd/t31l0L+WYdaj0V9Zb2bDim6XktAcxvADR+YWb)

</div>

### Seleção (`<select></select>`) {#select}

Seleção única:

```vue-html
<div>Selected: {{ selected }}</div>

<select v-model="selected">
  <option disabled value="">Please select one</option>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
```

<div class="demo">
  <div>Selected: {{ selected }}</div>
  <select v-model="selected">
    <option disabled value="">Please select one</option>
    <option>A</option>
    <option>B</option>
    <option>C</option>
  </select>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1j7EOgyAQhl/lwmI7tO4Nmti+QJOuLFTPxASBALoQ3r2H2jYOjvff939wkTXWXucJ2Y1x37rBBvAYJlsLPYzWuAARHPaQoHdmhILQQmihW6N9RhW2ATuoMnQqirPQvFw9ZKAh4GiVDEgTAPdW6hpeW+sGMf4VKVEz73Mvs8sC5stoOlSVYF9SsEVGiLFhMBq6wcu3IsUs1YREEvFUKD1udjAaebnS+27dHOT3g/yxy+nHywM08PJ3KksfXwJ2dA==)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1j1ELgyAUhf/KxZe2h633cEHbHxjstReXdxCYSt5iEP333XIJPQSinuN3jjqJyvvrOKAohAxN33oqa4tf73oCjR81GIKptgBakTqd4x6gRxp6uymAgAYbQl1AlkVvXhaeeMg8NbMg7LxRhKwAZPDKlvBK8WlKXTDPnFzOI7naMF46p9HcarFxtVgBRpyn1lnQbVBvwwWjMgMyycTToAr47wZnUeaR3mfL6sC/H/iPnc/vXS9gIfP0UTH/ACgWeYE=)

</div>

:::tip NOTA
Se o valor inicial da tua expressão de `v-model` não corresponder a quaisquer uma das opções, o elemento `<select>` interpretará em um estado "não selecionado (unselected)". Na iOS impedirá o utilizador de ser capaz de selecionar o primeiro item uma vez que a iOS não disparará o evento de mudança neste caso. É portanto recomendado fornecer uma opção desativada com um valor vazio, conforme demonstrado no exemplo acima.
:::

Seleção de várias escolhas (vinculadas ao arranjo (`array`)):

```vue-html
<div>Selected: {{ selected }}</div>

<select v-model="selected" multiple>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
```

<div class="demo">
  <div>Selected: {{ multiSelected }}</div>

  <select v-model="multiSelected" multiple>
    <option>A</option>
    <option>B</option>
    <option>C</option>
  </select>
</div>

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1kL2OwjAQhF9l5Ya74i7QBhMJeARKTIESIyz5Z5VsAsjyu7NOQEBB5xl/M7vaKNaI/0OvRSlkV7cGCTpNPVbKG4ehJYjQ6hMkOLXBwYzRmfLK18F3GbW6Jt3AKkM/+8Ov8rKYeriBBWmH9kiaFYBszFDtHpkSYnwVpCSL/JtDDE4+DH8uNNqulHiCSoDrLRm0UyWzAckEX61l8Xh9+psv/vbD563HCSxk8bY0y45u47AJ2D/HHyDm4MU0dC5hMZ/jdal8Gg8wJkS6A3nRew4=)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1UEEOgjAQ/MqmJz0oeMVKgj7BI3AgdI1NCjSwIIbwdxcqRA4mTbsznd2Z7CAia49diyIQsslrbSlMSuxtVRMofGStIRiSEkBllO32rgaokdq6XBBAgwZzQhVAnDpunB6++EhvncyAsLAmI2QEIJXuwvvaPAzrJBhH6U2/UxMLHQ/doagUmksiFmEioOCU2ho3krWVJV2VYSS9b7Xlr3/424bn1LMDA+n9hGbY0Hs2c4J4sU/dPl5a0TOAk+/b/rwsYO4Q4wdtRX7l)

</div>

As opções do elemento de seleção podem ser dinamicamente interpretadas com a `v-for`:

<div class="composition-api">

```js
const selected = ref('A')

const options = ref([
  { text: 'One', value: 'A' },
  { text: 'Two', value: 'B' },
  { text: 'Three', value: 'C' }
])
```

</div>
<div class="options-api">

```js
export default {
  data() {
    return {
      selected: 'A',
      options: [
        { text: 'One', value: 'A' },
        { text: 'Two', value: 'B' },
        { text: 'Three', value: 'C' }
      ]
    }
  }
}
```

</div>

```vue-html
<select v-model="selected">
  <option v-for="option in options" :value="option.value">
    {{ option.text }}
  </option>
</select>

<div>Selected: {{ selected }}</div>
```

<div class="composition-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNplkMFugzAQRH9l5YtbKYU7IpFoP6CH9lb3EMGiWgLbMguthPzvXduEJMqNYUazb7yKxrlimVFUop5arx3BhDS7kzJ6dNYTrOCxhwC9tyNIjkpllGmtmWJ0wJawg2MMPclGPl9N60jzx+Z9KQPcRfhHFch3g/IAy3mYkVUjIRzu/M9fe+O/Pvo/Hm8b3jihzDdfr8s8gwewIBzdcCZkBVBnXFheRtvhcFTiwq9ECnAkQ3Okt54Dm9TmskYJqNLR3SyS3BsYct3CRYSFwGCpusx/M0qZTydKRXWnl9PHBlPFhv1lQ6jL6MZl+xoR/gFjPZTD)

</div>
<div class="options-api">

[Experimentar na Zona de Testes](https://play.vuejs.org/#eNp1kMFqxCAQhl9l8JIWtsk92IVtH6CH9lZ7COssDbgqZpJdCHn3nWiUXBZE/Mdvxv93Fifv62lE0Qo5nEPv6ags3r0LBBov3WgIZmUBdEfdy2s6AwSkMdisAAY0eCbULVSn6pCrzlPv7NDCb64AzEB4J+a+LFYHmDozYuyCpfTtqJ+b21Efz6j/gPtpn8xl7C8douaNl2xKUhaEV286QlYAMgWB6e3qNJp3JXIyJSLASErFyMUFBjbZ2xxXCWijkXJZR1kmsPF5g+s1ACybWdmkarLSpKejS0VS99Pxu3wzT8jOuF026+2arKQRywOBGJfE)

</div>

## Vinculações de Valor {#value-bindings}

Para rádio, caixa de confirmação e opções de seleção, os valores de vinculação de `v-model` são normalmente sequências de caracteres estáticas (ou booleanos para caixa de confirmação):

```vue-html
<!-- `picked` é uma sequência de carácter "a" quando for confirmada -->
<input type="radio" v-model="picked" value="a" />

<!-- `toggle` é ou verdadeiro ou é falso -->
<input type="checkbox" v-model="toggle" />

<!-- `selected` é uma sequência de caracteres "abc" quando a primeira opção for selecionada -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>
```

Mas algumas vezes podes querer vincular o valor a uma propriedade dinâmica na atual instância ativa. Nós podemos utilizar `v-bind` para realizar isto. Além disto, utilizando a `v-bind` permite-nos vincular o valor de entrada para valores que não sequências de caracteres.

### Caixa de Confirmação (`<input type="checkbox" />`) {#checkbox-1}

```vue-html
<input
  type="checkbox"
  v-model="toggle"
  true-value="yes"
  false-value="no" />
```

A `true-value` e `false-value` são atributos específicos de Vue que só funcionam com a `v-model`. Aqui o valor da propriedade `toggle` será definido para `'yes'` quando a caixa for confirmada, e definida para `'no'` quando a confirmação for desfeita. Tu também podes vinculá-los à valores dinâmicos utilizando a `v-bind`:

```vue-html
<input
  type="checkbox"
  v-model="toggle"
  :true-value="dynamicTrueValue"
  :false-value="dynamicFalseValue" />
```

:::tip DICA
Os atributos `true-value` e `false-value` não afetam o atributo `value` da entrada (elemento `input`), porque os navegadores não incluem caixas não confirmadas na submissão de formulário. Para garantir que um dos valores é submetido em um formulário (por exemplo "yes" ou "no"), utilize entradas de rádio.
:::

### Rádio (`<input type="radio" />`) {#radio-1}

```vue-html
<input type="radio" v-model="pick" :value="first" />
<input type="radio" v-model="pick" :value="second" />
```

O `pick` será definido para o valor de `first` quando a primeira entrada de rádio for confirmada, e definida para o valor de `second` quando o segundo for confirmado.

### Opções de Seleção (`<option></option>`) {#select-options}

```vue-html
<select v-model="selected">
  <!-- literal de objeto em linha -->
  <option :value="{ number: 123 }">123</option>
</select>
```

A `v-model` também suporta vinculações de valor de valores que não são sequência de caracteres! No exemplo acima, quando a opção é selecionada, `selected` será definida para o valor literal de objeto de `{ number: 123 }`.

## Modificadores {#modifiers}

### `.lazy` {#lazy}

Por padrão, a `v-model` sincroniza a entrada com o dado depois de cada evento de `input` (com a exceção da composição de IME como [especificada acima](#vmodel-ime-tip)). Tu podes adicionar o modificador `lazy` no lugar de sincronizar depois dos eventos `change`:

```vue-html
<!-- sincronizado depois de "change" no lugar de "input" -->
<input v-model.lazy="msg" />
```

### `.number` {#number}

Se quiseres que a entrada do utilizador seja automaticamente tratada como um número, podes adicionar o modificador `number` as tuas entradas geridas pela `v-model`:

```vue-html
<input v-model.number="age" />
```

Se o valor não puder ser analisado com `parseFloat()`, então o valor original é utilizado no lugar.

O modificador `number` é aplicado automaticamente se a entrada tiver o `type="number"`.

### `.trim` {#trim}

Se quiseres que espaços em branco da entrada do utilizador sejam cortados automaticamente, podes adicionar o modificador `trim` as tuas entradas geridas pela `v-model`:

```vue-html
<input v-model.trim="msg" />
```

## `v-model` com Componentes {#v-model-with-components}

> Se ainda não estiveres familiarizados com os componentes da Vue, podes ignorar isto por agora.

Os tipos de entrada embutidos da HTML não irão sempre atender as tuas necessidades. Felizmente, os componentes da Vue permitem-te construir entradas reutilizáveis com comportamentos completamente personalizados. Estas entradas funcionam até com a `v-model`! Para aprender mais, leia a respeito [Uso com a `v-model`](/guide/components/v-model) no guia de Componentes.

---

---
url: /guide/essentials/class-and-style.md
---
# Vínculos de Classe e Estilo {#class-and-style-bindings}

Um necessidade comum de vínculo de dados é a manipulação da lista de classe e estilos em linha dum elemento. Uma vez que `class` e `style` são ambos atributos, podemos usar a `v-bind` para atribuí-las um valor de sequência de caracteres dinamicamente, da mesma maneira que podemos fazer com os outros atributos. No entanto, tentar gerar estes valores usando a concatenação de sequência de caracteres pode ser aborrecido e propenso a erros. Por esta razão, a Vue fornece otimizações especiais quando `v-bind` é usada com `class` e `style`. Além das sequências de caracteres, as expressões também podem avaliar-se para objetos e vetores.

## Vinculando Classes de HTML {#binding-html-classes}

<div class="options-api">
  <VueSchoolLink href="https://vueschool.io/lessons/dynamic-css-classes-with-vue-3" title="Aula Gratuita Sobre Classes de CSS Dinâmicas na Vue.js"/>
</div>

<div class="composition-api">
  <VueSchoolLink href="https://vueschool.io/lessons/vue-fundamentals-capi-dynamic-css-classes-with-vue" title="Aula Gratuita Sobre Classes de CSS Dinâmicas na Vue.js"/>
</div>

### Vinculando aos Objetos {#binding-to-objects}

Nós podemos passar um objeto à `:class` (abreviação para `v-bind:class`) para alternar classes dinamicamente:

```vue-html
<div :class="{ active: isActive }"></div>
```

A sintaxe acima significa que a presença da classe `active` será determinada pela [veracidade](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) da propriedade de dados `isActive`.

Nós podemos ter várias classes alternadas tendo mais campos no objeto. Além disto, a diretiva `:class` também pode coexistir com um atributo `class` simples. Então dado o seguinte estado:

<div class="composition-api">

```js
const isActive = ref(true)
const hasError = ref(false)
```

</div>

<div class="options-api">

```js
data() {
  return {
    isActive: true,
    hasError: false
  }
}
```

</div>

E o seguinte modelo de marcação:

```vue-html
<div
  class="static"
  :class="{ active: isActive, 'text-danger': hasError }"
></div>
```

Esta interpretará:

```vue-html
<div class="static active"></div>
```

Quando `isActive` ou `hasError` mudar, a lista de classe será atualizada de acordo. Por exemplo, se `hasError` tornar-se `true`, a lista de classe tornar-se-á `"static active text-danger"`.

O objeto vinculado não precisa de estar em linha:

<div class="composition-api">

```js
const classObject = reactive({
  active: true,
  'text-danger': false
})
```

</div>

<div class="options-api">

```js
data() {
  return {
    classObject: {
      active: true,
      'text-danger': false
    }
  }
}
```

</div>

```vue-html
<div :class="classObject"></div>
```

Isto produzirá:

```vue-html
<div class="active"></div>
```

Nós também podemos vincular à uma [propriedade computada](./computed) que retorna um objeto. Isto é um padrão comum e poderoso:

<div class="composition-api">

```js
const isActive = ref(true)
const error = ref(null)

const classObject = computed(() => ({
  active: isActive.value && !error.value,
  'text-danger': error.value && error.value.type === 'fatal'
}))
```

</div>

<div class="options-api">

```js
data() {
  return {
    isActive: true,
    error: null
  }
},
computed: {
  classObject() {
    return {
      active: this.isActive && !this.error,
      'text-danger': this.error && this.error.type === 'fatal'
    }
  }
}
```

</div>

```vue-html
<div :class="classObject"></div>
```

### Vinculando aos Vetores {#binding-to-arrays}

Nós podemos vincular `:class` à um vetor para aplicar uma lista de classes:

<div class="composition-api">

```js
const activeClass = ref('active')
const errorClass = ref('text-danger')
```

</div>

<div class="options-api">

```js
data() {
  return {
    activeClass: 'active',
    errorClass: 'text-danger'
  }
}
```

</div>

```vue-html
<div :class="[activeClass, errorClass]"></div>
```

O que interpretará:

```vue-html
<div class="active text-danger"></div>
```

Se também gostaríamos de alternar condicionalmente uma classe na lista, podemos fazer isto com uma expressão ternária:

```vue-html
<div :class="[isActive ? activeClass : '', errorClass]"></div>
```

Isto sempre aplicará `errorClass`, mas `activeClass` só será aplicada quando `isActive` for verdadeira.

No entanto, isto pode ser um pouco verboso se tivermos várias classes condicionais. É por isto que também é possível usar a sintaxe de objeto dentro da sintaxe de vetor:

```vue-html
<div :class="[{ activeClass: isActive }, errorClass]"></div>
```

### Com os Componentes {#with-components}

> Esta secção pressupõe o conhecimento de [Componentes](/guide/essentials/component-basics). Não precisamos hesitar em saltá-la e voltar mais tarde.

Quando usamos o atributo `class` sobre um componente com um único elemento de raiz, estas classes serão adicionadas ao elemento de raiz do componente, e combinados com qualquer classe já existente neste.

Por exemplo, se tivermos um componente nomeado `MyComponent` com o seguinte modelo de marcação:

```vue-html
<!-- modelo de marcação do componente filho -->
<p class="foo bar">Hi!</p>
```

Então adicionamos algumas classes quando o usamos:

```vue-html
<!-- quando usamos o componente -->
<MyComponent class="baz boo" />
```

O HTML interpretado será:

```vue-html
<p class="foo bar baz boo">Hi</p>
```

O mesmo é verdadeiro para os vínculos de classe:

```vue-html
<MyComponent :class="{ active: isActive }" />
```

Quando `isActive` for verdadeiro, o HTML interpretado será:

```vue-html
<p class="foo bar active">Hi</p>
```

Se o nosso componente tiver vários elementos de raiz, precisaríamos de definir qual elemento receberá esta classe. Nós podemos fazer isto usando a propriedade de componente `$attrs`:

```vue-html
<!-- modelo de marcação de MyComponent usando $attrs -->
<p :class="$attrs.class">Hi!</p>
<span>This is a child component</span>
```

```vue-html
<MyComponent class="baz" />
```

Interpretará:

```html
<p class="baz">Hi!</p>
<span>This is a child component</span>
```

Nós podemos aprender mais sobre a herança de atributo do componente na seção [Atributos de Herança](/guide/components/attrs).

## Vinculando Estilos Em Linha {#binding-inline-styles}

### Vinculando aos Objetos {#binding-to-objects-1}

O `:style` suporta a vinculação à valores de objeto de JavaScript - este corresponde à uma [propriedade `style` do elemento de HTML](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style):

<div class="composition-api">

```js
const activeColor = ref('red')
const fontSize = ref(30)
```

</div>

<div class="options-api">

```js
data() {
  return {
    activeColor: 'red',
    fontSize: 30
  }
}
```

</div>

```vue-html
<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
```

Embora as chaves de "caixaDeCamelo" sejam recomendadas, `:style` também suporta as chaves de propriedades de CSS em "caixa-espetada" (que corresponde à como são usadas na CSS real) - por exemplo:

```vue-html
<div :style="{ 'font-size': fontSize + 'px' }"></div>
```

Muitas vezes é uma boa ideia vincular diretamente à um objeto de estilo para o modelo de marcação estar mais limpo:

<div class="composition-api">

```js
const styleObject = reactive({
  color: 'red',
  fontSize: '13px'
})
```

</div>

<div class="options-api">

```js
data() {
  return {
    styleObject: {
      color: 'red',
      fontSize: '13px'
    }
  }
}
```

</div>

```vue-html
<div :style="styleObject"></div>
```

Novamente, o vínculo de estilo de objeto é muitas vezes usado em conjunto com as propriedades computadas que retornam objetos.

### Vinculando aos Vetores {#binding-to-arrays-1}

Nós podemos vincular o `:style` à um vetor de vários objetos de estilo. Estes objetos serão combinados e aplicados ao mesmo elemento:

```vue-html
<div :style="[baseStyles, overridingStyles]"></div>
```

### Prefixação Automática {#auto-prefixing}

Quando usarmos uma propriedade de CSS que requer um [prefixo fornecedor](https://developer.mozilla.org/en-US/docs/Glossary/Vendor_Prefix) no `:style`, a Vue adicionará automaticamente o prefixo apropriado. A Vue faz isto verificando durante a execução quais propriedades de estilo são suportadas no navegador atual. Se o navegador não suportar uma propriedade em especial então várias variantes prefixadas serão testadas para tentar encontrar uma que seja suportada.

### Vários Valores {#multiple-values}

Nós podemos fornecer um vetor de vários valores (prefixados) à uma propriedade de estilo, por exemplo:

```vue-html
<div :style="{ display: ['-webkit-box', '-ms-flexbox', 'flex'] }"></div>
```

Isto apenas interpretará o último valor do vetor que o navegador suporta. Neste exemplo, interpretará `display: flex` para os navegadores que suportam a versão sem prefixo de caixa flexível, ou melhor dizendo `flexbox`.

---

---
url: /guide/extras/web-components.md
---
# Vue e os Componentes da Web {#vue-and-web-components}

Os [Componentes da Web](https://developer.mozilla.org/en-US/docs/Web/Web_Components) é um termo abrangente para um conjunto de APIs nativas da Web que permitem os programadores criar elementos personalizados reutilizáveis.

Nós consideramos a Vue e os Componentes da Web como sendo tecnologias essencialmente complementares. A Vue tem excelente suporta para tanto consumir e criar elementos personalizados. Quer estejas a integrar os elementos personalizados à uma aplicação de Vue existente, ou usar a Vue para construir e distribuir elementos personalizados, estás em boa companhia.

## Usando Elementos Personalizados na Vue {#using-custom-elements-in-vue}

A Vue [atinge um pontuação perfeita de 100% nos testes da Custom Elements Everywhere]. Consumir elementos personalizados dentro de uma aplicação de Vue funciona em grande parte da mesma maneira como usamos elementos de HTML nativos, com algumas coisas a manter em mente:

### Saltando a Resolução de Componente {#skipping-component-resolution}

Por padrão, a Vue tentará resolver um marcador de HTML que não é nativo como um componente de Vue registado antes de retroceder para apresentá-lo como um elemento personalizado. Isto fará a Vue emitir um aviso `failed to resolve component` (falhou em resolver o componente) durante o desenvolvimento. Para deixar a Vue saber que certos elementos deveriam ser tratados como elementos personalizados e saltar a resolução de componente, podemos especificar a [opção `compilerOptions.isCustomElement`].

Se estiveres a usar Vue com uma configuração de construção, a opção deveria ser passada através das configurações de construção já que é uma opção do tempo de compilação. 

#### Exemplificar a Configuração No Navegador {#example-in-browser-config}

```js
// Apenas funciona se usas a compilação no navegador.
// Se usas ferramentas de construção,
// consulte os exemplos de configuração abaixo.
app.config.compilerOptions.isCustomElement = (tag) => tag.includes('-')
```

#### Exemplificar a Configuração da Vite {#example-vite-config}

```js
// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // trata todos os marcadores com um travessão,
          // como elementos personalizados.
          isCustomElement: (tag) => tag.includes('-')
        }
      }
    })
  ]
}
```

#### Exemplificar a Configuração da Linha de Comando da Vue {#example-vue-cli-config}

```js
// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          // trata qualquer marcador que começa com `ion-`,
          // como elementos personalizados.
          isCustomElement: tag => tag.startsWith('ion-')
        }
      }))
  }
}
```

### Passando Propriedades do DOM {#passing-dom-properties}

Já que os atributos do DOM apenas podem ser sequências de caracteres, precisamos de passar dados complexos para os elementos personalizados como propriedades de DOM. Quando definires propriedades num elemento personalizado, a Vue 3 verifica automaticamente a presença da propriedade do DOM usando o operador `in` e preferirá definir o valor como uma propriedade de DOM se a chave estiver presente. Isto significa que, na maioria dos casos, não precisarás de pensar sobre isto se o elemento personalizado segue as [boas práticas recomendadas](https://web.dev/custom-elements-best-practices/).

No entanto, poderia existir casos onde os dados devem ser passados como uma propriedade de DOM, mas o elemento personalizado não define ou reflete apropriadamente a propriedade (fazendo a verificação de `in` falhar). Neste caso, podes forçar um vínculo de `v-bind` para ser definido como uma propriedade de DOM usando o modificador `.prop`:

```vue-html
<my-element :user.prop="{ name: 'jack' }"></my-element>

<!-- abreviação equivalente -->
<my-element .user="{ name: 'jack' }"></my-element>
```

## Construindo Elementos Personalizados com a Vue {#building-custom-elements-with-vue}

O benefício primário dos elementos personalizados é que podem ser usados com qualquer abstração, ou mesmo sem uma abstração. Isto faz deles ideal para distribuir componentes onde o consumidor final talvez não esteja a usar a mesma pilha de frontend, ou quando quiseres isolar a aplicação final dos detalhes de implementação dos componentes que usa.

### defineCustomElement {#definecustomelement}

A Vue suporta a criação de elementos personalizados usando explicitamente as mesmas APIs de componente de Vue através do método [`defineCustomElement`](/api/general#definecustomelement). O método aceita o mesmo argumento que [`defineComponent`](/api/general#definecomponent), mas ao invés desta retorna um construtor de elemento personalizado que estende o `HTMLElement`:

```vue-html
<my-vue-element></my-vue-element>
```

```js
import { defineCustomElement } from 'vue'

const MyVueElement = defineCustomElement({
  // opções normais de componente de Vue
  props: {},
  emits: {},
  template: `...`,

  // apenas para defineCustomElement: CSS é injetada na raiz sombra
  styles: [`/* inlined css */`]
})

// Regista o elemento personalizado.
// Depois do registo, todos marcadores `<my-vue-element>`
// na página serão atualizados.
customElements.define('my-vue-element', MyVueElement)

// Tu podes também instanciar programaticamente o elemento:
// (apenas pode ser feito depois do registo)
document.body.appendChild(
  new MyVueElement({
    // propriedades iniciais (opcional)
  })
)
```

#### Ciclo de Vida {#lifecycle}

- Um elemento personalizado de Vue montará uma instância de componente de Vue interna dentro da sua raiz sombra quando a [`connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks) do elemento for chamada pela primeira vez.

- Quando a `disconnectedCallback` do elemento for invocada, a Vue verificará se o elemento está separado do documento depois de um tiquetaque de micro-tarefa.

  - Se o elemento ainda estiver no documento, é uma mudança e a instância do componente será preservada;

  - Se o elemento estiver separado do documento, é uma remoção e a instância do componente será desmontada.

#### Propriedades {#props}

- Todas propriedades declaradas usando a opção `props` será definida sobre o elemento personalizado como propriedades. A Vue lidará automaticamente com a reflexão entre atributos ou propriedades onde oportuno.

  - Os atributos sempre são refletidos para as propriedades correspondentes.

  - As propriedades com valores primitivos (`string`, `boolean` ou `number`) são refletidos como atributos.

- A Vue também lança automaticamente as propriedades declaradas com os tipos `Boolean` ou `Number` para o tipo desejado quando são definidas como atributos (os quais sempre são sequências de caracteres). Por exemplo, dada as seguinte declaração de propriedades:

  ```js
  props: {
    selected: Boolean,
    index: Number
  }
  ```

  E o uso do elemento personalizado:

  ```vue-html
  <my-element selected index="1"></my-element>
  ```

  No componente, `selected` será lançada para `true` (booleano) e `index` será lançada para `1` (número).

#### Eventos {#events}

Os eventos emitidos através de `this.$emit` ou `emit` de configuração são despachados como [CustomEvents](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) nativos sobre o elemento personalizado. Os argumentos de eventos adicionais (carga) serão expostos como um arranjo sobre o objeto `CustomEvent` como sua propriedade `detail`.

#### Ranhuras {#slots}

Dentro do componente, as ranhuras podem ser apresentadas usando o elemento `<slot/>` como de costume. No entanto, quando consomes o elemento resultante, este apenas aceita a [sintaxe de ranhuras nativas](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots):

- As [ranhuras isoladas](/guide/components/slots#scoped-slots) não são suportadas.

- Quando passares ranhuras nomeadas, use o atributo `slot` ao invés da diretiva `v-slot`:

  ```vue-html
  <my-element>
    <div slot="named">hello</div>
  </my-element>
  ```

#### Fornecer ou Injetar {#provide-inject}

A [API de Fornecimento ou Injeção](/guide/components/provide-inject#provide-inject) e sua [API de composição equivalente](/api/composition-api-dependency-injection#provide) também funciona entre os elementos personalizados definidos pela Vue. No entanto, nota que este funciona **apenas entre elementos personalizados**, por exemplo, um elemento personalizado definido pela Vue não será capaz de injetar propriedades fornecidas por um componente de Vue que não é um elemento personalizado.

### Componente de Ficheiro Único como Elemento Personalizado {#sfc-as-custom-element}

A `defineCustomElement` também funciona com Componentes de Ficheiro Único de Vue (SFCs, sigla em Inglês). No entanto, com a configuração de ferramental padrão, o `<style>` dentro dos Componentes de Ficheiro Único continuarão a ser extraídos e fundidos em um único ficheiro de CSS durante a construção de produção. Quando executares um Componente de Ficheiro Único como um elemento personalizado, é frequentemente desejável injetar os marcadores `<style>` para o raiz sombra do elemento personalizado.

O ferramental de Componente de Ficheiro Único oficial suporta a importação de Componentes de Ficheiro Único no "modo de elemento personalizado" (requer `@vitejs/plugin-vue@^1.4.0` ou `vue-loader@^16.5.0`). Um Componente de Ficheiro Único carregado no modo de elemento personalizado embute os seus marcadores `<style>` como sequências de caracteres de CSS e as expõe sob a opção `styles` do componente. Isto será buscada pela `defineCustomElement` e injetado para a raiz sombra do elemento quando instanciada.

Para optar para este modo, simplesmente termine o nome do teu ficheiro de componente com `.ce.vue`:

```js
import { defineCustomElement } from 'vue'
import Example from './Example.ce.vue'

console.log(Example.styles) // ["/* inlined css */"]

// converte para construtor de elemento personalizado
const ExampleElement = defineCustomElement(Example)

// registar
customElements.define('my-example', ExampleElement)
```

Se desejas personalizar o quais ficheiros deveriam ser importados no modo de elemento personalizado (por exemplo, tratar _todos_ os Componentes de Ficheiro Único como elementos personalizados), podes passar a opção `customElement` para as respetivas extensões de construção:

- [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#using-vue-sfcs-as-custom-elements)
- [vue-loader](https://github.com/vuejs/vue-loader/tree/next#v16-only-options)

### Conselhos para uma Biblioteca de Elementos Personalizado da Vue {#tips-for-a-vue-custom-elements-library}

Quando construires elementos personalizados com Vue, os elementos dependerão do executor da Vue. Existe um custo de tamanho base de mais ou menos 16kb dependendo de quantas funcionalidades estão a ser usadas. Isto significa que não é ideal usar a Vue se estás a entregar um único elemento personalizado - talvez queiras usar a JavaScript pura, [petite-vue](https://github.com/vuejs/petite-vue), ou abstrações que se especializam no tamanho de executor pequeno. No entanto, o tamanho de base é mais do que justificável se estás a entregar uma coleção de elementos personalizados com lógica complexa, já que a Vue permitirá que cada componente possa ser criado com menos código.

Se os elementos personalizados serão usados numa aplicação que também está a usar a Vue, podes escolher expor a Vue a partir do pacote construído assim os elementos estarão a usar a mesmo cópia de Vue a partir da aplicação hospedeira.

É recomendado exportar os construtores de elemento individual para dar aos teus utilizadores a flexibilidade de importá-los sobre demanda e registá-los com nomes de marcador desejado. Tu podes também exportar uma função de conveniência para registar automaticamente todos os elementos. Cá esta um ponto de entrada de exemplo duma biblioteca de elemento personalizado de Vue:

```js
import { defineCustomElement } from 'vue'
import Foo from './MyFoo.ce.vue'
import Bar from './MyBar.ce.vue'

const MyFoo = defineCustomElement(Foo)
const MyBar = defineCustomElement(Bar)

// exportar os elementos de maneira individual
export { MyFoo, MyBar }

export function register() {
  customElements.define('my-foo', MyFoo)
  customElements.define('my-bar', MyBar)
}
```

Se tiveres muitos componentes, podes também influenciar as funcionalidades da ferramenta de construção tais como a [importação de glob](https://pt.vitejs.dev/guide/features#glob-import) da Vite ou [`require.context`](https://webpack.js.org/guides/dependency-management/#requirecontext) da Webpack para carregar todos os componentes a partir dum diretório.

## Componentes da Web vs. Componentes da Vue {#web-components-vs-vue-components}

Alguns programadores acreditam que os modeles de componente proprietário da abstração deveriam ser evitados, e que usar exclusivamente os Elementos Personalizados tornam uma aplicação "imune ao futuro". Cá tentaremos explicar o porquê que acreditamos que isto é uma abordagem demasiadamente simplista de enfrentar o problema.

Existe de fato um certo nível de funcionalidade que sobrepõe-se entre os Elementos Personalizados e Componentes de Vue: ambos permitem-nos definir componentes reutilizáveis com a passagem de dados, emissão de evento, e gestão do ciclo de vida. No entanto, as APIs de Componentes da Web são relativamente de baixo nível e esqueletos. Para construiremos uma aplicação de fato, precisamos de razoavelmente algumas capacidades adicionais que a plataforma não cobre:

- Um sistema de criação de modelos de marcação declarativo e eficiente;

- Um sistema de gestão de estado reativo que facilita a extração e reutilização da lógica através de componente;

- Um maneira otimizada de gerar os componentes no servidor e hidratá-los no cliente (SSR, sigla em Inglês), o que é importante para otimização do motor de pesquisa (SEO, sigla em Inglês) e [Métricas Vitais da Web tais como LCP](https://web.dev/vitals/). A interpretação no lado do servidor de elementos personalizados nativos normalmente envolve a simulação do DOM na Node.js e depois a serialização do DOM modificado, enquanto a interpretação no lado de servidor da Vue compila para uma concatenação de sequência de caracteres sempre que possível, o que é muito mais eficiente.

O modelo de componente da Vue está desenhado com estas necessidades em mente como um sistema coerente.

Com uma equipa de engenharia competente, provavelmente poderias construir o equivalente sobre os Elementos Personalizados nativos -  mas isto também significa que estás a comprometer-se com fardo de manutenção de longo prazo de uma abstração interna, enquanto perdes os benefícios do ecossistema e comunidade duma abstração madura como a Vue.

Também existem abstrações construídas usando Elementos Personalizados como fundamento de seu modelo de componente, mas todas inevitavelmente têm de introduzir suas soluções proprietárias para os problemas listados acima. Usar estas abstrações implica comprar suas decisões técnicas sobre como solucionar estes problemas - o que, apesar o que pode ser anunciado, não protegem-te automaticamente de potenciais problemas do futuro.

Também existem algumas onde encontramos limitações nos elementos personalizados:

- A avaliação incansável da ranhura dificulta a composição do componente. As [ranhuras isoladas](/guide/components/slots#scoped-slots) da Vue são um poderoso mecanismo para composição de componente, que não podem ser suportadas pelos elementos personalizados devido a natura ansiosa das ranhuras nativas. As ranhuras ansiosas também significa que o recebimento do componente não pode controlar quanto ou se gera um pedaço de conteúdo da ranhura.

- Entregar elementos personalizados com CSS isolado do DOM sombra hoje requer fixar o CSS dentro da JavaScript para que possam ser injetadas nas raízes sombra em tempo de execução. Eles também resultam em estilos duplicados na marcação em cenários de interpretação no lado do servidor (SSR, sigla em Inglês). Existem [funcionalidades de plataforma](https://github.com/whatwg/html/pull/4898/) sendo trabalhadas sobre esta área - mas desde agora ainda não são universalmente suportas, e ainda existem preocupações quanto ao desempenho de produção ou interpretação no lado do servidor (SSR, sigla em Inglês) a serem abordados. No entretanto, os Componentes de Ficheiro Único da Vue fornecem [mecanismos de isolamento de CSS](/api/sfc-css-features) que suportam extração de estilos para ficheiros de CSS simples.

A Vue sempre continuará atualizada com padrões mais recentes na plataforma da Web, e entregaremos felizmente tudo aquilo que a plataforma fornecer se isto tornar o nosso trabalho mais fácil. No entanto, o nosso objetivo é fornecer soluções que funcionam bem e funcionam hoje. Isto significa que temos de incorporar novas funcionalidades da plataforma com uma mentalidade crítica - e isto envolve preencher os espaços em branco onde os padrões não conseguem enquanto isto for o caso.