DEV Community: Angela Caldas

[Boost]

Angela Caldas — Fri, 14 Nov 2025 21:44:23 +0000

GroupBy no JavaScript: a forma fácil de indexar e organizar dados

Angela Caldas ・ Nov 14

GroupBy no JavaScript: a forma fácil de indexar e organizar dados

Angela Caldas — Fri, 14 Nov 2025 21:29:53 +0000

Quantas vezes você precisou usar reduce para organizar arrays de objetos? No meu artigo anterior sobre Indexação de dados para aplicações front-end, explorei exatamente isso, mostrando como organizar estruturas complexas usando reduce e até Map.

Mas, convenhamos, reduce tende a deixar o código complexo e difícil de entender...

Quer uma boa notícia? Desde o lançamento do ECMAScript 2024 temos uma forma muito mais simples, expressiva e legível para fazer isso, utilizando os métodos Object.groupBy e Map.groupBy.

Sumário

Por que agrupar dados?
Object.groupBy
Map.groupBy
Conclusão

Por que agrupar dados?

Agrupar dados é uma forma de indexação: você pega uma lista linear e reorganiza tudo usando uma chave. Esse tipo de organização melhora a performance, além de facilitar buscas e o consumo de dados em interfaces dinâmicas.

Antes dessas novas APIs, recorrer ao reduce era quase obrigatório. Funcionava, claro, mas exigia escrever mais código do que o necessário e a legibilidade acabava sofrendo:

// Como fazíamos antes
const produtos = [
  { nome: "iPhone", categoria: "eletrônicos", preco: 5000 },
  { nome: "Notebook", categoria: "eletrônicos", preco: 3000 },
  { nome: "Camiseta", categoria: "roupas", preco: 50 },
  { nome: "Calça", categoria: "roupas", preco: 120 },
];

const agrupados = produtos.reduce((acc, produto) => {
  const categoria = produto.categoria;
  if (!acc[categoria]) acc[categoria] = [];
  acc[categoria].push(produto);
  return acc;
}, {});

Object.groupBy

O Object.groupBy chega para resolver o agrupamento mais simples — aquele em que a chave é uma string. Você passa a lista e uma função que retorna a chave e pronto. O JavaScript devolve um objeto organizado, sem precisar criar inicializações manuais, verificações ou boilerplate.

const produtosPorCategoria = Object.groupBy(
  produtos, // aqui a lista
  (produto) => produto.categoria // e aqui a função
);

console.log(produtosPorCategoria);
console.log(produtosPorCategoria instanceof Object); // true

O resultado é direto, limpo e fácil de interpretar:

{
  eletrônicos: [
    { nome: 'iPhone', categoria: 'eletrônicos', preco: 5000 },
    { nome: 'Notebook', categoria: 'eletrônicos', preco: 3000 }
  ],
  roupas: [
    { nome: 'Camiseta', categoria: 'roupas', preco: 50 },
    { nome: 'Calça', categoria: 'roupas', preco: 120 }
  ]
}

Voltar ao sumário

Map.groupBy

Já Map.groupBy atende aos casos em que a chave não pode ser tratada como texto comum. Quando você precisa agrupar usando:

datas,
objetos,
símbolos,
ou qualquer valor que não deve virar string,

é ele que faz a diferença:

class Professor {    
  constructor(nome, especialidade) {
    this.nome = nome;
      this.especialidade = especialidade;
  }
}

const professor1 = new Professor("João", "Matemática");
const professor2 = new Professor("Maria", "Física");

const alunos = [
  { nome: "Carlos",  idade: 20, professor: professor1 },
  { nome: "Beatriz", idade: 22, professor: professor2 },
  { nome: "Pedro",   idade: 19, professor: professor1 }
];

const alunosPorProfessor = Map.groupBy(alunos, aluno => aluno.professor);
console.log(alunosPorProfessor);

/*
Map(2) {
  Professor { nome: 'João', especialidade: 'Matemática' } => [
    { nome: 'Carlos', idade: 20, professor: [Professor] },
    { nome: 'Pedro', idade: 19, professor: [Professor] }
  ],
  Professor { nome: 'Maria', especialidade: 'Física' } => [
    { nome: 'Beatriz', idade: 22, professor: [Professor] }
  ],
}
*/

Acessar ou manipular os grupos fica mais explícito, o que ajuda bastante em projetos maiores:

console.log(alunosPorProfessor.get(professor1));

/*
[
  {
    nome: 'Carlos',
    idade: 20,
    professor: Professor { nome: 'João', especialidade: 'Matemática' }
  },
  {
    nome: 'Pedro',
    idade: 19,
    professor: Professor { nome: 'João', especialidade: 'Matemática' }
  }
]
*/

A principal vantagem é justamente essa: o Map mantém o tipo original da chave, o que evita conversões automáticas e ambiguidades — algo que pode gerar problemas silenciosos quando usamos objetos normais.

No fim das contas, Map.groupBy acaba sendo a alternativa mais flexível para quem lida com coleções diversas no JavaScript moderno.

Agradecimentos ao @matheusgondra pelo exemplo acima.

Voltar ao sumário

Conclusão

Os novos métodos de agrupamento chegam para simplificar algo que sempre fez parte do nosso cotidiano de desenvolvimento. Em vez de escrever blocos repetitivos com reduce, agora podemos contar com soluções nativas, pensadas exatamente para esse propósito.

Quando combinados com as técnicas que apresentei no artigo anterior, eles deixam o fluxo de indexação mais claro, mais direto e muito mais expressivo.

Se você trabalha com listas, filtros, tabelas ou dashboards, vale experimentar essas APIs, provavelmente elas vão enxugar bastante o seu código.

⚠️ Nota sobre compatibilidade

Se você está se perguntando sobre suporte nos navegadores, boa notícia: segundo os dados do Can I Use, tanto Object.groupBy quanto Map.groupBy são amplamente suportados nos navegadores modernos.
A única exceção relevante é o Internet Explorer, que não oferece suporte a essas APIs — e não receberá.

Ou seja: se o seu público não usa IE, você pode adotar groupBy sem preocupações.

[Boost]

Angela Caldas — Fri, 25 Jul 2025 12:53:19 +0000

Caio

Jul 25 '25

Padrões de Commits (Commit Patterns)

#git #github #programming #beginners

Comments

5 min read

Vue3: How to style components (global, scoped and modules)

Angela Caldas — Mon, 28 Apr 2025 22:13:05 +0000

Ler em pt-BR

In the past few years using Vue as my favorite framework, I’ve come across many people who believed that the only way to style a component was by using CSS inside the style tag within the .vue file itself. Some people even reported disliking Vue solely because of this!

So, to clarify this somewhat "cloudy" topic, come along and let’s explore the different approaches to styling Vue components.

Global styles
Scoped styles
CSS Modules
When to use each one

Global styles

As the name suggests, global styles are available throughout the entire application and are usually imported in the main.ts file inside your project’s /src folder.

When you start a Vue application, a global file is already configured and imported:

import './assets/main.css'

You can create as many global files as you want and import them directly in your main.ts. Alternatively, you can import your global styles into a single .css file (or .scss, .less, etc.) and then import that single file into your main.ts:

// assets/styles.scss
@import "base/reset";
@import "base/variables";
@import "base/typography";
@import "components/buttons";
@import "components/table";
@import "pages/home";

// main.ts
import './assets/styles.scss'

❓ "But don’t I need to have a style tag in my .vue file?"

👉🏽 No! The Vue SFC model only requires you to have the template that will be rendered, with both script and style being optional.

<!-- Example in App.vue -->
<template>
  <nav>
    <RouterLink to="/">Home</RouterLink>
    <RouterLink to="/about" class="txt-tomato">About</RouterLink>
    <!-- The class "txt-tomato" is in the global CSS and can be used -->
    <!-- directly in the component -->
  </nav>
</template>

If your project is small and/or you use strategies like Atomic Design or BEM, using global styles will work very well for you. However, it’s important to be cautious, as poorly managed global CSS can cause styles to "leak" between components and pages.

Back to Table of contents

Scoped styles

A Vue project comes by default with a <style scoped> tag in the App.vue file. Using the scoped attribute means that the CSS is scoped, meaning that all the CSS declared within the tag will be exclusive to the component.

⚠️ Using the style tag without the scoped attribute applies the styles globally, so be cautious with this detail!

<!-- App.vue -->
<template>
  <div>
    <HelloWorld />

    <nav>
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/about" class="example">About</RouterLink>
    </nav>
  </div>
</template>

<style scoped>
.example {
  color: darkorchid;
}
</style>

<!-- HelloWorld.vue -->
<template>
  <h1 class="example">You did it!</h1>
</template>

We created a class example only in the App.vue file. However, we also use this same class in another file, HelloWorld.vue. As a result, the darkorchid color will be applied only to App.vue, even though HelloWorld.vue is its child component.

❓ What if I wanted to reuse this class in the child component? Do I need to declare it in a global CSS?

👉🏽 Well, that’s one option... But Vue’s scoped attribute allows the classes to become "deep" with the :deep() selector, enabling you to pass...

Scoped styles from parent to child

<!-- App.vue -->
<template>
  <!-- We apply the "example" class to the parent element -->
  <!-- of HelloWorld.vue, in this case, the div -->
  <div class="example">
    <HelloWorld />

    <nav>
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/about" class="example">About</RouterLink>
    </nav>
  </div>
</template>

<style scoped>
/* And here we use the :deep() selector to apply inheritance from the child component */
.example :deep(.example) {
  color: darkorchid;
}
</style>

<!-- HelloWorld.vue -->
<template>
  <h1 class="example">You did it!</h1>
</template>

But if you really want to follow the approach of making this class global starting from a specific component, scoped also provides the :global() selector:

<style scoped>
:global(.example) {
  color: darkorchid;
}
</style>

This way, we make the .example class available to any other component in the application. Personally, I avoid using :global(), preferring to keep global styles in main.css for better organization and readability.

⚠️ Avoid using :global() as much as possible, because this selector increases the style specificity, overriding scoped styles.

There’s also the possibility of using two style tags in a component — one for global styles and another for scoped styles (but that might be a bit too much 😅).

<!-- In the same file... -->
<style>
/* global styles */
</style>

<style scoped>
/* scoped styles */
</style>

✒️ Learn more: Scoped CSS (Vue Docs)

Back to Table of contents

CSS Modules

There are two different ways to use CSS Modules with Vue:

by using the <style module> inside the component itself (SFC); or
by creating a .module.css file (or .module.scss, .module.less, etc.) and importing it into the component.

CSS Modules (SFC)

Using CSS Modules inside the component itself is very simple: just use the <style module> tag. From there, all CSS created within this scope will be accessible in the <template> through the $style object. Let’s check an example:

<!-- HelloWorld.vue -->
<template>
  <h1 :class="$style.example">You did it!</h1>
</template>

<!-- CSS Module -->
<style module>
.example {
  color: tomato;
}
</style>

Here we are using the module attribute and accessing the example class in the template through the $style object. So, even though we also have an example class in App.vue, they will have independent styles:

This approach allows for a more harmonious code structure, keeping the logic and styles of a component isolated in a single file. It also makes it easier for the developer to see the relationship between the template and the styles.

However, reusing these classes becomes more difficult, and it can also make your file very lengthy — a potential issue we can solve with...

CSS Modules in a Separate File

...which improves the separation of concerns and makes it easier to reuse styles across multiple components, also encouraging the use of more complex CSS.

To test this, let's create a file in our /assets folder called example.module.css:

.example {
  color: yellow;
}

This file must be imported into every component where you want to use the example class. Let's import it into our HelloWorld.vue:

<!-- HelloWorld.vue -->
<script setup lang="ts">
// Importing the CSS Module as styles -->
import styles from '@/assets/example.module.css'
</script>

<template>
  <!-- Accessing the class with styles -->
  <h1 :class="styles.example">You did it!</h1>
</template>

<style module>
/* Even with this module declared in the file, 
the "tomato" color from this 'example' class 
will not be applied */
.example {
  color: tomato;
}
</style>

