Skip to content

2. Primeiros passos com o Vue.js

2.1. Exemplo 01: A estrutura de uma aplicação Vue.js

2.1.1. O arquivo package.json

O arquivo [package.json] da pasta examples declara as bibliotecas utilizadas e os comandos do projeto:

{
  "name": "examples-vuejs",
  "version": "1.0.0",
  "description": "The small examples of the course [Step-by-step introduction to the Vue.js framework] - a single installation for all of them",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "check": "vue-tsc --noEmit"
  },
  "dependencies": {
    "bootstrap": "^5.3.8",
    "pinia": "^3.0.4",
    "vue": "^3.5.22",
    "vue-i18n": "~11.3.2",
    "vue-router": "^4.6.3"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.9.3",
    "vite": "^7.1.12",
    "vue-tsc": "^3.1.3"
  }
}

Vamos percorrer este arquivo:

  • Linha 6: Os arquivos [JavaScript] do projeto são módulos ES ([import] / [export]), o formato padrão do [JavaScript], que é suportado pelos navegadores e também pelo [Node.js];
  • Linhas 7–11: os comandos do projeto, iniciados por [npm run <name>]:
    • [npm run dev] inicia o servidor de desenvolvimento do [Vite];
    • [npm run check] faz com que os tipos [TypeScript] de todos os arquivos, inclusive os [.vue], sejam verificados pela ferramenta [vue-tsc];
    • [npm run build] verifica os tipos e depois gera a versão de produção dos exemplos;
  • Linhas 12–18: as bibliotecas de que a aplicação precisa no navegador: o [Vue.js] em si, seu roteador ([vue-router]), o [Pinia] para o estado compartilhado, o [vue-i18n] para os idiomas e o [Bootstrap] para a formatação;
  • linhas 19–26: as ferramentas de desenvolvimento: [Vite] e sua extensão para arquivos [.vue], o compilador [TypeScript] e o [vue-tsc]. Elas não fazem parte da aplicação entregue aos usuários.

O prefixo [^] de uma versão ([^3.5.22]) permite que o [npm] instale uma versão mais recente da mesma versão principal (3.x.y); o prefixo [~] ([~11.3.2]) permite apenas correções (11.3.x). A versão do [vue-i18n] está propositalmente travada na série 11.3: as versões seguintes exigem o [Node.js] 22.

2.1.2. O arquivo vite.config.ts

O [Vite] é a ferramenta que executa uma aplicação [Vue.js] durante o desenvolvimento e depois a compila para produção. Sua configuração, comum a todos os exemplos:

// =========================================================================
// vite.config.ts - a configuração do Vite, compartilhada por TODOS os exemplos.
// -------------------------------------------------------------------------
// O Vite é ao mesmo tempo:
//   - um servidor de desenvolvimento (npm run dev): compila na hora os
//     arquivos .vue e .ts solicitados pelo navegador e recarrega a página
//     (ou apenas o componente modificado) a cada salvamento;
//   - uma ferramenta de build (npm run build): gera, em dist/,
//     arquivos .js e .css otimizados para colocar em um servidor web.
//
// Cada exemplo é uma pequena aplicação independente, com seu próprio
// index.html: 01-first-application/index.html, 02-reactivity/index.html...
// Um único servidor Vite atende a todos: http://localhost:5173/ exibe o
// sumário (index.html desta pasta), http://localhost:5173/01-first-application/
// o primeiro exemplo, etc.
// =========================================================================

