@function

As funções são definidas usando a regra que usa arroba @function, que é escrita como @function <name>(<arguments...>) { ... }. Um nome de função pode ser qualquer identificador de Sass. Também podem conter declarações universais, bem como a regra que usa arroba @return que indica o valor à usar como resultado da chamada da função. As funções são chamadas usando a sintaxe de função de CSS normal.

@function pow($base, $exponent) {
  $result: 1;
  @for $_ from 1 through $exponent {
    $result: $result * $base;
  }
  @return $result;
}

.sidebar {
  float: left;
  margin-left: pow(4, 3) * 1px;
}

@function pow($base, $exponent)
  $result: 1
  @for $_ from 1 through $exponent
    $result: $result * $base

  @return $result


.sidebar
  float: left
  margin-left: pow(4, 3) * 1px

.sidebar {
  float: left;
  margin-left: 64px;
}

ArgumentosArgumentos permalink

Os argumentos permitem que o comportamento das funções sejam personalizados cada vez que forem chamadas. Os argumentos são especificados na regra @function depois do nome da função, como uma lista de nomes de variável entre parênteses. A função deve ser chamada com o mesmo número de argumentos na forma de expressões de SassScript. Os valores destas expressões estão disponíveis dentro do corpo da função de acordo com as variáveis correspondentes.

Argumentos OpcionaisArgumentos Opcionais permalink

Normalmente, cada argumento que uma função declara deve ser passado quando esta função for incluída. No entanto, podes criar um argumento opcional definindo um valor padrão que será usado se aquele argumento não for passado. Os valores padrão usam a mesma sintaxe de declarações de variáveis: o nome da variável, seguido por um sinal de dois pontos e uma expressão de SassScript. Isto torna fácil definir APIs de função flexíveis que podem ser usadas de maneiras simples ou complexas:

@function invert($color, $amount: 100%) {
  $inverse: change-color($color, $hue: hue($color) + 180);
  @return mix($inverse, $color, $amount);
}

$primary-color: #036;
.header {
  background-color: invert($primary-color, 80%);
}

@function invert($color, $amount: 100%)
  $inverse: change-color($color, $hue: hue($color) + 180)
  @return mix($inverse, $color, $amount)


$primary-color: #036
.header
  background-color: invert($primary-color, 80%)

.header {
  background-color: #523314;
}

Argumentos de Palavra-ChaveArgumentos de Palavra-Chave permalink

Quando uma função for chamada, os argumentos podem ser passados conforme o nome além de passá-los conforme sua posição na lista de argumento. Isto é especialmente útil para funções com vários argumentos opcionais, ou com argumentos booleanos cujos significados não são óbvios sem um nome ir com eles. Os argumentos de palavra-chave usam a mesma sintaxe de declarações de variável e argumentos opcionais:

$primary-color: #036;
.banner {
  background-color: $primary-color;
  color: scale-color($primary-color, $lightness: +40%);
}

$primary-color: #036
.banner
  background-color: $primary-color
  color: scale-color($primary-color, $lightness: +40%)

.banner {
  background-color: #036;
  color: #0a85ff;
}

Recebendo Argumentos ArbitráriosRecebendo Argumentos Arbitrários permalink

Algumas vezes é útil para uma função ser capaz de receber qualquer número de argumentos. Se o último argumento numa declaração de @function terminar em ..., então todos os argumentos adicionais para aquela função são passados para aquele argumento como uma lista. Este argumento é conhecido como uma lista de argumento:

@function sum($numbers...) {
  $sum: 0;
  @each $number in $numbers {
    $sum: $sum + $number;
  }
  @return $sum;
}

.micro {
  width: sum(50px, 30px, 100px);
}

@function sum($numbers...)
  $sum: 0
  @each $number in $numbers
    $sum: $sum + $number

  @return $sum


.micro
  width: sum(50px, 30px, 100px)

.micro {
  width: 180px;
}

Recebendo Argumentos de Palavra-Chave ArbitráriosRecebendo Argumentos de Palavra-Chave Arbitrários permalink

As listas de argumentos também podem ser usadas para receber argumentos de palavra-chave arbitrários. A função meta.keywords() recebe uma lista de argumento e retorna quaisquer palavras-chaves adicionais que foram passadas para a função como mapa a partir dos nomes de argumento (sem incluir $) para aqueles valores dos argumentos.

Passando Argumentos ArbitráriosPassando Argumentos Arbitrários permalink

Tal como as listas de argumentos permitem funções receber argumentos posicionais ou de palavra-chave arbitrários, a mesma sintaxe pode ser usada para passar argumentos posicionais e de palavra-chave para uma função. Se passares uma lista seguida por ... como último argumento duma chamada de função, seus elementos serão tratados como argumentos posicionais adicionais. Similarmente, um mapa seguido por ... será tratado como argumentos de palavra-chave adicionais. Tu podes até mesmo passar ambos de uma vez!

$widths: 50px, 30px, 100px;
.micro {
  width: min($widths...);
}

$widths: 50px, 30px, 100px
.micro
  width: min($widths...)

.micro {
  width: 30px;
}

@function fg($args...) {
  @warn "The fg() function is deprecated. Call foreground() instead.";
  @return foreground($args...);
}

@function fg($args...)
  @warn "The fg() function is deprecated. Call foreground() instead."
  @return foreground($args...)

@return@return permalink

A regra de arroba @return indica o valor à usar como resultado da chamada duma função. É apenas permitido dentro dum corpo de @function, e cada @function deve terminar com uma @return.

Quando uma @return for encontrada, termina imediatamente a função e retorna o seu resultado. Retornar cedo pode ser útil para manipular casos extremos ou casos onde um algoritmo mais eficiente estiver disponível sem embrulhar a função inteira num bloco @else:

@use "sass:string";

@function str-insert($string, $insert, $index) {
  // Avoid making new strings if we don't need to.
  @if string.length($string) == 0 {
    @return $insert;
  }

  $before: string.slice($string, 0, $index);
  $after: string.slice($string, $index);
  @return $before + $insert + $after;
}

@use "sass:string"

@function str-insert($string, $insert, $index)
  // Avoid making new strings if we don't need to.
  @if string.length($string) == 0
    @return $insert


  $before: string.slice($string, 0, $index)
  $after: string.slice($string, $index)
  @return $before + $insert + $after

Outras FunçõesOutras Funções permalink

Além da função definida pelo utilizador, a Sass fornece uma sólida biblioteca principal de funções embutidas que estão sempre disponíveis para uso. As implementações de Sass também tornam possível definir funções personalizadas na linguagem hospedeira. E claro, sempre podes chamar funções de CSS simples (mesmo aquelas com sintaxe esquisita).

Funções de CSS SimplesFunções de CSS Simples permalink

Qualquer chamada de função que não for duma função definida pelo utilizador ou embutida é compilada para uma função de CSS simples (a menos que use a sintaxe de argumento da Sass). Os argumentos serão compilados para a CSS e incluídos como está na chamada de função. Isto garante que a Sass suporta todas as funções de CSS sem precisar de lançar novas versões toda vez que uma nova for adicionada:

@debug var(--main-bg-color); // var(--main-bg-color)

$primary: #f2ece4;
$accent: #e1d7d2;
@debug radial-gradient($primary, $accent); // radial-gradient(#f2ece4, #e1d7d2)

@debug var(--main-bg-color)  // var(--main-bg-color)

$primary: #f2ece4
$accent: #e1d7d2
@debug radial-gradient($primary, $accent)  // radial-gradient(#f2ece4, #e1d7d2)