# Diretivas

# v-text

# v-html

  • Espera: string

  • Detalhes:

    Atualiza o innerHTML (opens new window) do elemento. Perceba que os conteúdos são inseridos como HTML puro - eles não serão compilados como templates Vue. Se você se encontra tentando compor templates usando v-html, tente repensar a solução usando componentes em vez disso.

    AVISO

    Renderizar dinamicamente HTML arbitrário em seu website pode ser muito perigoso porque isso pode facilmente levar a ataques XSS (opens new window). Apenas use v-html em conteúdo confiável e nunca em conteúdo fornecido pelo usuário.

    Em Componentes Single-File, estilos scoped não serão aplicados a conteúdos v-html, pois tal HTML não é processado pelo compilador de templates do Vue. Se você quer atingir o conteúdo de v-html com CSS scoped, é possível utilizar CSS Modules (opens new window) ou um adicional elemento <style> global, com uma estratégia manual de escopo como BEM.

  • Exemplo:

    <div v-html="html"></div>
    
    1
  • Ver também: Sintaxe de Templates - Interpolações

# v-show

  • Espera: any

  • Uso:

    Alterna a propriedade CSS display do elemento baseado na condição de verdade do valor da expressão.

    Esta diretiva dispara transições quando sua condição muda.

  • Ver também: Renderização Condicional - v-show

# v-if

  • Espera: any

  • Uso:

    Renderiza condicionalmente o elemento baseado na condição de verdade do valor da expressão. O elemento e suas diretivas/componentes contidos são destruídos e reconstruídos durante alternâncias (toggles). Se o elemento é um <template>, o seu conteúdo será extraído como o bloco condicional.

    Esta diretiva dispara transições quando sua condição muda.

    Quando usados juntos, v-if tem uma prioridade maior que v-for. Não recomendamos o uso dessas duas diretivas juntas em um elemento - consulte o guia de renderização de listas para obter detalhes.

  • Ver também: Renderização Condicional - v-if

# v-else

  • Não espera expressão

  • Restriction: o elemento-irmão anterior deve ter v-if ou v-else-if.

  • Uso:

    Denota o "bloco senão" de um v-if ou cadeia de v-if/v-else-if.

    <div v-if="Math.random() > 0.5">
      Agora você me vê
    </div>
    <div v-else>
      Agora você não me vê
    </div>
    
    1
    2
    3
    4
    5
    6
  • Ver também: Renderização Condicional - v-else

# v-else-if

  • Espera: any

  • Restriction: o elemento-irmão anterior deve ter v-if ou v-else-if.

  • Uso:

    Denota o "bloco senão se" para v-if. Pode ser encadeado.

    <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>
      Não é A/B/C
    </div>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
  • Ver também: Renderização Condicional - v-else-if

# v-for

  • Espera: Array | Object | number | string | Iterable

  • Uso:

    Renderiza o elemento ou bloco de template múltiplas vezes baseado nos dados de origem (source data). O valor da diretiva deve usar a sintaxe especial alias in expression para fornecer um apelido para o elemento atual sendo iterado:

    <div v-for="item in items">
      {{ item.text }}
    </div>
    
    1
    2
    3

    Alternativamente, você também pode especificar um apelido para o índice (ou a chave, se usada em um Objeto):

    <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>
    
    1
    2
    3

    O comportamento padrão de v-for tentará corrigir os elementos no local sem os mover. Para forçá-lo a reordenar elementos, você precisa fornecer uma sugestão de ordenação com o atributo especial key:

    <div v-for="item in items" :key="item.id">
      {{ item.text }}
    </div>
    
    1
    2
    3

    v-for também pode funcionar em valores que implementam o Protocolo Iterável (opens new window), incluindo Map e Set nativos.

    O uso detalhado de v-for é explicado na seção do guia com link abaixo.

  • Ver também:

# v-on

  • Forma abreviada: @

  • Espera: Function | Inline Statement | Object

  • Argumento: event

  • Modificadores:

    • .stop - chama event.stopPropagation().
    • .prevent - chama event.preventDefault().
    • .capture - adiciona escuta de eventos em modo de captura.
    • .self - aciona o manipulador somente se o evento foi disparado a partir deste elemento.
    • .{keyAlias} - aciona o manipulador apenas em certas teclas.
    • .once - aciona o manipulador somente uma vez.
    • .left - aciona o manipulador somente para eventos do botão esquerdo do mouse.
    • .right - aciona o manipulador somente para eventos do botão direito do mouse.
    • .middle - aciona o manipulador somente para eventos do botão do meio do mouse.
    • .passive - atribui um evento ao DOM com { passive: true }.
  • Uso:

    Atribui uma escuta de evento ao elemento. O tipo de evento é indicado pelo argumento. A expressão pode ser um nome de método, uma declaração inline, ou omitida quando há modificadores presentes.

    Quando usado em um elemento normal, escuta somente eventos nativos do DOM (opens new window). Quando usado em um componente de elemento personalizado, escuta eventos personalizados emitidos naquele componente-filho.

    Quando escutando a eventos nativos do DOM, o método recebe o evento nativo como argumento único. Quando usada declaração inline, ela tem acesso à propriedade especial $event: v-on:click="handle('ok', $event)".

    v-on também oferece suporte à vinculação a um objeto de pares evento/ouvinte sem um argumento. Observe que ao usar a sintaxe de objeto, ela não oferece suporte a nenhum modificador.

  • Exemplo:

    <!-- método manipulador -->
    <button v-on:click="doThis"></button>
    
    <!-- evento dinâmico -->
    <button v-on:[event]="doThis"></button>
    
    <!-- declaração inline -->
    <button v-on:click="doThat('hello', $event)"></button>
    
    <!-- forma abreviada -->
    <button @click="doThis"></button>
    
    <!-- forma abreviada para o evento dinâmico -->
    <button @[event]="doThis"></button>
    
    <!-- para a propagação -->
    <button @click.stop="doThis"></button>
    
    <!-- previne o padrão -->
    <button @click.prevent="doThis"></button>
    
    <!-- previne o padrão sem expressão -->
    <form @submit.prevent></form>
    
    <!-- modificadores encadeados -->
    <button @click.stop.prevent="doThis"></button>
    
    <!-- modificador de tecla usando keyAlias -->
    <input @keyup.enter="onEnter" />
    
    <!-- o evento de clique será acionado somente uma vez -->
    <button v-on:click.once="doThis"></button>
    
    <!-- sintaxe de objeto -->
    <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35

    Escutando eventos personalizados em um componente-filho (o manipulador é chamado quando “my-event” é emitido no filho):

    <my-component @my-event="handleThis"></my-component>
    
    <!-- declaração inline -->
    <my-component @my-event="handleThis(123, $event)"></my-component>
    
    1
    2
    3
    4
  • Ver também:

# v-bind

  • Forma abreviada: : ou . (quando usando o modificador .prop)

  • Espera: any (com argumento) | Object (sem argumento)

  • Argumento: attrOrProp (opcional)

  • Modificadores:

    • .camel - transforma o nome do atributo de kebab-case para camelCase.
    • .prop - força um vínculo a ser definido como uma propriedade do DOM. 3.2+
    • .attr - força um vínculo a ser definido como um atributo do DOM. 3.2+
  • Uso:

    Dinamicamente vincula um ou mais atributos ou propriedades de um componente a uma expressão.

    Quando usado para o vínculo de atributos class ou style, suporta tipos de valores adicionais como Array ou Objects. Veja na seção do guia com link abaixo para mais detalhes.

    Quando usado para vincular uma propriedade, a propriedade deve estar devidamente declarada no elemento-filho.

    Quando usado sem argumento, pode ser utilizado para vincular em um objeto contendo pares nome-valor. Perceba que, neste modo,class e style não suportam Array ou Objects.

  • Exemplo:

    <!-- vinculando a um atributo -->
    <img v-bind:src="imageSrc" />
    
    <!-- nome de atributo dinâmico -->
    <button v-bind:[key]="value"></button>
    
    <!-- forma abreviada -->
    <img :src="imageSrc" />
    
    <!-- forma abreviada do nome de atributo dinâmico -->
    <button :[key]="value"></button>
    
    <!-- com concatenação de string inline -->
    <img :src="'/path/to/images/' + fileName" />
    
    <!-- vinculando classes -->
    <div :class="{ red: isRed }"></div>
    <div :class="[classA, classB]"></div>
    <div :class="[classA, { classB: isB, classC: isC }]"></div>
    <!-- vinculando estilos -->
    <div :style="{ fontSize: size + 'px' }"></div>
    <div :style="[styleObjectA, styleObjectB]"></div>
    
    <!-- vinculando um objeto com atributos -->
    <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
    
    <!-- vinculando propriedade. "prop" deve estar declarado em my-component -->
    <my-component :prop="someThing"></my-component>
    
    <!-- transmite todas as props do pai em comum com o componente-filho -->
    <child-component v-bind="$props"></child-component>
    
    <!-- XLink -->
    <svg><a :xlink:special="foo"></a></svg>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34

    When setting a binding on an element, Vue by default checks whether the element has the key defined as a property using an in operator check. If the property is defined, Vue will set the value as a DOM property instead of an attribute. This should work in most cases, but you can override this behavior by explicitly using .prop or .attr modifiers. This is sometimes necessary, especially when working with custom elements.

    The .prop modifier also has a dedicated shorthand, .:

    <div :someProperty.prop="someObject"></div>
    
    <!-- equivalent to -->
    <div .someProperty="someObject"></div>
    
    1
    2
    3
    4

    O modificador .camel permite colocar na notação camelCase (camelizing) um nome do atributo v-bind quando usado em templates no DOM, por exemplo, o atributo viewBox de um SVG:

    <svg :view-box.camel="viewBox"></svg>
    
    1

    .camel não é necessário se você está usando templates baseados em String ou compilando com vue-loader/vueify.

  • Ver também:

# v-model

  • Espera: varia baseado no valor dos elementos de input de formulário ou output de componentes

  • Limitado a:

    • <input>
    • <select>
    • <textarea>
    • componentes
  • Modificadores:

    • .lazy - escuta por eventos change ao invés de input
    • .number - converte a String do input válida para números
    • .trim - faz trim dos dados do input
  • Uso:

    Cria um vínculo de mão dupla (two-way binding) em um elemento input de formulário ou componente. Para uso detalhado e outras observações, veja o link abaixo para a seção do Guia.

  • Ver também:

# v-slot

  • Forma abreviada: #

  • Espera: expressão JavaScript que seja válida na posição de um argumento de função (aceita desestruturação em ambientes suportados). Opcional - somente necessário se estiver esperando que propriedades sejam passadas ao slot.

  • Argumento: nome do slot (opcional, o valor padrão é default)

  • Limitado a:

    • <template>
    • componentes (para um único slot padrão com propriedades)
  • Uso:

    Denote slots nomeados ou slots que esperam receber propriedades.

  • Exemplo:

    <!-- Slots nomeados -->
    <base-layout>
      <template v-slot:header>
        Conteúdo do Header
      </template>
    
      <template v-slot:default>
        Conteúdo do slot Default
      </template>
    
      <template v-slot:footer>
        Conteúdo do Footer
      </template>
    </base-layout>
    
    <!-- Slot nomeado que recebe propriedades -->
    <infinite-scroll>
      <template v-slot:item="slotProps">
        <div class="item">
          {{ slotProps.item.text }}
        </div>
      </template>
    </infinite-scroll>
    
    <!-- Slot padrão que recebe propriedades, com desestruturação -->
    <mouse-position v-slot="{ x, y }">
      Mouse position: {{ x }}, {{ y }}
    </mouse-position>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28

    Para mais detalhes, veja os links abaixo.

  • Ver também:

# v-pre

  • Não espera expressão

  • Uso:

    Pula a compilação para esse elemento e todos seus filhos. Você pode usar isso para mostrar tags mustache sem conversão (raw). Pular uma grande quantidade de nós sem diretivas também pode acelerar a compilação.

  • Exemplo:

    <span v-pre>{{ isso não será compilado }}</span>
    
    1

# v-cloak

  • Não espera expressão

  • Uso:

    Essa diretiva permanecerá no elemento até que a instância de componente associada termine de compilar. Ao ser combinada com regras CSS como [v-cloak] { display: none }, essa diretiva pode ser usada para esconder interligações mustache não-compiladas até que a instância do componente esteja pronta.

  • Exemplo:

    [v-cloak] {
      display: none;
    }
    
    1
    2
    3
    <div v-cloak>
      {{ message }}
    </div>
    
    1
    2
    3

    A <div> não ficará visível até que a compilação tenha terminado.

# v-once

  • Não espera expressão

  • Detalhes:

    Renderiza o elemento e componente apenas uma vez. Em re-renderizações subsequentes, o elemento/componente e todos seus filhos serão tratados como conteúdo estático e pulados. Isso pode ser usado para otimizar o desempenho da atualização.

    <!-- elemento único -->
    <span v-once>Isso nunca vai mudar: {{msg}}</span>
    <!-- o elemento tem filhos -->
    <div v-once>
      <h1>comentário</h1>
      <p>{{msg}}</p>
    </div>
    <!-- componente -->
    <my-component v-once :comment="msg"></my-component>
    <!-- diretiva `v-for` -->
    <ul>
      <li v-for="i in list" v-once>{{i}}</li>
    </ul>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    Since 3.2, you can also memoize part of the template with invalidation conditions using v-memo.

  • Ver também:

# v-memo 3.2+

  • Expects: Array

  • Details:

    Memoize a sub-tree of the template. Can be used on both elements and components. The directive expects a fixed-length array of dependency values to compare for the memoization. If every value in the array was the same as last render, then updates for the entire sub-tree will be skipped. For example:

    <div v-memo="[valueA, valueB]">
      ...
    </div>
    
    1
    2
    3

    When the component re-renders, if both valueA and valueB remain the same, all updates for this <div> and its children will be skipped. In fact, even the Virtual DOM VNode creation will also be skipped since the memoized copy of the sub-tree can be reused.

    It is important to specify the memoization array correctly, otherwise we may skip updates that should indeed be applied. v-memo with an empty dependency array (v-memo="[]") would be functionally equivalent to v-once.

    Usage with v-for

    v-memo is provided solely for micro optimizations in performance-critical scenarios and should be rarely needed. The most common case where this may prove helpful is when rendering large v-for lists (where length > 1000):

    <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>
    
    1
    2
    3
    4

    When the component's selected state changes, a large amount of VNodes will be created even though most of the items remained exactly the same. The v-memo usage here is essentially saying "only update this item if it went from non-selected to selected, or the other way around". This allows every unaffected item to reuse its previous VNode and skip diffing entirely. Note we don't need to include item.id in the memo dependency array here since Vue automatically infers it from the item's :key.

    WARNING

    When using v-memo with v-for, make sure they are used on the same element. v-memo does not work inside v-for.

    v-memo can also be used on components to manually prevent unwanted updates in certain edge cases where the child component update check has been de-optimized. But again, it is the developer's responsibility to specify correct dependency arrays to avoid skipping necessary updates.

  • See also:

# v-is deprecated

Deprecated in 3.1.0. Use is attribute with vue: prefix instead.