Lzh on GitHub

@function

函数允许你定义对 SassScript 值的复杂操作，你可以在整个样式表中重复使用它们。它们使得以可读的方式抽象出通用公式和行为变得容易。

函数允许你定义对 SassScript 值的复杂操作，你可以在整个样式表中重复使用它们。它们使得以可读的方式抽象出通用公式和行为变得容易。

函数使用 @function at-rule 定义，其写法为 @function <name>(<arguments...>) { ... }。函数的名称可以是任何不以 -- 开头的 Sass 标识符。它只能包含通用语句，以及 @return at-rule，后者指示用作函数调用结果的值。函数使用普通 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 标识符一样，将连字符和下划线视为相同。这意味着 scale-color 和 scale_color 都指同一个函数。这是 Sass 早期的历史遗留问题，当时它只允许在标识符名称中使用下划线。一旦 Sass 添加了对连字符的支持以匹配 CSS 的语法，两者就被设置为等效，以使迁移更容易。
虽然从技术上讲，函数可以产生诸如设置全局变量之类的副作用，但这强烈不鼓励。混合宏用于副作用，而函数仅用于计算值。

参数

参数允许在每次调用时自定义函数的行为。参数在 @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%);
}
默认值可以是任何 SassScript 表达式，它们甚至可以引用较早的参数！

关键字参数

当一个函数被调用时，除了按其在参数列表中的位置传递参数外，还可以按名称传递参数。这对于具有多个可选参数或具有布尔参数的函数特别有用，如果没有名称，它们的含义就不那么明显。关键字参数使用与变量声明和可选参数相同的语法。

$primary-color: #036;
.banner {
  background-color: $primary-color;
  color: scale-color($primary-color, $lightness: +40%);
}
因为任何参数都可以按名称传递，所以在重命名函数的参数时要小心……它可能会破坏你的用户！将旧名称作为可选参数保留一段时间，并在有人传递它时打印警告，这样他们就知道要迁移到新参数，这会很有帮助。

接受任意参数

有时，让一个函数能够接受任意数量的参数会很有用。如果 @function 声明中的最后一个参数以 ... 结尾，那么传递给该函数的所有额外参数都将作为列表传递给该参数。这个参数被称为参数列表。

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

接受任意关键字参数

参数列表也可以用于接受任意关键字参数。meta.keywords() 函数接受一个参数列表，并返回作为映射传递给函数的任何额外关键字，该映射从参数名（不包括 $) 映射到这些参数的值。

如果你从不将参数列表传递给 meta.keywords() 函数，则该参数列表将不允许额外的关键字参数。这有助于函数的调用者确保他们没有意外拼错任何参数名称。

传递任意参数

就像参数列表允许函数接受任意位置或关键字参数一样，相同的语法可用于传递位置和关键字参数给函数。如果你将一个列表后跟 ... 作为函数调用的最后一个参数，其元素将被视为额外的位置参数。同样，后跟 ... 的映射将被视为额外的关键字参数。你甚至可以同时传递两者！

$widths: 50px, 30px, 100px;
.micro {
  width: min($widths...);
}
因为参数列表同时跟踪位置参数和关键字参数，所以你可以使用它一次将两者传递给另一个函数。这使得为函数定义别名变得超级容易！
@function fg($args...) {
  @warn "The fg() function is deprecated. Call foreground() instead.";
  @return foreground($args...);
}

@return

@return at-rule 指示用作调用函数结果的值。它只允许在 @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 还提供了一个庞大的核心库，其中包含始终可用的内置函数。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)
因为任何未知函数都会被编译为 CSS，所以很容易错过拼错函数名的情况。考虑在你的样式表输出上运行 CSS linter，以便在发生这种情况时得到通知！
一些 CSS 函数，如 calc() 和 element() 具有不寻常的语法。Sass 会将这些函数特别解析为不带引号的字符串。