@function

函数使用 @function at-rule 定义，写作 @function <n>(<参数...>) { ... }。函数名可以是任何不以 -- 开头的 Sass 标识符。它只能包含通用语句，以及 @return at-rule，后者指示用作函数调用结果的值。函数使用普通的 CSS 函数语法调用。

• SCSS
• Sass
• CSS

Playground

SCSS Syntax

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

Playground

Sass Syntax

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

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

参数参数 permalink

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

可选参数可选参数 permalink

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

• SCSS
• Sass
• CSS

Playground

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

Playground

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: rgb(81.6, 51, 20.4);
}

关键字参数关键字参数 permalink

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

• SCSS
• Sass
• CSS

Playground

SCSS Syntax

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

Playground

Sass Syntax

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

CSS Output

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

接受任意参数接受任意参数 permalink

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

• SCSS
• Sass
• CSS

Playground

SCSS Syntax

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

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

Playground

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() 函数接受一个参数列表，并返回传递给函数的任何额外关键字，作为从参数名（不包括 $）到这些参数值的映射。

传递任意参数传递任意参数 permalink

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

• SCSS
• Sass
• CSS

Playground

SCSS Syntax

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

Playground

Sass Syntax

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

CSS Output

.micro {
  width: 30px;
}

💡 Fun fact:

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

• SCSS
• Sass

Playground

SCSS Syntax

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

Playground

Sass Syntax

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

@return@return permalink

The @return at-rule indicates the value to use as the result of calling a function. It’s only allowed within a @function body, and each @function must end with a @return.

When a @return is encountered, it immediately ends the function and returns its result. Returning early can be useful for handling edge-cases or cases where a more efficient algorithm is available without wrapping the entire function in an @else block.

• SCSS
• Sass

Playground

SCSS Syntax

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

Playground

Sass Syntax

@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

Other FunctionsOther Functions permalink

In addition to user-defined function, Sass provides a substantial core library of built-in functions that are always available to use. Sass implementations also make it possible to define custom functions in the host language. And of course, you can always call plain CSS functions (even ones with weird syntax).

Plain CSS FunctionsPlain CSS Functions permalink

Any function call that’s not either a user-defined or built-in function is compiled to a plain CSS function (unless it uses Sass argument syntax). The arguments will be compiled to CSS and included as-is in the function call. This ensures that Sass supports all CSS functions without needing to release new versions every time a new one is added.

• SCSS
• Sass

Playground

SCSS Syntax

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

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

Playground

Sass Syntax

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

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