Skip to content

3. Os componentes

Até agora, cada exemplo cabia em um único componente, [App.vue]. Uma aplicação real contém dezenas deles: uma barra de navegação, formulários, janelas... Cada componente é uma peça autônoma da interface (seu HTML, seu código, seu estilo) e é reutilizável. Este capítulo mostra como os componentes se encaixam e se comunicam.

3.1. Exemplo 07: Componentes e suas props

O exemplo exibe um cartão por médico. O cartão é um componente, [DoctorCard.vue], usado três vezes por seu pai, [App.vue].

O tipo do médico, compartilhado pelos dois componentes, fica em um arquivo [TypeScript] comum:

1
2
3
4
5
6
7
8
9
// o tipo de dados compartilhado pelo pai (App.vue) e pelo filho (DoctorCard.vue)
export interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: string;
  available: boolean;
}

O componente filho:

<!--
  =========================================================================
  07-components/src/components/DoctorCard.vue - a CHILD component
  -------------------------------------------------------------------------
  It receives its data from its parent through PROPS (properties), declared
  with defineProps. The TypeScript type of the props is checked at
  compile time: <DoctorCard :doctor="42"> would be rejected.

  Golden rule: a component NEVER MODIFIES its props. The data
  flows down from the parent to the child ("one-way data flow"); to
  request a change, the child emits an event (see example 08).
  =========================================================================
-->
<script setup lang="ts">
import { computed } from 'vue';
import type { Doctor } from '../doctor';

// withDefaults: um valor padrão para as props opcionais (?)
const props = withDefaults(
  defineProps<{
    doctor: Doctor;
    rank: number;
    compact?: boolean;
  }>(),
  { compact: false },
);

// um computed baseado em uma prop: recalculado se o pai mudar a prop
const initials = computed(() => `${props.doctor.firstName[0]}${props.doctor.lastName[0]}`);
</script>

<template>
  <div class="card h-100" :class="{ 'border-success': doctor.available }">
    <div class="card-body d-flex gap-3 align-items-center">
      <div class="initials">{{ initials }}</div>
      <div>
        <!-- no template, as props são usadas diretamente pelo nome -->
        <h2 class="h6 mb-1">{{ rank }}. {{ doctor.title }} {{ doctor.firstName }} {{ doctor.lastName }}</h2>
        <p v-if="!compact" class="mb-0 text-muted small">{{ doctor.specialty }}</p>
      </div>
    </div>
  </div>
</template>

<style scoped>
.initials {
  width: 2.5rem;
  height: 2.5rem;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #0d6efd;
  color: white;
  font-weight: bold;
}
</style>
  • Linha 16: [import type] importa apenas um tipo: nada dessa importação permanece no [JavaScript] resultante;
  • Linhas 19–26: [defineProps<{...}>()] declara as props do componente — isto é, os dados que ele recebe de seu pai — junto com seus tipos. Uma prop seguida de [?] é opcional; [withDefaults] lhe dá um valor padrão. [defineProps] não precisa ser importado: é uma “macro” reconhecida pelo compilador de arquivos [.vue];
  • Linha 29: no script, as props são lidas pelo objeto [props]. O [computed] acompanha as props: se o pai mudar o médico atribuído, as iniciais são recalculadas;
  • linha 38: no template, as props são usadas diretamente pelo nome;
  • linha 39: uma prop pode modificar a exibição.

O pai:

<!--
  =========================================================================
  07-components/src/App.vue - the PARENT component
  -------------------------------------------------------------------------
  It imports the DoctorCard component and uses it as a new
  HTML tag, <DoctorCard>, as many times as needed: a component
  is a REUSABLE piece of interface, with its own data, its
  template and its style.
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';
// em <script setup>, um componente importado já pode ser usado no template
import DoctorCard from './components/DoctorCard.vue';
import type { Doctor } from './doctor';

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 compact = ref(false);

// o pai modifica SEUS dados: os filhos envolvidos se atualizam
function toggleAvailability(): void {
  for (const m of doctors.value) {
    m.available = !m.available;
  }
}
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 07 - components and their props</h1>
    <div class="d-flex gap-3 mb-3">
      <label class="form-check-label"><input v-model="compact" type="checkbox" class="form-check-input"> compact display</label>
      <button class="btn btn-sm btn-outline-primary" @click="toggleAvailability">Toggle availabilities</button>
    </div>
    <div class="row g-3">
      <div v-for="(m, i) in doctors" :key="m.id" class="col-md-4">
        <!-- :doctor="m" passes the OBJECT m (an expression);
             compact, without a colon, would pass the STRING "compact" -->
        <DoctorCard :doctor="m" :rank="i + 1" :compact="compact" />
      </div>
    </div>
  </div>
