Vue.js

# Atributo key
breaking

# Visão Geral

  • NOVO: keys não são mais necessárias em branches v-if/v-else/v-else-if, já que o Vue agora gera automaticamente keys únicas.
    • BREAKING: Se você informar keys manualmente, então cada branch deve ter uma key única. Você não pode mais usar intencionalmente a mesma key para forçar reuso de branch.
  • BREAKING: keys de <template v-for> devem ser colocadas na tag <template> (ao invés de em seus filhos).

# Background

O atributo especial key é usado como uma dica para o algoritmo de DOM virtual do Vue rastrear a identidade de um nó. Dessa forma, o Vue sabe quando pode reutilizar e corrigir nós existentes e quando precisa reordená-los ou recriá-los. Para mais informações, olhe as seções a seguir:

# Em Branches Condicionais

No Vue 2.x, era recomendado o uso de keys nos branches v-if/v-else/v-else-if.

<!-- Vue 2.x -->
<div v-if="condition" key="yes">Sim</div>
<div v-else key="no">Não</div>
1
2
3

O exemplo acima ainda funciona no Vue 3.x. Porém, não é mais recomendado o uso do atributo key em branches v-if/v-else/v-else-if, já que keys únicas são geradas automaticamente em branches condicionais caso você não as informe.

<!-- Vue 3.x -->
<div v-if="condition">Sim</div>
<div v-else>Não</div>
1
2
3

A grande mudança (breaking change) é que se você informar keys manualmente, cada branch deverá usar uma key única. Na maioria dos casos, você pode remover essas keys.

<!-- Vue 2.x -->
<div v-if="condition" key="a">Sim</div>
<div v-else key="a">Não</div>

<!-- Vue 3.x (solução recomendada: remover as keys) -->
<div v-if="condition">Sim</div>
<div v-else>Não</div>

<!-- Vue 3.x (solução alternativa: garantir que as keys sejam sempre únicas) -->
<div v-if="condition" key="a">Sim</div>
<div v-else key="b">Não</div>
1
2
3
4
5
6
7
8
9
10
11

# Com <template v-for>

No Vue 2.x, uma tag <template> não poderia ter uma key. Em vez disso, você poderia colocar as keys em cada uma de suas tags filhas.

<!-- Vue 2.x -->
<template v-for="item in list">
  <div :key="'heading-' + item.id">...</div>
  <span :key="'content-' + item.id">...</span>
</template>
1
2
3
4
5

No Vue 3.x, a key deve ser colocada na tag <template>.

<!-- Vue 3.x -->
<template v-for="item in list" :key="item.id">
  <div>...</div>
  <span>...</span>
</template>
1
2
3
4
5

Similarmente, quando houver uma tag <template v-for> com uma tag filha que use v-if, a key deve ser movida para a tag <template>.

<!-- Vue 2.x -->
<template v-for="item in list">
  <div v-if="item.isVisible" :key="item.id">...</div>
  <span v-else :key="item.id">...</span>
</template>

<!-- Vue 3.x -->
<template v-for="item in list" :key="item.id">
  <div v-if="item.isVisible">...</div>
  <span v-else>...</span>
</template>
1
2
3
4
5
6
7
8
9
10
11

← Modificadores KeyCode →