内置模块

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

Sass 提供了许多内置模块，其中包含有用的函数（以及偶尔的 mixin）。这些模块可以像任何用户定义的样式表一样使用 @use 规则加载，并且它们的功能可以调用像任何其他模块成员一样。所有内置模块 URL 都以 sass: 开头，表明它们是 Sass 本身的一部分。

⚠️ Heads up!

在引入 Sass 模块系统之前，所有 Sass 函数在任何时候都是全局可用的。许多函数仍然具有全局别名（这些别名在其文档中列出）。Sass 团队不鼓励使用它们，并将最终弃用它们，但目前它们仍然可与旧版 Sass 版本和 LibSass（尚不支持模块系统）兼容。

¥Before the Sass module system was introduced, all Sass functions were globally available at all times. Many functions still have global aliases (these are listed in their documentation). The Sass team discourages their use and will eventually deprecate them, but for now they remain available for compatibility with older Sass versions and with LibSass (which doesn’t support the module system yet).

即使在新的模块系统中，几个功能也仅在全局作用域内可用，因为它们具有特殊的评估行为（if()），或者因为它们在内置 CSS 函数（rgb() 和 hsl()）之上添加了额外的行为。这些不会被弃用并且可以自由使用。

¥A few functions are only available globally even in the new module system, either because they have special evaluation behavior (if()) or because they add extra behavior on top of built-in CSS functions (rgb() and hsl()). These will not be deprecated and can be used freely.

  SCSS

  Sass

  CSS

      
      Playground
    SCSS Syntax@use "sass:color";

.button {
  $primary-color: #6b717f;
  color: $primary-color;
  border: 1px solid color.scale($primary-color, $lightness: 20%);
}

      
      Playground
    Sass Syntax@use "sass:color"

.button
  $primary-color: #6b717f
  color: $primary-color
  border: 1px solid color.scale($primary-color, $lightness: 20%)

CSS Output.button {
  color: #6b717f;
  border: 1px solid rgb(135.1641025641, 140.8256410256, 154.0358974359);
}

Sass 提供了以下内置模块：

¥Sass provides the following built-in modules:

sass:math 模块提供在数字上运行的功能。

¥The sass:math module provides functions that operate on numbers.
sass:string 模块可以轻松组合、搜索或拆分字符串。

¥The sass:string module makes it easy to combine, search, or split apart strings.
sass:color 模块根据现有的生成新的颜色，从而可以轻松构建颜色主题。

¥The sass:color module generates new colors based on existing ones, making it easy to build color themes.
sass:list 模块允许你访问和修改列表中的值。

¥The sass:list module lets you access and modify values in lists.
sass:map 模块可以查找与映射中的键关联的值，等等。

¥The sass:map module makes it possible to look up the value associated with a key in a map, and much more.
sass:selector 模块提供对 Sass 强大的选择器引擎的访问。

¥The sass:selector module provides access to Sass’s powerful selector engine.
sass:meta 模块揭示了 Sass 内部运作的细节。

¥The sass:meta module exposes the details of Sass’s inner workings.

全局函数全局函数 permalink

¥Global Functions

💡 Fun fact:

你可以将特殊功能（如 calc() 或 var()）代替任何参数传递给全局颜色构造函数。你甚至可以使用 var() 代替多个参数，因为它可能会被多个值替换！当以这种方式调用颜色函数时，它会使用与调用时相同的签名返回一个未加引号的字符串。

¥You can pass special functions like calc() or var() in place of any argument to a global color constructor. You can even use var() in place of multiple arguments, since it might be replaced by multiple values! When a color function is called this way, it returns an unquoted string using the same signature it was called with.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug rgb(0 51 102 / var(--opacity)); // rgb(0 51 102 / var(--opacity))
@debug color(display-p3 var(--peach)); // color(display-p3 var(--peach))

      
      Playground
    Sass Syntax@debug rgb(0 51 102 / var(--opacity))  // rgb(0 51 102 / var(--opacity))
@debug color(display-p3 var(--peach))  // color(display-p3 var(--peach))

color($space $channel1 $channel2 $channel3)
color($space $channel1 $channel2 $channel3 / $alpha) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回给定颜色空间中具有给定通道值的颜色。