When a CSS Module is processed, each class from each module receives a unique hash in the final build, ensuring there are no conflicts with other classes, even if they have the same name in different files:

And the coolest part of using CSS Modules with TypeScript? Autocomplete! 🤩

✒️ Learn more: CSS Modules (Vue Docs)

Back to Table of contents

When to Use Each One?

Global styles will always exist in an application. Use them for general-purpose elements, like typography, colors, and custom spacing.

Use Scoped when:

You have simple and isolated components;
You prefer a simpler syntax;
You don't need programmatic access to the classes.

Use CSS Modules when:

You need to access classes via JavaScript;
You want to share styles across components;
You're working on larger projects with many developers.

The important thing to understand is that there isn't a one-size-fits-all solution when it comes to styling in Vue. Each method has its purpose and context:

Global styles are used to define the visual foundation of your project, while scoped styles help maintain organization and prevent conflicts in specific components. CSS Modules, on the other hand, are type-safe when used with TypeScript, which can be a big plus for developer experience in larger, more complex projects.

Vue offers complete flexibility when it comes to styling. Instead of being limited to using only the style tag in your .vue file, you can combine different approaches according to your needs and preferences.

Besides that, you can also use CSS-in-JS libraries like Vanilla Extract and Vue Styled Components, or UI libraries like Vuetify and PrimeVue, or even integrate with the popular Tailwind and Bootstrap 💚

Now, let’s go build some beautiful apps. Big hug!

Vue3: Como estilizar componentes (global, scoped e modules)

Angela Caldas — Mon, 28 Apr 2025 21:13:42 +0000

Read it in English

Nesses últimos anos usando Vue como meu framework favorito, acabei esbarrando em várias pessoas que acreditavam que a única forma de se estilizar um componente seria utilizando CSS dentro da tag <style> do próprio arquivo .vue. Algumas pessoas até relataram não gostar de Vue unicamente por esse motivo!

Então, pra esclarecer um pouco mais esse assunto "nebuloso", vem comigo ver as diferentes abordagens de estilização de componentes Vue.

Sumário

Estilos globais
Estilos escopados com scoped
Estilos escopados com CSS Modules
Quando usar cada um?

Estilos globais

Como o próprio nome diz, os estilos globais ficam disponíveis pra toda a aplicação e normalmente são importados no arquivo main.ts na pasta /src do seu projeto.

Quando você inicia uma aplicação Vue, um arquivo global já vem configurado e importado:

import './assets/main.css'

Você pode criar quantos arquivos globais quiser e importá-los diretamente no seu main.ts. Ou você pode importar seus arquivos globais em um único arquivo .css (ou .scss, .less, etc.) e importar esse único arquivo no seu main.ts:

// assets/styles.scss
@import "base/reset";
@import "base/variables";
@import "base/typography";
@import "components/buttons";
@import "components/table";
@import "pages/home";

// main.ts
import './assets/styles.scss'

❓ "Mas eu não preciso ter uma tag <style> no meu arquivo .vue?

👉🏽 Não! O modelo SFC do Vue apenas exige que você tenha o template que será renderizado, sendo o script e o style opcionais.

<!-- Exemplo no App.vue -->
<template>
  <nav>
    <RouterLink to="/">Home</RouterLink>
    <RouterLink to="/about" class="txt-tomato">About</RouterLink>
    <!-- A classe "txt-tomato" está no CSS global e pode ser utilizada --> 
    <!-- diretamente no componente -->
  </nav>
</template>

Se seu projeto é pequeno e/ou se você usa estratégias como Atomic Design ou BEM, utilizar estilos globais vai te atender muito bem. No entanto, é necessário ter cuidado, pois um CSS global mal gerenciado pode "vazar" estilos entre componentes e páginas.

Voltar ao Sumário

Estilos escopados com scoped

Um projeto Vue já vem por padrão com uma tag <style scoped> no arquivo App.vue. O uso do atributo scoped significa que o CSS é escopado, ou seja, todo o CSS declarado dentro da tag será exclusivo do componente.

⚠️ O uso da tag <style> sem o atributo scoped aplica os estilos de forma global, então cuidado aí com esse detalhe!

<!-- App.vue -->
<template>
  <div>
    <HelloWorld />

    <nav>
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/about" class="example">About</RouterLink>
    </nav>
  </div>
</template>

<style scoped>
.example {
  color: darkorchid;
}
</style>

<!-- HelloWorld.vue -->
<template>
  <h1 class="example">You did it!</h1>
</template>

Criamos uma classe example apenas no arquivo App.vue. No entanto, usamos essa mesma classe também em outro arquivo, o HelloWorld.vue.Como resultado, a cor darkorchid será aplicada apenas ao App.vue, mesmo que HelloWorld.vue seja seu componente-filho.

❓ E se eu quisesse reaproveitar essa classe no componente-filho? Preciso declará-la em um CSS global?

👉🏽 Bom, essa é uma das opções... Mas o atributo scoped do Vue permite que possamos tornar essas classes "profundas" com o seletor :deep(), permitindo que você consiga passar estilos...

Scoped de pai pra filho

<!-- App.vue -->
<template>
  <!-- Colocamos a classe "example" no elemento-pai -->
  <!-- de HelloWorld.vue, no caso, a div -->
  <div class="example">
    <HelloWorld />

    <nav>
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/about" class="example">About</RouterLink>
    </nav>
  </div>
</template>

<style scoped>
/* E aqui usamos o seletor :deep() para herança do componente-filho */
.example :deep(.example) {
  color: darkorchid;
}
</style>

<!-- HelloWorld.vue -->
<template>
  <h1 class="example">You did it!</h1>
</template>

Mas se você quiser mesmo seguir a linha de deixar essa classe global a partir de um determinado componente, o scoped também disponibiliza o seletor :global():

<style scoped>
:global(.example) {
  color: darkorchid;
}
</style>

Assim, disponibilizamos a classe .example para qualquer outro componente da aplicação. Pessoalmente, evito o uso de :global(), preferindo manter os estilos globais no main.css pra melhor organização e legibilidade.

⚠️ Evite usar :global() ao máximo, pois esse seletor aumenta a especificidade do estilo, se sobrepondo a estilos escopados.

Existe também a possibilidade de usar duas tags <style> em um componente, deixando um com estilos globais e outro com estilos escopados (mas aí também já é demais 😅).

<!-- Em um mesmo arquivo... -->
<style>
/* estilos globais */
</style>

<style scoped>
/* estilos locais */
</style>

✒️ Para saber mais: CSS Isolado (Vue Docs)

Voltar ao Sumário

Estilos escopados com CSS Modules

Existem duas formas distintas de usar CSS Modules com Vue:

usando a tag <style module> dentro do próprio componente (SFC); ou
criando um arquivo .module.css (ou .module.scss, .module.less, etc.) e importando-o no componente.

CSS Modules (SFC)

Usar CSS Modules dentro do próprio componente é muito simples: basta usar a tag <style module>. A partir disso, todo CSS criado dentro desse escopo será acessado no <template> através do objeto $style. Bora pro exemplo:

<!-- HelloWorld.vue -->
<template>
  <!-- Acessando a classe com $style -->
  <h1 :class="$style.example">You did it!</h1>
</template>

<!-- Declarando o CSS Module -->
<style module>
.example {
  color: tomato;
}
</style>

Aqui estamos usando o atributo module e acessando a classe example no template através do objeto $style. Então, apesar de também termos uma classe example em App.vue, elas vão ter seus estilos independentes:

Essa abordagem permite ter um código mais harmônico, mantendo lógica e estilos de um componente isolados em um único arquivo. Além disso, facilita pro desenvolvedor ver a relação entre template e estilos.

No entanto, o reuso dessas classes é dificultado, além de poder tornar o seu arquivo muito extenso, um possível problema que podemos resolver com...

CSS Modules em arquivo separado

... que melhora a separação de responsabilidades, além de facilitar o reuso dos estilos em outros componentes, favorecendo também o uso de CSS mais complexo.

Pra testarmos, vamos criar um arquivo em nossa pasta /assets chamado example.module.css:

.example {
  color: yellow;
}

Esse arquivo deverá ser importado em todos os componentes onde você quiser usar a classe example. Vamos importá-la no nosso HelloWorld.vue:

<!-- HelloWorld.vue -->
<script setup lang="ts">
// Importando o CSS Module como styles -->
import styles from '@/assets/example.module.css'
</script>

<template>
  <!-- Acessando a classe com styles -->
  <h1 :class="styles.example">You did it!</h1>
</template>

<style module>
/* Mesmo com esse módulo declarado no arquivo, a cor "tomato" da 
classe 'example' daqui não será atribuída */
.example {
  color: tomato;
}
</style>

Quando o CSS Module é processado, cada classe de cada módulo recebe um hash único no build final, garantindo que não haverá conflitos com outras classes, mesmo que tenham o mesmo nome em outros arquivos:

E o mais legal de usar CSS Modules com Typescript? Autocomplete! 🤩

✒️ Para saber mais: Módulos de CSS (Vue Docs)

Voltar ao Sumário

Quando usar cada um?

Estilos globais sempre vão existir em uma aplicação. Utilize-os para elementos de uso geral, como tipografia, cores e espaçamentos personalizados.

Use Scoped quando:

Tiver componentes simples e isolados;
Preferir uma sintaxe mais simples;
Não precisar de acesso programático às classes.

Use CSS Modules quando:

Precisar acessar classes via JavaScript;
Quiser compartilhar estilos entre componentes;
Trabalhar em projetos maiores com muitos desenvolvedores.

O que é importante entender é que não existe uma solução única quando se trata de estilização no Vue. Cada método tem um propósito e um contexto de aplicação:

Estilos globais são usados pra definir a base visual do seu projeto, enquanto o scoped ajuda a manter a organização e evitar conflitos em componentes específicos. Já os CSS Modules são type-safe quando usados com TypeScript, o que podemos considerar um ponto a mais pra experiência do desenvolvedor em projetos maiores e mais complexos.

O Vue oferece flexibilidade total quanto à estilização. E em vez de ficar limitado a usar apenas a tag <style> no seu arquivo .vue, você pode combinar diferentes abordagens de acordo com as suas necessidades e gostos.

Além disso, você pode usar libs CSS-in-JS, como Vanilla Extract e Vue Styled Components, ou libs de UI, como Vuetify e Prime Vue, ou até integrar com os famosos Tailwind e Bootstrap 💚

Agora, partiu criar apps bonitões. Um xero!

Exploring Promises: .all vs .allSettled / .race vs .any

Angela Caldas — Fri, 11 Apr 2025 19:36:39 +0000

Ler em pt/br

Promises emerged in 2015, with the release of ECMAScript 6 (ES2015), to make our experience as developers less complicated when dealing with asynchronous operations.

If you study or work with JavaScript, you have certainly used a Promise.all() or a Promise.race() somewhere. And to make the developer's life even easier, with the release of more recent versions of JavaScript, we had access to two new Promises methods: Promise.allSettled() and Promise.any() (ES11 and ES2021, respectively).

But what is the difference between them and when should we use each?

Summary

Promise.all vs Promise.allSettled: focus on result
Promise.race vs Promise.any: focus on speed

Promise.all vs Promise.allSettled: focus on result

Sometimes when you are developing an application, at a given moment you will need to execute different API calls. If these calls are independent of each other, it would be a good choice to execute all calls simultaneously, improving the application's performance, in addition to making the code more concise.

Promise.all()

Receives an array of Promises as an argument;
Executes the operations simultaneously (in parallel);
Resolves when all Promises are successfully resolved;
Rejects immediately if one of the Promises fails, blocking the execution of the following Promises.

async function getDataInParallel() { 
  const [users, products] = await Promise.all([
    fetch('/api/users').then(resp => resp.json()),
    fetch('/api/products').then(resp => resp.json()),
  ]);

  return { users, products };
}

The Promise.all() is quite useful when you need to ensure that all Promises succeed and the function receives all the results it needs before executing any other action.

Promise.allSettled()

