O `@forward` no SASS

Este artigo explica sobre o @forward no SASS.

Explicaremos o @forward de uma forma fácil de entender, incluindo exemplos práticos.

YouTube Video

O @forward no SASS

O que é @forward?

No sistema de módulos do SASS, você usa @use e @forward ao invés de @import. @forward é um recurso importante para manter sua arquitetura limpa. É uma diretiva usada para 'expor' variáveis, mixins e funções definidas em outros arquivos. Em vez de usá-lo sozinho, ele funciona como um ponto de entrada especificando: 'Use este módulo a partir daqui.'.

1@forward "variables";

• Esse código significa 'disponibilizar o conteúdo de variables.scss para uso em outros arquivos.'.

Diferença entre @use e @forward

@use e @forward são ambas sintaxes para manipulação de módulos, mas seus propósitos são claramente diferentes. @use é uma diretiva para usar itens dentro do arquivo, enquanto @forward é uma diretiva para tornar itens disponíveis para outros arquivos.

1// @use: import the module for use in this file
2@use "variables";
3
4// @forward: re-export the module for other files to consume
5@forward "variables";

• @use representa as dependências necessárias para a implementação do arquivo atual, enquanto @forward faz com que o arquivo funcione como um ponto de entrada de API pública. Compreender essa diferença ajudará você a decidir onde usar o @forward.

Por que o @forward é necessário?

À medida que você adiciona mais arquivos Sass, pode ser necessário escrever muitas instruções @use. Ao usar o @forward, você pode centralizar tudo em um único arquivo de entrada.

1styles/
2├─ foundation/
3│  ├─ _variables.scss
4│  ├─ _mixins.scss
5│  └─ _index.scss
6└─ main.scss

• Nessa estrutura, o _index.scss serve como a 'API pública.'.

Uso básico do @forward

Vamos ver como utilizar o @forward de modo básico.

1// _variables.scss
2// Color definitions used across the project
3
4$primary-color: #006ab1;
5$secondary-color: #e0f0ff;
6
7// Internal use only (will be hidden via @forward hide)
8$debug-color: magenta;

• Em vez de usar diretamente essa variável com @use, você as agrupa com @forward.

1// _index.scss
2@forward "variables";

• Neste ponto, o _index.scss não contém nada; ele é apenas um arquivo de repasse.

Usando módulos que foram expostos com @forward

Ao invés de usar diretamente cada arquivo com @use, você usa apenas o arquivo de índice que agrupou todos os @forwards do lado do consumidor. Isso permite que você use uma interface estável, sem precisar conhecer a estrutura interna.

1// main.scss
2// Import the public API of the foundation layer
3@use "foundation";
4
5.button {
6  background-color: foundation.$primary-color;
7}

• Com esse design, mesmo que a localização das definições de variáveis ou mixins mude, você pode alterar a estrutura interna sem precisar modificar nenhum código do lado do consumidor.

Combinando múltiplos módulos com @forward

No desenvolvimento real, é comum separar variáveis, mixins e funções de acordo com suas funções. O @forward pode ser escrito várias vezes, permitindo agrupar módulos separados em uma única API pública.

Abaixo, fornecemos exemplos de mixins e funções e demonstramos um design que os expõe externamente como uma única interface.

 1// _mixins.scss
 2// Reusable mixins for layout and components
 3
 4// Reset default button styles
 5@mixin button-reset {
 6  appearance: none;
 7  background: none;
 8  border: none;
 9  padding: 0;
10  margin: 0;
11  font: inherit;
12  color: inherit;
13}
14
15// Clearfix utility
16@mixin clearfix {
17  &::after {
18    content: "";
19    display: table;
20    clear: both;
21  }
22}
23
24// Internal mixin (not intended to be part of the public API)
25@mixin debug-outline {
26  outline: 2px dashed red;
27}

 1// _functions.scss
 2// Utility functions for consistent styling
 3
 4@use "sass:math";
 5
 6// Convert px to rem based on a 16px root size
 7@function rem($px) {
 8  @return math.div($px, 16) * 1rem;
 9}