¥Returns a color in the given color space with the given channel values.

这支持颜色空间 srgb、srgb-linear、display-p3、a98-rgb、prophoto-rgb、rec2020、xyz 和 xyz-d50，以及 xyz-d65（xyz 的别名）。对于所有空间，通道是 0 到 1（含）之间的数字或 0% 和 100%（含）之间的百分比。

¥This supports the color spaces srgb, srgb-linear, display-p3, a98-rgb, prophoto-rgb, rec2020, xyz, and xyz-d50, as well as xyz-d65 which is an alias for xyz. For all spaces, the channels are numbers between 0 and 1 (inclusive) or percentages between 0% and 100% (inclusive).

如果任何颜色通道超出 0 到 1 的范围，则表示颜色超出其颜色空间的标准色域。

¥If any color channel is outside the range 0 to 1, this represents a color outside the standard gamut for its color space.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug color(srgb 0.1 0.6 1); // color(srgb 0.1 0.6 1)
@debug color(xyz 30% 0% 90% / 50%); // color(xyz 0.3 0 0.9 / 50%)

      
      Playground
    Sass Syntax@debug color(srgb 0.1 0.6 1)  // color(srgb 0.1 0.6 1)
@debug color(xyz 30% 0% 90% / 50%)  // color(xyz 0.3 0 0.9 / 50%)

hsl($hue $saturation $lightness)
hsl($hue $saturation $lightness / $alpha)
hsl($hue, $saturation, $lightness, $alpha: 1)
hsla($hue $saturation $lightness)
hsla($hue $saturation $lightness / $alpha)
hsla($hue, $saturation, $lightness, $alpha: 1) //=> color

Dart Sass: since 1.15.0
LibSass: ✗
Ruby Sass: ✗

LibSass and Ruby Sass only support the following signatures:


hsl($hue, $saturation, $lightness)


hsla($hue, $saturation, $lightness, $alpha)


Note that for these implementations, the $alpha argument is required if
the function name hsla() is used, and forbidden if the function name
hsl() is used.

Dart Sass: ✓
LibSass: ✗
Ruby Sass: since 3.7.0

LibSass and older versions of Ruby Sass don't support alpha values specified
as percentages.

返回具有给定色调、饱和度和亮度和给定 alpha 通道的颜色。

¥Returns a color with the given hue, saturation, and lightness and the given alpha channel.

色调是 0deg 到 360deg（含）之间的数字，并且可以是无单位的。饱和度和亮度通常是 0% 到 100%（含）之间的数字，可以不是无单位。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The hue is a number between 0deg and 360deg (inclusive) and may be unitless. The saturation and lightness are typically numbers between 0% and 100% (inclusive) and may not be unitless. The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0deg 和 360deg 之外的色调相当于 $hue % 360deg。饱和度小于 0% 的将被限制为 0%。饱和度高于 100% 或亮度超出 0% 和 100% 都是允许的，并且表示标准 RGB 色域之外的颜色。

¥A hue outside 0deg and 360deg is equivalent to $hue % 360deg. A saturation less than 0% is clamped to 0%. A saturation above 100% or a lightness outside 0% and 100% are both allowed, and represent colors outside the standard RGB gamut.

⚠️ Heads up!

Sass's [special parsing rules][] for slash-separated values make it
difficult to pass variables for `$lightness` or `$alpha` when using the
`hsl($hue $saturation $lightness / $alpha)` signature. Consider using
`hsl($hue, $saturation, $lightness, $alpha)` instead.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug hsl(210deg 100% 20%); // #036
@debug hsl(210deg 100% 20% / 50%); // rgba(0, 51, 102, 0.5)
@debug hsla(34, 35%, 92%, 0.2); // rgba(241.74, 235.552, 227.46, 0.2)

      
      Playground
    Sass Syntax@debug hsl(210deg 100% 20%) // #036
@debug hsl(210deg 100% 20% / 50%)  // rgba(0, 51, 102, 0.5)
@debug hsla(34, 35%, 92%, 0.2)  // rgba(241.74, 235.552, 227.46, 0.2)

