Funções SASS

Este artigo explica as funções do SASS.

Vamos explicar detalhadamente as funções do SASS, desde o básico até tópicos avançados, incluindo exemplos práticos úteis no trabalho real.

YouTube Video

Funções SASS

As funções do SASS são ferramentas poderosas que encapsulam lógica reutilizável nas folhas de estilo, permitindo cálculos, formatação e ramificações condicionais.

Estrutura básica e uso de funções

As funções do SASS são definidas com @function e retornam um valor usando @return. As funções são chamadas da mesma forma que as funções nativas.

1// Example: Define a simple function that doubles a value
2@function double($n) {
3  @return $n * 2;
4}
5
6// Use the function
7.example {
8  width: double(10px);  // -> 20px
9}

• Este código define uma função que dobra um número e o aplica à largura. Como resultado, .example { width: 20px; } será gerado.

Argumentos, valores padrão e manipulação de tipos

As funções podem aceitar múltiplos argumentos e definir valores padrão. O SASS não exige tipagem estática, mas dar atenção ao formato dos argumentos torna suas funções mais robustas.

1// Example: Function with default parameters
2@function responsive-font($base-size, $scale: 1.2, $unit: px) {
3  @return $base-size * $scale + $unit;
4}
5
6.title {
7  font-size: responsive-font(16, 1.25);  // -> 20px
8}

• responsive-font possui valores padrão para scale e unit, e alguns argumentos podem ser omitidos ao chamá-la. Neste exemplo, será gerado um valor como font-size: 20px;.

Usando argumentos variádicos (...)

Use argumentos variádicos se quiser passar múltiplos valores. Isso é útil para manipular listas ou múltiplas cores.

 1// Example: Sum any number of numbers passed in
 2@function sum-all($numbers...) {
 3  $total: 0;
 4  @each $n in $numbers {
 5    $total: $total + $n;
 6  }
 7  @return $total;
 8}
 9
10.box {
11  padding: sum-all(4px, 6px, 10px);  // -> 20px
12}

• Um argumento variádico como $numbers... é tratado como uma lista e pode ser processado usando @each. Neste exemplo, será gerado padding: 20px;.

Retornando e manipulando listas ou mapas

As funções também podem retornar listas (separadas por espaço ou vírgula) e mapas. Isso é útil para retornar valores complexos.

 1@use "sass:map";
 2
 3// Example: Return a map of spacing scale
 4@function spacing-scale($base) {
 5  @return (
 6    'small': $base * 0.5,
 7    'medium': $base,
 8    'large': $base * 2
 9  );
10}
11
12$scale: spacing-scale(8px);
13
14.card {
15  margin-bottom: map.get($scale, 'medium');
16}

• Um mapa é retornado pela função, e então os valores são recuperados com map.get. Isso permite manter um sistema de espaçamento consistente.

Funções com condicionais e laços

@if, @else if, @else, @for, @each e @while podem ser usados dentro de funções. Você pode criar lógica de cálculo com condicionais e laços.

 1// Example: Generate modular scale value using loop
 2@function modular-scale($step, $base: 1rem, $ratio: 1.25) {
 3  $result: $base;
 4  @if $step == 0 {
 5    @return $result;
 6  }
 7  @if $step > 0 {
 8    @for $i from 1 through $step {
 9      $result: $result * $ratio;
10    }
11  } @else {
12    @for $i from 1 through abs($step) {
13      $result: $result / $ratio;
14    }
15  }
16  @return $result;
17}
18
19.h1 {
20  font-size: modular-scale(3, 1rem, 1.333);
21}

• Esta função calcula uma escala modular e multiplica ou divide dependendo dos passos positivos ou negativos. modular-scale(3, 1rem, 1.333) retorna um tamanho de fonte três passos acima do valor base.

Tratamento de erros e avisos (@error, @warn)

Você pode abortar com @error em argumentos inválidos ou operações inesperadas, e emitir avisos com @warn. O objetivo é alertar os usuários sobre problemas logo no início.

 1@use "sass:math";
 2@use "sass:meta";
 3
 4// Example: Validate input and throw an error for invalid units
 5@function ensure-length($value) {
 6  @if meta.type-of($value) != 'number' or math.is-unitless($value) {
 7    @error "Expected a length with units, got #{$value}.";
 8  }
 9  @return $value;
10}
11
12// Valid input (should pass)
13.test-valid {
14  width: ensure-length(10px); // expect: 10px
15}
16
17// Invalid input (should throw error during compilation)
18// Uncomment the following to test error handling:
19//
20// .test-invalid {
21//   // expect error: "Expected a length with units, got 10."
22//   width: ensure-length(10);
23// }

• Se você passar valores inválidos, um erro será emitido no momento da build, facilitando a identificação da causa. Verificações dentro de funções são úteis para detectar bugs antecipadamente.

Criando funções específicas para cores

