Introdução
A função setup é uma feature que foi adicionada no Vue 3 e faz parte da Composition API.
Essa função serve para indicar quais propriedades e métodos devem estar disponíveis no template.
Ou seja, as variáveis e funções que você quiser utilizar na parte do HTML do seu componente, devem ser retornadas por essa função.
Essa função é executada antes do componente ser criado e dentro dela não precisa utilizar o this para acessar propriedades e métodos, como fazia antes.
Ela também aceita dois parâmetros, que são as props e o context, veja mais sobre eles abaixo.
Props
As props são os dados recebidos de um outro componente.
Caso essa prop seja utilizada no template sem precisar de nenhuma manipulação, então você não precisa receber como parâmetro, pode utilizar diretamente no template.
Mas caso você precise manipular o dado de uma prop recebida, você pode utilizar como parâmetro dentro da função setup, e acessar os dados dela, veja um exemplo.
Vamos supor que eu tenha um componente chamado ExibeMensagem.vue e ele recebe a prop mensagem.
Se eu quiser somente mostrar a mensagem na tela, posso fazer assim:
<!-- ExibeMensagem.vue -->
<template>
<p>{{ mensagem }}</p>
</template>
<script>
export default {
props: {
mensagem: String
}
}
</script>
Assim o texto que for passado na prop “mensagem” será exibida na tela.
Mas vamos supor que precise atualizar essa mensagem, então será necessário receber ela dentro da função setup para manipular:
<!-- ExibeMensagem.vue -->
<template>
<p>{{ mensagem }}</p>
<p>{{ state.mensagem }}</p> <!-- mensagem atualizada -->
</template>
<script>
import { reactive } from 'vue'
export default {
props: {
mensagem: String
},
setup (props) {
const state = reactive({ mensagem: props.mensagem })
state.mensagem = 'mensagem atualizada'
return {
state,
}
}
}
</script>
A prop recebida não é uma variável reativa, então por esse motivo é necessário utilizar o reactive e colocar uma variável interna da função recebendo o valor de props.mensagem.
No caso eu atribui a um objeto chamado state, que tem a chave mensagem, faço a modificação do valor de state.mensagem e retorno o state, com isso no template é possível acessar state.mensagem que o valor estará atualizado.
Esse nome state é somente um nome que defini, fiz dessa forma para declarar somente um objeto reativo, mas daria para fazer variáveis separadas serem reativas também, ou utilizar outro nome que preferir.
Este assunto de reatividade é um pouco extenso e pretendo abordar em outros artigos.
Mas por enquanto tenha em mente que para manipular uma prop você precisará receber ela no setup, atribuir para uma uma variável reativa, manipular e retornar o valor no return do setup.
Context
O segundo parâmetro do setup é o context.
Esse parâmetro é um objeto literal do Javascript, e com isso você pode obter os valores dele a partir de desestruturação.
Dentro do context tem os valores de attrs, slots, emit e expose.
setup(props, context) { //exemplo context
//equivalente ao $attrs
console.log(context.attrs)
// equivalente ao $slots
console.log(context.slots)
// equivalente ao $emit
console.log(context.emit)
// expõe propriedades publicas
console.log(context.expose)
}
setup(props, {attrs, slots, emit, expose}) { //exemplo com desestruturação
//acessar emit
console.log(emit)
// ...
}
Talvez o mais utilizado seja o emit, que já existia no Vue 2 e era usado como this.$emit() para emitir um evento de um objeto filho para objeto pai.
Vamos supor que no componente ExibeMensagem.vue tenha um botão no qual ao ser clicado envia um evento para o componente que o chamar, no caso o App.vue, será preciso pegar o emit do segundo parâmetro da função setup, dessa forma:
setup(props, { emit })
Vou precisar também colocar uma função dentro do setup, que será retornada para ser utilizada no template, o componente ExibeMensagem.vue fica assim:
<!-- ExibeMensagem.vue -->
<template>
<p>{{ mensagem }}</p>
<p>{{ state.mensagem }}</p>
<button @click="emiteEvento">emitir evento</button>
</template>
<script>
import { reactive } from 'vue'
export default {
props: {
mensagem: String
},
setup (props, { emit }) {
const state = reactive({ mensagem: props.mensagem })
state.mensagem = 'mensagem atualizada'
function emiteEvento () {
emit('novo-evento')
}
return {
state,
emiteEvento
}
}
}
</script>
Vou usar o ExibeMensagem.vue dentro do App.vue que vai ficar assim:
<!-- App.vue -->
<template>
<div>
<ExibeMensagem mensagem="Nova mensagem" @novo-evento="exibeAlerta" />
</div>
</template>
<script>
import ExibeMensagem from './components/ExibeMensagem.vue'
export default {
name: 'App',
components: {
ExibeMensagem
},
setup () {
function exibeAlerta () {
alert('Olá Vue3')
}
return {
exibeAlerta
}
}
}
</script>
Assim que for clicado no botão do ExibeMensagem.vue, será exibido um alerta na tela.
Usar emit sem ter prop
Uma situação comum é um componente que não recebe prop precisar emitir um evento.
Nesse caso você ainda precisará receber o props como primeiro parâmetro da função setup, pois se você tentar pegar o contexto, ou utilizar com desestruturação no primeiro parâmetro não irá funcionar.
No primeiro parâmetro a função setup sempre espera as props.
Uma coisa que da para se fazer, é em vez de colocar o nome props no parâmetro, colocar somente um underline para indicar que é um parâmetro que não está sendo utilizado, dessa forma:
setup(_, { emit })
Dessa forma tem uma indicação visual de que o primeiro parâmetro não está sendo utilizado, porém ele está declarado, ai é possível acessar o segundo normalmente.
Conclusão
O Vue 3 veio com diversas novidades e com elas a Composition API com a função setup.
O principal é entender que essa função precisa retornar os dados que serão utilizados no template.
Caso você use Composition API, todas as variáveis e métodos utilizados no template precisam estar no retorno do setup.
Caso contrario a variável ou método não funcionará e você terá um comportamento indesejado.
Código Fonte
O código fonte dos exemplos está no meu CodeSandbox, neste link.
Para ver outros canais onde o posto conteúdo sobre HTML, CSS e Javascript, veja os Links do Programando Soluções.
Referências
https://v3.vuejs.org/guide/composition-api-introduction.html#why-composition-api
https://v3.vuejs.org/guide/composition-api-setup.html#context
https://blog.codecasts.com.br/conhe%C3%A7a-as-novas-funcionalidades-do-vue-3-bed5eb4d407b