</template>
  • linha 14: em [<script setup>], um componente importado fica imediatamente utilizável no template, como uma nova tag;
  • linha 43: cada cartão recebe SEU médico. [:doctor="m"] (com dois-pontos) passa o valor da expressão [m]; sem os dois-pontos, seria passada a cadeia de caracteres ["m"], que o [TypeScript] rejeitaria aqui. Os nomes de tags de componentes são escritos em [PascalCase] para distingui-los das tags HTML;
  • linhas 25–29: o pai modifica SEUS dados; os cartões afetados são atualizados.

A regra de ouro: um componente nunca modifica suas próprias props. Os dados fluem do pai para o filho ([one-way data flow]): o pai é o dono deles. Para solicitar uma mudança, o filho emite um evento, que o pai processa: esse é o assunto do exemplo seguinte.

Image

3.2. Exemplo 08: Eventos de componentes e v-model

3.2.1. Disparando um evento

O componente [Counter] notifica seu pai a cada clique em seu botão:

<!--
  =========================================================================
  08-component-events/src/components/Counter.vue
  -------------------------------------------------------------------------
  A child that NOTIFIES its parent: defineEmits declares the events
  it can emit, with the type of their data. The parent listens to them
  like HTML events: <Counter @change="..." @limit="...">.
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';

const props = defineProps<{ label: string; max: number }>();

// dois eventos: 'change' (com o novo valor) e 'limit' (sem dados)
const emit = defineEmits<{
  change: [value: number];
  limit: [];
}>();

const value = ref(0);

function plus(): void {
  if (value.value >= props.max) {
    emit('limit');
    return;
  }
  value.value++;
  emit('change', value.value);
}
</script>

<template>
  <div class="d-flex align-items-center gap-2 mb-2">
    <span class="w-25">{{ label }}</span>
    <button class="btn btn-sm btn-outline-primary" @click="plus">+1</button>
    <span class="badge text-bg-secondary">{{ value }} / {{ max }}</span>
  </div>
</template>
  • Linhas 16–19: [defineEmits] declara os eventos que o componente pode disparar, junto com os tipos de seus dados: [change] carrega um número, [limit] não carrega nada;
  • Linhas 25 e 29: emissão de um evento. O [TypeScript] verifica o nome do evento e o tipo de seus dados;
  • Linha 21: o filho pode ter seu próprio estado: [value] pertence a ele, não ao pai.

3.2.2. v-model em um componente

O componente [TextField] é um campo de formulário “personalizado”: um rótulo, o campo propriamente dito, uma dica e um contador de caracteres. Queremos usá-lo com [v-model], exatamente como um [<input>] comum:

<!--
  =========================================================================
  08-component-events/src/components/TextField.vue
  -------------------------------------------------------------------------
  A "home-made" form field (label + field + help + character
  counter) that accepts v-model, like an ordinary <input>:
      <TextField v-model="lastName" label="Last name" :max="20" />

  defineModel() creates a ref linked to the parent's v-model: READING it gives the
  parent's value, WRITING it emits the 'update:modelValue' event, which the
  parent handles by updating its data. The data thus remains
  the property of the parent.
  =========================================================================
-->
<script setup lang="ts">
import { useId } from 'vue';

const model = defineModel<string>({ required: true });
defineProps<{ label: string; max: number; help?: string }>();

// um identificador único por instância, para vincular <label for> e <input id>
const id = useId();
</script>

<template>
  <div class="mb-3">
    <label class="form-label" :for="id">{{ label }}</label>
    <!-- v-model="model": o campo nativo é vinculado ao ref de defineModel -->
    <input :id="id" v-model="model" class="form-control" :maxlength="max" :class="{ 'is-invalid': model.length === max }">
    <div class="form-text">{{ help }} ({{ model.length }} / {{ max }})</div>
  </div>
</template>
  • Linha 18: [defineModel] cria um [ref] ligado ao [v-model] do pai. Lê-lo retorna o valor do pai; escrever nele dispara o evento [update:modelValue], que o pai trata modificando SEUS dados. [v-model="lastName"] em um componente é simplesmente um atalho para a propriedade [modelValue] e esse evento: o dado continua sendo propriedade do pai;
  • linha 22: [useId()] fornece um identificador único por instância de componente: as duas instâncias de [TextField] na página não terão o mesmo [id], e cada [<label for>] se refere corretamente ao SEU campo;
  • Linha 29: o campo nativo está ligado ao [ref] de [defineModel].

3.2.3. O pai

<!--
  =========================================================================
  08-component-events/src/App.vue - the parent listens to its children
  -------------------------------------------------------------------------
  Two ways for a child to pass information up:
    1. emitting an event, which the parent listens to with @ (Counter);
    2. v-model on a component (TextField): a shortcut for the prop
       modelValue + the event update:modelValue.
  =========================================================================