No SASS, você pode combinar várias funções que manipulam cores para criar sua própria paleta de cores. Isso é útil para gerenciar um esquema de cores consistente em todo o seu projeto.

 1@use "sass:color";
 2@use "sass:list";
 3
 4// Example: Generate a color palette (tints and shades) from a base color
 5@function palette($color, $steps: 5, $strength: 10%) {
 6  $colors: ();
 7  @for $i from 0 through $steps {
 8    $amount: $i * $strength;
 9    $shade: if($i == 0, $color, color.mix(black, $color, $amount));
10    $tint: color.mix(white, $color, $amount);
11    $colors: list.append($colors, $shade);
12    $colors: list.append($colors, $tint);
13  }
14  @return $colors;
15}
16
17$palette: palette(#3498db, 3, 15%);
18
19.btn {
20  background-color: list.nth($palette, 1);
21}

• Neste exemplo, color.mix é usado para criar tons misturando com preto e matizes misturando com branco. Os valores são retornados em uma lista, e podem ser acessados usando list.nth.

Observações sobre performance e tempo de compilação

As funções do SASS são avaliadas no momento da compilação. Laços pesados, recursão profunda ou muitas operações com mapas aumentam o tempo de compilação. Mantenha as funções pequenas e simples; caso necessário, considere processamentos mais complexos fora do SASS, em ferramentas de build ou pré-processadores.

Coleção prática de funções utilitárias

Aqui estão algumas funções utilitárias comuns. O código foi projetado para ser usado imediatamente em projetos reais.

 1@use "sass:math";
 2
 3// Example: Clamp a value between min and max
 4@function clamp-value($value, $min, $max) {
 5  @if $value < $min {
 6    @return $min;
 7  } @else if $value > $max {
 8    @return $max;
 9  }
10  @return $value;
11}
12
13// Example: Convert px to rem (with optional root size)
14@function px-to-rem($px, $root: 16px) {
15  @if math.unit($px) != "px" {
16    @error "px-to-rem requires a px value.";
17  }
18  @return ($px / $root) * 1rem;
19}

• clamp-value impõe limites superior e inferior a um valor, e px-to-rem converte valores em pixels para rem. Ambas simplificam processos frequentes em design responsivo.

Escolhendo entre @function e mixins (@mixin)

Funções se especializam em retornar valores, enquanto mixins geram blocos de CSS. Se o resultado da lógica for um valor de propriedade único, use uma função; se for um bloco de estilo inteiro, use um mixin.

 1// Example: Function returns a value
 2@function border-radius-value($size) {
 3  @return $size * 1px;
 4}
 5
 6// Example: Mixin outputs properties
 7@mixin rounded($size) {
 8  border-radius: border-radius-value($size);
 9  -webkit-border-radius: border-radius-value($size);
10}
11.card {
12  @include rounded(8);
13}

• Funções retornam valores como números ou cores para uso em outras propriedades, enquanto mixins inserem diretamente grupos de propriedades. Separação rigorosa no design aumenta a manutenibilidade.

Manipulação de strings e considerações sobre o formato de saída

Seja cuidadoso ao lidar com números com unidade e strings no SASS. Concatenar uma string a um número com unidade pode gerar resultados indesejados. Use unquote() ou interpolação de string (#{}) conforme necessário.

 1@use "sass:math";
 2
 3// Example: Safely create a CSS value string
 4@function px-percentage($px, $total) {
 5  $percent: math.div($px, $total) * 100;
 6  @return "#{$percent}%";
 7}
 8
 9// Safer with interpolation and math module
10@function px-percentage-safe($px, $total) {
11  $percent: math.div($px, $total) * 100;
12  // Round to 2 decimal places safely
13  $rounded: math.div(math.round($percent * 100), 100);
14  @return "#{$rounded}%";
15}

• Ao retornar porcentagens como strings, controle a precisão usando interpolação ou round para melhor clareza. Para evitar bugs, sempre trate cuidadosamente os tipos de dados ao concatenar resultados de cálculos com strings.

Melhores práticas para teste e documentação

Após escrever uma função, crie pequenos arquivos SCSS com exemplos de uso como testes, o que facilita a manutenção. Você pode documentar para cada função o tipo/unidade de entrada, tipo de retorno, comportamento em falha e exemplos de uso.

 1@use "sass:math";
 2
 3// Example: Inline "tests" (partial usage examples)
 4// These can be compiled separately during development
 5
 6@function double($n) {
 7  @return $n * 2;
 8}
 9
10@function px-to-rem($px, $root: 16px) {
11  @if math.unit($px) != "px" {
12    @error "px-to-rem requires a px value.";
13  }
14  @return math.div($px, $root) * 1rem;
15}
16
17// Test double()
18.test-double {
19  width: double(12px); // expect 24px
20}
21
22// Test px-to-rem()
23.test-rem {
24  font-size: px-to-rem(18px, 18px); // expect 1rem
25}
26
27// --- Inline debug tests ---
28@debug "double(12px) => #{double(12px)} (expect 24px)";
29@debug "px-to-rem(18px, 18px) => #{px-to-rem(18px, 18px)} (expect 1rem)";

• Deixar comentários com exemplos pequenos de 'saída esperada' facilita a identificação de regressões durante futuros refatoramentos. Compilar automaticamente em um ambiente de CI e verificar visualmente a saída é eficaz.

Resumo

Funções SASS são uma forma poderosa de aumentar a reutilização e a consistência nos estilos. Projete-as para serem pequenas e simples, e garanta a segurança usando @error e @warn. Funções utilitárias para cor, espaçamento e conversão de unidades são convenientes para consolidar em uma biblioteca compartilhada. Para evitar sobrecarga de compilação, separe processamentos complexos em outras etapas do build quando necessário.

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