hwb($hue $whiteness $blackness)
hwb($hue $whiteness $blackness / $alpha)
color.hwb($hue $whiteness $blackness)
color.hwb($hue $whiteness $blackness / $alpha)
color.hwb($hue, $whiteness, $blackness, $alpha: 1) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回具有给定色相、白度和黑度和给定 alpha 通道的颜色。

¥Returns a color with the given hue, whiteness, and blackness and the given alpha channel.

色调是 0deg 到 360deg（含）之间的数字，并且可以是无单位的。白度和黑度通常是 0% 到 100%（含）之间的数字，可以不是无单位。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The hue is a number between 0deg and 360deg (inclusive) and may be unitless. The whiteness and blackness are numbers typically between 0% and 100% (inclusive) and may not be unitless. The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0deg 和 360deg 之外的色调相当于 $hue % 360deg。如果为 $whiteness + $blackness > 100%，则两个值会按比例缩放，使其相加为 100%。如果 $whiteness、$blackness 或两者都小于 0%，则表示颜色超出标准 RGB 色域。

¥A hue outside 0deg and 360deg is equivalent to $hue % 360deg. If $whiteness + $blackness > 100%, the two values are scaled so that they add up to 100%. If $whiteness, $blackness, or both are less than 0%, this represents a color outside the standard RGB gamut.

⚠️ Heads up!

The `color.hwb()` variants are deprecated. New Sass code should use the
global `hwb()` function instead.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug hwb(210deg 0% 60%); // #036
@debug hwb(210 0% 60% / 0.5); // rgba(0, 51, 102, 0.5)

      
      Playground
    Sass Syntax@debug hwb(210deg 0% 60%)  // #036
@debug hwb(210 0% 60% / 0.5)  // rgba(0, 51, 102, 0.5)

if($condition, $if-true, $if-false)

如果 $condition 是真实的，则返回 $if-true，否则返回 $if-false。

¥Returns $if-true if $condition is truthy, and $if-false otherwise.

该函数的特殊之处在于它甚至不计算未返回的参数，因此即使未使用的参数会引发错误，调用也是安全的。

¥This function is special in that it doesn’t even evaluate the argument that isn’t returned, so it’s safe to call even if the unused argument would throw an error.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug if(true, 10px, 15px); // 10px
@debug if(false, 10px, 15px); // 15px
@debug if(variable-defined($var), $var, null); // null

      
      Playground
    Sass Syntax@debug if(true, 10px, 15px)  // 10px
@debug if(false, 10px, 15px)  // 15px
@debug if(variable-defined($var), $var, null)  // null

lab($lightness $a $b)
lab($lightness $a $b / $alpha) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回具有给定 [亮度、a、b] 和 alpha 通道的颜色。

¥Returns a color with the given [lightness, a, b], and alpha channels.

亮度是 0% 到 100%（含）之间的数字，可以无单位。a 和 b 通道可以指定为 -125 到 125（含）之间的无单位的数字，或 -100% 到 100%（含）之间的百分比。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The lightness is a number between 0% and 100% (inclusive) and may be unitless. The a and b channels can be specified as either unitless numbers between -125 and 125 (inclusive), or percentages between -100% and 100% (inclusive). The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0% 和 100% 范围之外的亮度被限制在该范围内。如果 a 或 b 通道超出 -125 到 125 的范围，则表示颜色超出标准 CIELAB 色域。

¥A lightness outside the range 0% and 100% is clamped to be within that range. If the a or b channels are outside the range -125 to 125, this represents a color outside the standard CIELAB gamut.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug lab(50% -20 30); // lab(50% -20 30)
@debug lab(80% 0% 20% / 0.5); // lab(80% 0 25 / 0.5);

      
      Playground
    Sass Syntax@debug lab(50% -20 30)  // lab(50% -20 30)
@debug lab(80% 0% 20% / 0.5)  // lab(80% 0 25 / 0.5);

lch($lightness $chroma $hue)
lch($lightness $chroma $hue / $alpha) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回具有给定 [亮度、色度和色调] 和给定 alpha 通道的颜色。

