Você está navegando a documentação da v2.x e anterior. Para a v3.x, clique aqui.

Sintaxe de Templates

O Vue.js utiliza uma sintaxe de templates baseada em HTML, permitindo que você vincule declarativamente o DOM renderizado aos dados da instância Vue. Todos os templates do Vue.js são compostos por HTML válido que pode ser compilado por navegadores compatíveis com as especificações e também por compiladores HTML.

Internamente, Vue compila os templates dentro de funções de renderização de Virtual DOM. Combinado com o sistema de reatividade, Vue é capaz de identificar de forma inteligente a menor quantidade possível de componentes a serem “re-renderizados” e aplica o mínimo possível de manipulações DOM quando o estado da aplicação muda.

Se você é familiarizado com os conceitos de Virtual DOM e prefere o poder do JavaScript puro, também é possível escrever diretamente funções de renderização em vez de utilizar templates, inclusive podendo contar com o suporte opcional para JSX nestas funções.

Interpolações

Texto

O mais básico data binding, interpolando texto com a sintaxe Mustache (chaves duplas):

<span>Mensagem: {{ msg }}</span>

A tag mustache vai ser trocada pelo valor da propriedade msg do objeto de dados correspondente. Esse texto também reagirá sempre que a propriedade msg for modificada.

Você também pode realizar interpolações únicas que não são atualizadas quando os dados mudam através da diretiva v-once, mas lembre-se que isso afetará qualquer binding realizado no mesmo nó:

<span v-once>Esse valor nunca será modificado: {{ msg }}</span>

HTML

As chaves duplas interpretam os dados como texto simples, e não HTML. Para que você exiba HTML, utilize a diretiva v-html:

<p>Interpolação textual: {{ rawHtml }}</p>
<p>Diretiva v-html: <span v-html="rawHtml"></span></p>

Os conteúdos do span serão substituídos com o valor da propriedade rawHtml, interpretada como HTML puro - data bindings são ignorados. Note que você não pode utilizar a diretiva v-html para compor templates parciais, porque o Vue não é uma engine baseada em templates através de String. Em vez disso, componentes são a maneira indicada como peça fundamental de composição e reutilização de elementos de interface.

Dinamicamente renderizar HTML sem precauções pode ser muito perigoso, pois pode levar a ataques XSS. Utilize a interpolação de HTML apenas em conteúdos que você confia e nunca em conteúdos enviados por seus usuários.

Atributos

Chaves duplas não podem ser usadas em atributos HTML. Para isso, utilize a diretiva v-bind:

<div v-bind:id="dynamicId"></div>

No caso de atributos booleanos, onde sua mera existência implica em true, v-bind funciona um pouco diferente. Neste exemplo:

<button v-bind:disabled="isButtonDisabled">Botão</button>

Se isButtonDisabled possui um valor null, undefined ou false, o atributo disabled nem mesmo será incluído no elemento <button> renderizado.

Expressões JavaScript

Até aqui nós apenas estivemos vinculando propriedades simples diretamente em nossos templates. Mas o Vue.js suporta todo o poder das expressões JavaScript dentro de qualquer tipo de data binding:

{{ number + 1 }}

{{ ok ? 'SIM' : 'NÃO' }}

{{ message.split('').reverse().join('') }}

<div v-bind:id="'list-' + id"></div>

Essas expressões serão compiladas como JavaScript no escopo de dados da instância do Vue. A única restrição é que cada binding pode conter apenas uma expressão, então os códigos a seguir são exemplos de coisas que NÃO funcionarão:

<!-- isso é uma atribuição, e não uma expressão -->
{{ var a = 1 }}

<!-- controle de fluxo também não funciona, utilize expressões ternárias -->
{{ if (ok) { return message } }}

Expressões em templates são restritas a um ambiente controlado e somente possuem acesso a uma lista de variáveis globais permitidas, como Math e Date. Você não deve tentar acessar variáveis globais definidas pelo usuário em uma expressão de template.

Diretivas

Diretivas são atributos especiais com o prefixo v-. Espera-se que os valores atribuídos às diretivas sejam uma simples expressão Javascript (com a excessão do v-for, que será discutido posteriormente). O trabalho de uma diretiva é aplicar reativamente efeitos colaterais ao DOM, ou seja, realizar algum efeito quando o valor da expressão é modificado. Vamos revisar o exemplo que vimos na introdução:

<p v-if="seen">Agora você me viu</p>

Aqui, a diretiva v-if irá remover/inserir o elemento <p> baseado na veracidade do valor da expressão seen.

Parâmetros

Algumas diretivas podem aceitar um “parâmetro”, denotado pelo símbolo de dois pontos após a diretiva. Por exemplo, a diretiva v-bind é utilizada para atualizar um atributo HTML reativamente:

<a v-bind:href="url"> ... </a>

Aqui href é o parâmetro, que informará à diretiva v-bind para interligar o atributo href do elemento ao valor da expressão url de forma reativa.

Outro simples exemplo é a diretiva v-on, que observa eventos do DOM:

<a v-on:click="doSomething"> ... </a>

Aqui o valor é o nome do evento DOM que ela está escutando. Falaremos sobre gerenciamento de eventos com mais detalhes em breve.

Argumentos Dinâmicos

Novo na versão 2.6.0+

A partir da versão 2.6.0, também é possível usar uma expressão JavaScript no argumento de uma diretiva envolvendo-a com colchetes:

<!--
Note que existem algumas restrições à expressão do argumento, como explicado na seção
"Restrições da Expressão de Argumento Dinâmico" abaixo.
-->
<a v-bind:[attributeName]="url"> ... </a>

Aqui, attributeName será dinamicamente processado como uma expressão JavaScript, seu valor será usado como o final para o argumento. Por exemplo, se sua instância do Vue tem um propriedade de dados, attributeName, cujo o valor é "href", essa ligação irá ser equivalente a v-bind:href.

Igualmente, você pode usar argumentos dinâmicos para vincular um manipulador a um nome de evento dinâmico:

<a v-on:[eventName]="doSomething"> ... </a>

Neste exemplo, quando o valor de eventName for "focus", por exemplo, v-on:[eventName] será equivalente a v-on:focus.

Restrições de Valores de Argumentos Dinâmicos

Se espera que argumentos dinâmicos sejam avaliados resultando-se em uma String, com exceção do null. O valor especial null pode ser usado para explicitamente remover um vínculo. Qualquer outro valor que não seja uma String acionará um aviso.

Restrições da Expressão de Argumento Dinâmico

Expressões de argumentos dinâmicos possuem algumas restrições de sintaxe por causa de determinados caracteres, como espaços e aspas, os quais são inválidos dentro de nomes de atributos HTML. Por exemplo, o seguinte é inválido:

<!-- Isso irá disparar um aviso do compilador. -->
<a v-bind:['foo' + bar]="value"> ... </a>

A solução alternativa é usar expressões sem espaço ou aspas, ou simplesmente substituir a expressão complexa por uma propriedade computada.

Quando estiver usando templates no DOM (i.e., templates escritos diretamente no arquivo HTML), você também deve evitar nomear suas chaves de argumentos dinâmicos com caracteres maiúsculos, já que os navegadores forçarão os nomes dos atributos a ficarem em minúsculas:

<!--
Isso será convertido em v-bind:[someattr] em templates no DOM.
A menos que você tenha uma propriedade "someattr" (totalmente em minúsculas) em sua instância, tal código não funcionará.
-->
<a v-bind:[someAttr]="value"> ... </a>

Modificadores

Modificadores são sufixos especiais denotados por um ponto, que indicam que aquela diretiva deve ser vinculada de alguma maneira especial. Por exemplo, o modificador .prevent indica que o v-on chamará a função event.preventDefault() quando o evento for disparado:

<form v-on:submit.prevent="onSubmit"> ... </form>

Você verá outros exemplos de modificadores futuramente, modificadores para v-on e modificadores para v-model, quando estivermos explorando tais funcionalidades.

Abreviações

O prefixo v- serve como dica visual para identificar atributos específicos do Vue nos templates. Isso é útil quando se está utilizando o Vue para aplicar comportamento dinâmico em HTML existente, mas você pode achar um pouco verboso se precisar usar frequentemente. Ao mesmo tempo, o uso do prefixo v- se torna menos importante quando se está construindo uma SPA, onde o Vue gerencia cada template. Assim, Vue oferece abreviações especiais para as duas diretivas mais utilizadas, v-bind e o v-on:

Abreviação para v-bind

<!-- sintaxe completa -->
<a v-bind:href="url"> ... </a>

<!-- abreviação -->
<a :href="url"> ... </a>

<!-- abreviação com argumentos dinâmicos (2.6.0+) -->
<a :[key]="url"> ... </a>

Abreviação para v-on

<!-- sintaxe completa -->
<a v-on:click="doSomething"> ... </a>

<!-- abreviação -->
<a @click="doSomething"> ... </a>

<!-- abreviação com argumentos dinâmicos (2.6.0+) -->
<a @[event]="doSomething"> ... </a>

Essas abreviações podem parecer um pouco diferentes do HTML normalmente utilizado, mas os caracteres : e @ são válidos para nomes de atributos em todos os navegadores que o Vue suporta. Além disso, não aparecerão no código renderizado. Essa sintaxe é totalmente opcional, mas você provavelmente vai apreciar quando utilizar diretivas frequentemente.