import { existsSync, readdirSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { resolve } from 'node:path';
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

const root = fileURLToPath(new URL('.', import.meta.url));

// as pastas dos exemplos: aquelas cujo nome começa com dois dígitos
const examples = readdirSync(root).filter((d) => /^\d\d-/.test(d) && existsSync(resolve(root, d, 'index.html')));

export default defineConfig({
  // o plugin que ensina o Vite a compilar arquivos .vue
  plugins: [vue()],

  server: {
    port: 5173,
    // o PROXY: qualquer requisição do navegador para /api/... é encaminhada pelo
    // Vite ao servidor JSON do RdvMedecins (porta 8080) e a resposta volta
    // ao navegador. Para o navegador, página e API têm assim a MESMA origem
    // (http://localhost:5173): sem CORS para configurar, e o cookie do
    // token JWT trafega normalmente (veja o capítulo sobre a caixa-preta).
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },

  // npm run build: uma página HTML de entrada por exemplo, mais o sumário
  build: {
    rollupOptions: {
      input: Object.fromEntries([
        ['contents', resolve(root, 'index.html')],
        ...examples.map((d) => [d, resolve(root, d, 'index.html')]),
      ]),
    },
  },
});
  • linha 31: a extensão que instrui o [Vite] a compilar os arquivos [.vue]. Um navegador não consegue ler um arquivo [.vue]: quando ele solicita um, o [Vite] o converte na hora em um [JavaScript] padrão;
  • linha 34: a porta do servidor de desenvolvimento;
  • linhas 40–41: o proxy, que só será usado a partir do Exemplo 17: toda requisição do navegador a um endereço que comece por [/api] é encaminhada ao servidor JSON [RdvMedecins], na porta 8080. Voltaremos a isso;
  • Linhas 27 e 46–53: o [npm run build] precisa conhecer todas as páginas de entrada da aplicação. Fornecemos a ele o índice e o arquivo [index.html] de cada pasta cujo nome começa com dois dígitos.

2.1.3. Os arquivos tsconfig.json e env.d.ts

1
2
3
4
5
6
7
8
9
{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "types": ["vite/client"],
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["*/src/**/*.ts", "*/src/**/*.vue", "common/**/*.ts", "common/**/*.vue", "env.d.ts"]
}
  • Linha 2: Usamos a configuração [TypeScript] recomendada para o [Vue.js] (pacote [@vue/tsconfig]): código moderno, modo estrito, verificação de tipos no navegador (DOM);
  • Linha 4: Tipos específicos do [Vite] (como ao importar um arquivo [.css] ou [.svg] );
  • Linhas 5–7: Uma variável ou parâmetro não utilizado é reportado como erro;
  • linha 8: os arquivos a verificar: os das pastas [src] dos exemplos e da pasta [common].

O arquivo [env.d.ts] contém apenas uma diretiva, que torna visíveis no editor os mesmos tipos do [Vite] :

// os tipos específicos do Vite (importação de arquivos .css, import.meta.env...)
/// <reference types="vite/client" />

2.1.4. A página index.html

Cada exemplo tem sua própria página HTML. A página do Exemplo 01:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Example 01 - a first application</title>
</head>
<body>
  <!-- a aplicação Vue.js é exibida neste elemento (veja src/main.ts) -->
  <div id="app"></div>
  <script type="module" src="./src/main.ts"></script>
</body>
</html>

Esta é a única página que o navegador carregará. Ela é quase vazia:

  • linha 10: o elemento no qual o [Vue.js] exibirá a aplicação;
  • linha 11: o programa da aplicação. O [Vite] o compila e o envia ao navegador como [JavaScript].

2.1.5. O ponto de entrada: main.ts

// =========================================================================
// 01-first-application/src/main.ts - o ponto de entrada da aplicação
// -------------------------------------------------------------------------
// index.html carrega este arquivo (<script type="module" src="./src/main.ts">).
// Ele constrói a aplicação Vue.js a partir de seu componente RAIZ (App.vue)
// e a exibe no elemento <div id="app"> da página.
// =========================================================================

import { createApp } from 'vue';
// a folha de estilo do Bootstrap: o Vite a insere na página
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App.vue';

// createApp(App): uma aplicação cujo componente raiz é App;
// mount('#app'): sua renderização HTML substitui o conteúdo de <div id="app">
createApp(App).mount('#app');
  • Linha 9: a função do [Vue.js] que cria uma aplicação;
  • linha 11: uma folha de estilo, [CSS], é importada como se fosse um módulo. O [Vite] a insere na página;
  • linha 12: o componente raiz da aplicação, definido no arquivo [App.vue];
  • linha 16: a aplicação é criada a partir desse componente e depois “montada” no elemento [<div id="app">]: o HTML produzido por [App.vue] substitui o conteúdo dele.

2.1.6. O componente raiz: App.vue

<!--
  =========================================================================
  01-first-application/src/App.vue - a first component
  -------------------------------------------------------------------------
  A .vue file (Single File Component) groups the three facets of a
  component:
    - <script setup>: the data and the code of the component (TypeScript);
    - <template>    : the HTML to display, with {{ ... }};
    - <style>       : its CSS (here "scoped": it only applies to it).
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';

// dados "comuns": o template pode exibi-los
const title = 'Welcome to Vue.js';
const languages = ['TypeScript', 'HTML', 'CSS'];

// ref(...): um dado REATIVO. Quando seu valor (.value) muda, o Vue
// atualiza AUTOMATICAMENTE os pontos da página que o exibem
const counter = ref(0);
const time = ref(new Date().toLocaleTimeString());

// uma função chamada pelo botão do template
function increment(): void {
  counter.value++;
  time.value = new Date().toLocaleTimeString();
}
</script>

<template>
  <div class="container py-4">
    <!-- {{ expression }}: o valor da expressão, inserido na página -->
    <h1 class="h3">{{ title }}</h1>
    <p>This page is built in the browser, by Vue.js, from three files: index.html, main.ts and App.vue.</p>
    <p>It is written in {{ languages.join(', ') }} ({{ languages.length }} languages).</p>

    <!-- @click: a função a chamar em um clique (veja o exemplo 04) -->
    <button class="btn btn-primary" @click="increment">Click me</button>
    <!-- no template, sem .value: o Vue "desembrulha" os refs sozinho -->
    <p class="mt-3 counter">You clicked {{ counter }} times (last click: {{ time }}).</p>
  </div>
</template>

<style scoped>
/* "scoped": esta regra se aplica apenas aos elementos DESTE componente */
.counter {
  font-weight: bold;
  color: #0d6efd;
}
</style>

Um arquivo [.vue] (Single File Component, ou SFC) reúne as três facetas de um componente:

  • linhas 12–29: o código do componente, em [TypeScript] ([lang="ts"]). Com [setup], todas as variáveis e funções declaradas no nível superior do script ficam diretamente utilizáveis no template;
    • linhas 16–17: dois dados comuns;
    • linha 21: [ref(0)] cria um dado reativo com valor inicial 0. Seu valor é lido e modificado por meio de sua propriedade [value]. Quando ele muda, o [Vue.js] atualiza todos os pontos da página em que ele é exibido;
    • linhas 25–27: uma função que modifica dois dados reativos. Ela não altera a página: o [Vue.js] se encarrega de atualizá-la;
  • linhas 31–43: o HTML do componente:
    • linha 34: a sintaxe [{{ expression }}] (os “bigodes”) insere na página o valor de uma expressão [TypeScript]. Ela é escapada: se [title] contivesse [<b>], [<b>] seria exibido sem que a tag fosse interpretada;
    • linha 36: a expressão pode ser qualquer coisa: uma chamada de método, um cálculo;
    • linha 39: o clique no botão chama a função [increment] (veja o exemplo 04);
    • linha 41: no template, escreve-se [counter], não [counter.value]: o [Vue.js] “desembrulha” automaticamente o [ref];
  • linhas 45–51: o CSS do componente. Com [scoped], suas regras se aplicam apenas aos elementos deste componente: o [Vite] adiciona um atributo único aos elementos dele ([data-v-xxxx]) e o inclui nos seletores.

2.1.7. Execução

Com o servidor [Vite] em execução ([npm run dev]), abra a URL http://localhost:5173/01-first-application/ e clique no botão três vezes:

Image

Dois experimentos para fazer:

  • Edite o texto do título em [App.vue] e salve o arquivo: a página é atualizada imediatamente, sem recarregar, e o contador mantém seu valor. É a troca a quente de módulos (HMR, [Hot Module Replacement]) do [Vite];
  • Veja o código-fonte da página (Ctrl-U): ele contém apenas a página [index.html], quase vazia. O HTML exibido foi gerado pelo [Vue.js] dentro do navegador. Para vê-lo, use o inspetor das ferramentas de desenvolvedor (F12, aba Elements) ou a extensão [Vue.js devtools], que também exibe os componentes e seus dados.

2.2. Exemplo 02: Reatividade

A reatividade está no coração do [Vue.js]. Este exemplo calcula o preço com IVA de um item:

<!--
  =========================================================================
  02-reactivity/src/App.vue - ref, reactive, computed, watch
  -------------------------------------------------------------------------
  A small calculator of prices including VAT:
    - ref      : a simple reactive value (a number, a string...);
    - reactive : a reactive OBJECT (all its properties are reactive);
    - computed : a value COMPUTED from other ones, recomputed
                 automatically when they change;
    - watch    : code executed when a value changes (an "effect").
  =========================================================================
-->
<script setup lang="ts">
import { computed, reactive, ref, watch } from 'vue';

// ref: seu valor é lido e escrito por meio de .value (no código TypeScript)
const quantity = ref(1);

// reactive: um objeto, cujas propriedades são lidas e escritas diretamente
const item = reactive({
  label: 'Pen',
  priceExclVat: 2.5,
  vatRate: 20, // em %
});

// computed: nunca atribuído diretamente, sempre recalculado. O Vue sabe de quais
// dados ele depende (quantity, item.priceExclVat, item.vatRate):
// ele o recalcula quando um deles muda, e somente nesse caso
const totalExclVat = computed(() => quantity.value * item.priceExclVat);
const vatAmount = computed(() => (totalExclVat.value * item.vatRate) / 100);
const totalInclVat = computed(() => totalExclVat.value + vatAmount.value);

// um formatador de valores em euros, no estilo inglês (€1,234.50)
const euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });

// watch: a cada mudança do total com impostos, guardamos um registro
const history = ref<string[]>([]);
watch(totalInclVat, (newValue, oldValue) => {
  history.value.unshift(`${euros.format(oldValue)} -> ${euros.format(newValue)}`);
  history.value = history.value.slice(0, 5); // os 5 últimos
});

function reset(): void {
  quantity.value = 1;
  item.priceExclVat = 2.5;
  item.vatRate = 20;
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 02 - reactivity</h1>
    <div class="row g-4">
      <div class="col-md-6">
        <div class="card p-3">
          <!-- v-model vincula um campo a um dado, nos dois sentidos (veja o exemplo 05) -->
          <label class="form-label">Item</label>
          <input v-model="item.label" class="form-control mb-2">
          <label class="form-label">Unit price excl. VAT</label>
          <input v-model.number="item.priceExclVat" type="number" step="0.1" min="0" class="form-control mb-2">
          <label class="form-label">Quantity</label>
          <input v-model.number="quantity" type="number" min="0" class="form-control mb-2">
          <label class="form-label">VAT rate</label>
          <select v-model.number="item.vatRate" class="form-select mb-3">
            <option :value="5.5">5.5 %</option>
            <option :value="10">10 %</option>
            <option :value="20">20 %</option>
          </select>
          <button class="btn btn-outline-secondary" @click="reset">Reset</button>
        </div>
      </div>
      <div class="col-md-6">
        <div class="card p-3">
          <h2 class="h5">{{ quantity }} x {{ item.label }}</h2>
          <table class="table mb-0">
            <tbody>
              <tr><td>Total excl. VAT</td><td class="text-end">{{ euros.format(totalExclVat) }}</td></tr>
              <tr><td>VAT ({{ item.vatRate }} %)</td><td class="text-end">{{ euros.format(vatAmount) }}</td></tr>
              <tr class="fw-bold"><td>Total incl. VAT</td><td class="text-end">{{ euros.format(totalInclVat) }}</td></tr>
            </tbody>
          </table>
        </div>
        <div class="card p-3 mt-3">
          <h2 class="h6">History of the total incl. VAT (watch)</h2>
          <ul class="mb-0">
            <li v-for="(line, i) in history" :key="i">{{ line }}</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</template>
  • linha 17: [ref] aceita um valor simples (número, string, booleano);
  • linhas 20–24: [reactive] torna reativo um objeto inteiro: cada uma de suas propriedades é reativa. Elas são lidas e escritas diretamente ([item.priceExclVat]), sem [.value];
  • linhas 29–31: [computed] define um valor calculado a partir de outros valores. O [Vue.js] memoriza os dados lidos durante o cálculo ([quantity], [item.priceExclVat]...) e só recalcula quando um deles muda. Nunca se atribui um valor a ele: ele é lido ([totalExclVat.value]);
  • linha 34: [Intl.NumberFormat], a ferramenta de formatação de números integrada ao [JavaScript]: [2.5] torna-se “€2.50”;
  • linhas 38–41: [watch] executa código sempre que um dado muda, recebendo o novo valor e o antigo. Ele serve para ações como salvar dados, enviar uma requisição ou escrever no armazenamento do navegador... Para exibir um valor derivado, preferimos o [computed];
  • linhas 43–46: basta modificar os dados; todos os campos, totais e o histórico são atualizados de acordo;
  • linhas 58–64: [v-model] liga cada campo a um dado, nos dois sentidos (veja o exemplo 05);
  • linha 77: no template, um [computed] é usado da mesma forma que um [ref], sem [.value];
  • linha 86: uma lista repetida para cada elemento do array [history] (veja o exemplo 03).

Image

2.3. Exemplo 03: Diretivas

Uma diretiva é um atributo especial do template, prefixado por [v-], que define o comportamento do elemento ao qual é aplicada.

<!--
  =========================================================================
  03-directives/src/App.vue - the basic directives
  -------------------------------------------------------------------------
  A DIRECTIVE is a special attribute of the template, prefixed by v-:
    - v-bind:attr="expr" (short form :attr="expr"): the value of an HTML
      attribute computed by an expression; :class and :style accept
      objects and arrays;
    - v-if / v-else-if / v-else: the element only exists in the page if
      the condition is true;
    - v-show: the element always exists, it is only hidden (display:none);
    - v-for="x in list": the element is repeated for each x, with a
      unique :key that allows Vue to follow each row.
  =========================================================================
-->
<script setup lang="ts">
import { computed, ref } from 'vue';
// importação de uma imagem: o Vite fornece sua URL (e, em produção, uma
// cópia otimizada do arquivo, com um nome único)
import logoUrl from './assets/doctor.svg';

// uma interface TypeScript descreve a forma dos objetos da lista
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: string;
  available: boolean;
}