10
11// Clamp a value between a minimum and maximum
12@function clamp-value($value, $min, $max) {
13  @return math.max($min, math.min($value, $max));
14}

1// _index.scss
2// Re-export variables, mixins, and functions as a single public API
3@forward "variables";
4@forward "mixins";
5@forward "functions";

• Ao expor apenas esse arquivo index para o exterior, você pode ocultar a estrutura interna e fornecer uma interface amigável para os consumidores.

Evitando conflitos de nomes (as)

Se os mesmos nomes de variáveis ou mixins estiverem definidos em vários módulos, você pode usar as em @forward para adicionar um prefixo ao expô-los e evitar conflitos de nomes.

1// Add a prefix when re-exporting to avoid name collisions
2@forward "variables" as var-*;

Com esse código, $primary-color em variables será exposto com o seguinte nome:.

1// foundation.$var-primary-color

• Esse método é uma maneira de definir regras de design de forma clara e escalar com segurança, sendo uma técnica essencial, especialmente em projetos de grande escala ou em bibliotecas compartilhadas.

Ocultando membros desnecessários (hide)

Os módulos podem conter variáveis ou mixins destinados apenas para implementação interna. Ao usar hide, você pode excluí-los ao reexpor e impedir o acesso externo.

1// Re-export everything except internal debug variables
2@forward "variables" hide $debug-color;

Com essa configuração, $debug-color é válido apenas dentro do módulo, o que ajuda a evitar uso acidental por parte dos consumidores.

Especificando quais membros expor (show)

Se você quiser expor apenas alguns mixins ou funções, use show. Ao limitar o que é exposto, você pode esclarecer o propósito do módulo e sua intenção de design.

1// Explicitly expose only selected mixins as the public API
2@forward "mixins" show button-reset, clearfix;

• Ao usar show desta forma, fica claro à primeira vista quais APIs estão oficialmente disponíveis para uso.

@forward não pode ser usado sozinho

Um ponto importante é que as variáveis expostas com @forward não podem ser usadas dentro desse mesmo arquivo.

1@forward "variables";
2
3.test {
4  color: $primary-color; // Error
5}

• @forward serve apenas para 'reexpor', enquanto 'usar' é a função de @use.

Um exemplo de separação adequada de funções

No design de módulos para Sass, é ideal separar claramente a camada pública (API) e a camada de implementação. @forward define a API pública e @use a consome no lado da implementação.

1// _index.scss (public API)
2@forward "variables";
3@forward "mixins";

1// _component.scss
2// Consume the public API of the foundation layer
3@use "foundation";
4
5.card {
6  color: foundation.$primary-color;
7}

• Com essa estrutura, fica claro quais partes são interfaces públicas e quais são implementações internas, levando a uma melhor transparência de design.

A diferença definitiva em relação ao @import

@import expande todas as definições importadas no escopo global. Por outro lado, @use e @forward expõem explicitamente os itens e os acessam por meio de namespaces.

 1// @import (deprecated)
 2// Everything is injected into the global scope
 3$color: red;
 4
 5.button-import {
 6  color: $color;
 7}
 8
 9// @use + @forward (recommended)
10// Access values explicitly through a namespace
11@use "foundation";
12
13.button-use {
14  color: foundation.$primary-color;
15}

• Por causa dessa diferença, você pode melhorar muito a manutenibilidade e a segurança ao evitar sobrescritas indesejadas e confusão de dependências.

Resumo

O @forward é um recurso importante que apoia um design sustentável. Ao considerar 'o que expor e o que ocultar como implementação interna', a estrutura do seu estilo torna-se mais segura e legível. Ao usar corretamente @use e @forward, você pode clarificar dependências e alcançar um design robusto e resistente a mudanças.

Você pode acompanhar o artigo acima usando o Visual Studio Code em nosso canal do YouTube. Por favor, confira também o canal do YouTube.

YouTube Video