¥Returns a color with the given [lightness, chroma, and hue], and the given alpha channel.

亮度是 0% 到 100%（含）之间的数字，可以无单位。色度通道可以指定为 0 到 150（含）之间的无单位的数字，或 0% 到 100%（含）之间的百分比。色调是 0deg 到 360deg（含）之间的数字，并且可以是无单位的。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The lightness is a number between 0% and 100% (inclusive) and may be unitless. The chroma channel can be specified as either a unitless number between 0 and 150 (inclusive), or a percentage between 0% and 100% (inclusive). The hue is a number between 0deg and 360deg (inclusive) and may be unitless. The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0% 和 100% 范围之外的亮度被限制在该范围内。低于 0 的色度被限制为 0，高于 150 的色度表示超出标准 CIELAB 色域的颜色。0deg 和 360deg 之外的色调相当于 $hue % 360deg。

¥A lightness outside the range 0% and 100% is clamped to be within that range. A chroma below 0 is clamped to 0, and a chroma above 150 represents a color outside the standard CIELAB gamut. A hue outside 0deg and 360deg is equivalent to $hue % 360deg.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug lch(50% 10 270deg); // lch(50% 10 270deg)
@debug lch(80% 50% 0.2turn / 0.5); // lch(80% 75 72deg / 0.5);

      
      Playground
    Sass Syntax@debug lch(50% 10 270deg)  // lch(50% 10 270deg)
@debug lch(80% 50% 0.2turn / 0.5)  // lch(80% 75 72deg / 0.5);

oklab($lightness $a $b)
oklab($lightness $a $b / $alpha) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回具有给定感知均匀亮度，a，b 和 alpha 通道的颜色。

¥Returns a color with the given perceptually-uniform lightness, a, b, and alpha channels.

亮度是 0% 到 100%（含）之间的数字，可以无单位。a 和 b 通道可以指定为 -0.4 到 0.4（含）之间的无单位的数字，或 -100% 到 100%（含）之间的百分比。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The lightness is a number between 0% and 100% (inclusive) and may be unitless. The a and b channels can be specified as either unitless numbers between -0.4 and 0.4 (inclusive), or percentages between -100% and 100% (inclusive). The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0% 和 100% 范围之外的亮度被限制在该范围内。如果 a 或 b 通道超出 -0.4 到 0.4 的范围，则表示颜色超出标准 Oklab 色域。

¥A lightness outside the range 0% and 100% is clamped to be within that range. If the a or b channels are outside the range -0.4 to 0.4, this represents a color outside the standard Oklab gamut.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug oklab(50% -0.1 0.15); // oklab(50% -0.1 0.15)
@debug oklab(80% 0% 20% / 0.5); // oklab(80% 0 0.08 / 0.5)

      
      Playground
    Sass Syntax@debug oklab(50% -0.1 0.15)  // oklab(50% -0.1 0.15)
@debug oklab(80% 0% 20% / 0.5)  // oklab(80% 0 0.08 / 0.5)

oklch($lightness $chroma $hue)
oklch($lightness $chroma $hue / $alpha) //=> color

Dart Sass: since 1.78.0
LibSass: ✗
Ruby Sass: ✗

返回具有给定 [感知均匀的亮度、色度和色调] 和给定 alpha 通道的颜色。

¥Returns a color with the given [perceptually-uniform lightness, chroma, and hue], and the given alpha channel.

亮度是 0% 到 100%（含）之间的数字，可以无单位。色度通道可以指定为 0 到 0.4（含）之间的无单位的数字，或 0% 到 100%（含）之间的百分比。色调是 0deg 到 360deg（含）之间的数字，并且可以是无单位的。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥The lightness is a number between 0% and 100% (inclusive) and may be unitless. The chroma channel can be specified as either a unitless number between 0 and 0.4 (inclusive), or a percentage between 0% and 100% (inclusive). The hue is a number between 0deg and 360deg (inclusive) and may be unitless. The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

0% 和 100% 范围之外的亮度被限制在该范围内。低于 0 的色度被限制为 0，高于 0.4 的色度表示超出标准 Oklab 色域的颜色。0deg 和 360deg 之外的色调相当于 $hue % 360deg。