Also receives an array of Promises as an argument;
Also executes the operations simultaneously (in parallel);
Resolves when all Promises finish their execution, either successfully or failed, returning an object for each Promise containing its status (fulfilled or rejected);
Never rejects and, consequently, does not block the execution of Promises.

async function getFailableDataInParallel() { 
  const results = await Promise.allSettled([
    fetch('/api/users').then(resp => resp.json()),
    fetch('/api/products').then(resp => resp.json()),
  ]);

  // Check each result individually:
  const data = results.map(result => {
    if (result.status === 'fulfilled') {
      return result.value;
    } else {
      console.error(result.reason);
      return null;
    }
  });

  return data;
}

The Promise.allSettled() does not block the application if any Promise fails, in addition to allowing individual treatment for each call's success or error status. It is like a status report, which waits for all requests to be resolved or rejected and allows the user to evaluate and treat each case.

Back to summary

Promise.race vs Promise.any: focus on speed

On the other hand, Promise.race() and Promise.any() are about handling the first response in a set of asynchronous operations.

Promise.race()

Receives an array of Promises as arguments;
Executes the operations simultaneously (in parallel);
Returns the first Promise that is completed OR rejected.

async function getUserData() {
  const timeout = new Promise((_, reject) => {
    setTimeout(() => reject('Timeout!'), 5000);
  });

  try {
    // Use race to get the first available result
    const result = await Promise.race([
      getFromCache,
      getLocalData,
      getFromAPI,
      timeout
    ]);

    return result;
  } catch (error) {
    console.log(error);
    // Execution stops here if there is an error
  }
}

Promise.race() is very useful when we need a fast response — the first available return, regardless of whether it is success or error. It is also often used with timeouts, as in the example above, to ensure that we get any response within a time limit and to prevent slow requests from continuing to consume resources.

Promise.any()

Also receives an array of Promises as arguments;
Executes the operations simultaneously (in parallel);
Returns the first Promise that completes successfully, ignoring rejections;
Only rejects if all Promises are rejected.

async function getUserData() {
  try {
    // Returns the first successful search
    const result = await Promise.any([
      getFromCache,
      getLocalData,
      getFromAPI
    ]);

    return result;
  } catch (error) {
    console.log(error); // Only falls here if ALL fetches fail
  }
}

Promise.any() is useful when you need at least one of the requests to complete successfully, and is ideal for fallbacks and redundancies, such as loading a resource from multiple sources (CDN, local, etc.) or connecting to different servers in case of failure.

Back to summary

In an increasingly asynchronous digital world, understanding how to manage multiple concurrent operations in JavaScript has become an essential skill for developers. In this article, we explore some important Promises methods with examples, showing how each of them works and, more importantly, when and why you should choose one over the other.

