@function

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

函数使用 @function at 规则定义，该规则写为 @function <name>(<arguments...>) { ... }。函数的名称可以是任何 Sass 标识符。它只能包含 通用语句，以及 @return at 规则，该规则指示用作函数调用结果的值。函数使用正常的 CSS 函数 语法调用。

SCSS 语法

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

💡 有趣的事实

函数名称与所有 Sass 标识符一样，将连字符和下划线视为相同。这意味着 scale-color 和 scale_color 都指代同一个函数。这是 Sass 早期遗留的历史问题，当时 Sass 仅允许标识符名称中使用下划线。一旦 Sass 添加了对连字符的支持以匹配 CSS 的语法，两者就变得等价，以便更容易地进行迁移 。

⚠️ 注意！

虽然函数在技术上可以产生副作用，例如设置 全局变量，但强烈不建议这样做。使用 混合 产生副作用，并仅使用函数计算 值。

参数参数永久链接

参数允许在每次调用函数时自定义函数的行为。参数在 @function 规则中指定，位于函数名称之后，作为用括号括起来的变量名称列表。必须使用 SassScript 表达式 的形式调用具有相同数量参数的函数。这些表达式的值在函数体中作为相应的 变量可用。

💡 有趣的事实

参数列表也可以有尾随逗号！这使得在重构 样式表时更容易避免语法错误。

可选参数可选参数永久链接

通常，函数声明的每个参数都必须在包含该函数时传递。但是，你可以通过定义一个默认值来使参数变为可选，如果该参数未传递，则将使用该默认值。默认值使用与 变量声明 相同的语法：变量名称，后跟冒号和 SassScript 表达式。这使得可以轻松定义灵活的函数 API，这些 API 可以以简单或复杂 的方式使用。

SCSS 语法

@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: #523314;
}

💡 有趣的事实

默认值可以是任何 SassScript 表达式，甚至可以引用更早的 参数！

关键字参数关键字参数永久链接

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

SCSS 语法

$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: #0a85ff;
}

⚠️ 注意！

因为任何参数都可以按名称传递，所以在重命名函数的参数时要小心……它可能会破坏你的用户！将旧名称保留为 可选参数 一段时间并打印 警告 可能会很有帮助，如果有人传递了该参数，他们就会知道要迁移到新的 参数。

接受任意参数接受任意参数 永久链接

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

SCSS 语法

@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() 函数 也可以使用参数列表来接受任意关键字参数，它接受一个参数列表，并将作为 映射 传递给函数的任何额外关键字返回，其中包含参数名称（不包括 $）及其参数的 值。

💡 有趣的事实

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

传递任意参数传递任意参数 永久链接

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

SCSS 语法

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

Sass 语法

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

CSS 输出

.micro {
  width: 30px;
}

💡 有趣的事实

由于 参数列表 同时跟踪位置和关键字参数，因此您可以使用它一次将两者传递给另一个函数。这使得为 函数定义别名变得非常容易！

SCSS 语法

@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 永久链接

@return at 规则指示用作调用函数结果的值。它仅允许在 @function 正文内，并且每个 @function 都必须以 @return 结尾。

遇到 @return 时，它会立即结束函数并返回其结果。提前返回对于处理边缘案例或在无需用 @else 块 包装整个函数的情况下可以使用更有效算法的情况非常有用。

SCSS 语法

@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

其他函数其他函数 permalink

除了用户定义的函数，Sass 还提供了一个丰富的 核心库，其中包含始终可用的内置函数。Sass 实现还允许在宿主语言中定义 自定义函数。当然，您始终可以调用 普通 CSS 函数（即使是具有 奇怪语法 的函数）。

普通 CSS 函数普通 CSS 函数 permalink

任何既不是用户定义函数也不是 内置 函数的函数调用都会编译为普通 CSS 函数（除非它使用 Sass 参数语法）。参数将被编译为 CSS 并按原样包含在函数调用中。这确保了 Sass 支持所有 CSS 函数，而无需在每次添加新函数时发布新版本。

SCSS 语法

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

⚠️ 注意！

由于任何未知函数都将被编译为 CSS，因此很容易错过输入函数名称时出现的错误。考虑对样式表的输出运行 CSS linter，以便在发生这种情况时收到通知！

💡 有趣的事实

一些 CSS 函数，如 calc() 和 element() 具有不寻常的语法。Sass 以特殊方式解析这些函数，作为 未加引号的 字符串。