@function

Функции позволяют вам определять сложные операции со значениями SassScript, которые вы можете повторно использовать в своей таблице стилей. Они позволяют легко абстрагироваться от общих формул и поведения в удобочитаемой форме.

Функции определяются с помощью at-правила @function, которое записывается как @function <name>(<arguments...>) { ... }. Имя функции может быть любым идентификатором Sass. Он может содержать только универсальные конструкции, а также at-правило @return, которое указывает значение, используемое в результате вызова функции. Функции вызываются с использованием обычного синтаксиса функций CSS.

SCSS Syntax

@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;
}

Sass Syntax

@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

CSS Output

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








💡 Интересный факт:

Имена функций, как и все идентификаторы Sass, рассматривают дефисы и подчеркивания как идентичные. Это означает, что scale-color и scale_color относятся к одной и той же функции. Это историческое наследие самых ранних дней Sass, когда он только разрешал подчеркивание в именах идентификаторов. После того, как Sass добавил поддержку дефисов в соответствии с синтаксисом CSS, они стали эквивалентными, чтобы упростить миграцию.

⚠️ Внимание!

Хотя технически возможно, чтобы функции имели побочные эффекты, такие как установка глобальных переменных, это настоятельно не рекомендуется. Используйте примеси для побочных эффектов и используйте функции только для вычисления значений.

Аргументы permalinkАргументы

Аргументы позволяют настраивать поведение функций при каждом их вызове. Аргументы указываются в правиле @function после имени функции в виде списка имен переменных, заключенного в круглые скобки. Функция должна вызываться с таким же количеством аргументов в виде выражений SassScript. Значения этих выражений доступны в теле функции как соответствующие переменные.

💡 Интересный факт:

Списки аргументов также могут иметь конечные запятые! Это позволяет избежать синтаксических ошибок при рефакторинге таблиц стилей.

Необязательные аргументы permalinkНеобязательные аргументы

Обычно каждый аргумент, который объявляет функция, должен быть передан при включении этой функции. Однако вы можете сделать аргумент необязательным, указав значение по умолчанию, которое будет использоваться, если эти аргументы не переданы. Значения по умолчанию используют тот же синтаксис, что и объявления переменных: имя переменной, за которым следует двоеточие и выражение SassScript. Это упрощает определение гибких API-интерфейсов unction, которые можно использовать как простыми, так и сложными способами.

SCSS Syntax

@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%);
}

Sass Syntax

@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%)

CSS Output

.header {
  background-color: #523314;
}






💡 Интересный факт:

Значения по умолчанию могут быть любым выражением SassScript, и они могут даже ссылаться на более ранние аргументы!

Аргументы ключевых слов permalinkАргументы ключевых слов

При вызове функции аргументы могут передаваться по имени в дополнение к передаче их по позиции в списке аргументов. Это особенно полезно для функций с несколькими необязательными аргументами или с аргументами boolean, значение которых неочевидно без имени, которое будет им соответствовать. Аргументы ключевого слова используют тот же синтаксис, что и объявления переменных и необязательные аргументы.

SCSS Syntax

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

Sass Syntax

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

CSS Output

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

⚠️ Внимание!

Поскольку *любой аргумент может передаваться по имени, будьте осторожны при переименовании аргументов функции… это может сломать ваших пользователей! Может быть полезно сохранить старое имя в качестве необязательного аргумента на некоторое время и напечатать предупреждение, если кто-то его передаст, чтобы они знали, что нужно перейти на новый аргумент.

Принятие произвольных аргументов permalinkПринятие произвольных аргументов

Иногда полезно, чтобы функция могла принимать любое количество аргументов. Если последний аргумент в объявлении @function заканчивается на ..., то все дополнительные аргументы этой функции передаются этому аргументу как список. Этот аргумент известен как список аргументов.

SCSS Syntax

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

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

Sass Syntax

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

  @return $sum


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

CSS Output

.micro {
  width: 180px;
}








Принятие произвольных аргументов ключевого слова permalinkПринятие произвольных аргументов ключевого слова

Списки аргументов также могут использоваться для получения аргументов произвольного ключевого слова. Функция meta.keywords() принимает список аргументов и возвращает любые дополнительные ключевые слова, которые были переданы функции в виде карты от имен аргументов (не включая $) до значений этих аргументов.

💡 Интересный факт:

Если вы никогда не передаете список аргументов функции meta.keywords(), этот список аргументов не будет допускать дополнительных аргументов ключевого слова. Это помогает вызывающим абонентам вашей функции быть уверенным, что они случайно не ошиблись в именах аргументов.

Передача произвольных аргументов permalinkПередача произвольных аргументов

Так же, как списки аргументов позволяют функциям принимать произвольные позиционные аргументы или аргументы ключевого слова, тот же синтаксис может использоваться для передачи позиционных аргументов и аргументов ключевого слова функции. Если вы передадите список, за которым следует ... в качестве последнего аргумента вызова функции, его элементы будут рассматриваться как дополнительные позиционные аргументы. Точно так же карта, за которой следует ..., будет рассматриваться как дополнительные аргументы ключевого слова. Вы даже можете пройти оба сразу!

SCSS Syntax

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

Sass Syntax

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

CSS Output

.micro {
  width: 30px;
}

💡 Интересный факт:

Поскольку список аргументов отслеживает как позиционные, так и ключевые аргументы, вы используете его для передачи обоих сразу в другую функцию. Это упрощает определение псевдонима для функции!

SCSS Syntax

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

Sass Syntax

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

@return permalink@return

At-правило @return указывает значение, используемое в результате вызова функции. Это разрешено только внутри тела @function, и каждая @function должна оканчиваться на @return.

Когда встречается @return , он немедленно завершает функцию и возвращает ее результат. Ранний возврат может быть полезен для обработки крайних случаев или случаев, когда доступен более эффективный алгоритм без обертывания всей функции в блоке @else block.

SCSS Syntax

@use "sass:string";

@function str-insert($string, $insert, $index) {
  // Избегайте создания новых строк, если нам это не нужно.
  @if string.length($string) == 0 {
    @return $insert;
  }

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

Sass Syntax

@use "sass:string"

@function str-insert($string, $insert, $index)
  // Избегайте создания новых строк, если нам это не нужно.
  @if string.length($string) == 0
    @return $insert


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

Прочие функции permalinkПрочие функции

Помимо пользовательских функций, Sass предоставляет обширную базовую библиотеку встроенных функций, которые всегда доступны для использования. Реализации Sass также позволяют определять пользовательские функции на основном языке. И, конечно же, вы всегда можете вызвать простые функции CSS (даже те, которые имеют странный синтаксис).

Простые функции CSS permalinkПростые функции CSS

Любой вызов функции, который не является ни определяемой пользователем, ни встроенной функцией, компилируется в обычную функцию CSS (если только он не использует синтаксис аргументов Sass). Аргументы будут скомпилированы в CSS и включены в вызов функции как есть. Это гарантирует, что Sass поддерживает все функции CSS без необходимости выпускать новые версии каждый раз, когда добавляется новая.

SCSS Syntax

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

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

Sass Syntax

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

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

⚠️ Внимание!

Поскольку любая неизвестная функция будет скомпилирована в CSS, ее легко пропустить, если вы напечатаете опечатку в имени функции. Подумайте о запуске CSS линтера для вывода вашей таблицы стилей, чтобы получать уведомления, когда это произойдет!

💡 Интересный факт:

Некоторые функции CSS, такие как calc() и element(), имеют необычный синтаксис. Sass специально анализирует эти функции как строки без кавычек.