Until next time (and I promise I'll be back soon)!

Indexação de dados para aplicações frontend

Angela Caldas — Thu, 27 Mar 2025 17:15:47 +0000

A eficiência no tratamento de dados de APIs é um fator crítico para garantir uma experiência fluida ao usuário. À medida que os conjuntos de dados crescem, operações aparentemente simples, como buscar um item específico em uma lista, podem se tornar inimigos de performance.

Nesse artigo, vou mostrar algumas formas de lidar com dados de API que podem transformar buscas lentas em acessos instantâneos. Pega um cafezinho e vamos nessa! ☕

Sumário

O problema dos arrays
A Solução: Indexação de Dados da API
Técnicas ninja de indexação
Performance na prática
Um extra: Objetos vs Maps
Conclusão

Quem aí lembra do Gato A Jato?

O problema dos arrays

Normalmente, uma API entrega dados assim:

const produtos = [
  { id: 1, nome: "Smartphone Ultra Mega", categoria: "eletronicos", preco: 1599.99 },
  { id: 2, nome: "Sofá Confortex", categoria: "moveis", preco: 899.50 },
  { id: 3, nome: "Smart TV 55pol", categoria: "eletronicos", preco: 2499.99 },
  // ... e mais uns 500 produtos que sua aplicação precisa gerenciar
];

Quando você precisa acessar esses dados, você acaba recorrendo a métodos como find() ou filter():

// Todo mundo já escreveu isso um dia
function encontrarProdutoPorId(id) {
  return produtos.find(produto => produto.id === id);
}

function filtrarPorCategoria(categoria) {
  return produtos.filter(produto => produto.categoria === categoria);
}

O problema é que esses métodos fazem uma busca linear, o que significa que o tempo de execução aumenta linearmente com o tamanho do array. Ou seja: quanto mais produtos você tem, mais tempo demora. E isso ocorre porque esses métodos percorrem cada item da lista até encontrar o que você quer (busca de performance O(n)).

Pra gente ter uma ideia geral sobre a performance de um algoritmo, é só a gente dar uma olhada no gráfico abaixo pra saber onde cada notação big-O se encontra. Aqui, vamos focar em performances O(n) e O(1).

Fonte: Complexidade e performance de um algoritmo, por Ivan Queiroz

Observação: A performance que levaremos em conta nesse artigo é a de acesso aos dados indexados e não a de criação das indexações, já que, para o usuário final, o acesso aos dados é o que vai fazer a diferença.

A Solução: Indexação de Dados da API

Indexar significa criar uma estrutura de dados onde o acesso é instantâneo, como um índice de livro. No JavaScript, podemos fazer isso facilmente com objetos ou Maps.

// Transformando nosso array em um objeto indexado
// Com reduce:
const produtosPorId = produtos.reduce((acc, produto) => {
  acc[produto.id] = produto;
  return acc;
}, {});

// OU com Object.fromEntries:
const produtosPorId = Object.fromEntries(
  produtos.map(produto => [produto.id, produto])
);

// Agora o acesso é instantâneo: performance O(1)
function encontrarProdutoPorId(id) {
  return produtosPorId[id];
}

/* Exemplo de retorno de produtosPorId:
{
  1: { id: 1, nome: "Smartphone Ultra Mega", categoria: "eletronicos", preco: 1599.99 },
  etc...
}
*/

Se você quiser, também pode usar a classe Map para mais flexibilidade, já que o Map possui vários métodos embutidos pra te auxiliar na manipulação dos dados:

const mapaProdutos = new Map(
  produtos.map(produto => [produto.id, produto])
);

// Aqui também temos performance O(1)!
function encontrarProduto(id) {
  return mapaProdutos.get(id);
}

Todas as abordagens acima tem performance O(1), ou seja, independente da quantidade de itens que você tiver no array, a velocidade de acesso aos dados é praticamente constante!🚀

Técnicas ninja de indexação

Lookup por ID

O básico que funciona, indexando listas pelo id dos itens. É a mesma abordagem que utilizamos nos exemplos anteriores, mas segue um novo exemplo:

const usuariosPorId = usuarios.reduce((acc, usuario) => {
  acc[usuario.id] = usuario;
  return acc;
}, {});

// Performance O(1), é tipo teleporte de dados!
const usuario = usuariosPorId[123]; // { id: 123, nome: "Fulano", idade: 25 }

/*
Exemplo de retorno de usuariosPorId:
{
  123: { id: 123, nome: "Fulano", idade: 25 },
  234: { id: 234, nome: "Beltrano", idade: 48 },
  ...
}
*/

Também podemos criar um LookUp por id indexando os itens com Map e acessando-os com .get(id):

// Gosta de one-liners?
const usuariosPorId = new Map(usuarios.map(usuario => [usuario.id, usuario]));

// Acesso O(1)
const usuario = usuariosPorId.get(123); // { id: 123, nome: "Fulano", idade: 25 }

Indexação Multi-Valor

Quando precisamos agrupar itens por uma propriedade que pode ter valores repetidos (como a categoria de produtos):

const produtosPorCategoria = produtos.reduce((acc, produto) => {
  // Se a categoria não existe ainda, cria um array vazio
  if (!acc[produto.categoria]) {
    acc[produto.categoria] = [];
  }
  // Joga o produto lá dentro
  acc[produto.categoria].push(produto);
  return acc;
}, {});

// Busca instantânea por categoria, performance O(1)
const eletronicos = produtosPorCategoria["eletronicos"];

// Exemplo de retorno de produtosPorCategoria
// {
//   eletronicos: [ /* Lista de eletronicos */ ],
//   moveis: [ /* Lista de moveis */ ]
// }

Vamos ver como fazer essa indexação combinando .reduce() e Map e acessando com Map.get(id):

const produtosPorCategoria = produtos.reduce((acc, produto) => {
  // .has() e .set() são métodos nativos de Maps...
  if (!acc.has(produto.categoria)) {
    acc.set(produto.categoria, []);
  }

  // ...assim como .get()
  acc.get(produto.categoria).push(produto);
  return acc;
}, new Map());

// Acesso O(1) para a categoria "moveis"
produtosPorCategoria.get("moveis"); // [{ id: 2, nome: "Sofá Confortex", categoria: "moveis", preco: 899.50 }]

Índices compostos

Quando você precisa de buscas mais complexas, como uma busca por combinações de campos, por exemplo:

const produtosPorCategoriaEPreco = produtos.reduce((acc, produto) => {
  // Cria uma chave composta, tipo "eletronicos_premium"
  const chave = `${produto.categoria}_${produto.preco >= 1000 ? "premium" : "basico"}`;

  if (!acc[chave]) {
    acc[chave] = [];
  }

  acc[chave].push(produto);
  return acc;
}, {});

// Busca O(1): Quer todos os eletrônicos caros? Toma!
const eletronicosCaros = produtosPorCategoriaEPreco["eletronicos_premium"];

/* retorno
[
  { id: 1, nome: "Smartphone Ultra Mega", categoria: "eletronicos", preco: 1599.99 },
  { id: 3, nome: "Smart TV 55pol", categoria: "eletronicos", preco: 2499.99 }
]
*/

Usar um Map para um índice composto (como categoria_preço) funciona de maneira similar, mas aproveita as vantagens do Map, como melhor performance em grandes volumes de dados e suporte a qualquer tipo de chave:

const produtosPorCategoriaEPreco = produtos.reduce((acc, produto) => {
  const chave = `${produto.categoria}_${produto.preco >= 1000 ? "premium" : "basico"}`;

// Aqui usamos os métodos de Map:
  if (!acc.has(chave)) {
    acc.set(chave, []);
  }

  acc.get(chave).push(produto);
  return acc;
}, new Map());

// Buscar eletrônicos premium: O(1)
produtosPorCategoriaEPreco.get("moveis_basico"); // [{ id: 2, nome: "Sofá Confortex", categoria: "moveis", preco: 899.50 }]

Performance na prática

Vamos ver o que acontece quando temos 10.000 produtos. Para isso, vamos criar nosso setup pro teste (nossa lista gigante de produtos que viria de uma API):

const listaGiganteDeProdutos = Array.from({ length: 10000 }, (_, i) => ({
  id: i + 1,
  nome: `Produto ${i + 1}`,
  categoria: i % 5 === 0 ? "eletrônicos" : "outros",
  preco: Math.random() * 2000
}));

Agora, faremos a indexação da lista acima:

const produtosIndexados = listaGiganteDeProdutos.reduce((acc, p) => {
  acc[p.id] = p;
  return acc;
}, {});

E agora, o embate: Acesso Não Indexado VS Acesso Indexado! Vamos usar console.time() e console.timeEnd() antes e depois dos nossos acessos para registrar o tempo decorrido em cada um:

// Acesso não indexado: O(n)
console.time("Sem indexação (modo tartaruga 🐢)");
for (let i = 0; i < 1000; i++) {
  const id = Math.floor(Math.random() * 10000) + 1;
  listaGiganteDeProdutos.find(p => p.id === id);
}
console.timeEnd("Sem indexação (modo tartaruga 🐢)");

// Busca indexada: O(1)
console.time("Com indexação (modo foguete 🚀)");
for (let i = 0; i < 1000; i++) {
  const id = Math.floor(Math.random() * 10000) + 1;
  produtosIndexados[id];
}
console.timeEnd("Com indexação (modo foguete 🚀)");

Spoiler: a versão indexada normalmente é centenas de vezes mais rápida em conjuntos grandes, com diferenças cada vez mais pronunciadas conforme o tamanho do conjunto de dados aumenta. Saca só:

Nosso exemplo rodou cerca de 350x mais rápido com indexação!

O preço da velocidade

Claro, nada é de graça nessa vida. A indexação tem seu custo em memória adicional, pois você está praticamente duplicando as referências dos dados. Em aplicações com restrições severas de memória, este trade-off deve ser considerado cuidadosamente:

Uma estrutura indexada simples (por ID) aproximadamente dobra o uso de memória;
Índices multi-valor multiplicam esse custo;
Índices parciais (apenas com campos necessários em vez do objeto completo) podem reduzir esse impacto;

A indexação aumenta o consumo de memória, mas geralmente o ganho de performance compensa, especialmente em aplicações web e mobile.

A chave é encontrar o equilíbrio entre performance, legibilidade do código e uso de memória. Nem sempre a solução mais complexa é a melhor.

Quando não indexar

Nem sempre a indexação é necessária:

Conjuntos de dados muito pequenos (<100 itens): em conjuntos pequenos, a diferença entre a busca indexada e a busca padrão reflete pouco ganho de performance;
Buscas realizadas com raridade: não compensa o gasto com memória;
Protótipos e projetos iniciais: foque no básico que funciona.

Um extra: Objetos vs Maps

Se você tá lidando com algumas centenas de itens: relaxa, qualquer um dos dois vai voar. Mas se você tá com milhares ou milhões: aí sim começa a fazer diferença. Maps geralmente levam vantagem em operações frequentes de adição/remoção e quando você precisa iterar sobre tudo.

Objeto: O clássico que não sai de moda

😁 Vantagens:

Todo mundo sabe usar;
Tem integração nativa com JSON (podem ser facilmente convertidos);
Acesso facilitado com obj[key];
Performance sólida que não deixa na mão.

😬 Desvantagens:

Só aceita strings e Symbols como chave;
Não tem métodos nativos pra manipulação, apenas funções auxiliares;
Pode ser complicado conseguir o tamanho sem usar Object.keys();

🤔 Quando usar:

Quando precisar de integração direta com JSON;
Pra estruturas de dados mais simples;
Se as chaves forem sempre strings;
Quando performance de leitura for a prioridade.

Map: O primo moderninho

😁 Vantagens:

Aceita qualquer coisa como chave (até objetos, imagina!);
Mantém a ordem que você inseriu (tem TOC? Esse é pra você);
Vem com métodos úteis de fábrica, como .set(), .get(), .has(), etc;
Performance melhor pra manipulações e iterações frequentes.

😬 Desvantagens:

Boa parte da galera ainda não conhece muito bem;
Se precisar usar JSON, precisa de conversão manual;
Tem suporte limitado pra browsers mais antigos (mas quem ainda usa IE?).

🤔 Quando usar:

Pra estruturas de dados mais complexas;
Quando precisar de outros tipos de chave além de strings;
Quando a ordem de inserção for importante (meu TOC agradece);
Quando performance de manipulação e iteração for prioridade.

Conclusão

Transformar arrays em estruturas indexadas pode parecer um trabalho extra no começo, mas o ganho de performance é tão absurdo que você vai se perguntar como viveu tanto tempo sem fazer isso.

A diferença entre um app que trava e um que flui como manteiga no pão quente muitas vezes está na forma como organizamos os dados. Com as técnicas deste artigo, você pode reduzir tempos de busca de centenas de milissegundos para apenas alguns milissegundos, melhorando significativamente a experiência do usuário.

Lembre-se: em desenvolvimento, preguiça estratégica (fazer o trabalho pesado uma vez só, na indexação inicial) quase sempre compensa. Seu app fica mais rápido, seus usuários mais felizes, e você com mais tempo para tomar aquele café enquanto admira seu código otimizado. 😎

Dica Final: Sempre meça a performance antes e depois das otimizações. Ferramentas de profiling do navegador são suas melhores amigas nessa jornada. Um xero!

Explorando Promises: .all vs .allSettled / .race vs .any

Angela Caldas — Mon, 11 Nov 2024 23:38:46 +0000

Read it in English

As Promises surgiram em 2015, com o lançamento da especificação ECMAScript 6 (ES2015) do JavaScript, para deixar nossa experiência como desenvolvedor menos complicada ao lidar com operações assíncronas.

Se você estuda ou trabalha com JavaScript, com certeza já usou um Promise.all() ou um Promise.race() por aí. E pra facilitar ainda mais a vida do desenvolvedor, com o lançamento de versões mais atuais do JavaScript, tivemos acesso a dois novos métodos de Promises: Promise.allSettled() e Promise.any() (ES11 e ES2021, respectivamente).

Mas qual a diferença entre eles e quando devemos usar cada um?

Sumário

Promise.all vs Promise.allSettled: foco no resultado
Promise.race vs Promise.any: foco na velocidade

Promise.all vs Promise.allSettled: foco no resultado

Imagine que você está desenvolvendo uma aplicação que, em determinado momento, precisa executar diferentes chamadas à API. Se essas chamadas forem independentes entre si, uma boa opção seria executar todas as chamadas simultaneamente, melhorando a performance da aplicação, além de deixar o código mais conciso.

Promise.all()

Recebe um array de Promises como argumento;
Executa as operações simultaneamente (em paralelo);
Resolve quando todas as Promises são resolvidas com sucesso;
Rejeita imediatamente se uma das Promises falhar, bloqueando a execução das Promises seguintes.

async function buscarDadosParalelo() {  
  const [usuarios, produtos] = await Promise.all([
    fetch('/api/usuarios').then(resp => resp.json()),
    fetch('/api/produtos').then(resp => resp.json()),
  ]);

  return { usuarios, produtos };
}

O Promise.all() é bastante útil quando você precisa garantir que todas as Promises tenham sucesso e a função receba todos os resultados que precisa antes de executar alguma outra ação.

Promise.allSettled()

Também recebe um array de Promises como argumento;
Também executa as operações simultaneamente (em paralelo);
Resolve quando todas as Promises finalizam sua execução, seja com sucesso ou falha, retornando um objeto para cada Promise contendo o status desta (fulfilled ou rejected);
Nunca rejeita e, consequentemente, não bloqueia a execução das Promises.

async function buscarDadosParaleloComFalhas() {   
  const resultados = await Promise.allSettled([
    fetch('/api/usuarios').then(resp => resp.json()),
    fetch('/api/produtos').then(resp => resp.json()),
  ]);

    // Verificar cada resultado individualmente:
  const dados = resultados.map(resultado => {
    if (resultado.status === 'fulfilled') {
      return resultado.value;
    } else {
      console.error(resultado.reason);
      return null;
    }
  });

  return dados;
}

O Promise.allSettled() não bloqueia a aplicação caso alguma Promise finalize com falha, além de permitir tratamento individual do sucesso ou erro de cada chamada. Ele é como um relatório de status, que aguarda todas as requisições resolverem ou rejeitarem e permite ao usuário avaliar e tratar cada caso.

Voltar ao sumário

Promise.race vs Promise.any: foco na velocidade

Por outro lado, quando falamos de Promise.race() e Promise.any(), estamos falando de abordagens para lidar com a primeira resposta em um conjunto de operações assíncronas.

Promise.race()

Recebe um array de Promises como argumento;
Executa as operações simultaneamente (em paralelo);
Retorna a primeira Promise que for concluída OU rejeitada.

async function buscarDadosUsuario() {
  const timeout = new Promise((_, reject) => {
    setTimeout(() => reject('Timeout!'), 5000);
  });

  try {
    // Usa race para pegar o primeiro resultado disponível
    const resultado = await Promise.race([
      buscarCache,
      buscarBancoLocal,
      buscarAPI,
      timeout
    ]);

    return resultado;
  } catch (erro) {
    console.log(erro);
    // A execução para aqui se houver erro
  }
}

O Promise.race() é bastante útil quando precisamos de uma resposta rápida — o primeiro retorno disponível, independente de ser sucesso ou erro. Também é bastante utilizado com timeouts, como no exemplo acima, para garantir que tenhamos qualquer resposta dentro de um limite de tempo e possamos evitar que requisições lentas continuem consumindo recursos.

Promise.any()

Também recebe um array de Promises como argumento;
Executa as operações simultaneamente (em paralelo);
Retorna a primeira Promise que for concluída com sucesso, ignorando as rejeições;
Só rejeita se todas as Promises forem rejeitadas.

async function buscarDadosUsuario() {
  try {
    // Retorna a primeira busca que responder com sucesso
    const resultado = await Promise.any([
      buscarCache,
      buscarBancoLocal,
      buscarAPI
    ]);

    return resultado;
  } catch (erro) {
    console.log(erro);
    // Só cai aqui se TODAS as buscas falharem
  }
}

O Promise.any() é útil quando você precisa que pelo menos uma das requisições seja concluída com sucesso, sendo ideal para fallbacks e redundâncias, como carregar um recurso de múltiplas fontes (CDN, local, etc.) ou conectar-se a diferentes servidores em caso de falha.

Voltar ao sumário

Em um mundo digital cada vez mais assíncrono, entender como gerenciar múltiplas operações simultâneas em JavaScript tornou-se uma habilidade essencial para desenvolvedores. Nesse artigo, exploramos com alguns exemplos alguns métodos importantes das Promises, mostrando como cada um deles funciona e, mais importante, quando e por que você deveria escolher um em detrimento do outro.

Até a próxima (e prometo que volto em breve)!

Vue3: directives — cheat sheet (built-in and custom) (en)

Angela Caldas — Tue, 01 Oct 2024 19:49:01 +0000

Ler em pt/br

One of the advantages of Vue is the ease of manipulating the DOM through special attributes called Directives. In addition to having several built-in directives, Vue also allows us to create custom ones.

If you're tired of using querySelector's and addEventListener's, then this article is for you!

Want to get straight to the point?
What are directives?
Creating custom directives
Creating local custom directives
Importing an external custom directive into a component
Declaring custom directives globally
Custom directives with modifiers
Phew! I think we've seen enough...

Want to see a specific directive?

v-text v-html v-show v-if / v-else-if / v- else v-for v-on

v-bind v-model v-slot v-pre v-once v-memo v-cloak

What are directives?

Directives are nothing more than template-manipulating attributes used in HTML tags. With them, we can dynamically alter our DOM, adding or omitting information and elements (Leonardo Vilarinho in Front-end com Vue.js: Da teoria à prática sem complicações).

Vue has a large number of built-in directives. To better understand how to use them, we'll walk through some practical examples for each one (you can also directly access some examples in Vue’s documentation).

Back to table of contents

v-text

<h1 v-text="title"></h1>
<!-- is the same as -->
<h1>{{ title }}</h1>

The v-text directive is used to insert a textContent into an element and works exactly the same as mustache interpolation ({{ }}). The difference in usage between them is that v-text will replace the entire textContent of the element, while interpolation allows you to replace only parts of the content.

Back to table of contents

v-html

<script setup>
import { ref } from "vue"
const myTitle = ref("<h1>Title</h1>")
</script>

<template>
  <div v-html="myTitle"></div>
</template>

<!--
The code above will render:
<div>
  <h1>Title</h1>
</div>
 -->

The v-html directive is used to inject dynamic HTML into another element (equivalent to using innerHTML in JavaScript). It's a directive that should be used with caution, as it can allow for XSS (Cross-site Scripting) attacks, where malicious code can be injected into your application's DOM.

Back to table of contents

v-show

<script setup>
import { ref } from "vue"
const visible = ref(true)
</script>

<template>
  <div>
    <button @click="visible = !visible">Hide/Show</button>
    <p v-show="visible">Lorem ipsum</p>
  </div>
</template>

The v-show directive dynamically changes the element's display property based on the received value. In the example above, when the visible state is true, the paragraph receives display: block (the default display of a <p> element). Clicking the button changes the visible state to false and assigns display: none to the paragraph.

Back to table of contents

v-if / v-else-if / v-else

<p v-if="type === 'A'">A paragraph</p>
<a v-else-if="type === 'B'" href="#">A link</a>
<ErrorComponent v-else />

Considered as some of the most used directives in Vue, v-if, v-else-if, and v-else, are used for dynamic rendering of components and elements and follow the same logic as if, else if, and else in vanilla JavaScript. In the example, if type is 'A', we render a paragraph; however, if it's 'B', we render an anchor; and in any other case, we render a component called ErrorComponent.

Note: Elements managed by v-if, v-else-if, and v-else are completely destroyed or reconstructed in the DOM according to the condition met, unlike v-show which only changes the element's display.

Back to table of contents

v-for

<script setup>
import { ref } from "vue"
const users = ref([
  { name: 'John' },
  { name: 'Jane' }
])
</script>

<template>
  <p v-for="user in users">
    {{ user.name }}
  </p>
</template>

The v-for directive renders a list of elements or components by iterating over an array or object, similar to a forEach. In our example:

we have an array of objects called users;
using the v-for directive, we iterate over this array using the variable in expression syntax to access each element of the iteration;
each user will be an object from our array. Thus, we will have two users, resulting in two paragraphs;
each paragraph will render the value of the name key of each user.

An important point about v-for is that we need to provide a special :key attribute, which must receive a unique value. This value can be derived directly from our user or we can use the index of our array (which is not recommended if you need to manipulate the items in the array, as it can result in errors).

<!-- using an unique value from 'user' -->
<p v-for="user in users" :key="user.name">
  {{ user.name }}
</p>

<!-- using the array index -->
<p v-for="(user, index) in users" :key="index">
  {{ user.name }}
</p>

Back to table of contents

v-on

<button v-on:click="handleClick">Click</button>
<button @click="handleClick">Click</button>

<input type="text" v-on:focus="handleFocus" />
<input type="text" @focus="handleFocus" />

<!-- events with modifiers -->
<button type="submit" @click.prevent="submit">Send</button>
<input @keyup.enter="handleEnterKey" />

The v-on directive (or simply @ as a shorthand) adds an "event listener" to HTML elements, similar to what we would do with JavaScript's addEventListener.

Any standard JavaScript event can be used with the v-on directive, which also accepts behavior modifiers and/or key modifiers.

In the code block above, we have some examples of events, such as v-on:click (or @click) and v-on:focus (or @focus), and we also show some events with modifiers, like .prevent (referring to event.preventDefault()) and .enter (which identifies the "Enter" key for the keyup event).

Back to table of contents

v-bind

<!-- Dynamic attributes -->
<img v-bind:src="imgSrc" />
<img :src="imgSrc" />
<img :src /> <!-- equivalent to :src="src" -->

<!-- Dynamic classes -->
<div :class="myClasses"></div>
<div :class="{ myClass: isValid }"></div>
<!-- Results in <div class="red"></div> if `isRed` is truthy -->

<!-- Props for child components -->
<ChildComponent :prop="myProp" />

The v-bind directive is used to create/bind dynamic HTML attributes to elements or to pass props to child components. The v-bind directive can be abbreviated to just : as a shorthand.

In our examples, we have:

An imgSrc state used as the src attribute of an image, as well as a myClasses state used as a dynamic class;
The shortened form :src, for when the variable name is the same as the attribute name;
An example of dynamically assigning a "myClass" class if the isValid state is truthy;
An example of a myProp prop being passed to a child component.

Back to table of contents

v-model

<script setup>
import { ref } from "vue"
const message = ref("")
</script>

<template>
  <input type="text" v-model="message" />
</template>

The v-model directive creates two-way data bindings, making it easy to synchronize states between inputs, selects, and components.

In the example above, the message state is bound to an <input> via v-model, so when you type in the input, the value of message is automatically updated with what was typed. Similarly, if we have a function that changes the value of message, for example, the input will reflect that change.

We can also use v-model to create this two-way binding from parent to child component:

<!-- passing props as readonly -->
<ChildComponent :msg="message" />

<!-- passing props with two-way data binding -->
<ChildComponent v-model="message" />
<!-- or -->
<ChildComponent v-model:msg="message" />

Back to table of contents

v-slot

<!-- child component with named slots -->
<div>
  <slot name="title" />
  <slot name="message" />
</div>

<!-- parent component -->
<ChildComponent>
  <template v-slot:title>
    <h1>My title</h1>
  </template>
  <template #message>
    <p>Lorem ipsum</p>
  </template>
</ChildComponent>

The v-slot directive is used to define and use slots in components. Slots are a way to pass content to a child component more flexibly than through props and can be named or unnamed, helping you insert elements into the child component in the correct places.

In the example above, we have a ChildComponent consisting of a div that encompasses two named slots: title and message. When using the child component, we pass two elements (h1 and p) to it through templates that use the v-slot directive with the name of the slot we want each element to receive. The v-slot directive can be abbreviated with the # symbol.

Back to table of contents

v-pre

<script setup>
import { ref } from "vue"
const message = ref("A simple message")
</script>

<template>
  <p>{{ message }}</p>
  <p v-pre>{{ message }}</p> 
</template>

The v-pre directive ignores the compilation of the element it's used on, as well as all its child elements, rendering the content that would be dynamic as plain text (the first paragraph will render A simple message while the second paragraph will render {{ message }}).

Back to table of contents

v-once

<div v-once>
  <h1>Comment</h1>
  <p>{{msg}}</p>
</div>

The v-once directive helps with performance by rendering the content of an element only once, making it static thereafter. Above, the paragraph will render the msg state only once and will remain static even if the value of msg changes later.

Back to table of contents

v-memo

<script setup>
import { ref, computed } from "vue"
const count = ref(0)
function calculate() {
  return // Some logic which uses `count`
}
</script>

<template>
  <div v-memo="[count]">
    {{ calculate() }}
  </div>
</template>

The v-memo directive is somewhat similar to v-once, but it limits the re-rendering of the element or component to changes in one or more states, which must be passed as dependencies of the directive. In our example, we have a calculate function whose result should be rendered inside the div. However, this re-rendering should only occur if the value of count is updated, as it is referenced in the v-memo directive as a dependency.

The v-memo directive caches the content and only updates it if one of its dependencies is updated. This is exactly what happens with computed properties.

This directive is used for micro-optimizations of rendering, used more commonly in more complex components. However, if your component's logic is following best practices, the need to use v-memo becomes almost nonexistent.

For example, if calculate were a computed property, we wouldn't need v-memo, as computed properties do exactly what the directive does: they cache values and only update them again when dependencies change:

<script setup>
// omitted code
const calculate = computed(() => {
  return // Some logic which uses `count`
})
</script>

<template>
  <div>{{ calculate }}</div>
</template>

Back to table of contents

v-cloak

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- omitted code -->
  <style>
    [v-cloak] {
      display: none;
    }
  </style>
</head>

<body>
  <div id="app">
    <p v-cloak>{{ message }}</p>
  </div>

  <script src="https://unpkg.com/vue@3"></script>
  <script>
    const app = Vue.createApp({
      data() {
        return {
          message: 'Hello, World!'
        }
      }
    })

    app.mount('#app')
  </script>
</body>
</html>

The v-cloak directive prevents uncompiled content from being rendered on the screen until Vue finishes its initialization (which typically happens when creating a Vue application directly in an HTML file via CDN). In the example above, the v-cloak directive will hide the paragraph until the message state is initialized and the component is fully mounted.

Back to table of contents

Creating custom directives

Custom directives allow you to bind Vue states to HTML elements, manipulating them according to your application's business rules. This way, you'll have greater control over the application's layout.

These directives are defined as an object that contains lifecycle hooks (the same ones we use in components), and each hook receives the element on which the directive will be used. The Vue documentation offers very easy-to-understand examples.

Creating local custom directives

<template>
  <input v-focus />
</template>

<!-- Options API -->
<script>
export default {
  directives: {
    focus: {
      mounted: (el) => el.focus()
    }
  }
}
</script>

<!-- Composition API -->
<script setup>
const vFocus = { mounted: (el) => el.focus() }
</script>

Here we have a local custom directive called v-focus that automatically focuses on an input when the component is mounted. With the Options API, we need to declare our directive inside the directives object, but in the Composition API, we simply create a variable (which must start with 'v').

Importing an external custom directive into a component

Imagine that you need to use the v-focus directive in multiple components. This would generate a lot of repeated code in your application, as you would have to redeclare the directive in every component where you intend to use it, right?

Let's finish those repeated codes off!

To avoid this repetition, we can extract the logic of our new directive to a file in the directives folder:

// src/directives/v-focus.js
export const vFocus = {
  mounted: (el) => el.focus()
};

Now, just import the directive into the desired component and use it:

<template>
  <input v-focus />
</template>

<!-- Options API -->
<script>
import { vFocus } from '@/directives/v-focus.js';

export default {
  directives: {
    focus: vFocus
  }
}
</script>

<!-- Composition API -->
<script setup>
import { vFocus } from '@/directives/v-focus.js';
</script>

Declaring custom directives globally

If you need to use a particular custom directive very often, a more suitable solution might be to declare it globally in your main.js or main.ts file:

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import { vFocus } from '@/directives/v-focus.js'

const app = createApp(App)

// You can import the directive from an external file:
app.directive('focus', vFocus)

// Or you can declare ir directly like this:
app.directive('focus', {
  mounted: (el) => el.focus()
})

app.mount('#app')

Back to table of contents

Custom directives with modifiers

So far, we've learned how to create simple custom directives. But what if you want a more complex directive that has action modifiers, like @click.prevent?

A directive can have up to four types of attributes that can be used in its declaration, with the most important (and our focus in this article) being the following:

el: The element on which the directive is being used (as we saw in vFocus); and
binding: Object containing various properties that we can use in our directives, such as value (the value passed in the directive) and modifiers, which is what we will use to create our modifiers.

For example, if we have the directive <div v-example:foo.bar="one">, our binding object would be:

{
  arg: 'foo',
  modifiers: { bar: true },
  value: 'one',
  oldValue: /* any previous value from the directive */
}

Let's see how to create a directive to format text in uppercase, lowercase, or capitalized letters.

1. We create the initial structure of the vFormat directive, which will execute actions when the element is mounted in the component. Note that we are using el and binding as parameters of our hook:

// src/directives/vFormat.js
export const vFormatText = {
  mounted: (el, binding) => {},
}

2. We'll create a modifier variable that will identify the modifier used in the directive. When we use a modifier in a directive, they are saved in a modifiers object within the binding object. So, if we use v-format.uppercase, binding.modifiers will be { uppercase: true } and the value of the modifier variable will be uppercase:

// src/directives/vFormat.js
export const vFormatText = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];
  },
}