¥A lightness outside the range 0% and 100% is clamped to be within that range. A chroma below 0 is clamped to 0, and a chroma above 0.4 represents a color outside the standard Oklab gamut. A hue outside 0deg and 360deg is equivalent to $hue % 360deg.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug oklch(50% 0.3 270deg); // oklch(50% 0.3 270deg)
@debug oklch(80% 50% 0.2turn / 0.5); // oklch(80% 0.2 72deg / 0.5);

      
      Playground
    Sass Syntax@debug oklch(50% 0.3 270deg)  // oklch(50% 0.3 270deg)
@debug oklch(80% 50% 0.2turn / 0.5)  // oklch(80% 0.2 72deg / 0.5);

rgb($red $green $blue)
rgb($red $green $blue / $alpha)
rgb($red, $green, $blue, $alpha: 1)
rgb($color, $alpha)
rgba($red $green $blue)
rgba($red $green $blue / $alpha)
rgba($red, $green, $blue, $alpha: 1)
rgba($color, $alpha) //=> color

Dart Sass: since 1.15.0
LibSass: ✗
Ruby Sass: ✗

LibSass and Ruby Sass only support the following signatures:


rgb($red, $green, $blue)


rgba($red, $green, $blue, $alpha)


rgba($color, $alpha)


Note that for these implementations, the $alpha argument is required if
the function name rgba() is used, and forbidden if the function name
rgb() is used.

Dart Sass: ✓
LibSass: ✗
Ruby Sass: since 3.7.0

LibSass and older versions of Ruby Sass don't support alpha values specified
as percentages.

如果传递了 $red、$green、$blue 和可选的 $alpha，则返回具有给定红色、绿色、蓝色和 Alpha 通道的颜色。

¥If $red, $green, $blue, and optionally $alpha are passed, returns a color with the given red, green, blue, and alpha channels.

每个通道可以指定为 0 到 255（含）之间的无单位的数字，或 0% 到 100%（含）之间的百分比。Alpha 通道可以指定为 0 到 1（含）之间的无单位数字，或者 0% 到 100%（含）之间的百分比。

¥Each channel can be specified as either a unitless number between 0 and 255 (inclusive), or a percentage between 0% and 100% (inclusive). The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

如果任何颜色通道超出 0 到 255 的范围，则表示颜色超出标准 RGB 色域。

¥If any color channel is outside the range 0 to 255, this represents a color outside the standard RGB gamut.

⚠️ Heads up!

Sass's [special parsing rules][] for slash-separated values make it
difficult to pass variables for `$blue` or `$alpha` when using the
`rgb($red $green $blue / $alpha)` signature. Consider using
`rgb($red, $green, $blue, $alpha)` instead.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug rgb(0 51 102); // #036
@debug rgb(95%, 92.5%, 89.5%); // #f2ece4
@debug rgb(0 51 102 / 50%); // rgba(0, 51, 102, 0.5)
@debug rgba(95%, 92.5%, 89.5%, 0.2); // rgba(242, 236, 228, 0.2)

      
      Playground
    Sass Syntax@debug rgb(0 51 102)  // #036
@debug rgb(95%, 92.5%, 89.5%)  // #f2ece4
@debug rgb(0 51 102 / 50%)  // rgba(0, 51, 102, 0.5)
@debug rgba(95%, 92.5%, 89.5%, 0.2)  // rgba(242, 236, 228, 0.2)

如果传递了 $color 和 $alpha，则返回带有给定 $alpha 通道的 $color，而不是其原始 Alpha 通道。

¥If $color and $alpha are passed, this returns $color with the given $alpha channel instead of its original alpha channel.

  SCSS

  Sass

      
      Playground
    SCSS Syntax@debug rgb(#f2ece4, 50%); // rgba(242, 236, 228, 0.5);
@debug rgba(rgba(0, 51, 102, 0.5), 1); // #003366

      
      Playground
    Sass Syntax@debug rgb(#f2ece4, 50%)  // rgba(242, 236, 228, 0.5)
@debug rgba(rgba(0, 51, 102, 0.5), 1)  // #003366