Você está navegando a documentação da v2.x e anterior. Para a v3.x, clique aqui.
API
Configuração Global
Vue.config
é um objeto contendo a configuração global do Vue. Você pode modificar suas propriedades listadas abaixo antes de iniciar sua aplicação:
silent
Tipo:
boolean
Padrão:
false
Uso:
Vue.config.silent = true
Suprime todos os logs e avisos do Vue.
optionMergeStrategies
Tipo:
{ [key: string]: Function }
Padrão:
{}
Uso:
Vue.config.optionMergeStrategies._my_option = function (parent, child, vm) { return child + 1 } const Profile = Vue.extend({ _my_option: 1 }) // Profile.options._my_option = 2
Define opções de mesclagem personalizadas.
A estratégia de mesclagem recebe o valor da opção definida no pai e nas instâncias filhas como o primeiro e segundo argumento respectivamente. O contexto da instância Vue é passado como o terceiro argumento.
Ver também: Estratégias de Mesclagem de Opções Personalizadas
devtools
Tipo:
boolean
Padrão:
true
(false
em builds de produção)Uso:
// tenha certeza de definir isso imediatamente síncrono após o carregamento do Vue Vue.config.devtools = true
Configura se deseja permitir a inspeção do vue-devtools. O valor padrão dessa opção é
true
em compilações de desenvolvimento efalse
em compilações de produção. Você pode definirtrue
para forçar habilitar a inspeção em compilações de produção.
errorHandler
Tipo:
Function
Padrão:
undefined
Uso:
Vue.config.errorHandler = function (err, vm, info) { // manuseia o erro // `info` é um erro específico do Vue, ex: cada lifecycle hook // que o erro foi encontrado. Disponível apenas em 2.2.0+ }
Atribui um manipulador para erros não detectados durante a renderização do componente e dos observadores. O manipulador é chamado com o erro e a instância Vue.
No 2.2.0+, esse gatilho também captura erros em gatilhos de ciclo de vida do componente. Além disso, quando esse gatilho é
undefined
, os erros capturados são registrados comconsole.error
em vez de quebrar o aplicativo.No 2.4.0+, esse gatilho também captura erros disparados dentro de manipuladores de eventos personalizados.
Mo 2.6.0+, esse gatilho também captura erros disparados dentro de escutadores do DOM
v-on
. Em adição, se algum dos gatilhos cobertos ou manipuladores retorna uma Promise em cadeia (como funções async), o erro daquela Promise também será manipulado.Serviços de rastreamento de erros Sentry e Bugsnag fornecem integrações oficiais usando esta opção.
warnHandler
Novo em 2.4.0+
Tipo:
Function
Padrão:
undefined
Uso:
Vue.config.warnHandler = function (msg, vm, trace) { // `trace` é a pilha da hierarquia do componente }
Atribui um gatilho personalizado para avisos Vue de tempo de execução. Observe que isto funciona apenas durante o desenvolvimento e será ignorado em produção.
ignoredElements
Tipo:
Array<string | RegExp>
Padrão:
[]
Uso:
Vue.config.ignoredElements = [ 'my-custom-web-component', 'another-web-component', // Use a `RegExp` to ignore all elements that start with "ion-" // 2.5+ only /^ion-/ ]
Faz com que o Vue ignore elementos customizados definidos fora do Vue (ex: usando APIs de Web Components). De outra forma, Vue lançaria um aviso sobre
Unknown custom element
(elemento customizado desconhecido), pois assumiria que você esqueceu de registrar algum componente global ou escreveu erroneamente o nome de um componente.
keyCodes
Tipo:
{ [key: string]: number | Array<number> }
Padrão:
{}
Uso:
Vue.config.keyCodes = { v: 86, f1: 112, // camelCase não funciona mediaPlayPause: 179, // ao invés disso, pode usar kebab-case com aspas duplas "media-play-pause": 179, up: [38, 87] }
<input type="text" @keyup.media-play-pause="method">
Define atalhos personalizados de teclas para o
v-on
.
performance
Novo em 2.2.0+
Tipo:
boolean
Padrão:
false (desde 2.2.3+)
Uso:
Defina
true
para habilitar o rastreamento de desempenho do init, compile, render e patch do componente na linha-do-tempo de inspeção do navegador. Só funciona no modo de desenvolvimento e em navegadores que suportam a API do performance.mark.
productionTip
Novo em 2.2.0+
Tipo:
boolean
Padrão:
true
Uso:
Defina
false
para prevenir a exibição da dica sobre o modo de produção ao iniciar o Vue.
Métodos Globais
Vue.extend( options )
Argumentos:
{Object} options
Uso:
Cria uma “subclasse” do construtor base do Vue. O argumento deve ser um objeto contendo opções do componente.
O caso especial a ser observado aqui é a opção
data
- ela deve ser uma função quando usada comVue.extend()
.<div id="mount-point"></div>
// cria o construtor var Profile = Vue.extend({ template: '<p>{{firstName}} {{lastName}} vulgo {{alias}}</p>', data: function () { return { firstName: 'Walter', lastName: 'White', alias: 'Heisenberg' } } }) // cria uma instância de Profile e monta isto em um elemento new Profile().$mount('#mount-point')
Irá resultar em:
<p>Walter White vulgo Heisenberg</p>
Ver também: Componentes
Vue.nextTick( [callback, context] )
Argumentos:
{Function} [callback]
{Object} [context]
Uso:
Adia o callback para ser executado depois do próximo ciclo de atualização do DOM. Use imediatamente após modificar algum dado para esperar a atualização do DOM.
// modifica dados vm.msg = 'Hello' // DOM ainda não atualizado Vue.nextTick(function () { // DOM atualizado }) // usage as a promise (2.1.0+, see note below) Vue.nextTick() .then(function () { // DOM updated })
Novo em 2.1.0+: retorna uma Promise se nenhum callback é fornecido e Promise tiver suporte no ambiente de execução. Observe que Vue não vem com um polyfill para Promise, portanto, se seu navegador alvo não oferece suporte a Promises (estamos olhando para você, IE), você precisará escolher um polyfill por sua conta.
Ver também: Fila de Atualização Assíncrona
Vue.set( target, propertyName/index, value )
Argumentos:
{Object | Array} target
{string | number} propertyName/index
{any} value
Returna: o valor atribuído.
Uso:
Adiciona uma propriedade em um objeto reativo, garantindo que a nova propriedade também seja reativa, disparando atualizações na interface. Deve ser utilizado para adicionar novas propriedades em objetos reativos, já que o Vue não pode detectar adição de propriedades direta (ex.:
this.myObject.newProperty = 'hi'
).O objeto alvo não pode ser uma instância Vue, ou um objeto de dados raiz de uma instância Vue.
Ver também: Reatividade em Profundidade
Vue.delete( target, propertyName/index )
Argumentos:
{Object | Array} target
{string | number} propertyName/index
Somente em 2.2.0+: Também funciona com Array + index.
Uso:
Remove uma propriedade de um objeto. Se o objeto é reativo, certifique-se que a remoção dispara atualizações na view. Isto é usado primariamente para contornar a limitação que o Vue não consegue detectar remoção de propriedades, mas você raramente precisará usar isto.
O objeto a ser removido não pode ser uma instância do Vue ou o dado de um objeto root de uma instância do Vue
Ver também: Reatividade em Profundidade
Vue.directive( id, [definition] )
Argumentos:
{string} id
{Function | Object} [definition]
Uso:
Registra ou recupera uma diretiva global.
// registra Vue.directive('my-directive', { bind: function () {}, inserted: function () {}, update: function () {}, componentUpdated: function () {}, unbind: function () {} }) // registra (diretiva de função) Vue.directive('my-directive', function () { // isto será chamado como `bind` e `update` }) // getter, retorna a definição da diretiva se registrada var myDirective = Vue.directive('my-directive')
Ver também: Diretivas Personalizadas
Vue.filter( id, [definition] )
Argumentos:
{string} id
{Function} [definition]
Uso:
Registra ou recupera um filtro global.
// registra Vue.filter('my-filter', function (value) { // retorna o valor processado }) // getter, retorna o filtro se registrado var myFilter = Vue.filter('my-filter')
Ver também: Filters
Vue.component( id, [definition] )
Argumentos:
{string} id
{Function | Object} [definition]
Uso:
Registra ou recupera um componente global. O registro também atribui, automaticamente, o objeto
name
do componente com oid
passado.// registra um construtor extendido Vue.component('my-component', Vue.extend({ /* ... */ })) // registra um objeto com opções (automaticamente chama Vue.extend) Vue.component('my-component', { /* ... */ }) // recupera um componente registrado (sempre retorna um construtor) var MyComponent = Vue.component('my-component')
Ver também: Componentes
Vue.use( plugin )
Argumentos:
{Object | Function} plugin
Uso:
Instala um plugin do Vue.js. Se o plugin é um Objeto, ele deve expor um método
install
. Se for uma função, ela será tratada como o próprio método de instalação. O método será chamado com Vue como argumento.Este método deve ser chamado antes da execução de
new Vue()
.Quando este método é chamado no mesmo plugin múltiplas vezes, o plugin só será instalado uma única vez.
Ver também: Plugins
Vue.mixin( mixin )
Argumentos:
{Object} mixin
Uso:
Aplica um mixin globalmente, o qual afeta toda instância do Vue criada posteriormente. Isto pode ser usado por autores de plugins para injetar um comportamento personalizado em componentes. Não recomendado no código da aplicação.
Ver também: Mixin Global
Vue.compile( template )
Argumentos:
{string} template
Uso:
Compila um template string em uma função de renderização. Somente disponível no build completo.
var res = Vue.compile('<div><span>{{ msg }}</span></div>') new Vue({ data: { msg: 'hello' }, render: res.render, staticRenderFns: res.staticRenderFns })
Ver também: Funções de Renderização
Vue.observable( object )
Novo em 2.6.0+
Argumentos:
{Object} object
Uso:
Torna um objeto reativo. Internamente, Vue utiliza este método no objeto retornado pela função
data
.O objeto retornado pode ser utilizado diretamente dentro de funções de renderização e dados computados, e irá disparar as atualizações apropriadas quando for modificado. Também pode ser usado como um armazenamento de estado mínimo entre componentes, para cenários simples:
const state = Vue.observable({ count: 0 }) const Demo = { render(h) { return h('button', { on: { click: () => { state.count++ }} }, `count is: ${state.count}`) } }
No Vue 2.x,
Vue.observable
diretamente modifica o objeto passado para ele, de forma que seja equivalente ao objeto retornado, como demonstrado aqui. No Vue 3.x, um proxy de reatividade será retornado, mantendo o objetivo original não-reativo se mutado diretamente. Sendo assim, para futura compatibilidade, recomendamos que sempre trabalhe com o objeto retornado porVue.observable
, ao invés de utilizar o objeto originalmente passado para tal método.Ver também: Reatividade em Profundidade
Vue.version
Detalhes: Disponibiliza a versão do Vue instalado como string. Isto é especialmente útil para plugins e componentes da comunidade, onde você pode usar diferentes estratégias para diferentes versões.
Uso:
var version = Number(Vue.version.split('.')[0]) if (version === 2) { // Vue v2.x.x } else if (version === 1) { // Vue v1.x.x } else { // Versões não suportadas do Vue }
Opções / Dados
data
Tipo:
Object | Function
Restrição: Somente aceita
Function
quando usado na definição de um componente.Detalhes:
O objeto
data
para a instância do Vue. Vue irá recursivamente converter esta propriedade em getter/setters para tornar “reativo”. O objeto deve ser simples: objetos nativos como API do navegador e propriedades prototype são ignoradas. A regra geral é:data
deverá ser somente dados - não é recomendável observar objetos que têm seu próprio comportamento stateful.Como observado, você não pode adicionar propriedades reativas ao objeto data raiz. É recomendado declarar todas as propriedades ‘nível raiz’ reativas com antecedência, antes da criação da instância.
Depois que a instância é criada, o objeto data original pode ser acessado como
vm.$data
. A instância Vue também faz proxy de todas as propriedade achadas no objeto data, entãovm.a
será equivalente avm.$data.a
.Propriedades que comecem com
_
ou$
não será feito proxy na instância do Vue porque eles podem conflitar com métodos de API ou propriedades internas do Vue. Você terá de acessar elas comvm.$data._property
.Quando definindo um componente,
data
deve ser declarado como uma função que retorna o objeto de dados inicial, pois haverá muitas instâncias criadas usando a mesma definição. Se usarmos um objeto simples paradata
, este mesmo objeto será compartilhado por referência entre todas as instâncias criadas! Provendo uma funçãodata
, toda vez que uma nova instância é criada, podemos chamá-la para retornar uma nova cópia do dado inicial.Se necessário, uma cópia profunda do objeto original pode ser obtida passando
vm.$data
através deJSON.parse(JSON.stringify(...))
.Exemplo:
var data = { a: 1 } // Criação direta de instância var vm = new Vue({ data: data }) vm.a // => 1 vm.$data === data // => true // deve-se usar function quando em uso com Vue.extend() var Component = Vue.extend({ data: function () { return { a: 1 } } })
Note que se você usar arrow function com a propriedade
data
,this
não será a instância do componente, mas você poderá continuar tendo acesso a instância através do argumento:data: vm => ({ a: vm.myProp })
Ver também: Reatividade em Profundidade
props
Tipo:
Array<string> | Object
Detalhes:
Uma lista/hash de atributos que são expostos para aceitar dados do componente pai. Possui tanto uma sintaxe baseada em Array como, alternativamente, uma sintaxe baseada em Object, que permite configurações avançadas como checagem de tipos, validações personalizadas e valores padrão.
Com a sintaxe baseada em Object, você pode usar 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 array dessas. Irá verificar se um prop tem o tipo determinado e emitirá um aviso se não tem. Mais informação em tipos de prop.default
:any
Especifica um valor padrão para o prop. Se o prop não é passado, este valor será usado em seu lugar. Valores padrão de tipo Object ou Array devem ser retornados de uma função factory.required
:Boolean
Define se o prop é necessário. Em ambiente de não-produção, um aviso de console será lançado se esse valor for verdadeiro e o prop não for passado.validator
:Function
Função validadora personalizada que usa o valor do prop como único argumento. Em ambiente de não-produção, um aviso de console será acionado se essa função retornar um valor falso (ou seja, a validação falhar). Você pode ler mais sobre validação de prop aqui.
Exemplo:
// sintaxe simples Vue.component('props-demo-simple', { props: ['size', 'myMessage'] }) // sintaxe de objeto com validação Vue.component('props-demo-advanced', { props: { // checagem de tipos height: Number, // checagem de tipos com validações age: { type: Number, default: 0, required: true, validator: function (value) { return value >= 0 } } } })
Ver também: Propriedades
propsData
Tipo:
{ [key: string]: any }
Restrição: somente respeitado em criação de instâncias via
new
.Detalhes:
Passa props a uma instância durante a sua criação. A intenção disso é primariamente tornar testes unitários mais fáceis.
Exemplo:
var Comp = Vue.extend({ props: ['msg'], template: '<div>{{ msg }}</div>' }) var vm = new Comp({ propsData: { msg: 'hello' } })
computed
Tipo:
{ [key: string]: Function | { get: Function, set: Function } }
Detalhes:
Dados Computados para serem misturadas na instância Vue. Todos os getters e setters tem o seu contexto
this
automaticamente feito bind a instância Vue.Note que se você usar arrow function com uma propriedade computada,
this
não será a instância do componente, mas você poderá ter acesso a instância através do seguinte argumento:computed: { aDouble: vm => vm.a * 2 }
Dados Computados são cacheadas, e somente re-computados quando dependências reativas mudam. Note que se uma certa dependência está fora do escopo da instância (ex.: não reativa), o dado computado não será atualizado.
Exemplo:
var vm = new Vue({ data: { a: 1 }, computed: { // somente get aDouble: function () { return this.a * 2 }, // get e set aPlus: { get: function () { return this.a + 1 }, set: function (v) { this.a = v - 1 } } } }) vm.aPlus // => 2 vm.aPlus = 3 vm.a // => 2 vm.aDouble // => 4
Ver também: Dados Computados
methods
Tipo:
{ [key: string]: Function }
Detalhes:
Métodos para serem misturadas na instância Vue. Você pode acessar esses métodos diretamente na instância VM ou usar eles em expressões de diretivas. Todos os métodos terão seu contexto
this
feito bind a instância Vue.Note que você não deve usar arrow function para definir um método (ex.:
plus: () => this.a++
). A razão é que arrow functions fazem bind do contexto pai, entãothis
não será a instância Vue como você está esperando ethis.a
será undefined.Exemplo:
var vm = new Vue({ data: { a: 1 }, methods: { plus: function () { this.a++ } } }) vm.plus() vm.a // 2
Ver também: Manipulação de Eventos
watch
Tipo:
{ [key: string]: string | Function | Object | Array}
Detalhes:
Um objeto onde as chaves são expressões para observar e os valores são os callbacks correspondentes. O valor pode ser uma string do nome do método, ou um Objeto que contém opções adicionais. A instância Vue chamará
$watch()
para cada entrada no objeto na inicialização.Exemplo:
var vm = new Vue({ data: { a: 1, b: 2, c: 3, d: 4, e: { f: { g: 5 } } }, watch: { a: function (val, oldVal) { console.log('novo: %s, antigo: %s', val, oldVal) }, // nome do método como string b: 'someMethod', // o callback será chamado na alteração das propriedades do objeto // observado, independentemente de sua profundidade aninhada c: { handler: function (val, oldVal) { /* ... */ }, deep: true }, // o callback será chamado imediatamente após o início da observação d: { handler: 'someMethod', immediate: true }, // você pode passar uma array de callbacks, eles serão chamados um por um e: [ 'handle1', function handle2 (val, oldVal) { /* ... */ }, { handler: function handle3 (val, oldVal) { /* ... */ }, /* ... */ } ], // watch vm.e.f's value: {g: 5} 'e.f': function (val, oldVal) { /* ... */ } } }) vm.a = 2 // => new: 2, old: 1
Note que você não deve usar arrow function para definir um observador (e.g.
searchQuery: newValue => this.updateAutocomplete(newValue)
). A razão é que arrow functions fazem bind do contexto pai, entãothis
não será a instância Vue como você está esperando ethis.updateAutocomplete
será undefined.Ver também: Métodos da Instância / Data - vm.$watch
Opções / DOM
el
Tipo:
string | Element
Restrição: respeitado apenas durante a criação da instância com
new
.Detalhes:
Fornece um elemento existente no DOM para a instância Vue ser montada. Pode ser um seletor CSS ou um
HTMLElement
.Após a instância ser montada, o elemento gerado poderá ser acessado utilizando
vm.$el
.Se essa opção estiver disponível durante a instanciação, a instância irá compilar imediatamente; caso contrário, o usuário terá que chamar explicitamente
vm.$mount()
para iniciar manualmente a compilação.O elemento fornecido serve apenas como ponto de montagem. Diferentemente do Vue 1.x, o elemento montado será substituído pelo DOM gerado pelo Vue em todos os casos. Portanto, não é recomendado montar a instância raiz em
<html>
ou<body>
.Se a função
render
ou a opçãotemplate
não estiverem presentes, o HTML já existente no DOM do elemento sendo montado será extraído como seu template. Neste caso, a versão Runtime + Compilador do Vue precisa ser utilizada.Ver também:
template
Tipo:
string
Detalhes:
Um template dentro de uma String para ser usado como marcação para a instância Vue. O template irá substituir o elemento montado. Qualquer marcação existente dentro do elemento montado será ignorada, a menos que slots de distribuição de conteúdo estejam presentes no template.
Se a String começa com
#
, ela será usada como umquerySelector
e utilizará oinnerHTML
do elemento selecionado como template String. Isto permite o uso do truque comum com<script type="x-template">
para incluir templates.De uma perspective de segurança, você deve usar apenas templates Vue em que possa confiar. Nunca use conteúdo gerado pelo usuário como seu template.
Se a função
render
estiver presente nas opções Vue, o template será ignorado.Ver também:
render
Tipo:
(createElement: () => VNode) => VNode
Detalhes:
Uma alternativa aos templates baseados em Strings, que permite aproveitar o completo poder pragmático do JavaScript. A função de renderização recebe um método
createElement
como primeiro argumento para criar elementosVNode
.Se o componente é um componente funcional, a função de renderização também recebe um argumento extra
context
que fornece acesso a dados contextuais, uma vez que componentes funcionais não possuem instância própria.A função
render
tem prioridade sobre funções de renderização compiladas através da opçãotemplate
e sobre template extraído do DOM do elemento sendo montado conforme especificado com a opçãoel
.Ver também: Funções de Renderização
renderError
Novo em 2.2.0+
Tipo:
(createElement: () => VNode, error: Error) => VNode
Detalhes:
Funciona apenas em Modo de Desenvolvimento.
Provê uma saída de renderização alternativa para quando a função
render
padrão encontrar um erro. O objeto de erro será passado aorenderError
como seu segundo argumento. É particularmente útil quando utilizado em conjunto com hot-reload.Exemplo:
new Vue({ render (h) { throw new Error('oops') }, renderError (h, err) { return h('pre', { style: { color: 'red' }}, err.stack) } }).$mount('#app')
Ver também: Funções de Renderização
Opções / Ciclo-de-Vida
Todos os gatilhos de ciclo de vida automaticamente possuem seus contextos this
vinculados à instância, assim você pode acessar dados, propriedades computadas e métodos. Isso significa que você não deve usar Arrow Function para definir este tipo de método (por exemplo, created: () => this.fetchTodos()
). Isto porque arrow functions vinculam o contexto pai, assim this
não será a instância Vue como você espera e this.fetchTodos
será undefined
.
beforeCreate
Tipo:
Function
Detalhes:
Invocado sincronicamente logo após a instância ser inicializada, antes da observação de dados e configuração de eventos e observadores.
Ver também: Diagrama do Ciclo de Vida
created
Tipo:
Function
Detalhes:
Invocado sincronicamente após a instância ser criada. Neste ponto, a instância finalizou o processamento das opções, o que significa que foi configurado: observação de dados, propriedades computadas, métodos, watch/event callbacks. Entretanto, a fase de montagem não foi iniciada, e a propriedade
$el
não estará disponível ainda.Ver também: Diagrama do Ciclo de Vida
beforeMount
Tipo:
Function
Detalhes:
Invocado logo antes da montagem começar: a função
render
está prestes a ser invocada pela primeira vez.Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também: Diagrama do Ciclo de Vida
mounted
Tipo:
Function
Detalhes:
Invocado logo após a instância ter sido montada, onde
el
é substituído pelo recém criadovm.$el
. Se a instância raiz é montada em um elemento já presente no documento,vm.$el
também estará presente no documento quandomounted
for invocada.Observe que o
mounted
não garante que todos os componentes filhos também já tenham sido montados. Se você quiser esperar até que toda a camada view do componente em questão tiver sido renderizada, você pode utilizar vm.$nextTick dentro domounted
:mounted: function () { this.$nextTick(function () { // Código que irá rodar apenas após toda // a árvore do componente ter sido renderizada }) }
Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também: Diagrama do Ciclo de Vida
beforeUpdate
Tipo:
Function
Detalhes:
Invocado quando os dados mudam, antes do virtual DOM ser re-renderizado e atualizado. Este é um bom local para acessar DOM existente antes de uma atualização, por exemplo, para remover escutas de eventos adicionadas manualmente.
Este gatilho não é invocado em Renderização no Lado do Servidor, pois apenas a renderização inicial é realizada no servidor.
Ver também: Diagrama do Ciclo de Vida
updated
Tipo:
Function
Detalhes:
Invocado após a mudança de dados fazer o virtual DOM ser re-renderizado e atualizado.
O DOM do componente estará no estado
updated
quando este gatilho for invocado, assim você pode realizar operações dependentes de DOM neste gatilho.
Entretanto, na maioria dos casos você deveria evitar mudar o estado deste gatilho, melhor utilizar propriedades computadas ou observadores.Observe que o
updated
não garante que todos os componentes filhos também já tenham sido montados. Se você quiser esperar até que toda a camada view do componente em questão tiver sido renderizada, você pode utilizar vm.$nextTick dentro doupdated
:updated: function () { this.$nextTick(function () { // Código que irá rodar apenas após toda // a árvore do componente ter sido re-renderizada }) }
Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também: Diagrama do Ciclo de Vida
activated
Tipo:
Function
Detalhes:
Invocado quando um componente keep-alive é ativado.
Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também:
deactivated
Tipo:
Function
Detalhes:
Invocado quando um componente keep-alive é desativado.
Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também:
beforeDestroy
Tipo:
Function
Detalhes:
Invocado logo antes da instância Vue ser destruída. Neste ponto a instância ainda é completamente funcional.
Este gatilho não é invocado em Renderização no Lado do Servidor.
Ver também: Diagrama do Ciclo de Vida
destroyed
Tipo:
Function
Detalhes:
Invocado após a instância Vue ter sido destruída. Quando este gatilho é invocado, todas as diretivas da instância Vue já foram desvinculadas, todos os event listeners foram removidos, e todas as instâncias Vue filhas também foram destruídas.
Este gatilho não é invocado em Renderização no Lado do Servidor.
- Ver também: Diagrama do Ciclo de Vida
errorCaptured
Novo em 2.5.0+
Tipo:
(err: Error, vm: Component, info: string) => ?boolean
Detalhes:
Invocado quando um erro emitido por qualquer componente descendente é capturado. O gatilho recebe três argumentos: o erro, a instância do componente que disparou o erro, e uma String contendo informações sobre onde o erro foi capturado. O gatilho pode retornar
false
para impedir o erro de continuar se propagando.Você pode modificar o estado do componente neste gatilho. Entretanto, é importante possuir condicionais em seu template ou função de renderização que alterne para outro conteúdo quando um erro tiver sido capturado; caso contrário, o componente cairá em um loop infinito de renderização.
Regras de Propagação de Erros
Por padrão, todos os erros ainda são enviados para o global
config.errorHandler
se estiver definido, desta forma estes erros ainda podem ser reportados a algum serviço de análise em um local único.Se múltiplos gatilhos
errorCaptured
existirem em uma cadeia de heranças ou em uma cadeia de componentes pai, todos serão invocados pelo mesmo erro.Se o próprio gatilho
errorCaptured
dispara um erro, tanto este erro quanto o original são capturados e enviados ao gatilho globalconfig.errorHandler
.Um gatilho
errorCaptured
pode retornarfalse
para prevenir o erro de continuar se propagando. Isto essencialmente diria “este erro já foi interceptado e deve ser ignorado.” Irá prevenir quaisquer gatilhoserrorCaptured
adicionais e o globalconfig.errorHandler
de serem invocados por este erro.
Opções / Recursos
directives
Tipo:
Object
Detalhes:
Um conjunto de diretivas que será disponibilizado para a instância Vue.
Ver também: Diretivas Personalizadas
filters
Tipo:
Object
Detalhes:
Um conjunto de filtros que será disponibilizado para a instância Vue.
Ver também:
Vue.filter
components
Tipo:
Object
Detalhes:
Um conjunto de componentes que será disponibilizado para a instância Vue.
Ver também: Componentes
Opções / Composição
parent
Tipo:
Vue instance
Detalhes:
Especifica a instância pai para instância que será criada. Estabelece a relação pai-filho entre as duas. O pai será acessível como
this.$parent
para o filho, e o filho será inserido no vetor$children
do pai.Use
$parent
e$children
com moderação - eles servem, na maioria das vezes, como saída de emergência. Use, preferencialmente, propriedades e eventos para comunicação pai-filho.
mixins
Tipo:
Array<Object>
Detalhes:
A opção
mixins
aceita um Array de objetos mixin. Esses objetos mixin podem conteroptions
da instância, assim como, as instâncias de objetos normais. Eles serão combinados com as eventuais opções usando a mesma lógica de combinação noVue.extend()
. Por exemplo, se o seu mixin contém um gatilho created e o componente por si só também contém um, as duas funções serão chamadas.Os gatilhos de mixin são chamados na ordem em que são fornecidos e chamados antes dos hooks do próprio componente.
Exemplo:
var mixin = { created: function () { console.log(1) } } var vm = new Vue({ created: function () { console.log(2) }, mixins: [mixin] }) // => 1 // => 2
Ver também: Mixins
extends
Tipo:
Object | Function
Detalhes:
Possibilita estender outro componente declarativamente (pode ser tanto um objeto plano com opções ou um construtor) sem ter que usar
Vue.extend
. Isso visa primeiramente tornar mais fácil extensão entre componentes single file.Isso é parecido com
mixins
.Exemplo:
var CompA = { ... } // estende CompA sem ter que invocar Vue.extend var CompB = { extends: CompA, ... }
provide / inject
Novo em 2.2.0+
Tipo:
- provide:
Object | () => Object
- inject:
Array<string> | { [key: string]: string | Symbol | Object }
- provide:
Detalhes:
Esse par de opções é usado para possibilitar que um componente pai sirva de injetor de dependência para todos os filhos, independente de quão funda é a hierarquia do componente, desde que eles sejam usados no mesmo escopo pai. Se você é familiar com o React, isso é muito similar ao recurso React’s context.
A opção
provide
deve ser um objeto ou uma função que retorna um objeto. Esse objeto contém as propriedades que estão disponíveis para serem injetadas em seus descendentes. Você pode usar ES2015 Symbols como chaves nesse objeto, mas só em ambientes que suportam nativamenteSymbol
eReflect.ownKeys
.A opção
inject
deve ser uma das opções:- um array de Strings, ou
- um objeto onde as chaves referenciam os nomes de bind local, e os valores sendo:
- uma chave (String ou Symbol) para buscar nas inserções disponíveis, ou
- um objeto onde:
- a propriedade
from
é a chave (String ou Symbol) para buscar possíveis inserções, e - a propriedade
default
é usada como valor padrão
- a propriedade
Nota: os binds
provide
einject
não são reativos. Isso é intencional. Porém, se você passar um objeto observed, a propriedades desse objeto se mantém reativas.Exemplo:
// parent component providing 'foo' var Provider = { provide: { foo: 'bar' }, // ... } // child component injecting 'foo' var Child = { inject: ['foo'], created () { console.log(this.foo) // => "bar" } // ... }
Com ES2015 Symbols, função
provide
e objetoinject
:const s = Symbol() const Provider = { provide () { return { [s]: 'foo' } } } const Child = { inject: { s }, // ... }
Os próximos 2 exemplos funcionam com Vue 2.2.1+. Anteriormente a essa versão, os valores injetados eram resolvidos depois da inicialização de
propriedades
edata
Usando um valor injetado como padrão para uma propriedade:
const Child = { inject: ['foo'], props: { bar: { default () { return this.foo } } } }
Usando um valor injetado como valor de entrada para data:
const Child = { inject: ['foo'], data () { return { bar: this.foo } } }
Em 2.5.0+ injeções podem ser opcionais com um valor padrão:
const Child = { inject: { foo: { default: 'foo' } } }
Se precisar ser injetado a partir de uma propriedade com um nome diferente, use
from
para identificar a propriedade de origem:const Child = { inject: { foo: { from: 'bar', default: 'foo' } } }
Similar aos valores padrões em
props
, você precisa usar uma função de fábrica para valores não primitivos:const Child = { inject: { foo: { from: 'bar', default: () => [1, 2, 3] } } }
Opções / Diversos
name
Tipo:
string
Restrição: somente é respeitada quando usada como uma opção do componente.
Detalhes:
Permite que o componente invoque a si mesmo recursivamente no seu template. Note que quando um componente é registrado globalmente com
Vue.component()
e seu ID global é automaticamente especificado com seu nome.Outro benefício de se especificar a opção
name
é depuração. Componentes nomeados resultarão em mensagens de aviso mais prestativas. Além disso, ao se inspecionar uma aplicação em vue-devtools, componentes não nomeados aparecerão como<AnonymousComponent>
, o que não é muito informativo. Ao fornecer a opçãoname
, você terá uma árvore de componentes muito mais informativa.
delimiters
Tipo:
Array<string>
Padrão:
["{{", "}}"]
Restrições: Esta opção só está disponível na build completa, com compilação no navegador.
Detalhes:
Altera os delimitadores de interpolação de texto simples.
Exemplo:
new Vue({ delimiters: ['${', '}'] }) // Mudando os delimitadores para o estilo do ES6 template string
functional
Tipo:
boolean
Detalhes:
Faz com que um componente seja stateless (ou seja, não possui
data
) e instanceless (ou seja, não possui o contextothis
). Componentes com esta opção habilitada serão apenas uma funçãorender
que retorna nós virtuais, fazendo com que sejam muito menos custosos para renderizar.Ver também: Componentes Funcionais
model
Novo em 2.2.0
Tipo:
{ prop: string, event: string }
Detalhes:
Permite que um componente personalize a propriedade e o evento usados quando
v-model
é utilizado. Por padrão,v-model
em um componente usavalue
como a propriedade einput
como o evento, mas alguns tipos de inputs (como checkbox e radio buttons) podem querer usar a propriedadevalue
com outro propósito. Usar a opçãomodel
pode evitar conflitos nesses casos.Exemplo:
Vue.component('my-checkbox', { model: { prop: 'checked', event: 'change' }, props: { // Isto permite usar a propriedade `value` com um propósito diferente value: String, // Usando `checked` como a propriedade, ao invés de `value` checked: { type: Number, default: 0 } }, // ... })
<my-checkbox v-model="foo" value="some value"></my-checkbox>
O código acima equivale a:
<my-checkbox :checked="foo" @change="val => { foo = val }" value="some value"> </my-checkbox>
inheritAttrs
Novo em 2.4.0+
Tipo:
boolean
Padrão:
true
Detalhes:
Por padrão, atributos binded ao escopo do componente pai que não são reconhecidos como props serão aplicados ao elemento raíz do componente filho como atributos normais de HTML. Quando um componente é implementado com o objetivo de envolver um elemento-alvo ou outro componente, este comportamento nem sempre é o mais desejado. Ao especificar
inheritAttrs
parafalse
, este comportamento padrão pode ser desabilitado. Os atributos estarão disponíveis pela propriedade de instância$attrs
(também nova na versão 2.4) e podem ser explicitamente vinculados a um elemento que não seja a raíz utilizandov-bind
.Nota: esta opção não afeta bindings de
class
estyle
.
comments
Novo em 2.4.0+
Tipo:
boolean
Padrão:
false
Restrições: Esta opção só está disponível na build completa, com compilação no navegador.
Detalhes:
Quando especificada para
true
, esta opção irá preservar e renderizar comentários HTML encontrados nos templates. O comportamento padrão é descartá-los.
Propriedades de Instância
vm.$data
Tipo:
Object
Detalhes:
O objeto data que a instância do Vue está observando. A instância do Vue provê acesso a estas propriedades no seu objeto data.
Ver também: Opções / Dados - data
vm.$props
Novo em 2.2.0+
Tipo:
Object
Detalhes:
Um objeto que representa as props atuais que um componente recebeu. A instância do Vue provê acesso a estas propriedades no seu objeto props.
vm.$el
Tipo:
Element
Somente leitura
Detalhes:
O elemento DOM raíz que a instância do Vue está gerenciando.
vm.$options
Tipo:
Object
Somente leitura
Detalhes:
As opções de instanciação usadas para a instância atual do Vue. Isto é útil quando se deseja incluir propriedades personalizadas nas opções:
new Vue({ customOption: 'foo', created: function () { console.log(this.$options.customOption) // => 'foo' } })
vm.$parent
Tipo:
Instância do Vue
Somente leitura
Detalhes:
A instância pai, se a instância atual contém uma.
vm.$root
Tipo:
Instância do Vue
Somente leitura
Detalhes:
A instância do Vue raíz da árvore do componente atual. Se a instância atual não tem uma instância pai, este valor vai ser ele mesmo.
vm.$children
Tipo:
Array<Instância do Vue>
Somente leitura
Detalhes:
Os componentes filhos diretos da instância atual. Note que não há ordem garantida para
$children
e esta propriedade não é reativa. Se você está tentando usar$children
para binding de dados, considere usar um Array ev-for
para gerar os componentes filhos e use o Array como a fonte da verdade.
vm.$slots
Tipo:
{ [name: string]: Array<VNode> }
Read only
Reativo? Não
Detalhes:
Usado para acessar programaticamente o conteúdo distribuído pelos slots. Cada slot nomeado tem sua propriedade correspondente (por exemplo, o conteúdo do
v-slot:foo
poderá ser acessado viavm.$slots.foo
). A propriedadedefault
contém todo nó que não está inserido em nenhum slot nomeado ou conteúdo dev-slot:default
.Observe que os slots não são reativos. Se você precisa que um componente renderize novamente com base em alterações dos dados passados para um slot, sugerimos considerar uma estratégia diferente que depende de uma opção de instância reativa, como
props
oudata
.Nota:
v-slot:foo
é suportado em v2.6+. Para versões mais antigas, você pode usar a sintaxe obsoleta.É bastante útil acessar
vm.$slots
quando se está escrevendo um componente com uma função de renderização.Exemplo:
<blog-post> <template v-slot:header> <h1>Sobre mim</h1> </template> <p>Aqui há conteúdo da página que será incluído em vm.$slots.default, pois não está dentro de nenhum _slot_ nomeado.</p> <template v-slot:footer> <p>Copyright 2016 Evan You</p> </template> <p>Se eu tenho algum conteúdo aqui embaixo, este também será incluído em vm.$slots.default.</p>. </blog-post>
Vue.component('blog-post', { render: function (createElement) { var header = this.$slots.header var body = this.$slots.default var footer = this.$slots.footer return createElement('div', [ createElement('header', header), createElement('main', body), createElement('footer', footer) ]) } })
Ver também:
vm.$scopedSlots
Novo em 2.1.0+
Tipo:
{ [name: string]: props => Array<VNode> | undefined }
Somente leitura
Detalhes:
Usado para acessar programaticamente scoped slots. Para cada slot, incluindo o slot
default
, o objeto contém uma função correspondente que retorna VNodes.É bastante útil acessar
vm.$scopedSlots
quando se está escrevendo um componente com uma função de renderização.Nota: desde 2.6.0+, há duas mudanças notáveis nessa propriedade:
Agora, é garantido que as funções de slot com escopo retornarão um array de VNodes, a menos que o valor de retorno seja inválido. Nesse caso, a função retornará
undefined
.Todos os
$slots
agora também estão expostos em$scopedSlots
como funções. Se você trabalha com funções de renderização, agora é recomendável sempre acessar slots através de$scopedSlots
, se eles atualmente usam um escopo ou não. Isso não apenas fará com que as futuras refatorações adicionem um escopo mais simples, mas também facilitarão sua eventual migração para o Vue 3, onde todos os slots serão funções.
Ver também:
vm.$refs
Tipo:
Object
Somente leitura
Detalhes:
Um objeto do elemento DOM que mantém componentes filhos que têm atributos
ref
registrados.Ver também:
vm.$isServer
Tipo:
boolean
Somente leitura
Detalhes:
Retorna se a instância atual do Vue está sendo executada no servidor.
Ver também: Renderização do lado do servidor
vm.$attrs
Novo em 2.4.0+
Tipo:
{ [key: string]: string }
Somente leitura
Detalhes:
Contém bindings de atributos do escopo do componente pai (exceto para
class
estyle
) que não são reconhecido como props. Quando um componente não tem nenhum props declarado, esta propriedade essencialmente contém todos os bindings do escopo do componente pai (exceto paraclass
estyle
), e pode ser passada para os componentes internos viav-bind="$attrs"
- útil quando se quer criar componentes de ordem superior.
vm.$listeners
Novo em 2.4.0+
Tipo:
{ [key: string]: Function | Array<Function> }
Somente leitura
Detalhes:
Contém ouvintes de eventos (event listeners) advindos de
v-on
do escopo do componente pai. Esta propriedade pode ser para os componentes internos viav-on="$listeners"
- útil quando se quer criar componentes de ordem superior.
Contém listeners de eventos v-on
(sem os modificadores.native
). Isso pode ser passado para um componente interno via v-on="$ listeners"
- útil ao criar wrapper transparentes de componentes.
Métodos da Instância / Dados
vm.$watch( expOrFn, callback, [options] )
Argumentos:
{string | Function} expOrFn
{Function | Object} callback
{Object} [options]
{boolean} deep
{boolean} immediate
Returns:
{Function} unwatch
Uso:
Observa por mudanças uma expressão ou uma função computada na instância do Vue. A função callback é chamada com o novo valor e o antigo. A expressão somente aceita caminhos delimitados por pontos. Para expressões mais complexas, utilize uma função.
Nota: quando se está alterando (ao invés de substituindo) um objeto ou um Array, o valor antigo será igual ao novo valor, pois eles referenciam o mesmo objeto/Array. O Vue não mantém uma cópia dos valores antes de serem mutados.
Exemplo:
// caminho da chave vm.$watch('a.b.c', function (newVal, oldVal) { // faz alguma coisa }) // função vm.$watch( function () { // every time the expression `this.a + this.b` yields a different result, // the handler will be called. It's as if we were watching a computed // property without defining the computed property itself return this.a + this.b }, function (newVal, oldVal) { // faz alguma coisa } )
vm.$watch
retorna uma função unwatch que para de lançar o callback:var unwatch = vm.$watch('a', cb) // depois, destruirá o watcher unwatch()
Opção: deep
Para também detectar valores aninhados dentro de objetos, você deve passar
deep: true
nas opções. Note que você não precisa fazer isso para mutações em Array.vm.$watch('someObject', callback, { deep: true }) vm.someObject.nestedValue = 123 // callback é acionado
Opção: immediate
Passar
immediate: true
nas opções irá acionar a função de callback imediatamente com o novo valor da expressão:vm.$watch('a', callback, { immediate: true }) // `callback` é acionada imediatamente com o novo valor de 'a'
Observe que com a opção
immediate
você não será capaz de parar a observação da propriedade na primeira chamada da função de callback.// Isso irá causar um erro var unwatch = vm.$watch( 'value', function () { doSomething() unwatch() }, { immediate: true } )
Se você ainda assim quer chamar uma função de unwatch dentro da função de callback, observe se ela está disponível primeiro:
var unwatch = vm.$watch( 'value', function () { doSomething() if (unwatch) { unwatch() } }, { immediate: true } )
vm.$set( target, propertyName/index, value )
Argumentos:
{Object | Array} target
{string | number} propertyName/index
{any} value
Retorno: o valor determinado.
Uso:
Esta método é um alias para a função global
Vue.set
.Ver também: Vue.set
vm.$delete( target, propertyName/index )
Argumentos:
{Object | Array} target
{string | number} propertyName/index
Uso:
Este método é um alias para a função global
Vue.delete
.Ver também: Vue.delete
Métodos da Instância / Eventos
vm.$on( event, callback )
Argumentos:
{string | Array<string>} event
(array somente é suportado em 2.2.0+){Function} callback
Uso:
Escuta um evento personalizado na vm atual. Eventos podem ser lançados utilizando
vm.$emit
. A função de callback irá receber todos os argumentos adicionais passados nos métodos que lançam eventos.Exemplo:
vm.$on('test', function (msg) { console.log(msg) }) vm.$emit('test', 'hi') // => "hi"
vm.$once( event, callback )
Argumentos:
{string} event
{Function} callback
Uso:
Escuta um evento personalizado, porém somente uma vez. A escuta será removida assim que for acionada pela primeira vez.
vm.$off( [event, callback] )
Argumentos:
{string | Array<string>} event
(array somente é suportado em 2.2.2+){Function} [callback]
Uso:
Remove escutas de eventos personalizados.
Se nenhum argumento é passado, esta função irá remover todas as escutas;
Se apenas o evento é passado, esta função irá remover todas as escutas para este evento;
Se tanto o evento quanto o callback forem passados, esta função somente irá remover a escuta para este callback específico.
vm.$emit( eventName, […args] )
Argumentos:
{string} eventName
[...args]
Lança um evento na instância atual. Qualquer argumento adicional será passado para a função de callback da escuta.
Exemplos:
Usando
$emit
com apenas um nome de evento:Vue.component('welcome-button', { template: ` <button v-on:click="$emit('welcome')"> Me clique para receber um olá </button> ` })
<div id="emit-example-simple"> <welcome-button v-on:welcome="sayHi"></welcome-button> </div>
new Vue({ el: '#emit-example-simple', methods: { sayHi: function () { alert('Olá!') } } })
Usando
$emit
com argumentos adicionais:Vue.component('magic-eight-ball', { data: function () { return { possibleAdvice: ['Sim', 'Não', 'Talvez'] } }, methods: { giveAdvice: function () { var randomAdviceIndex = Math.floor(Math.random() * this.possibleAdvice.length) this.$emit('give-advice', this.possibleAdvice[randomAdviceIndex]) } }, template: ` <button v-on:click="giveAdvice"> Me clique para aconselhamento </button> ` })
<div id="emit-example-argument"> <magic-eight-ball v-on:give-advice="showAdvice"></magic-eight-ball> </div>
new Vue({ el: '#emit-example-argument', methods: { showAdvice: function (advice) { alert(advice) } } })
Métodos da Instância / Ciclo-de-Vida
vm.$mount( [elementOrSelector] )
Argumentos:
{Element | string} [elementOrSelector]
{boolean} [hydrating]
Returns:
vm
- a própria instânciaUso:
Se a instância do Vue não recebeu a opção
el
durante a instanciação, ela estará em um estado “não montado” sem um elemento DOM associado.vm.$mount()
pode ser usada para começar a montagem de uma instância não montada do Vue.Se o argumento
elementOrSelector
não for passado, o template será renderizado como um elemento “fora do documento” e você terá que usar a API nativa do DOM para inseri-lo no documento.O método retorna a própria instância para que você possa encadear outros métodos de instâncias depois dele.
Exemplo:
var MyComponent = Vue.extend({ template: '<div>Hello!</div>' }) // cria e monta em #app (irá substituir #app) new MyComponent().$mount('#app') // a linha acima é o mesmo que: new MyComponent({ el: '#app' }) // ou renderiza como "fora do documento" e anexa depois: var component = new MyComponent().$mount() document.getElementById('app').appendChild(component.$el)
Ver também:
vm.$forceUpdate()
Uso:
Força a instância do Vue a renderizar novamente. Note que isso não afeta todos os componentes filhos, apenas a própria instância e os componentes filhos com conteúdo em inseridos em seus respectivos slots.
vm.$nextTick( [callback] )
Argumentos:
{Function} [callback]
Uso:
Adia a execução do callback para o próximo ciclo de atualização. Use esta função imediatamente após você alterar algum dado para esperar pela atualização do DOM. Este método é o mesmo que a função global
Vue.nextTick
exceto que o contexto dothis
no callback é automaticamente vinculado (bound) à instância que chama este método.Novo em 2.1.0+: retorna uma Promise se nenhum callback é fornecido e Promise tiver suporte no ambiente de execução. Observe que Vue não vem com um polyfill para Promise, portanto, se seu navegador alvo não oferece suporte a Promises (estamos olhando para você, IE), você precisará escolher um polyfill por sua conta.
Exemplo:
new Vue({ // ... methods: { // ... example: function () { // modifica um dado this.message = 'changed' // DOM ainda não está atualizada this.$nextTick(function () { // DOM agora está atualizada // `this` é vinculado (bound) à instância atual this.doSomethingElse() }) } } })
Ver também:
vm.$destroy()
Uso:
Destrói completamente a vm. Limpa todas as suas conexões com outras vms e desvincula (unbind) todas as suas diretivas e desliga todas as escutas de eventos.
Aciona os hooks
beforeDestroy
edestroyed
.Em casos normais você não deve chamar este método. Prefira controlar o ciclo de vida dos componentes filhos em um modelo direcionado a dados utilizando
v-if
ev-for
.Ver também: Diagrama do Ciclo de Vida
Diretivas
v-text
Espera:
string
Detalhes:
Atualiza o
textContent
do elemento. Se você precisa atualizar a parte detextContent
, você deve usar interpolações{{ Mustache }}
.Exemplo:
<span v-text="msg"></span> <!-- o mesmo que --> <span>{{msg}}</span>
Ver também: Sintaxe de Templates - Interpolações
v-html
Espera:
string
Detalhes:
Atualiza o
innerHTML
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 pegar tentando compor templates usandov-html
, tente repensar a solução usando componentes.Renderizar dinamicamente HTML arbitrário em seu website pode ser muito perigoso porque isso pode facilmente levar a ataques XSS. Use
v-html
somente em conteúdo confiável e nunca em conteúdo fornecido por usuário.Em Componentes Single-File, estilos
scoped
não serão aplicados a conteúdosv-html
, pois tal HTML não é processado pelo compilador de templates do Vue. Se você quer atingir conteúdov-html
com CSS com escopo, é possível utilizar CSS Modules ou um elemento global adicional<style>
, com uma estratégia manual de escopo como BEM.Exemplo:
<div v-html="html"></div>
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>
, seu conteúdo será extraído como o bloco condicional.Esta diretiva dispara transições quando sua condição muda.
Quando usada em conjunto com v-if, v-for tem uma prioridade maior. Veja o guia de Renderização de Listas para detalhes.
Ver também: Renderização Condicional - v-if
v-else
Não espera expressão
Restrição: o elemento-irmão anterior deve ter
v-if
ouv-else-if
.Uso:
Denota o “bloco senão” de uma cadeia
v-if
ouv-if
/v-else-if
.<div v-if="Math.random() > 0.5"> Agora você me vê </div> <div v-else> Agora não vê </div>
Ver também: Renderização Condicional - v-else
v-else-if
Novo em 2.1.0+
Espera:
any
Restrição: o elemento-irmão anterior deve ter
v-if
ouv-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>
Ver também: Renderização Condicional - v-else-if
v-for
Espera:
Array | Object | number | string | Iterável (desde 2.6)
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 alias para o elemento atual ser iterado em:<div v-for="item in items"> {{ item.text }} </div>
Alternativamente, você também pode especificar um alias para o índice (ou a chave, se usada em um Objeto):
<div v-for="(item, index) in items"></div> <div v-for="(val, key) in object"></div> <div v-for="(val, name, index) in object"></div>
O comportamento padrão de
v-for
tentará corrigir os elementos in-place sem os mover. Para forçá-lo a reordenar elementos, você precisa fornecer uma sugestão de ordenação com o atributo especialkey
:<div v-for="item in items" :key="item.id"> {{ item.text }} </div>
Em 2.6+,
v-for
também pode trabalhar em valores que implementam o protocolo iterável), incluindoMap
eSet
nativos. No entanto, deve-se notar que o Vue 2.x atualmente não suporta a reatividade nos valoresMap
eSet
, portanto não pode detectar automaticamente as alterações.Quando usada em conjunto com v-if, v-for tem uma prioridade maior. Veja o guia de Renderização de Listas para detalhes.
O uso detalhado de
v-for
é explicado na seção de Guia com link abaixo.Ver também:
v-on
Forma abreviada:
@
Espera:
Function | Inline Statement | Object
Argumento:
event
Modificadores:
.stop
- chamaevent.stopPropagation()
..prevent
- chamaevent.preventDefault()
..capture
- adiciona escuta de eventos em modo de captura..self
- aciona o manipulador somente se o evento foi disparado a partir deste elemento..{keyCode | keyAlias}
- aciona o manipulador apenas em certas chaves..native
- escuta por um evento nativo no elemento-raiz do componente..once
- aciona o manipulador somente uma vez..left
- (2.2.0+) aciona o manipulador somente para eventos do botão esquerdo do mouse..right
- (2.2.0+) aciona o manipulador somente para eventos do botão direito do mouse..middle
- (2.2.0+) aciona o manipulador somente para eventos do botão do meio do mouse..passive
- (2.3.0+) atribui um evento ao DOM com{ passive: true }
.
Uso:
Atribui uma escuta de evento ao elemento. O tipo de evento é denotado pelo argumento. A expressão pode ser um nome de método, uma declaração em linha ou omitida quando há modificadores presentes.
Quando usada em um elemento normal, escuta somente eventos nativos de DOM. Quando usada em um componente de elemento personalizado, também escuta a eventos personalizados emitidos naquele componente-filho.
Quando escutando a eventos nativos de DOM, o método recebe o evento nativo como argumento único. Se usando declaração em linha, a declaração tem acesso à propriedade especial
$event
:v-on:click="handle('ok', $event)"
.A partir do 2.4.0+,
v-on
também suporte bind para um objeto de um event/listener sem argumentos. Note que quando usar a sintaxe de objetos, este não suporta nenhum modificador.Examplo:
<!-- manipulador de método --> <button v-on:click="doThis"></button> <!-- evento dinâmico (2.6.0+) --> <button v-on:[event]="doThis"></button> <!-- declaração em linha --> <button v-on:click="doThat('hello', $event)"></button> <!-- forma abreviada --> <button @click="doThis"></button> <!-- forma abreviada para evento dinâmico (2.6.0+) --> <button @[event]="doThis"></button> <!-- para a propagação --> <button @click.stop="doThis"></button> <!-- previne padrão --> <button @click.prevent="doThis"></button> <!-- previne padrão sem expressão --> <form @submit.prevent></form> <!-- modificadores em cadeia --> <button @click.stop.prevent="doThis"></button> <!-- modificador de chave usando keyAlias --> <input @keyup.enter="onEnter"> <!-- modificador de chave usando keyCode --> <input @keyup.13="onEnter"> <!-- o evento de clique será acionado somente uma vez --> <button v-on:click.once="doThis"></button> <!-- sintaxe de objeto (2.4.0+) --> <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>
Escutando a eventos personalizados em um componente-filho (o manipulador é chamado quando “my-event” é emitido no filho):
<my-component @my-event="handleThis"></my-component> <!-- declaração em linha --> <my-component @my-event="handleThis(123, $event)"></my-component> <!-- evento nativo no componente --> <my-component @click.native="onClick"></my-component>
Ver também:
v-bind
Forma abreviada:
:
Espera:
any (sem argumento) | Object (sem argumento)
Argumento:
attrOrProp (opcional)
Modificadores:
.prop
- Interliga como uma propriedade DOM ao invés de um atributo (qual a diferença?). Se a tag é um componente, então.prop
irá definir a propriedade no$el
do componente..camel
- (2.1.0+) transforma o nome do atributo de kebab-case para camelCase..sync
- (2.3.0+) um “açúcar sintático” que se expande em umv-on
para atualizar o valor vinculado.
Uso:
Dinamicamente faz a interligação de um ou mais atributos ou propriedades de um componente a uma expressão.
Quando usado para o vínculo de atributos
class
oustyle
, suporta tipos de valores adicionais como Array ou Objects. Veja na seção do Guia abaixo para mais detalhes.Quando usado para vincular uma propriedade, a propriedade deve ser devidamente declarada no elemento-filho.
Quando usado sem argumentos, pode ser utilizado para vincular em um objeto contendo pares nome-valor. Perceba que, neste modo,
class
estyle
não suportam Array ou Objects.Exemplo:
<!-- interligando a um atributo --> <img v-bind:src="imageSrc"> <!-- nome de atributo dinâmico (2.6.0+) --> <button v-bind:[key]="value"></button> <!-- forma abreviada --> <img :src="imageSrc"> <!-- forma abreviada do nome de atributo dinâmico (2.6.0+) --> <button :[key]="value"></button> <!-- com concatenação de string na linha --> <img :src="'/path/to/images/' + fileName"> <!-- interligando classes --> <div :class="{ red: isRed }"></div> <div :class="[classA, classB]"></div> <div :class="[classA, { classB: isB, classC: isC }]"> <!-- interligando estilos --> <div :style="{ fontSize: size + 'px' }"></div> <div :style="[styleObjectA, styleObjectB]"></div> <!-- interligando um objeto com atributos --> <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div> <!-- interligando atributo DOM com modificador de propriedade --> <div v-bind:text-content.prop="text"></div> <!-- interligando propriedade. "prop" deve existir 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>
O modificador
.camel
permite colocar na notação camelCase (camelizing) um nome do atributov-bind
quando usando em templates no DOM, por exemplo, o atributoviewBox
de um SVG:<svg :view-box.camel="viewBox"></svg>
.camel
não é necessário se você está usando templates baseados em String ou compilando comvue-loader
/vueify
.Ver também:
v-model
Espera: varia baseado no valor do elemento de input de formulário ou saída de componentes
Limitado a:
<input>
<select>
<textarea>
- componentes
Modificadores:
Uso:
Cria uma interligação de mão dupla (two-way binding) em um elemento de entrada (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
Abreviação:
#
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>
- components (para um único slot padrão com propriedades)
Uso:
Denotar slots ou slots nomeados que esperam receber propriedades.
Exemplo:
<!-- Slots nomeados --> <base-layout> <template v-slot:header> Header content </template> Default _slot_ content <template v-slot:footer> Footer content </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>
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 pode acelerar a compilação.
Exemplo:
<span v-pre>{{ isso não será compilado }}</span>
v-cloak
Não espera expressão
Uso:
Essa diretiva permanecerá no elemento até que a instância associada de Vue 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 de Vue esteja pronta.Exemplo:
[v-cloak] { display: none; }
<div v-cloak> {{ mensagem }} </div>
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 somente 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>
Ver também:
Atributos Especiais
key
Espera:
number | string | boolean (desde v2.4.2) | symbol (desde v2.5.12)
O atributo especial
key
é usado principalmente como um aviso para o algoritmo do virtual DOM do Vue identificar VNodes quando comparar a nova lista de nós com a anterior. Semkeys
, o Vue usa um algoritmo que minimiza a movimentação de elementos e tenta corrigir/reusar elementos do mesmo tipo no local tanto quanto possível. Comkeys
, ele irá reordenar os elementos baseado na ordem de mudança daskeys
e elementos comkeys
, que não estão mais presentes, serão sempre removidos/destruídos.Componentes filhos com pai em comum precisam ter keys únicas.
keys
duplicadas causarão erros de renderização.O caso mais comum é combinado com o
v-for
:<ul> <li v-for="item in items" :key="item.id">...</li> </ul>
Também pode ser usado para forçar a substituição de um elemento/componente ao invés de reusa-lo. Isso pode ser útil quando você quiser:
- Ativar corretamente os hooks do ciclo de vida de um componente.
- Ativar transições.
Por exemplo:
<transition> <span :key="text">{{ text }}</span> </transition>
Quanto
text
mudar, o<span>
será substituído em vez de alterado e então a transição será ativada.
ref
Espera:
string
ref
é usada para registrar a referência para um elemento ou um componente filho. A referência será registrada no objeto$refs
do componente pai. Se usada em um elemento normal do DOM, a referência será aquele elemento; Se usada em um componente filho, a referência será a instância do componente:<!-- vm.$refs.p será o nó do DOM--> <p ref="p">Olá</p> <!-- vm.$refs.child será a instância do componente filho --> <child-component ref="child"></child-component>
Quando usada em elementos/componentes com
v-for
, a referência registrada será um Array contendo nós do DOM ou instâncias de componentes.Uma observação importante sobre o tempo do registro de
ref
: como asrefs
são criadas como resultados da função de renderização, você não pode acessá-las na renderização inicial - elas ainda não existem!$refs
são não-reativas, portanto você não deve tentar usá-las em templates para data-binding.Ver também: Referencias a Componentes Filhos
is
Espera:
string | Object (de opções do componente)
Usado para Componentes Dinâmicos e para trabalhar limitações dos templates do DOM.
Por exemplo:
<!-- component é alterado quando o currentView é alterado --> <component v-bind:is="currentView"></component> <!-- necessário, porque <my-row> seria inválido dentro --> <!-- do elemento <table> e seria içado para fora (hoisted out) --> <table> <tr is="my-row"></tr> </table>
Para maiores detalhes de uso, veja os links na descrição abaixo.
Ver também:
slot obsoleto
Prefira v-slot em 2.6.0+.
Espera:
string
Usado dentro de conteúdos inseridos no componente filho para indicar a qual named slot o conteúdo pertence.
Para maiores detalhes de uso, veja a sessão no guia do link abaixo:
Ver também: Slots Nomeados
slot-scope obsoleto
Prefira v-slot em 2.6.0+.
Espera:
function argument expression
Uso:
Usado para denotar um elemento ou componente como um slot de escopo. O valor do atributo deve ser uma expressão de JavaScript válida que pode aparecer na posição do argumento de uma assinatura de função. Isso significa que, em ambientes suportados, você também pode usar a desestruturação ES2015 na expressão. Serve como um substituto para scope
em 2.5.0+.
Este atributo não suporta ligação dinâmica.
- Ver também: Slot com Escopo
scope removido
Substituído por slot-scope em 2.5.0+. Prefira v-slot em 2.6.0+.
Usado para denotar um elemento <template>
como um slot de escopo.
Uso:
O mesmo que
slot-scope
exceto quescope
somente pode ser utilizado em elementos<template>
.
Componentes Integrados
component
Props:
is
- string | ComponentDefinition | ComponentConstructorinline-template
- boolean
Uso:
Um “componente meta” para renderizar componentes dinâmicos. O componente real a renderizar é determinado pelo propriedade
is
:<!-- um componente dinâmico controlado --> <!-- pela propriedade `componentId` na vm --> <component :is="componentId"></component> <!-- pode também renderizar um componente registrado ou componente passado como propriedade --> <component :is="$options.components.child"></component>
Ver também: Componentes Dinâmicos
transition
Propriedades:
name
- string. Usado para gerar automaticamente nomes de classes CSS de transição. Por exemplo,name: 'fade'
expandirá automaticamente para.fade-enter
,.fade-enter-active
e etc. Por padrão,"v"
(v-enter
,v-enter-active
).appear
- boolean. Aplicar ou não a transição na renderização inicial. Por padrão,false
.css
- boolean. Aplicar ou não classes de transição CSS. Padrão étrue
. Se configurado parafalse
, apenas irá desencadear gatilhos registrado no JavaScript por meio de eventos de componentes.type
- string. Especifica os tipos de eventos de transição à aguardar a especificação do tempo final da transição. Valores disponíveis são"transition"
e"animation"
. Por padrão, será detectado automaticamente o tipo que tenha uma duração mais longa.mode
- string. Controla a sequência de temporização das transições de saída/entrada. Modos disponíveis são"out-in"
e"in-out"
. Por padrão, simultaneamente.duration
- number | {enter
: number,leave
: number }. Especifica a duração da transição. Por padrão, o Vue aguarda o primeiro evento detransitionend
ouanimationend
no elemento de transição raiz.enter-class
- stringleave-class
- stringappear-class
- stringenter-to-class
- stringleave-to-class
- stringappear-to-class
- stringenter-active-class
- stringleave-active-class
- stringappear-active-class
- string
Eventos:
before-enter
before-leave
before-appear
enter
leave
appear
after-enter
after-leave
after-appear
enter-cancelled
leave-cancelled
(v-show
somente)appear-cancelled
Uso:
<transition>
servem como efeitos de transição para elemento/componente único. O<transition>
aplica apenas o comportamento de transição para o conteúdo envolvido dentro; Ele não processa um elemento DOM extra ou aparece na hierarquia dos componentes inspecionados.<!-- simple element --> <transition> <div v-if="ok">conteúdo alternado</div> </transition> <!-- dynamic component --> <transition name="fade" mode="out-in" appear> <component :is="view"></component> </transition> <!-- event hooking --> <div id="transition-demo"> <transition @after-enter="transitionComplete"> <div v-show="ok">conteúdo alternado</div> </transition> </div>
new Vue({ ... methods: { transitionComplete: function (el) { // para o 'el' passado que é um elemento do DOM como um argumento } } ... }).$mount('#transition-demo')
Ver também: Transições: Transicao-de-Entrada-Saida-de-Lista
transition-group
Propriedades:
tag
- string. Padrão paraspan
.move-class
- Substituí a classe CSS aplicada durante a transição em movimento.- Expõe as mesmas propriedades que
<transition>
excetomode
.
Eventos:
- Expõe os mesmos eventos que
<transition>
.
- Expõe os mesmos eventos que
Uso:
<transition-group>
serve como efeito de transição para múltiplos elementos/componentes. O<transition-group>
renderiza um elemento DOM real. Por padrão, renderiza-se um<span>
, e você pode configurar qual elemento deverá ser renderizado através do atributotag
.Note que cada filho em um
<transition-group>
deve ser identificado unicamente para as animações funcionarem corretamente.<transition-group>
suporta transições em movimento via transformações CSS. Quando a posição de um filho na tela muda após uma atualização, ele aplicará uma classe CSS de movimento (gerada automaticamente a partir do atributoname
ou configurada com o atributomove-class
). Se a propriedade CSStransform
for passível de transição quando a classe de movimento é aplicada, o elemento será animado de forma suave para seu destino usando a técnica FLIP.<transition-group tag="ul" name="slide"> <li v-for="item in items" :key="item.id"> {{ item.text }} </li> </transition-group>
Ver também: Transições: Transicao-de-Entrada-Saida-de-Lista
keep-alive
Propriedades:
include
- string ou RegExp ou Array. Somente os componentes correspondentes serão armazenados em cache.exclude
- string ou RegExp ou Array. Qualquer componente compatível com isso não será armazenado em cache.max
- number. O número máximo de instâncias do componente a serem armazenadas em cache.
Uso:
Quando enrolado em torno de um componente dinâmico,
<keep-alive>
armazena as instâncias do componente inativo sem destruí-las. Semelhante a<transition>
,<keep-alive>
é um componente abstrato: ele não processa um próprio elemento DOM e não aparece na cadeia principal do componente.Quando um componente é alternado dentro de
<keep-alive>
, os hooks de ciclo de vida ‘ativados’ e ‘desativados’ serão invocados de acordo.Em 2.2.0+, “activated” e “deactivated” dispararão para todos os componentes aninhados dentro de uma árvore
<keep-alive>
.Usado principalmente para preservar o estado do componente ou evitar re-renderização.
<!-- básico --> <keep-alive> <component :is="view"></component> </keep-alive> <!-- filhos com multi condicional --> <keep-alive> <comp-a v-if="a > 1"></comp-a> <comp-b v-else></comp-b> </keep-alive> <!-- usado junto com `<transition>` --> <transition> <keep-alive> <component :is="view"></component> </keep-alive> </transition>
Nota:
<keep-alive>
é projetado para o caso em que ele possui um componente filho direto que está sendo alternado. Isso não funciona se você tiver “v-for” dentro dele. Quando há múltiplos filhos condicionais, como acima,<keep-alive>
exige que apenas uma criança seja renderizada de cada vez.include
eexclude
Novo em 2.1.0+
Os acessórios include
e exclude
permitem que os componentes sejam armazenados em cache condicionalmente. Ambas as propriedades podem ser uma string delimitada por vírgulas, um RegExp ou uma Array:
<!-- string delimitada por vírgulas -->
<keep-alive include="a,b">
<component :is="view"></component>
</keep-alive>
<!-- regex (usando `v-bind`) -->
<keep-alive :include="/a|b/">
<component :is="view"></component>
</keep-alive>
<!-- Array (usando `v-bind`) -->
<keep-alive :include="['a', 'b']">
<component :is="view"></component>
</keep-alive>
A correspondência é verificada pela primeira vez na opção name
do componente, em seguida, pelo nome no registro local (a chave dentro das opções do components
pai) se a opção name
não estiver disponível. Os componentes anônimos não podem ser comparados.
max
Novo em 2.5.0+
O número máximo de instâncias do componente a serem armazenadas em cache. Quando esse número for atingido, a instância do componente em cache que foi acessada menos recentemente será destruída antes de criar uma nova instância.
<keep-alive :max="10"> <component :is="view"></component> </keep-alive>
<keep-alive>
não funciona com componentes funcionais porque eles não têm instâncias a serem armazenadas em cache.Ver também: Componentes Dinâmicos - keep-alive
slot
Propriedades:
name
- string. Usado para o slot nomeado.
Uso:
<slot>
servem como pontos de distribuição de conteúdo em modelos de componentes. O<slot>
em si será substituído.Para um uso detalhado, veja a seção do guia ligada abaixo.
Ver também: Distribuição de Conteúdo com Slots
Interface VNode
- Por favor, consulte a declaração da classe VNode.
Renderização no Lado do Servidor
- Por favor, consulte a documentação do pacote vue-server-renderer.