3. Now we'll create the actions variable, which contains the text formatting functions for our directive. We'll capture the innerText of the element the directive will be used on and format it to uppercase, lowercase, or capitalized:

// src/directives/vFormat.js
export const vFormatText = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];

    const actions = {
      uppercase() {
        el.innerHTML = el.innerHTML.toUpperCase();
      },
      lowercase() {
        el.innerHTML = el.innerHTML.toLowerCase();
      },
      capitalized() {
        const txt = el.innerHTML.split(" ");
        el.innerHTML = "";

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML +=
            txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + " ";
        }
      },
    };
  },
}

4. Finally, let's identify the modifier and execute the function that corresponds to it:

// src/directives/vFormat.js
export const vFormatText = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];

    const actions = {
      uppercase() {
        el.innerHTML = el.innerHTML.toUpperCase();
      },
      lowercase() {
        el.innerHTML = el.innerHTML.toLowerCase();
      },
      capitalized() {
        const txt = el.innerHTML.split(" ");
        el.innerHTML = "";

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML +=
            txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + " ";
        }
      },
    };

    if (modifier in actions) {
      const action = actions[modifier];
      action();
    }
  },
}

Great! Our v-format directive is complete and ready to be used in a component. Let's see an example:

<script setup>
import { vFormatar } from "@/directives/vFormatar.js"
</script>