const doctors = ref<Doctor[]>([
  { id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true },
  { id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false },
  { id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner', available: true },
]);

const filter = ref(''); // texto pesquisado
const onlyAvailable = ref(false);
const showHelp = ref(true);

// a lista exibida: um computed, recalculado quando o filtro muda
const displayedDoctors = computed(() =>
  doctors.value.filter(
    (m) =>
      (!onlyAvailable.value || m.available) &&
      `${m.firstName} ${m.lastName} ${m.specialty}`.toLowerCase().includes(filter.value.trim().toLowerCase()),
  ),
);
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">
      <!-- :src: o valor do atributo src é o da variável logoUrl -->
      <img :src="logoUrl" alt="logo" width="32" height="32">
      Example 03 - directives
    </h1>

    <div class="d-flex flex-wrap gap-3 align-items-center mb-3">
      <input v-model="filter" class="form-control w-auto" placeholder="search...">
      <label class="form-check-label">
        <input v-model="onlyAvailable" type="checkbox" class="form-check-input"> available only
      </label>
      <button class="btn btn-sm btn-outline-secondary" @click="showHelp = !showHelp">
        {{ showHelp ? "Hide help" : "Show help" }}
      </button>
    </div>

    <!-- v-show: o parágrafo permanece na página, apenas oculto -->
    <p v-show="showHelp" class="alert alert-info">
      Type a name or a specialty. Unavailable doctors are greyed out.
    </p>

    <!-- v-if / v-else-if / v-else: apenas um dos três blocos existe por vez -->
    <p v-if="doctors.length === 0" class="text-muted">No doctors.</p>
    <p v-else-if="displayedDoctors.length === 0" class="text-warning">No doctor matches "{{ filter }}".</p>
    <table v-else class="table">
      <thead>
        <tr><th>#</th><th>Doctor</th><th>Specialty</th><th>Status</th></tr>
      </thead>
      <tbody>
        <!-- v-for: one row per doctor; (m, index) also gives the rank.
             :key="m.id": the identity of each row, so that Vue knows
             which row to add, move or remove when the list changes -->
        <tr v-for="(m, index) in displayedDoctors" :key="m.id" :class="{ 'text-muted': !m.available }">
          <td>{{ index + 1 }}</td>
          <td>{{ m.title }} {{ m.firstName }} {{ m.lastName }}</td>
          <td>{{ m.specialty }}</td>
          <td>
            <!-- :class com um array: várias classes, uma delas calculada -->
            <span :class="['badge', m.available ? 'text-bg-success' : 'text-bg-secondary']">
              {{ m.available ? 'available' : 'unavailable' }}
            </span>
          </td>
        </tr>
      </tbody>
    </table>

    <!-- :style com um objeto: propriedades CSS calculadas -->
    <p :style="{ fontSize: 12 + displayedDoctors.length * 2 + 'px' }">
      {{ displayedDoctors.length }} doctor(s) displayed - the size of this text depends on it.
    </p>
  </div>
</template>
  • Linha 23: Uma interface [TypeScript] descreve o formato dos objetos da lista; [ref<Doctor[]>(...)] especifica o tipo do dado;
  • linha 20: uma imagem é importada como módulo. O [Vite] fornece seu endereço; em produção, ele criará uma cópia com nome único (que muda com o conteúdo: os navegadores nunca manterão uma versão antiga no cache);
  • linha 43: a lista exibida, filtrada pelo campo de entrada e pela caixa de seleção;
  • linha 56: [v-bind:src="expression"], abreviado como [:src="expression"], atribui o valor de uma expressão ao atributo [src]. Sem os dois-pontos, [src="logoUrl"] designaria um arquivo chamado “logoUrl”;
  • linha 71: [v-show] oculta o elemento ([display: none]) quando a condição é falsa. O elemento continua na página;
  • Linhas 76–78: [v-if], [v-else-if], e [v-else]: apenas um desses três elementos existe na página a cada momento. Escolhemos [v-show] para um elemento que é exibido e ocultado com frequência, e [v-if] nos demais casos;
  • Linha 86: [v-for] repete o elemento para cada médico; [index] é a posição dele (começando em 0). O atributo [:key="m.id"] dá a cada linha uma identidade: quando a lista muda, o [Vue.js] sabe quais linhas adicionar, excluir ou mover, em vez de reconstruir tudo do zero. Uma chave deve ser única e estável: usamos o identificador do objeto, nunca sua posição;
  • linha 86: [:class] com um objeto: a classe [text-muted] é adicionada se a condição for verdadeira;
  • linha 92: [:class] com um array: várias classes, entre elas uma calculada;
  • linha 101: [:style] com um objeto de propriedades [CSS] calculadas (em [camelCase]).

Image

Com um filtro que não retorna resultados, o parágrafo [v-else-if] é exibido:

Image

2.4. Exemplo 04: Eventos

<!--
  =========================================================================
  04-events/src/App.vue - reacting to the user's actions
  -------------------------------------------------------------------------
  v-on:event="handler" (short form @event="handler"):
    - @click="f"          calls f(nativeEvent);
    - @click="f(3, $event)" calls f with arguments; $event is
                          the native event of the browser;
    - modifiers: @submit.prevent (prevents the classic submission of the
      form), @keyup.enter (only the Enter key), @click.stop...
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';

interface Task {
  id: number;
  label: string;
  done: boolean;
}

const tasks = ref<Task[]>([
  { id: 1, label: 'Install Node.js', done: true },
  { id: 2, label: 'Read the chapter on events', done: false },
]);
const newTask = ref('');
const log = ref<string[]>([]);
let nextId = 3;

function trace(message: string): void {
  log.value.unshift(`${new Date().toLocaleTimeString()} ${message}`);
}

// chamado por @submit.prevent: o navegador NÃO envia o formulário ao
// servidor (sem recarregar a página), é o nosso código que age
function add(): void {
  const label = newTask.value.trim();
  if (label === '') {
    return;
  }
  tasks.value.push({ id: nextId++, label, done: false });
  trace(`added "${label}"`);
  newTask.value = '';
}

function remove(task: Task): void {
  tasks.value = tasks.value.filter((t) => t.id !== task.id);
  trace(`removed "${task.label}"`);
}

// $event: o evento nativo (aqui um MouseEvent), com suas coordenadas
function position(event: MouseEvent): void {
  trace(`click at (${event.offsetX}, ${event.offsetY})`);
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 04 - events</h1>

    <!-- @submit.prevent: Enter no campo OU clique no botão -->
    <form class="d-flex gap-2 mb-3" @submit.prevent="add">
      <input v-model="newTask" class="form-control" placeholder="new task" @keyup.esc="newTask = ''">
      <button type="submit" class="btn btn-primary">Add</button>
    </form>

    <ul class="list-group mb-3">
      <li v-for="t in tasks" :key="t.id" class="list-group-item d-flex align-items-center gap-2">
        <input v-model="t.done" type="checkbox" class="form-check-input" @change="trace(`“${t.label}”: ${t.done ? 'done' : 'to do'}`)">
        <span :class="{ 'text-decoration-line-through text-muted': t.done }" class="flex-grow-1">{{ t.label }}</span>
        <!-- um handler com um argumento: a tarefa DESTA linha -->
        <button class="btn btn-sm btn-outline-danger" @click="remove(t)">Delete</button>
      </li>
    </ul>

    <div class="area p-3 mb-3 rounded" @click="position($event)">Click in this area</div>

    <h2 class="h6">Log</h2>
    <ul class="small">
      <li v-for="(line, i) in log" :key="i">{{ line }}</li>
    </ul>
  </div>
</template>

<style scoped>
.area {
  background: #e9f2ff;
  height: 80px;
  cursor: crosshair;
}
</style>
  • Linha 62: [v-on:submit], abreviado como [@submit], escuta o evento [submit] do formulário (pressionar Enter em um campo ou clicar em um botão). O modificador [.prevent] chama [event.preventDefault()]: o navegador NÃO envia o formulário ao servidor e não recarrega a página; a função [add] é que é executada;
  • linha 63: um modificador de tecla: apenas pressionar Esc aciona o handler. É uma instrução simples escrita no template;
  • linha 69: um handler pode ser uma chamada de função com argumentos;
  • linha 72: cada botão passa SUA tarefa para [remove];
  • linha 76: [$event] designa o evento nativo do navegador — aqui, um [MouseEvent] — com as coordenadas do clique;
  • linhas 36–43: adicionar uma tarefa significa adicionar um objeto ao array reativo; limpar o campo significa limpar o dado ao qual ele está ligado;
  • linhas 46–47: o array é substituído por uma cópia filtrada. O [Vue.js] acompanha tanto as modificações “no local” ([push], [splice]) quanto a substituição completa.

Image

2.5. Exemplo 05: Campos de formulário

Mesmo formulário do Exemplo 18 do curso [NestJS], mas aqui tudo acontece no navegador:

<!--
  =========================================================================
  05-forms/src/App.vue - all the field types, linked by v-model
  -------------------------------------------------------------------------
  v-model="data" links a form field to a reactive piece of data, in
  BOTH directions: typing in the field modifies the data, and modifying the
  data (by code) modifies the field. The data received depends on the field:
    - text input, textarea              -> string
    - input + .number                   -> number
    - single checkbox                   -> boolean
    - checkboxes on the same array      -> string[] (the checked values)
    - radio buttons                     -> the value of the chosen button
    - select / select multiple          -> the value / an array of values
    - input type="date"                 -> string "yyyy-MM-dd"
  Modifiers: .trim (spaces removed), .number, .lazy (update when
  leaving the field rather than on each key).
  Same form as example 18 of the NestJS course; but here, no
  server: everything happens in the browser.
  =========================================================================
-->
<script setup lang="ts">
import { reactive, ref } from 'vue';

const titles = ['Mr', 'Mme', 'Melle'];
const possibleHobbies = ['sport', 'music', 'reading', 'cinema'];
const countries = [
  { code: 'fr', name: 'France' },
  { code: 'be', name: 'Belgium' },
  { code: 'ch', name: 'Switzerland' },
];

// todos os valores do formulário, em UM único objeto reativo
const form = reactive({
  title: 'Mme',
  name: '',
  age: 30,
  presentation: '',
  newsletter: false,
  hobbies: ['reading'] as string[],
  country: 'fr',
  languages: [] as string[],
  birthDate: '',
});

const sent = ref<string | null>(null);

function send(): void {
  // JSON.stringify: o que enviaríamos a um servidor (veja o exemplo 18)
  sent.value = JSON.stringify(form, null, 2);
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 05 - the fields of a form</h1>
    <div class="row g-4">
      <form class="col-md-7" @submit.prevent="send">
        <div class="mb-3">
          <span class="form-label d-block">Title</span>
          <!-- botões de opção (radio): mesmo v-model, um valor por botão -->
          <div v-for="t in titles" :key="t" class="form-check form-check-inline">
            <input :id="'title-' + t" v-model="form.title" type="radio" :value="t" class="form-check-input">
            <label :for="'title-' + t" class="form-check-label">{{ t }}</label>
          </div>
        </div>
        <div class="row g-3 mb-3">
          <div class="col-8">
            <label class="form-label" for="name">Name</label>
            <!-- .trim: " martin " vira "martin" -->
            <input id="name" v-model.trim="form.name" class="form-control">
          </div>
          <div class="col-4">
            <label class="form-label" for="age">Age</label>
            <!-- .number: o dado recebe um número, não a string "30" -->
            <input id="age" v-model.number="form.age" type="number" class="form-control">
          </div>
        </div>
        <div class="mb-3">
          <label class="form-label" for="presentation">About you</label>
          <textarea id="presentation" v-model="form.presentation" rows="2" class="form-control"></textarea>
        </div>
        <div class="mb-3 form-check">
          <!-- um único checkbox: true / false -->
          <input id="newsletter" v-model="form.newsletter" type="checkbox" class="form-check-input">
          <label for="newsletter" class="form-check-label">Receive the newsletter</label>
        </div>
        <div class="mb-3">
          <span class="form-label d-block">Hobbies</span>
          <!-- vários checkboxes no mesmo array: os valores marcados -->
          <div v-for="h in possibleHobbies" :key="h" class="form-check form-check-inline">
            <input :id="'hobby-' + h" v-model="form.hobbies" type="checkbox" :value="h" class="form-check-input">
            <label :for="'hobby-' + h" class="form-check-label">{{ h }}</label>
          </div>
        </div>
        <div class="row g-3 mb-3">
          <div class="col-6">
            <label class="form-label" for="country">Country</label>
            <select id="country" v-model="form.country" class="form-select">
              <!-- :value: o valor transmitido (o código), sendo o texto exibido o nome -->
              <option v-for="c in countries" :key="c.code" :value="c.code">{{ c.name }}</option>
            </select>
          </div>
          <div class="col-6">
            <label class="form-label" for="languages">Spoken languages</label>
            <select id="languages" v-model="form.languages" multiple class="form-select" size="3">
              <option value="fr">French</option>
              <option value="en">English</option>
              <option value="es">Spanish</option>
            </select>
          </div>
        </div>
        <div class="mb-3">
          <label class="form-label" for="birthDate">Date of birth</label>
          <input id="birthDate" v-model="form.birthDate" type="date" class="form-control w-auto">
        </div>
        <button type="submit" class="btn btn-primary">Send</button>
      </form>

      <div class="col-md-5">
        <h2 class="h6">The model, live</h2>
        <!-- {{ object }} exibe o objeto em formato JSON -->
        <pre class="bg-light p-2 rounded small">{{ form }}</pre>
        <template v-if="sent">
          <h2 class="h6">Last submission</h2>
          <pre class="bg-success-subtle p-2 rounded small">{{ sent }}</pre>
        </template>
      </div>
    </div>
  </div>
</template>
  • Linhas 33–43: todos os valores do formulário, em um objeto reativo. As anotações [as string[]] indicam ao [TypeScript] o tipo dos arrays, que não pode ser inferido a partir de [[]];
  • linha 62: os botões de opção compartilham o mesmo [v-model]; o dado recebe o valor ([:value]) do botão selecionado;
  • linha 70: o modificador [.trim] remove os espaços no início e no fim;
  • linha 75: [.number] converte a entrada em número. Sem ele, o dado seria definido como a string ["30"]: um campo HTML contém apenas texto;
  • linha 84: uma caixa de seleção sozinha retorna um valor booleano;
  • Linha 91: várias caixas de seleção ligadas ao mesmo array: ele contém os valores das caixas marcadas;
  • linha 100: em uma lista suspensa, [:value] é o valor transmitido (o código do país); o texto da opção é apenas seu rótulo;
  • linha 105: uma lista de múltipla escolha resulta em um array;
  • linha 114: um campo de data retorna uma string ["yyyy-MM-dd"], independentemente de como o navegador a exiba;
  • linha 122: [{{ object }}] exibe um objeto no formato JSON: dá para ver o template mudar a cada tecla digitada;
  • linha 49: [JSON.stringify(form, null, 2)] gera o texto JSON de um objeto, indentado com 2 espaços. É isso que seria enviado a um servidor (veja o Exemplo 18).

Image

2.6. Exemplo 06: Validação de formulário

Usaremos as regras do formulário “Criar uma conta de paciente” do servidor [RdvMedecins] e as verificaremos no navegador enquanto o usuário digita:

<!--
  =========================================================================
  06-validation/src/App.vue - validating a form in the browser
  -------------------------------------------------------------------------
  The errors are COMPUTED values: they are recomputed on each keystroke.
  They are not displayed right away (an empty form covered in red is
  unpleasant): only for a field already left ("touched"), or for
  all the fields after a submission attempt.

  Same rules as the RdvMedecins server ("Create a patient account" form):
  title in the list, first name and last name required (20 characters at most),
  login in lower case, password of at least 6 characters, confirmation.

  WARNING: this validation is only a COMFORT for the user (an
  immediate answer, without a round trip to the server). It protects
  nothing: anyone can send the server a request built by
  hand (curl...). The server therefore ALWAYS revalidates everything (see example 20).
  =========================================================================
-->
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';

const TITLES = ['Mr', 'Mme', 'Melle'];
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
const PASSWORD_MIN = 6;

type Field = 'title' | 'firstName' | 'lastName' | 'login' | 'password' | 'confirmation';

const input = reactive<Record<Field, string>>({
  title: 'Mr',
  firstName: '',
  lastName: '',
  login: '',
  password: '',
  confirmation: '',
});

// os campos já abandonados pelo usuário (evento blur)
const touched = reactive(new Set<Field>());
const submitAttempted = ref(false);
const success = ref(false);

// o erro de cada campo ('' = sem erro), recalculado a cada tecla digitada
const errors = computed<Record<Field, string>>(() => ({
  title: TITLES.includes(input.title) ? '' : 'Choose a title from the list.',
  firstName: required(input.firstName, 'The first name') || maximum(input.firstName, 'The first name', 20),
  lastName: required(input.lastName, 'The last name') || maximum(input.lastName, 'The last name', 20),
  login:
    required(input.login, 'The login') ||
    (LOGIN_FORMAT.test(input.login.trim())
      ? ''
      : 'Unaccented lower-case letters, digits, dot, hyphen, underscore.'),
  password:
    required(input.password, 'The password') ||
    (input.password.length < PASSWORD_MIN ? `At least ${PASSWORD_MIN} characters.` : ''),
  confirmation: input.confirmation === input.password ? '' : 'The confirmation does not match the password.',
}));

const formValid = computed(() => Object.values(errors.value).every((e) => e === ''));

function required(value: string, name: string): string {
  return value.trim() === '' ? `${name} is required.` : '';
}
function maximum(value: string, name: string, max: number): string {
  return value.trim().length > max ? `${name} must not exceed ${max} characters.` : '';
}

// o erro a EXIBIR para um campo: somente se ele foi tocado, ou após
// uma tentativa de envio
function visibleError(field: Field): string {
  return touched.has(field) || submitAttempted.value ? errors.value[field] : '';
}

function send(): void {
  submitAttempted.value = true;
  success.value = formValid.value;
}
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 06 - form validation</h1>
    <!-- novalidate: the browser's own validation is disabled, to
         display OUR messages, in OUR style -->
    <form class="card p-4" novalidate @submit.prevent="send">
      <div class="mb-3">
        <label class="form-label" for="title">Title</label>
        <select id="title" v-model="input.title" class="form-select" :class="{ 'is-invalid': visibleError('title') }">
          <option v-for="t in TITLES" :key="t">{{ t }}</option>
        </select>
      </div>
      <div class="row g-3 mb-3">
        <div class="col-sm-6">
          <label class="form-label" for="firstName">First name</label>
          <!-- @blur: the user leaves the field, which becomes "touched";
               the Bootstrap class is-invalid frames it in red and makes
               the following .invalid-feedback appear -->
          <input id="firstName" v-model="input.firstName" class="form-control"
                 :class="{ 'is-invalid': visibleError('firstName') }" @blur="touched.add('firstName')">
          <div class="invalid-feedback">{{ visibleError('firstName') }}</div>
        </div>
        <div class="col-sm-6">
          <label class="form-label" for="lastName">Last name</label>
          <input id="lastName" v-model="input.lastName" class="form-control"
                 :class="{ 'is-invalid': visibleError('lastName') }" @blur="touched.add('lastName')">
          <div class="invalid-feedback">{{ visibleError('lastName') }}</div>
        </div>
      </div>
      <div class="mb-3">
        <label class="form-label" for="login">Login</label>
        <input id="login" v-model="input.login" class="form-control" autocomplete="username"
               :class="{ 'is-invalid': visibleError('login'), 'is-valid': touched.has('login') && !errors.login }"
               @blur="touched.add('login')">
        <div class="invalid-feedback">{{ visibleError('login') }}</div>
      </div>
      <div class="row g-3 mb-4">
        <div class="col-sm-6">
          <label class="form-label" for="password">Password</label>
          <input id="password" v-model="input.password" type="password" class="form-control" autocomplete="new-password"
                 :class="{ 'is-invalid': visibleError('password') }" @blur="touched.add('password')">
          <div class="invalid-feedback">{{ visibleError('password') }}</div>
        </div>
        <div class="col-sm-6">
          <label class="form-label" for="confirmation">Confirmation</label>
          <input id="confirmation" v-model="input.confirmation" type="password" class="form-control" autocomplete="new-password"
                 :class="{ 'is-invalid': visibleError('confirmation') }" @blur="touched.add('confirmation')">
          <div class="invalid-feedback">{{ visibleError('confirmation') }}</div>
        </div>
      </div>
      <button type="submit" class="btn btn-primary">Create the account</button>
      <div v-if="submitAttempted && !formValid" class="alert alert-danger mt-3 mb-0">The form contains errors.</div>
      <div v-if="success" class="alert alert-success mt-3 mb-0">Valid form: it could be sent to the server.</div>
    </form>
  </div>
</template>
  • Linha 27: o tipo dos nomes dos campos. [Record<Field, string>] é um objeto com exatamente essas propriedades: um erro de digitação no nome de um campo seria detectado em tempo de compilação;
  • linha 39: os campos que o usuário já deixou. Um [Set] reativo: [touched.add(...)] atualiza a página;
  • linhas 44–57: os erros dos campos, recalculados a cada tecla digitada. Uma string vazia significa “nenhum erro”; [a || b] retorna [b] quando [a] está vazio: isso permite encadear as verificações de um campo, com a primeira que falhar acionando a mensagem;
  • linha 59: verdadeiro se não houver erros;
  • linhas 70–72: o erro de um campo só é exibido se ele foi “tocado” ou após uma tentativa de envio. Um formulário em branco destacado em vermelho antes mesmo de você começar seria desagradável;
  • linha 85: [novalidate] desativa os controles do navegador (atributo [required]...), de modo que apenas nossas mensagens sejam exibidas, em nosso estilo;
  • linha 99: o evento [blur]: o usuário sai do campo;
  • linha 99: a classe [Bootstrap] [is-invalid] contorna o campo em vermelho e exibe o [<div class="invalid-feedback">] que vem em seguida;
  • linha 112: [is-valid], ao contrário, o contorna em verde.

Depois de clicar em “Criar a conta”, o formulário fica vazio:

Image

depois, quando o formulário é preenchido corretamente:

Image

Uma observação importante: esta validação é apenas uma comodidade. Ela responde imediatamente, sem ida e volta ao servidor, mas não oferece nenhuma proteção: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente (usando o [curl], por exemplo), sem passar por nossas páginas. O servidor deve, portanto, revalidar o que recebe. No Exemplo 20, e mais adiante no estudo de caso, veremos outra abordagem: deixar o servidor cuidar da validação e exibir as mensagens.