-->
<script setup lang="ts">
import { computed, ref } from 'vue';
import Counter from './components/Counter.vue';
import TextField from './components/TextField.vue';

const total = ref(0);
const message = ref('');
const firstName = ref('Marie');
const lastName = ref('PELISSIER');
const fullName = computed(() => `${firstName.value} ${lastName.value.toUpperCase()}`);

// o handler do evento 'change': ele recebe os dados emitidos
function onChange(label: string, value: number): void {
  total.value++;
  message.value = `${label} is now ${value}`;
}
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 08 - events and v-model on a component</h1>

    <div class="card p-3 mb-4">
      <h2 class="h6">1. Events emitted by the children</h2>
      <Counter label="Coffees" :max="3" @change="(v) => onChange('Coffees', v)" @limit="message = 'No more than 3 coffees!'" />
      <Counter label="Glasses of water" :max="8" @change="(v) => onChange(`Glasses of water`, v)" @limit="message = 'Enough drinking.'" />
      <p class="mb-0">Total clicks: {{ total }} - <em>{{ message }}</em></p>
    </div>

    <div class="card p-3">
      <h2 class="h6">2. v-model on a component</h2>
      <TextField v-model="firstName" label="First name" :max="20" help="Required" />
      <TextField v-model="lastName" label="Last name" :max="20" help="Displayed in upper case" />
      <p class="mb-0">Data of the parent: <strong>{{ fullName }}</strong></p>
      <button class="btn btn-sm btn-outline-secondary mt-2 align-self-start" @click="firstName = ''; lastName = ''">Clear (from the parent)</button>
    </div>
  </div>
</template>
  • Linha 35: o pai escuta os eventos de seus filhos com [@], exatamente como os eventos HTML. A arrow function [(v) => onChange('Coffees', v)] recebe os dados do evento; [@limit] executa uma única instrução;
  • linha 42: [v-model] em um componente;
  • linha 45: quando o PAI esvazia seus dados, os campos o acompanham: a ligação funciona nos dois sentidos.

Image

3.3. Exemplo 09: Templates e slots

As props passam dados; os slots passam conteúdo: HTML, outros componentes. O componente [Card] define a moldura (borda, cabeçalho, rodapé), e seu pai determina o que vai dentro dela:

<!--
  =========================================================================
  09-slots/src/components/Card.vue - a reusable TEMPLATE
  -------------------------------------------------------------------------
  Props pass DATA; slots pass CONTENT
  (HTML, other components). Card sets the frame (border, header,
  footer), the parent provides what goes inside:
    - <slot />              the default slot: the "main" content;
    - <slot name="header">  a named slot, filled by <template #header>;
    - the text placed BETWEEN <slot> and </slot> is displayed if the parent
      provides nothing (default content).
  It is the client-side equivalent of the layout.hbs template and its {{{body}}}
  in the NestJS course.
  =========================================================================
-->
<script setup lang="ts">
defineProps<{ color?: 'primary' | 'success' | 'danger' }>();
</script>

<template>
  <div class="card mb-3" :class="color ? `border-${color}` : ''">
    <div class="card-header" :class="color ? `text-bg-${color}` : ''">
      <slot name="header">Untitled</slot>
    </div>
    <div class="card-body">
      <slot />
    </div>
    <!-- $slots.footer: o pai forneceu um footer? Se não, nenhum <div> vazio -->
    <div v-if="$slots.footer" class="card-footer text-muted small">
      <slot name="footer" />
    </div>
  </div>
</template>
  • linha 23: um slot nomeado; o texto entre [<slot>] e [</slot>] é exibido se o pai não fornecer nada;
  • linha 26: o slot padrão: o conteúdo “principal”;
  • linha 29: [$slots] indica quais slots o pai preencheu: sem rodapé, não há [<div>] vazio.

Este é o equivalente, no lado do cliente, do template [layout.hbs] e de seu [{{{body}}}] no curso [NestJS].

Um segundo componente, [DataTable], exibe linhas de qualquer tipo:

<!--
  =========================================================================
  09-slots/src/components/DataTable.vue - a GENERIC table, with a "scoped" slot
  -------------------------------------------------------------------------
  generic="T": a generic component, like a generic TypeScript
  class - it displays rows of any type T.

  The table knows how to iterate over the rows, but not how to display a
  row: it PASSES each row to its slot (<slot name="row" :row="l">),
  and it is the parent that says what to do with it (<template #row="{ row }">).
  This is called a "scoped" slot: the content provided by the parent uses
  data that belongs to the child.
  =========================================================================
-->
<script setup lang="ts" generic="T extends { id: number }">
defineProps<{ rows: T[]; columns: string[] }>();
</script>

<template>
  <table class="table table-sm align-middle mb-0">
    <thead>
      <tr><th v-for="c in columns" :key="c">{{ c }}</th></tr>
    </thead>
    <tbody>
      <tr v-for="(l, i) in rows" :key="l.id">
        <slot name="row" :row="l" :index="i" />
      </tr>
      <tr v-if="rows.length === 0">
        <td :colspan="columns.length" class="text-muted"><slot name="empty">No data.</slot></td>
      </tr>
    </tbody>
  </table>
</template>
  • linha 15: um componente genérico, como uma classe genérica [TypeScript]: [T] é o tipo das linhas, das quais só uma propriedade é exigida: [id] (para a chave do [v-for]);
  • Linha 26: a tabela sabe percorrer as linhas, mas não sabe como exibir uma linha. Ela passa cada linha ao seu slot, e o pai a exibe. Isso é chamado de slot “com escopo” (scoped slot): o conteúdo fornecido pelo pai usa dados que pertencem ao filho.

O pai:

<!--
  =========================================================================
  09-slots/src/App.vue - using the Card and DataTable templates
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';
import Card from './components/Card.vue';
import DataTable from './components/DataTable.vue';

interface Slot {
  id: number;
  time: string;
  patient: string | null;
}

const slots = ref<Slot[]>([
  { id: 1, time: '8:00 - 8:20', patient: null },
  { id: 2, time: '8:20 - 8:40', patient: 'Mme Alice DURAND' },
  { id: 3, time: '8:40 - 9:00', patient: null },
]);
</script>

<template>
  <div class="container py-4" style="max-width: 720px">
    <h1 class="h3 mb-3">Example 09 - templates and slots</h1>

    <!-- #header é a forma curta de v-slot:header -->
    <Card color="primary">
      <template #header>Schedule of Mme PELISSIER</template>
      <!-- o slot padrão: tudo o que não está em um <template #...> -->
      <DataTable :rows="slots" :columns="['#', 'Slot', 'Status']">
        <!-- recebemos os dados passados pelo DataTable: { row, index } -->
        <template #row="{ row, index }">
          <td>{{ index + 1 }}</td>
          <td>{{ row.time }}</td>
          <td>
            <span v-if="row.patient" class="badge text-bg-secondary">{{ row.patient }}</span>
            <span v-else class="badge text-bg-success">Free</span>
          </td>
        </template>
      </DataTable>
      <template #footer>{{ slots.filter((c) => c.patient === null).length }} free slot(s)</template>
    </Card>

    <Card color="success">
      <template #header>A card without a footer</template>
      <p class="mb-0">The footer is not provided: the card does not display it.</p>
    </Card>

    <Card>
      <!-- nenhum header fornecido: o conteúdo padrão do slot, "Untitled" -->
      <DataTable :rows="[]" :columns="['Name']">
        <template #empty>Nobody for now.</template>
      </DataTable>
    </Card>
  </div>
</template>
  • linha 30: [<template #header>] (abreviação de [v-slot:header]) preenche o slot chamado [header];
  • linha 32: tudo o que não estiver em um [<template #...>] vai para o slot padrão;
  • linha 34: os dados passados pela tabela são recuperados. Graças ao componente genérico, o [TypeScript] sabe que [row] é um [Slot];
  • linha 51: um cartão sem cabeçalho: o conteúdo padrão, “Sem título”, é exibido.

Image

3.4. Exemplo 10: O ciclo de vida de um componente

Um componente é criado, exibido, atualizado e depois removido. O [Vue.js] permite executar código em cada uma dessas etapas. O componente [Clock]:

<!--
  =========================================================================
  10-lifecycle/src/components/Clock.vue
  -------------------------------------------------------------------------
  The lifecycle of a component:
    1. setup      : the code of <script setup> runs (creation);
    2. onMounted  : the component is DISPLAYED, its HTML elements exist;
    3. onUpdated  : its display has just been updated;
    4. onUnmounted: the component has been REMOVED from the page.
  A clock starts a timer (setInterval) when displayed... and must
  absolutely stop it when it disappears: otherwise the timer
  would keep running for nothing (memory leak).
  =========================================================================
-->
<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';

const emit = defineEmits<{ log: [message: string] }>();

const time = ref(new Date().toLocaleTimeString());
let timer: number | undefined;

emit('log', 'Clock: setup (creation)');

onMounted(() => {
  emit('log', 'Clock: onMounted - starting the timer');
  timer = window.setInterval(() => {
    time.value = new Date().toLocaleTimeString();
  }, 1000);
});

onUnmounted(() => {
  window.clearInterval(timer);
  emit('log', 'Clock: onUnmounted - timer stopped');
});
</script>

<template>
  <div class="display-6 font-monospace">{{ time }}</div>
</template>
  • linha 23: o código de [<script setup>] é executado uma vez quando o componente é criado;
  • linhas 25–30: [onMounted]: o componente foi exibido, e seus elementos HTML existem. O temporizador é iniciado;
  • linhas 32–35: [onUnmounted]: o componente foi removido da página. O temporizador deve ser interrompido; caso contrário, ele continuaria a executar para um componente que não existe mais (um “vazamento de memória”).

O pai:

<!--
  =========================================================================
  10-lifecycle/src/App.vue
  -------------------------------------------------------------------------
    - v-if on <Clock>: checking / unchecking the box creates / destroys the
      component (onMounted / onUnmounted, see Clock.vue);
    - a "template ref": ref="field" gives access to the HTML <input> element
      itself, once the component is displayed (to give it the focus);
    - watch with { immediate: true }: executed right away, then on each
      change;
    - nextTick: waiting for Vue to have updated the page.
  =========================================================================
-->
<script setup lang="ts">
import { nextTick, onMounted, ref, useTemplateRef, watch } from 'vue';
import Clock from './components/Clock.vue';

const withClock = ref(true);
const log = ref<string[]>([]);
const search = ref('');
const showSearch = ref(false);

// o elemento <input ref="field"> do template (null enquanto não for exibido)
const field = useTemplateRef<HTMLInputElement>('field');

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

onMounted(() => trace('App: onMounted'));

watch(
  search,
  (value) => {
    document.title = value ? `Search: ${value}` : 'Example 10';
  },
  { immediate: true },
);

async function openSearch(): Promise<void> {
  showSearch.value = true;
  // neste momento, o <input> ainda não existe: o Vue atualizará a página
  // um pouco depois. nextTick() espera por essa atualização.
  await nextTick();
  field.value?.focus();
}
</script>

<template>
  <div class="container py-4" style="max-width: 720px">
    <h1 class="h3 mb-3">Example 10 - the lifecycle of a component</h1>

    <div class="card p-3 mb-3">
      <label class="form-check-label mb-2">
        <input v-model="withClock" type="checkbox" class="form-check-input"> show the clock
      </label>
      <Clock v-if="withClock" @log="trace" />
    </div>

    <div class="card p-3 mb-3">
      <button v-if="!showSearch" class="btn btn-outline-primary align-self-start" @click="openSearch">
        Search...
      </button>
      <input v-else ref="field" v-model="search" class="form-control" placeholder="the tab title follows what you type">
    </div>

    <h2 class="h6">Log</h2>
    <ol class="small">
      <li v-for="(line, i) in log" :key="i">{{ line }}</li>
    </ol>
  </div>
</template>
  • Linha 57: marcar e desmarcar a caixa cria e destrói o relógio: o log mostra [setup], [onMounted], [onUnmounted];
  • Linha 24: uma referência de template: o [ref="field"] atributo do elemento [<input>] dá acesso ao próprio elemento HTML. Ele é igual a [null] enquanto o elemento não é exibido;
  • linhas 32–37: [watch] com [{ immediate: true }] executa imediatamente e depois a cada mudança: o título da aba é atualizado conforme o texto é digitado;
  • linhas 40–45: depois de [showSearch.value = true], o campo ainda não existe: o [Vue.js] agrupa as atualizações da página e as executa um pouco depois. [await nextTick()] espera por essa atualização; só então o foco pode ser dado ao campo.

Image

3.5. Exemplo 11: Composables, provide e inject

Como compartilhar lógica entre componentes? No lado do servidor, o [NestJS] injetava seus serviços nos controllers. O [Vue.js] tem seus composables: funções simples, cujos nomes começam por [use], que combinam estado reativo e o código que o acompanha.

// =========================================================================
// 11-composables/src/composables/useClock.ts - um COMPOSABLE
// -------------------------------------------------------------------------
// Um composable é uma função simples, cujo nome começa com "use"
// por convenção, que agrupa um estado reativo E a lógica que o acompanha
// (aqui: o temporizador, seu início e sua parada). Todo componente que
// o chama obtém o SEU próprio relógio, sem copiar o código.
//
// É a maneira do Vue.js de compartilhar lógica entre componentes - o
// papel desempenhado, no lado do servidor, pelos serviços do NestJS.
// =========================================================================

import { onMounted, onUnmounted, ref, type Ref } from 'vue';

export function useClock(periodMs = 1000): { now: Ref<Date> } {
  const now = ref(new Date());
  let timer: number | undefined;

  // os hooks de ciclo de vida se vinculam ao componente que CHAMA o composable
  onMounted(() => {
    timer = window.setInterval(() => (now.value = new Date()), periodMs);
  });
  onUnmounted(() => window.clearInterval(timer));

  return { now };
}
  • linha 15: a função retorna um objeto contendo o [ref] [now];
  • linhas 20–22: as funções de ciclo de vida chamadas dentro de um composable ficam associadas ao componente que chama o composable: cada componente tem seu próprio temporizador, que para quando o componente é destruído.

Um segundo composable, sem ciclo de vida:

// =========================================================================
// 11-composables/src/composables/useCart.ts
// -------------------------------------------------------------------------
// Um segundo composable, SEM ciclo de vida: um carrinho (lista de itens,
// total, adição, remoção). Cada chamada de useCart() cria um carrinho NOVO:
// dois componentes que o chamam têm cada um o seu.
// (Para um carrinho COMPARTILHADO por toda a aplicação, veja provide / inject
// abaixo e o Pinia no exemplo 15.)
// =========================================================================

import { computed, ref } from 'vue';

export interface Item {
  label: string;
  price: number;
}

export function useCart() {
  const items = ref<Item[]>([]);
  const total = computed(() => items.value.reduce((sum, a) => sum + a.price, 0));

  function add(item: Item): void {
    items.value.push(item);
  }
  function remove(index: number): void {
    items.value.splice(index, 1);
  }

  return { items, total, add, remove };
}

// o tipo do que useCart retorna: útil para provide / inject
export type Cart = ReturnType<typeof useCart>;
  • linha 19: cada chamada a [useCart()] cria um NOVO carrinho de compras;
  • linha 33: o tipo do que [useCart] retorna, inferido pelo [TypeScript].

Para que vários componentes compartilhem o MESMO carrinho de compras, usamos [provide] e [inject], uma forma de injeção de dependência:

// =========================================================================
// 11-composables/src/keys.ts - as chaves de provide / inject
// -------------------------------------------------------------------------
// provide(key, value): um componente DISPONIBILIZA um valor para
// todos os seus descendentes, qualquer que seja a profundidade;
// inject(key): um descendente o recupera - sem que os componentes
// intermediários precisem repassá-lo de prop em prop.
// É uma forma de injeção de dependência, como no NestJS.
//
// Uma InjectionKey<T> (um Symbol tipado) garante que inject() retorne um
// valor do tipo correto.
// =========================================================================

import type { InjectionKey } from 'vue';
import type { Cart } from './composables/useCart';

export const CART_KEY: InjectionKey<Cart> = Symbol('cart');
  • Linha 17: a chave sob a qual o carrinho é fornecido: um [Symbol] (valor único) tipado por [InjectionKey<Cart>], para que [inject] retorne um objeto do tipo correto.

O componente raiz cria o carrinho de compras e o fornece:

<!--
  =========================================================================
  11-composables/src/App.vue
  -------------------------------------------------------------------------
    - useClock(): App has its clock (1 s), CartSummary its own (5 s);
    - useCart() + provide: App creates ONE cart and provides it to all its
      descendants; Catalog and CartSummary inject it and therefore
      share the same one.
  =========================================================================
-->
<script setup lang="ts">
import { provide } from 'vue';
import { useClock } from './composables/useClock';
import { useCart } from './composables/useCart';
import { CART_KEY } from './keys';
import Catalog from './components/Catalog.vue';
import CartSummary from './components/CartSummary.vue';

const { now } = useClock();
provide(CART_KEY, useCart());
</script>

<template>
  <div class="container py-4" style="max-width: 720px">
    <h1 class="h3 mb-3">Example 11 - composables and provide / inject</h1>
    <p class="text-muted">Clock of App: {{ now.toLocaleTimeString() }}</p>
    <div class="row g-3">
      <div class="col-md-6"><Catalog /></div>
      <div class="col-md-6"><CartSummary /></div>
    </div>
  </div>
</template>
  • linha 19: App tem seu próprio relógio, atualizado a cada segundo;
  • linha 20: a aplicação disponibiliza um carrinho de compras a TODOS os seus descendentes, qualquer que seja a profundidade, sem precisar passá-lo de props em props.

Dois descendentes o injetam:

<!--
  11-composables/src/components/Catalog.vue - a descendant that INJECTS the cart
-->
<script setup lang="ts">
import { inject } from 'vue';
import { CART_KEY } from '../keys';
import type { Item } from '../composables/useCart';

// o carrinho fornecido por App.vue (provide); erro explícito se estiver ausente
const cart = inject(CART_KEY);
if (!cart) {
  throw new Error('Catalog must be placed under a component that provides the cart');
}

const catalog: Item[] = [
  { label: 'Consultation', price: 30 },
  { label: 'Vaccine', price: 12.5 },
  { label: 'Certificate', price: 5 },
];
</script>

<template>
  <ul class="list-group">
    <li v-for="a in catalog" :key="a.label" class="list-group-item d-flex justify-content-between align-items-center">
      {{ a.label }} (€{{ a.price }})
      <button class="btn btn-sm btn-outline-primary" @click="cart.add(a)">Add</button>
    </li>
  </ul>
</template>
  • linha 10: o carrinho fornecido por um ancestral é recuperado; [inject] retorna [undefined] se nenhum ancestral o forneceu: isso é sinalizado por um erro explícito.
<!--
  11-composables/src/components/CartSummary.vue - another descendant, the SAME cart
-->
<script setup lang="ts">
import { inject } from 'vue';
import { CART_KEY } from '../keys';
import { useClock } from '../composables/useClock';

const cart = inject(CART_KEY)!;
// este componente tem O SEU próprio relógio, atualizado a cada 5 segundos
const { now } = useClock(5000);
</script>

<!-- cart.items.value: in a template, Vue only "unwraps" (implicit
     .value) the TOP-LEVEL refs of the script, like now.
     The refs stored INSIDE an object (cart.items) are written with .value -->
<template>
  <div class="card p-3">
    <h2 class="h6">Cart ({{ cart.items.value.length }} item(s)) - {{ now.toLocaleTimeString() }}</h2>
    <ul class="mb-2">
      <li v-for="(a, i) in cart.items.value" :key="i">
        {{ a.label }} <a href="#" @click.prevent="cart.remove(i)">remove</a>
      </li>
    </ul>
    <strong>Total: €{{ cart.total.value }}</strong>
  </div>
</template>
  • Linha 9: mesma injeção; [!] confirma ao [TypeScript] que o valor existe;
  • linha 11: este componente tem seu PRÓPRIO relógio, atualizado a cada 5 segundos;
  • linha 19: em um template, o [Vue.js] “desembrulha” automaticamente apenas os [ref] de nível superior do script. Um [ref] armazenado DENTRO de um objeto ([cart.items]) é escrito com [.value].

Os dois componentes exibem o mesmo carrinho de compras; os dois relógios correm cada um em seu ritmo:

Image

3.6. Exemplo 12: Uma janela de confirmação reutilizável

Antes de excluir um item, o sistema pergunta “Tem certeza?”. A função do navegador [window.confirm()] existe, mas sua caixa de diálogo não pode ser formatada, nem seus botões traduzidos. Nós a substituímos por uma janela [Bootstrap], controlada por um composable. Esta é a versão [Vue.js] do Exemplo 21 do curso [NestJS].

// =========================================================================
// 12-confirmation/src/composables/useConfirmation.ts
// -------------------------------------------------------------------------
// "Tem certeza?": window.confirm() existe, mas não pode ser
// estilizado, nem seus botões podem ser traduzidos. Nós o substituímos por um
// diálogo Bootstrap (ConfirmDialog.vue), controlado por este composable.
//
// O truque: confirm(message) retorna uma PROMISE, resolvida com true (Sim)
// ou false (Não) quando o usuário responde. O código chamador é então escrito
// tão simplesmente quanto com window.confirm:
//
//     if (await confirm('Delete this doctor?')) { ... }
//
// O estado (mensagem exibida, função a chamar na resposta) é declarado
// FORA da função: ele é portanto ÚNICO para toda a aplicação. Um
// único diálogo, colocado uma vez em App.vue, atende a todos os componentes.
// =========================================================================

import { readonly, ref } from 'vue';

const message = ref<string | null>(null); // null: diálogo fechado
let answer: ((yes: boolean) => void) | null = null;

export function useConfirmation() {
  function confirm(text: string): Promise<boolean> {
    message.value = text;
    return new Promise<boolean>((resolve) => {
      answer = resolve;
    });
  }

  function respond(yes: boolean): void {
    message.value = null;
    answer?.(yes);
    answer = null;
  }

  // readonly: os componentes leem a mensagem, somente o composable a modifica
  return { message: readonly(message), confirm, respond };
}
  • Linhas 21 e 22: o estado é declarado FORA da função [useConfirmation] , no nível do módulo. Ele é, portanto, único em toda a aplicação: uma única janela atende a todos os componentes;
  • Linhas 25–30: [confirm] abre a janela (atribuindo um valor à mensagem) e retorna uma promise. Ele armazena a função [resolve] dessa promise em [answer]: a promise só será resolvida quando o usuário tiver respondido;
  • linhas 32–35: a resposta do usuário fecha a janela e resolve a promise como [true] ou [false];
  • linha 39: os componentes podem ler a mensagem, mas não modificá-la.

A janela:

<!--
  =========================================================================
  12-confirmation/src/components/ConfirmDialog.vue
  -------------------------------------------------------------------------
  The modal dialog, placed ONCE in App.vue.
    - <Teleport to="body">: its HTML is inserted at the end of <body>, outside
      the component tree - a modal dialog must go
      above everything, wherever it is declared;
    - same Bootstrap classes as a real modal (.modal, .modal-backdrop),
      displayed "hard-coded" (show d-block): no need for Bootstrap's JavaScript;
    - keyboard: Escape = No; the focus is placed on the "No" button (the
      least dangerous choice) on opening.
  =========================================================================
-->
<script setup lang="ts">
import { nextTick, onUnmounted, useTemplateRef, watch } from 'vue';
import { useConfirmation } from '../composables/useConfirmation';

const { message, respond } = useConfirmation();
const noButton = useTemplateRef<HTMLButtonElement>('noButton');

function onKeydown(e: KeyboardEvent): void {
  if (e.key === 'Escape') {
    respond(false);
  }
}

// na abertura: foco em "Não", escuta da tecla Escape; no fechamento: paramos de escutar
watch(message, async (value) => {
  if (value !== null) {
    document.addEventListener('keydown', onKeydown);
    await nextTick();
    noButton.value?.focus();
  } else {
    document.removeEventListener('keydown', onKeydown);
  }
});
onUnmounted(() => document.removeEventListener('keydown', onKeydown));
</script>

<template>
  <Teleport to="body">
    <template v-if="message !== null">
      <div class="modal-backdrop fade show"></div>
      <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true" @click.self="respond(false)">
        <div class="modal-dialog modal-dialog-centered">
          <div class="modal-content">
            <div class="modal-header">
              <h5 class="modal-title">Confirmation</h5>
              <button type="button" class="btn-close" aria-label="Close" @click="respond(false)"></button>
            </div>
            <div class="modal-body">
              <p class="mb-0">{{ message }}</p>
            </div>
            <div class="modal-footer">
              <button ref="noButton" type="button" class="btn btn-secondary" @click="respond(false)">No, go back</button>
              <button type="button" class="btn btn-danger" @click="respond(true)">Yes, confirm</button>
            </div>
          </div>
        </div>
      </div>
    </template>
  </Teleport>
</template>
  • linha 42: o HTML da janela é inserido no final de [<body>], fora da árvore de componentes: uma janela modal deve ter precedência sobre todo o resto, não importa onde seja declarada;
  • linha 45: as classes [Bootstrap] de uma janela modal, exibida “fixa no código” ([show d-block]): não há necessidade do [JavaScript] do [Bootstrap];
  • linha 45: o modificador [.self]: apenas um clique no próprio elemento (a área sombreada), e não na janela que ele contém, aciona a resposta “Não”;
  • Linhas 29–37: ao abrir, o programa escuta a tecla Esc e dá o foco ao botão “Não” (a opção mais segura: um Enter pressionado por acidente não excluirá nada); ao fechar, o programa para de escutar o teclado.

O componente que o utiliza:

<!--
  =========================================================================
  12-confirmation/src/App.vue - using the confirmation dialog
  -------------------------------------------------------------------------
  Same page as example 21 of the NestJS course (links, buttons, confirmation),
  but without any round trip to a server.
  =========================================================================
-->
<script setup lang="ts">
import { ref } from 'vue';
import ConfirmDialog from './components/ConfirmDialog.vue';
import { useConfirmation } from './composables/useConfirmation';

interface Contact {
  id: number;
  name: string;
}

const contacts = ref<Contact[]>([
  { id: 1, name: 'Jean MARTIN' },
  { id: 2, name: 'Alice DURAND' },
  { id: 3, name: 'Luc GERMAN' },
]);
const message = ref('');
const { confirm } = useConfirmation();

// uma função async: ela "espera" pela resposta do usuário
async function remove(c: Contact): Promise<void> {
  if (!(await confirm(`Delete the contact ${c.name}?`))) {
    message.value = 'Deletion cancelled.';
    return;
  }
  contacts.value = contacts.value.filter((x) => x.id !== c.id);
  message.value = `${c.name} has been deleted.`;
}

async function removeAll(): Promise<void> {
  if (await confirm(`Delete the ${contacts.value.length} contacts?`)) {
    contacts.value = [];
    message.value = 'All the contacts have been deleted.';
  }
}
</script>

<template>
  <div class="container py-4" style="max-width: 640px">
    <h1 class="h3 mb-3">Example 12 - a confirmation dialog</h1>
    <ul class="list-group mb-3">
      <li v-for="c in contacts" :key="c.id" class="list-group-item d-flex justify-content-between align-items-center">
        {{ c.name }}
        <button class="btn btn-sm btn-outline-danger" @click="remove(c)">Delete</button>
      </li>
      <li v-if="contacts.length === 0" class="list-group-item text-muted">No contacts.</li>
    </ul>
    <button class="btn btn-danger" :disabled="contacts.length === 0" @click="removeAll">Delete all</button>
    <p v-if="message" class="alert alert-info mt-3">{{ message }}</p>
  </div>
  <!-- o diálogo, UMA ÚNICA VEZ para toda a aplicação -->
  <ConfirmDialog />
</template>
  • linha 29: graças à promise, o código é tão simples de escrever quanto com [window.confirm]: a função [async] “espera” a resposta do usuário;
  • linha 59: a janela, criada UMA ÚNICA VEZ para toda a aplicação.

Image

Após “Sim, confirmar”:

Image