<template>
  <p v-format.uppercase>My text</p> <!-- "MY TEXT" -->
  <p v-format.lowercase>My text</p> <!-- "my text" -->
  <p v-format.capitalized>My text</p> <!-- "My Text" -->
</template>

How about seeing how this directive would be with the Options API?

// src/directives/vFormat.js
export default {
  mounted: function(el, binding) {
    const modifier = Object.keys(binding.modifiers)[0]
    const actions = {
      uppercase() {
        el.innerHTML = el.innerHTML.toUpperCase()
      },
      lowercase() {
        el.innerHTML = el.innerHTML.toLowerCase()
      },
      capitalized() {
        let txt = el.innerHTML.split(' ')
        el.innerHTML = ''

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML += txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + ' '
        }
      },
    }

    if(modifier in actions) {
      const action = actions[modifier]
      action()
    }
  }
}

Using the directive in a component:

<script>
import vFormat from "@/directives/vFormat"

export default {
  directives: { format: vFormat }
}
</script>

<template>
  <p v-format.uppercase>My text</p> <!-- "MY TEXT" -->
  <p v-format.lowercase>My text</p> <!-- "my text" -->
  <p v-format.capitalized>My text</p> <!-- "My Text" -->
</template>

And always remember that you can also register the directive globally in the main.js file:

import vFormat from "./directives/vFormat";

const app = createApp(App)
app.directive('format', vFormat)
app.mount('#app')

Back to table of contents

Phew! I think we've seen enough...

Creating custom directives which are more complet may seem a bit confusing at first, but nothing that practice can't solve!

Knowing how to use Vue's built-in directives will be essential for your Vue application to always have great performance when dealing with component rendering and DOM manipulation, as well as being great for your developer experience, making your work easier and your code more elegant.

However, never say never, my young Padawan. In more complex situations, you may realize that a querySelector can still be a lifesaver from time to time!

I hope this article is helpful. See you next time!

Vue3: diretivas — cheat sheet (built-in e custom)

Angela Caldas — Thu, 22 Aug 2024 19:33:41 +0000

Read it in English

Uma das vantagens do Vue é a facilidade de manipular o DOM através de atributos especiais que chamamos de Diretivas. Além de ter várias delas embutidas, o Vue também permite que criemos diretivas personalizadas.

Se você está cansado de usar querySelector's e addEventListener's, então esse artigo é pra você!

Sumário

Quer ir direto ao ponto?
O que são diretivas?
Como criar diretivas customizadas
Criando diretivas customizadas locais
Importando uma diretiva customizada externa no componente
Declarando custom directives globalmente
Diretivas customizadas com modificadores
Ufa! Acho que vimos o suficiente...

Quer ver uma diretiva específica?

v-text v-html v-show v-if / v-else-if / v- else v-for v-on

v-bind v-model v-slot v-pre v-once v-memo v-cloak

O que são diretivas?

As Diretivas nada mais são que atributos manipuladores de templates usadas nas tags do HTML. Com elas, podemos alterar dinamicamente nosso DOM, acrescentando ou omitindo informações e elementos (Leonardo Vilarinho em Front-end com Vue.js: Da teoria à prática sem complicações).

O Vue possui uma grande quantidade de diretivas embutidas. Pra saber mais como usá-las, vamos mostrar aqui alguns exemplos práticos pra cada uma delas (você também pode acessar diretamente alguns exemplos na documentação do Vue).

Voltar ao sumário

v-text

<h1 v-text="title"></h1>
<!-- é o mesmo que -->
<h1>{{ title }}</h1>

A diretiva v-text é usada para inserir um textContent em um elemento e funciona exatamente igual à interpolação com mustache ({{ }}). A diferença de uso entre eles é que o v-text vai substituir todo o textContent do elemento, e a interpolação permite que você substitua apenas partes do conteúdo.

Voltar ao sumário

v-html

<script setup>
import { ref } from "vue"
const myTitle = ref("<h1>Título</h1>")
</script>

<template>
  <div v-html="myTitle"></div>
</template>

<!--
O código acima vai renderizar:
<div>
  <h1>Título</h1>
</div>
 -->

A diretiva v-html é usada para injetar um HTML dinâmico dentro de outro elemento (equivalente ao que acontece quando usamos innerHtml no JavaScript). É uma diretiva que deve ser usada com cautela, pois pode permitir ataques XSS (Cross-site Scripting), onde códigos maliciosos podem ser inseridos no DOM da sua aplicação.

Voltar ao sumário

v-show

<script setup>
import { ref } from "vue"
const visivel = ref(true)
</script>

<template>
  <div>
    <button @click="visivel = !visivel">Ocultar/Mostrar</button>
    <p v-show="visivel">Lorem ipsum</p>
  </div>
</template>

A diretiva v-show altera o display do elemento dinamicamente dependendo do valor recebido. No exemplo acima, quando o estado visivel é true, o parágrafo recebe display: block (display padrão do elemento <p>). Ao clicar no botão, o estado visivel recebe vira false e atribui ao parágrafo o display: none.

Voltar ao sumário

v-if / v-else-if / v-else

<p v-if="type === 'A'">Um parágrafo</p>
<a v-else-if="type === 'B'" href="#">Um link</a>
<ErrorComponent v-else />

Algumas das diretivas mais utilizadas no Vue, v-if, v-else-if e v-else são utilizadas para renderização dinâmica de componentes e elementos e seguem a mesma lógica de if, else if e else no JavaScript vanilla. No exemplo, se type for 'A', renderizamos um parágrafo; no entanto, se for 'B', renderizamos uma âncora; e em qualquer outro caso, renderizamos um componente chamado ErrorComponent.

Nota: Os elementos gerenciados através de v-if, v-else-if e v-else são totalmente destruídos ou reconstruídos no DOM de acordo com a condição alcançada, diferente do v-show que apenas muda o display do elemento.

Voltar ao sumário

v-for

<script setup>
import { ref } from "vue"
const users = ref([
  { name: 'John' },
  { name: 'Jane' }
])
</script>

<template>
  <p v-for="user in users">
    {{ user.name }}
  </p>
</template>

A diretiva v-for renderiza uma lista de elementos ou componentes ao iterar com um array ou um objeto, similar a um forEach. No nosso exemplo:

temos um array de objetos chamado users;
com a diretiva v-for, iteramos por esse array usando a sintaxe variavel in expressao para acessar cada elemento da iteração;
cada user será um objeto de nosso array. Dessa forma, teremos dois user, que resultarão em dois parágrafos;
cada parágrafo vai renderizar o valor da chave name de cada user.

Um ponto importante do v-for é que precisamos fornecer um atributo especial :key, que deve receber um valor único. Esse valor pode ser derivado diretamente do nosso user ou podemos utilizar o index do nosso array (que não é recomendado caso você precise manipular os itens do array, pois pode resultar em erros):

<!-- usando um valor único de 'user' -->
<p v-for="user in users" :key="user.name">
  {{ user.name }}
</p>

<!-- usando o índice do array -->
<p v-for="(user, index) in users" :key="index">
  {{ user.name }}
</p>

Voltar ao sumário

v-on

<button v-on:click="handleClick">Clique</button>
<button @click="handleClick">Clique</button>

<input type="text" v-on:focus="handleFocus" />
<input type="text" @focus="handleFocus" />

<!-- eventos com modificadores -->
<button type="submit" @click.prevent="submit">Enviar</button>
<input @keyup.enter="handleEnterKey" />

A diretiva v-on (ou apenas @, como atalho) adiciona um "escutador de eventos" aos elementos HTML, semelhante ao que faríamos com o addEventListener do JavaScript.

Qualquer evento padrão do JavaScript pode ser utilizado com a diretiva v-on, que também aceita modificadores de comportamentos e/ou modificadores de teclas.

No bloco de código acima, temos alguns exemplos de eventos, como v-on:click (ou @click) e v-on:focus (ou @focus), e também mostramos alguns eventos com modificadores, como .prevent (referente a event.preventDefault()) e .enter (que identifica a tecla "Enter" para o evento de keyup).

Voltar ao sumário

v-bind

<!-- Atributos dinâmicos -->
<img v-bind:src="imgSrc" />
<img :src="imgSrc" />
<img :src /> <!-- equivale a :src="src" -->

<!-- Classes dinâmicas -->
<div :class="myClasses"></div>
<div :class="{ myClass: isValid }"></div>
<!-- Resulta em <div class="red"></div> se `isRed` for truthy -->

<!-- Props para componentes-filhos -->
<ChildComponent :prop="myProp" />

A diretiva v-bind é utilizada para criar/vincular atributos HTML dinâmicos aos elementos ou para enviar propriedades (props) para componentes-filhos. A diretiva v-bind pode ser substituída apenas por : como atalho.

Nos nossos exemplos, temos:

Um estado imgSrc utilizado como atributo src de uma imagem, bem como um estado myClasses utilizado como classe dinâmica;
A forma reduzida :src, para o caso do nome da variável ser igual ao nome do atributo;
Exemplo de atribuição dinâmica de uma classe "myClass" caso o estado isValid seja truthy.
Exemplo de uma prop myProp sendo passada para um componente-filho.

Voltar ao sumário

v-model

<script setup>
import { ref } from "vue"
const message = ref("")
</script>

<template>
  <input type="text" v-model="message" />
</template>

A diretiva v-model cria vínculos bidirecionais (two-way data binding), facilitando a sincronização de estados entre inputs, selects e componentes.

No exemplo acima, o estado message é vinculado a um <input> através da v-model, logo, quando digitarmos no input, o valor de message é automaticamente atualizado com o que foi digitado. Da mesma forma, se tivermos uma função que altere o valor de message, por exemplo, o input vai refletir essa alteração.

Podemos usar o v-model também para criar esse vínculo bidirecional de componente-pai para componente-filho:

<!-- passando props como somente leitura -->
<ChildComponent :msg="message" />

<!-- passando props com vínculo bidirecional -->
<ChildComponent v-model="message" />
<!-- ou -->
<ChildComponent v-model:msg="message" />

Voltar ao sumário

v-slot

<!-- componente-filho com slots nomeados -->
<div>
  <slot name="title" />
  <slot name="message" />
</div>

<!-- componente-pai -->
<ComponenteFilho>
  <template v-slot:title>
    <h1>Meu título</h1>
  </template>
  <template #message>
    <p>Lorem ipsum</p>
  </template>
</ComponenteFilho>

A diretiva v-slot serve para definir e usar named slots em componentes. Slots são uma forma de passar conteúdo para um componente filho de forma mais flexível do que através de props e que podem ou não receber um nome para identificá-los, ajudando-o a inserir os elementos no componente-filho nos locais corretos.

No exemplo acima, temos um ComponenteFilho que consiste em uma div que engloba dois named slots: title e message. Ao usar o componente-filho, passamos dois elementos (h1 e p) para ele através de templates que utilizam a diretiva v-slot com o nome do slot que queremos que receba cada elemento. A diretiva v-slot pode ser abreviada com o símbolo #.

Voltar ao sumário

v-pre

<script setup>
import { ref } from "vue"
const message = ref("Uma mensagem qualquer")
</script>

<template>
  <p>{{ message }}</p>
  <p v-pre>{{ message }}</p> 
</template>

A diretiva v-pre ignora a compilação do elemento em que é usado, bem como todos os seus elementos-filhos, renderizando na tela o conteúdo que seria dinâmico como texto simples (o primeiro parágrafo renderizará Uma mensagem qualquer enquanto que o segundo parágrafo renderizará {{ message }}).

Voltar ao sumário

v-once

<div v-once>
  <h1>Comentário</h1>
  <p>{{msg}}</p>
</div>

A diretiva v-once auxilia em questões de performance fazendo com que o conteúdo de um elemento renderize apenas uma vez, se tornando estático logo em seguida. Acima, o parágrafo vai renderizar o estado msg apenas uma vez e permanecerá estático mesmo que o valor de msg mude posteriormente.

Voltar ao sumário

v-memo

