@function

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

@function fibonacci($n) {
  $sequence: 0 1;
  @for $_ from 1 through $n {
    $new: nth($sequence, length($sequence)) + nth($sequence, length($sequence) - 1);
    $sequence: append($sequence, $new);
  }
  @return nth($sequence, length($sequence));
}

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

// SASS
@function fibonacci($n)
  $sequence: 0 1
  @for $_ from 1 through $n
    $new: nth($sequence, length($sequence)) + nth($sequence, length($sequence) - 1)
    $sequence: append($sequence, $new)
  @return nth($sequence, length($sequence))

.sidebar
  float: left
  margin-left: fibonacci(4) * 1px

/* CSS */
.sidebar {
  float: left;
  margin-left: 5px;
}

Аргументы

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

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

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

@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
@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 */
.header {
  background-color: rgb(81.6, 51, 20.4);
}

Аргументы по имени

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

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

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

/* CSS */
.banner {
  background-color: #036;
  color: rgb(10.2, 132.6, 255);
}

Прием произвольного количества аргументов

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

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

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

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

  @return $sum


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

/* CSS */
.micro {
  width: 180px;
}

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

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

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

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

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

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

/* CSS */
.micro {
  width: 30px;
}

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

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

@return

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

При встрече @return функция немедленно завершается и возвращает свой результат. Преждевременное возвращение может быть полезным для обработки граничных случаев или случаев, где доступен более эффективный алгоритм, без необходимости обертывания всей функции в @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;
}

// SASS
@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

Другие функции

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

Обычные функции CSS

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

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

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

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

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