<script setup>
import { ref, computed } from "vue"
const count = ref(0)
function calculate() {
  return // Lógica que utiliza `count`
}
</script>

<template>
  <div v-memo="[count]">
    {{ calculate() }}
  </div>
</template>

A diretiva v-memo é um pouco parecida com a v-once, porém ela limita a re-renderização do elemento ou componente a alterações em um ou mais estados, que devem ser passados como dependências da diretiva. No nosso exemplo, temos uma função calculate cujo resultado deve ser renderizado dentro da div. No entanto, essa re-renderização só deve ocorrer caso o valor de count seja atualizado, pois ele está referenciado na diretiva v-memo como dependência.

A diretiva v-memo salva o conteúdo em cache e só o atualiza se uma das suas dependências sofrer atualização. Exatamente o que acontece com as computed properties.

Essa diretiva serve para micro-otimizações de renderização, utilizada mais comumente em componentes mais complexos. No entanto, se a lógica do seu componente estiver seguindo as boas práticas, a necessidade de uso de v-memo se torna quase inexistente.

Por exemplo, se calculate fosse uma computed property, não precisaríamos de v-memo, pois as propriedades computadas fazem exatamente o que a diretiva faz: salva valores em cache e só as atualiza novamente quando as dependências mudam:

<script setup>
// código ocultado
const calculate = computed(() => {
  return // Lógica que utiliza `count`
})
</script>

<template>
  <div>{{ calculate }}</div>
</template>

Voltar ao sumário

v-cloak

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- código ocultado -->
  <style>
    [v-cloak] {
      display: none;
    }
  </style>
</head>

<body>
  <div id="app">
    <p v-cloak>{{ message }}</p>
  </div>

  <script src="https://unpkg.com/vue@3"></script>
  <script>
    const app = Vue.createApp({
      data() {
        return {
          message: 'Hello, World!'
        }
      }
    })

    app.mount('#app')
  </script>
</body>
</html>

A diretiva v-cloak evita que conteúdo não-compilado seja renderizado na tela até que o Vue finalize sua inicialização (o que normalmente acontece quando criamos uma aplicação Vue diretamente em um arquivo HTML via CDN. No exemplo acima, a diretiva v-cloak vai esconder o parágrafo até que o estado message seja inicializado e o componente esteja devidamente montado.

Voltar ao sumário

Como criar diretivas customizadas

Diretivas customizadas permitem vincular estados do Vue aos elementos HTML, manipulando-os às regras de negócio que sua aplicação possa ter. Dessa forma, você terá um maior controle do layout da aplicação.

Essas diretivas são definidas como um objeto que contém lifecycle hooks (os mesmos que usamos nos componentes), e cada hook recebe o elemento no qual a diretiva vai ser usada. A documentação do Vue oferece exemplos bem fáceis de entender.

Criando diretivas customizadas locais

<template>
  <input v-focus />
</template>

<!-- Options API -->
<script>
export default {
  directives: {
    focus: {
      mounted: (el) => el.focus()
    }
  }
}
</script>

<!-- Composition API -->
<script setup>
const vFocus = { mounted: (el) => el.focus() }
</script>

Aqui temos uma diretiva customizada local chamada v-focus que foca em um input automaticamente quando o componente for montado. Com a Options API, precisamos declarar nossa diretiva dentro do objeto directives, mas na Composition API, basta criarmos uma variável (que deve iniciar obrigatoriamente com v).

Importando uma diretiva customizada externa no componente

Imagine que você precisa usar a diretiva v-focus em vários componentes. Isso geraria um monte de código repetido na sua aplicação, pois você teria que redeclarar a diretiva em todos os componentes em que pretende usar, correto?

Vamos acabar com esses códigos repetidos.

Pra evitar essa repetição, podemos extrair a lógica da nossa nova diretiva para um arquivo na pasta directives:

// src/directives/v-focus.js
export const vFocus = {
  mounted: (el) => el.focus()
};

Agora, é só importar a diretiva no componente desejado e usá-la:

<template>
  <input v-focus />
</template>

<!-- Options API -->
<script>
import { vFocus } from '@/directives/v-focus.js';

export default {
  directives: {
    focus: vFocus
  }
}
</script>

<!-- Composition API -->
<script setup>
import { vFocus } from '@/directives/v-focus.js';
</script>

Declarando custom directives globalmente

Se você precisar usar demais uma determinada diretiva customizada, uma solução mais adequada pode ser declará-la globalmente no seu main.js ou main.ts:

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import { vFocus } from '@/directives/v-focus.js'

const app = createApp(App)

// Você pode importar a diretiva de um arquivo externo
app.directive('focus', vFocus)

// Ou você pode declará-la diretamente assim
app.directive('focus', {
  mounted: (el) => el.focus()
})

app.mount('#app')

Voltar ao sumário

Diretivas customizadas com modificadores

Até agora, aprendemos a criar diretivas customizadas simples. Mas e se você quiser uma diretiva mais complexa, que tenha modificadores de ações, como @click.prevent?

Uma diretiva pode ter até quatro tipos de atributos que podem ser utilizados em sua declaração, sendo os mais importantes (e nosso foco nesse artigo) os seguintes:

el: O elemento no qual a diretiva está sendo usado (como vimos no vFocus; e
binding: Objeto contendo várias propriedades que podemos usar em nossas diretivas, como value (o valor passado na diretiva) e modifiers, que é o que usaremos para criar nossos modificadores.

Por exemplo, se tivermos a diretiva <div v-exemplo:foo.bar="um">, o nosso objeto binding seria:

{
  arg: 'foo',
  modifiers: { bar: true },
  value: 'um',
  oldValue: /* qualquer valor anterior que a diretiva teve */
}

Vamos ver na prática como criar um diretiva para formatar o texto em letras maiúsculas, minúsculas ou capitalizadas.

1. Criamos a estrutura inicial da diretiva vFormatar, que vai executar ações quando o elemento for montado (mounted) no componente. Veja que estamos utilizando el e binding como parâmetros do nosso hook:

// src/directives/vFormatar.js
export const vFormatarTexto = {
  mounted: (el, binding) => {},
}

2. Criaremos uma variável modifier que vai identificar o modificador utilizado na diretiva. Quando usamos um modificador em uma diretiva, eles são salvos em um objeto modifiers dentro do objeto binding. Então, se usarmos v-formatar.maiusculo, binding.modifiers será { maiusculo: true } e o valor da variável modifier será maiusculo:

// src/directives/vFormatar.js
export const vFormatarTexto = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];
  },
}

3. Agora criaremos a variável actions, que contém as funções formatadoras de texto da nossa diretiva. Vamos capturar o innerText do elemento onde a diretiva será usada e formataremos para maiúsculo, minúsculo ou capitalizado:

// src/directives/vFormatar.js
export const vFormatarTexto = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];

    const actions = {
      maiusculo() {
        el.innerHTML = el.innerHTML.toUpperCase();
      },
      minusculo() {
        el.innerHTML = el.innerHTML.toLowerCase();
      },
      capitalizado() {
        const txt = el.innerHTML.split(" ");
        el.innerHTML = "";

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML +=
            txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + " ";
        }
      },
    };
  },
}

4. Por último, vamos identificar o modificador e executar a função que corresponde a ele:

// src/directives/vFormatar.js
export const vFormatarTexto = {
  mounted: (el, binding) => {
    const modifier = Object.keys(binding.modifiers)[0];

    const actions = {
      maiusculo() {
        el.innerHTML = el.innerHTML.toUpperCase();
      },
      minusculo() {
        el.innerHTML = el.innerHTML.toLowerCase();
      },
      capitalizado() {
        const txt = el.innerHTML.split(" ");
        el.innerHTML = "";

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML +=
            txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + " ";
        }
      },
    };

    if (modifier in actions) {
      const action = actions[modifier];
      action();
    }
  },
}

Prontinho! Nossa diretiva v-formatar está completa e já pode ser utilizada em um componente. Vamos a um exemplo:

<script setup>
import { vFormatar } from "@/directives/vFormatar.js"
</script>

<template>
  <p v-formatar.maiusculo>Meu texto</p> <!-- "MEU TEXTO" -->
  <p v-formatar.minusculo>Meu texto</p> <!-- "meu texto" -->
  <p v-formatar.capitalizado>Meu texto</p> <!-- "Meu Texto" -->
</template>

E que tal ver como seria essa diretiva com a Options API?

// src/directives/vFormatar.js
export default {
  mounted: function(el, binding) {
    const modifier = Object.keys(binding.modifiers)[0]
    const actions = {
      maiusculo() {
        el.innerHTML = el.innerHTML.toUpperCase()
      },
      minusculo() {
        el.innerHTML = el.innerHTML.toLowerCase()
      },
      capitalizado() {
        let txt = el.innerHTML.split(' ')
        el.innerHTML = ''

        for (let i = 0; i < txt.length; i++) {
          el.innerHTML += txt[i].substring(0, 1).toUpperCase() + txt[i].substring(1) + ' '
        }
      },
    }

    if(modifier in actions) {
      const action = actions[modifier]
      action()
    }
  }
}

Utilizando a diretiva em um componente:

<script>
import vFormatar from "@/directives/vFormatar"

export default {
  directives: { formatar: vFormatar }
}
</script>

<template>
  <p v-formatar.maiusculo>Meu texto</p> <!-- "MEU TEXTO" -->
  <p v-formatar.minusculo>Meu texto</p> <!-- "meu texto" -->
  <p v-formatar.capitalizado>Meu texto</p> <!-- "Meu Texto" -->
</template>

E sempre lembrando que você também pode registrar a diretiva de forma global no arquivo main.js:

import vFormatar from "./directives/vFormatar";

const app = createApp(App)
app.directive('formatar', vFormatar)
app.mount('#app')

Voltar ao sumário

Ufa! Acho que vimos o suficiente...

Criar diretivas customizadas mais completas pode parecer um pouco confuso num primeiro momento, mas nada que a prática não resolva!

Saber como usar as diretivas built-in do Vue vai ser essencial pra que sua aplicação Vue tenha sempre uma ótima performance ao lidar com renderizações de componentes e manipulação de informações no DOM, além de serem uma mão na roda pra sua experiência como desenvolvedor, deixando seu trabalho mais fácil e seu código mais elegante.

Porém, nunca diga nunca, jovem padawan. Em situações mais complexas, você pode perceber que um querySelector de vez em quando ainda pode quebrar um bom galho!

Espero que este artigo seja útil. Nos vemos na próxima. Um xero!

VueJS: o que é, como funciona e como começar a usar o framework

Angela Caldas — Tue, 18 Jun 2024 13:29:43 +0000

Você trabalha com desenvolvimento Front End (ou estuda essa área) e procura uma ferramenta flexível e eficaz para criar projetos incríveis? Então, este guia é para você!

Neste artigo escrito em parceria e com exclusividade para a Alura, você conhecerá uma ferramenta para o desenvolvimento web: o Vue.js.

Vamos explorar juntos o que é, para que serve e como se aprofundar nesse framework cada vez mais popular. É só clicar no link abaixo e acessar o artigo gratuitamente!

Vue.js: o que é, como funciona e como começar a usar esse framework JS

Boa leitura!

Redefinindo horizontes: Minha transição para a tecnologia e dicas para novos navegantes

Angela Caldas — Mon, 11 Mar 2024 22:25:34 +0000

Em 2017, por motivos pessoais e profissionais, percebi que precisava ter um plano B de carreira. Sou formada em Arquitetura e Urbanismo com pós-graduação em Projetos Luminotécnicos e percebi que, por mais que eu focasse em me aperfeiçoar na minha área de formação, algo não me fazia feliz.

Resolvi então, relembrar caminhos outrora cogitados, mas não seguidos. Decidi que meu plano B de carreira seria a área de tecnologia, pois meu primeiro vestibular havia sido feito para o curso de Ciências da Computação (na época o único na Federal relacionado à área), mas acabei não levando adiante.

Com a chegada da pandemia de Covid-19 em 2020 e as oportunidades de estudo remoto e gratuito proporcionadas por várias empresas e instituições, foquei em dedicar todos os meus esforços para a transição de carreira para Tecnologia, que acabou se tornando meu Plano A. E hoje, quase um ano depois de conseguir minha primeira oportunidade oficial como desenvolvedora front-end, resolvi compartilhar um pouco das dificuldades e soluções que encontrei para ter sucesso na transição.

Sumário
Você não está começando do zero
Tecnologia é um universo inteiro
Como sabe que não gosta se nunca experimentou?
Aprenda bem a base, evolua naturalmente
Você precisa dar alguns passos para trás para pegar o impulso necessário para seguir em frente
Quem não é visto, não é lembrado
Pratique, crie, divulgue

Você não está começando do zero

Apesar de parecer um pouco assustador se deparar com tantas áreas diferentes de atuação e tantas terminologias, siglas, além do código em si, saiba que muito desses detalhes você acaba aprendendo naturalmente ao longo dos seus estudos.

Costumamos separar o contexto do conhecimento de tecnologia em hard skills e soft skills, ou conhecimento técnico e capacidades sociais e comportamentais, respectivamente — e é nessa última que a sua carreira anterior pode fazer toda a diferença!

Por mais que você ache que sua carreira anterior não tenha nada a ver com a área de tecnologia, é importante ressaltar que as suas habilidades interpessoais pesam bastante nas avaliações de tech recruiters.

Por exemplo, se você trabalhava na área do comércio ou vendas, isso pode significar que você tem bastante experiência ao lidar com clientes e sabe detalhar bem o produto no qual está trabalhando. Trabalhar na área bancária pode te dar a munição necessária para entender a regra de negócio de bancos e instituições financeiras e ajudar na criação de novos produtos digitais para o setor. O importante é perceber que você não está saindo do completo zero: você tem uma bagagem de conhecimento, experiência prévia e maturidade profissional que podem ter grande destaque pra sua decolagem!

Como disse lá em cima, atuei como Arquiteta e Urbanista e escrevi um artigo sobre as similaridades que eu notei de imediato entre essa área e o Desenvolvimento Front-End. Te convido a tentar colocar no papel o que você teve de aprendizado na sua carreira atual que podem ser pontos fortes em sua carreira na área tech.

Tecnologia é um universo inteiro

Algo muito interessante para quem deseja ir para a área da tecnologia é buscar mentorias de carreira, algo que me ajudou bastante no meu primeiro momento da transição. Depois de trabalhar quinze anos em uma área diferente (sendo mais de dez anos numa mesma empresa), acabei me sentindo completamente desinformada sobre a área tech e "enferrujada" em certas habilidades pessoais, especificamente em como fazer meu marketing pessoal, seja nas redes sociais, seja em entrevistas de emprego para a área.

Quando você vem de uma carreira diferente, você se assusta um pouco com as várias subáreas da tecnologia nas quais você pode atuar: Front-End, Back-End, Ciência de Dados, DevOps... A mentoria de carreira pode (e deve) ajudar em todos esses pormenores, te orientando para algo que possa encaixar melhor com o seu perfil, além de te trazer um pouco mais de familiaridade e conforto ao conversar com outras pessoas sobre essas áreas e suas nuances.

Existem plataformas online onde você pode agendar mentorias de diferentes aspectos, como a Mentora, que oferece mentorias gratuitas. Além disso, você sempre pode praticar o seu networking com pessoas da área através do LinkedIn, ou de comunidades de tecnologia, além de ler artigos ou livros sobre o assunto em questão.

Nesse âmbito, uma leitura que também me ajudou bastante a compreender um pouco melhor sobre Tecnologia em geral foi o livro O Universo da programação: Um guia de carreira em desenvolvimento de software, que tem uma linguagem amigável pra quem é de fora da área e dá um ótimo embasamento pra você dar o pontapé inicial nos seus estudos.

Como sabe que não gosta se nunca experimentou?

É comum a gente já entrar com o pé na área da tecnologia querendo estudar algo que um amigo ou alguém da área recomendou. Quando pensei em iniciar os estudos para a transição de carreira, foram inúmeras as pessoas que me recomendaram focar na área de Back-End com Java, por exemplo.

Porém, talvez essa não seja a sua praia. Talvez você goste de algo mais visual, como Front-End ou UX/UI Design... ou talvez você goste mais de analisar dados e tecer métricas. Focar no que você realmente gosta de fazer pode ser crucial para que você determine a área mais afim com sua personalidade, o que vai te garantir mais prazer no aprendizado, mais sede de conhecimento e, logicamente, aumentar suas chances de sucesso.

Avalie com carinho as diferentes áreas de atuação que a Tecnologia pode oferecer e veja o que mais te agrada. E se você já começou a estudar algo e depois percebeu que gostaria de estudar outra coisa, não tenha medo de experimentar. Em Tecnologia, nenhum conhecimento se perde. Já ouviu falar do Profissional em T?

“Escolha um trabalho que você ama e você nunca terá que trabalhar um dia sequer na vida.” — Confúcio, filósofo.

Aprenda bem a base, evolua naturalmente

Esse prazer no aprendizado é algo que vai te ajudar muito na fase inicial dos seus estudos, onde você vai precisar focar em aprender e praticar bem o conhecimento básico necessário, como Lógica de Programação, Algoritmos, Versionamento de Código, entre outros.

Em qualquer profissão é importante que estejamos sempre atualizados, e no mundo da tecnologia não é diferente: tudo acontece muito rápido em comparação com outras carreiras (e a necessidade de se manter atualizado é até mais intensa). Então, saiba que você vai estar num ritmo constante de aprendizado e atualização, onde o prazer em estudar vai ser peça fundamental para que esse ritmo não seja afetado.

Como diria minha mãe: "não coloque a carroça na frente dos bois". Ao nos depararmos com os requisitos das vagas que vemos por aí, é bem tentador querer partir para estudos mais avançados dentro da área que desejamos seguir, mas de nada adianta você estudar um framework Front-End como Angular, por exemplo, sem ter uma boa base em desenvolvimento com JavaScript puro e algum conhecimento em TypeScript, linguagens que são o núcleo de desenvolvimento com esse framework.

Evoluir meu conhecimento em Front End partindo dos conceitos básicos foi primordial para que meu aprendizado de frameworks e bibliotecas fosse mais natural e mais fácil ao longo do tempo. Por exemplo: foquei meu avanço no aprendizado de React, porém toda a base de conhecimento de Single Page Applications (SPA) que adquiri nesse processo foi determinante para que eu conseguisse meu primeiro emprego atuando com outro framework (Vue), com o qual eu tinha pouca experiência, mas cujo aprendizado foi acelerado por toda a bagagem técnica que eu já havia conseguido.

Tire proveito de conteúdos gratuitos que existem aos montes pela internet! É possível aprender bastante vendo vídeos e tutoriais no YouTube ou estudando trilhas gratuitas, como os oferecidos por empresas e comunidades da área, como:

Trilhas de estudo gratuitas da comunidade Orange Juice Tech, que abordam Desenvolvimento FullStack, UX/UI Design e Quality Assurance;
TechGuide da Alura, um guia de aprendizado das principais tecnologias do mercado;
Plataforma FreeCodeCamp, que oferece certificações gratuitas em diversas áreas;
Formação gratuita da PUCRS em Design Centrado no Usuário;
Entre várias outras!

Conhecer bem a base vai fazer com que qualquer aprendizado futuro dentro da área que você escolheu se torne ainda mais rápido e fácil.

Você precisa dar alguns passos para trás para pegar o impulso necessário para seguir em frente

Um dos maiores desafios que eu tive, deixando de lado todo o conteúdo técnico que precisei enfrentar, foi a questão financeira. É imprescindível que você compreenda que, caso você esteja empregado, muito provavelmente não vai entrar na área da programação ganhando o mesmo que você ganha no seu emprego atual.

O fato é que, seja você autodidata ou não, você muito provavelmente vai iniciar sua carreira em tecnologia com nível Estagiário (se estiver cursando graduação), Trainee ou, se tiver um bom portfólio e um pouco mais de conhecimento, nível Junior. Esses níveis são considerados iniciais, então não espere salários excepcionais, você vai precisar descer alguns degraus nesse quesito.

Organize bem suas finanças, faça um bom planejamento e determine o valor mínimo viável que você precisa receber para efetivar sua transição.

Quem não é visto, não é lembrado

E precisamos ser francos: conseguir sua primeira oportunidade em tecnologia não vai ser fácil como muitos acreditam ser. O alto índice de contratações que tivemos na era da pandemia do Covid-19 criou um cenário um tanto quanto irreal de fácil empregabilidade que não retrata a realidade: houve uma alta demanda de profissionais, mas os contratados eram pessoas que já estavam aptas para tal, mesmo que em níveis iniciantes.

Atualmente, o cenário de contratações para a área da tecnologia continua com grandes demandas de profissionais, mas não tanto quanto em 2020 e há muito menos oportunidades para desenvolvedores em nível Junior. Não se engane, você vai receber muitos Não's até receber o seu tão esperado Sim e, uma forma de diminuir esse tempo de espera é investir em ser visto e ser lembrado.

Mantenha seu perfil no LinkedIn sempre atualizado e com o máximo de informações possíveis. Você pode ter dúvidas, mas posso garantir que o LinkedIn traz bastante resultados quando você o mantém sempre atualizado e quando você mantém uma boa rede de networking por lá. Fortalecer a sua rede de contatos pode trazer indicações preciosas para sua primeira oportunidade.

Pratique, crie, divulgue

Pratique sempre! Independente da área tech que você esteja almejando, aproveite os seus estudos e mantenha a prática constante: por experiência própria, estudar um pouco todos os dias é absurdamente mais efetivo do que estudar muito conteúdo apenas nos fim de semana. Manter constância na sua prática é o que vai te dar o know-how necessário pra se destacar dos demais.

Enquanto não consegue a tão sonhada vaga, participe de projetos de forma voluntária. Em minhas entrevistas, meu voluntariado sempre foi visto com bons olhos, além de caracterizar experiência profissional em seu currículo. Um outra boa opção é contribuir em projetos opensource, que também é um ótimo diferencial!

Crie projetos autorais e construa um portfólio com os seus projetos para que tech recruiters e avaliadores técnicos possam ver, de fato, como você organiza seu código, que boas práticas você aplica, como resolve problemas e afins. Se você estiver evoluindo na área de UX/UI Design, crie protótipos, artigos e documentações mostrando como você aplica seus conhecimentos de User Experience pra criar interfaces mais intuitivas e user-friendly, além de bonitas, claro!

Crie conteúdos sobre sua área de atuação. Ao escrever ou gravar conteúdos técnicos sobre o que você estuda ou usa para trabalhar, você consegue fixar melhor seu conhecimento, além de ter sempre material para ajudar outras pessoas que podem estar na mesma situação que a sua. Lógico que você não precisa se tornar um influencer na área, mas até postagens bem elaboradas nas redes sociais, publicadas com certa frequência, podem te fazer ser notado por alguém importante.

Participe de comunidades de tecnologia que, além de constituírem um ambiente de troca de experiências e networking, também podem te dar oportunidades de compartilhar conhecimento, ajudando pessoas com menos experiências que você e também observando outras pessoas agindo da mesma forma.

“Quem ensina aprende ao ensinar. E quem aprende ensina ao aprender.” — Paulo Freire, Pedagogo.

Em minha própria jornada de transição para a área da tecnologia, percebi que as dicas compartilhadas neste artigo foram verdadeiros catalisadores de sucesso. Ao incorporar esses conselhos na prática, pude não apenas superar desafios, mas também colher frutos significativos em minha nova carreira. Portanto, encorajo a todos que estão trilhando esse caminho a adotarem essas estratégias com confiança. Lembre-se, a transição pode ser desafiadora, mas com determinação e a aplicação consistente desses insights, você está construindo as bases sólidas para um futuro promissor na tecnologia.

Siga em frente, ouse, e permita que sua jornada na tecnologia seja não apenas uma mudança de carreira, mas uma transformação positiva em sua vida profissional.