元数据 Meta

Compatibility: Dart Sass since 1.23.0 LibSass ✗ Ruby Sass ✗

Mixins

meta.load-css($url, $with: null)

Compatibility: Dart Sass since 1.23.0 LibSass ✗ Ruby Sass ✗

在 $url 加载 module 并包含其 CSS，就好像它是作为此 mixin 的内容编写的一样。 $with 参数为模块提供 configuration；如果通过，则它必须是从变量名(不带 $)到要在加载模块中使用的变量值的映射。

如果 $url 是相对的，它被解释为相对于包含 meta.load-css() 的文件。

就像 @use 规则：

这只会评估给定的模块一次，即使它以不同的方式加载了多次。
这不能为已经加载的模块提供配置，无论它是否已经加载了配置。

不同于 @use 规则：

这不会使加载模块中的任何成员在当前模块中可用。
这可以在样式表中的任何地方使用。它甚至可以嵌套在样式规则中以创建嵌套样式！
正在加载的模块 URL 可以来自变量并包含 interpolation。

⚠️ 注意！

$url 参数应该是一个包含 URL 的字符串，就像您传递给 @use 规则一样。它不应该是 CSS url()！

SCSS Syntax

dark-theme/_code.scss

scss

$border-contrast: false !default;

code {
  background-color: #6b717f;
  color: #d2e1dd;
  @if $border-contrast {
    border-color: #dadbdf;
  }
}

style.scss

scss

@use "sass:meta";

body.dark {
  @include meta.load-css("dark-theme/code",
      $with: ("border-contrast": true));
}

Functions

scss

meta.calc-args($calc) //=> list

Compatibility: Dart Sass since 1.40.0 LibSass ✗ Ruby Sass ✗

返回给定 calculation 的参数。

如果参数是数字或嵌套计算，则返回该类型。否则，它作为未加引号的字符串返回。

SCSS Syntax

scss

@debug meta.calc-args(calc(100px + 10%)); // unquote("100px + 10%")
@debug meta.calc-args(clamp(50px, var(--width), 1000px)); // 50px, unquote("var(--width)"), 1000px

scss

meta.calc-name($calc) //=> quoted string

Compatibility: Dart Sass since 1.40.0 LibSass ✗ Ruby Sass ✗

Returns the name of the given calculation.

SCSS Syntax

scss

@debug meta.calc-name(calc(100px + 10%)); // "calc"
@debug meta.calc-name(clamp(50px, var(--width), 1000px)); // "clamp"

scss

meta.call($function, $args...)
call($function, $args...)

Compatibility (Argument Type): Dart Sass ✓ LibSass since 3.5.0 Ruby Sass since 3.5.0

使用 $args 调用 $function 并返回结果。

$function 应该是由 meta.get-function() 返回的 function。

SCSS Syntax

scss

@use "sass:list";
@use "sass:meta";
@use "sass:string";

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition) {
  $new-list: ();
  $separator: list.separator($list);
  @each $element in $list {
    @if not meta.call($condition, $element) {
      $new-list: list.append($new-list, $element, $separator: $separator);
    }
  }
  @return $new-list;
}

$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;

content {
  @function contains-helvetica($string) {
    @return string.index($string, "Helvetica");
  }
  font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

scss

meta.content-exists()
content-exists() //=> boolean

返回当前 mixin 是否传递了 @content 块。

如果在 mixin 外部调用，则会抛出错误。

SCSS Syntax

scss

@mixin debug-content-exists {
  @debug meta.content-exists();
  @content;
}

@include debug-content-exists; // false
@include debug-content-exists { // true
  // Content!
}

scss

meta.feature-exists($feature)
feature-exists($feature) //=> boolean

返回当前 Sass 实现是否支持 $feature。

$feature 必须是字符串。目前公认的特征是：

global-variable-shadowing，这意味着局部变量将 shadow 全局变量，除非它有 !global 标志。
extend-selector-pseudoclass，这意味着 @extend 规则将影响嵌套在伪类中的选择器，例如 :not()。
units-level3，这意味着 unit arithmetic 支持 [CSS Values and Units Level 3](http://www.w3.org/TR /css3-值)。
at-error，这意味着支持 @error 规则。
custom-property，这意味着自定义属性声明值不支持任何 [表达式](/syntax/structure# 表达式)而不是 interpolation。

Returns false for any unrecognized $feature.

SCSS Syntax

scss

@debug meta.feature-exists("at-error"); // true
@debug meta.feature-exists("unrecognized"); // false

scss

meta.function-exists($name, $module: null)
function-exists($name) //=> boolean

返回名为$name的函数是否被定义为内置函数或用户定义函数。

如果传递了 $module，这也会检查名为 $module 的模块的函数定义。 $module 必须是匹配当前文件中 @use 规则的命名空间的字符串。

SCSS Syntax

scss

@use "sass:math";

@debug meta.function-exists("div", "math"); // true
@debug meta.function-exists("scale-color"); // true
@debug meta.function-exists("add"); // false

@function add($num1, $num2) {
  @return $num1 + $num2;
}
@debug meta.function-exists("add"); // true

scss

meta.get-function($name, $css: false, $module: null)
get-function($name, $css: false, $module: null) //=> function

返回名为 $name 的 function。

如果 $module 为 null，则返回名为 $name 的函数，不带命名空间(包括全局内置函数)。否则，$module 必须是匹配当前文件中 @use 规则的命名空间的字符串，在这种情况下，这将返回该模块中名为 $名字。

默认情况下，如果 $name 没有引用 Sass 函数，则会抛出错误。但是，如果 $css 为 true，它会返回一个纯 CSS 函数。

可以使用 meta.call() 调用返回的函数。

SCSS Syntax

@use "sass:list";
@use "sass:meta";
@use "sass:string";

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition) {
  $new-list: ();
  $separator: list.separator($list);
  @each $element in $list {
    @if not meta.call($condition, $element) {
      $new-list: list.append($new-list, $element, $separator: $separator);
    }
  }
  @return $new-list;
}

$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;

content {
  @function contains-helvetica($string) {
    @return string.index($string, "Helvetica");
  }
  font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

meta.global-variable-exists($name, $module: null)
global-variable-exists($name, $module: null) //=> boolean

返回是否存在名为“$name”(不带“$”)的全局变量。

如果 $module 为 null，则返回是否存在名为 $name 的没有命名空间的变量。否则，$module 必须是与当前文件中的 @use 规则的命名空间相匹配的字符串，在这种情况下，这将返回该模块是否具有变量名为$name。

另见 meta.variable-exists()。

SCSS Syntax

@debug meta.global-variable-exists("var1"); // false

$var1: value;
@debug meta.global-variable-exists("var1"); // true

h1 {
  // $var2 is local.
  $var2: value;
  @debug meta.global-variable-exists("var2"); // false
}

meta.inspect($value)
inspect($value) //=> unquoted string

返回 $value 的字符串表示形式。

返回_any_ Sass 值的表示，而不仅仅是那些可以用 CSS 表示的值。因此，不保证其返回值是有效的 CSS。

⚠️ 注意！

此功能用于调试；不保证其输出格式在 Sass 版本或实现中保持一致。

SCSS Syntax

@debug meta.inspect(10px 20px 30px); // unquote("10px 20px 30px")
@debug meta.inspect(("width": 200px)); // unquote('("width": 200px)')
@debug meta.inspect(null); // unquote("null")
@debug meta.inspect("Helvetica"); // unquote('"Helvetica"')

meta.keywords($args)
keywords($args) //=> map

返回传递给采用任意参数的 mixin 或函数的关键字。 $args 参数必须是一个参数列表。

关键字作为参数名称作为不带引号的字符串(不包括“$”)到这些参数的值的映射返回。

SCSS Syntax

@use "sass:meta";

@mixin syntax-colors($args...) {
  @debug meta.keywords($args);
  // (string: #080, comment: #800, variable: #60b)

  @each $name, $color in meta.keywords($args) {
    pre span.stx-#{$name} {
      color: $color;
    }
  }
}

@include syntax-colors(
  $string: #080,
  $comment: #800,
  $variable: #60b,
)

meta.mixin-exists($name, $module: null)
mixin-exists($name, $module: null) //=> boolean

返回名为 $name 的 mixin 是否存在。

如果 $module 为 null，则返回是否存在名为 $name 的没有命名空间的 mixin。否则，$module 必须是匹配当前文件中 @use 规则的命名空间的字符串，在这种情况下，这将返回该模块是否具有混合名为$name。

SCSS Syntax

@debug meta.mixin-exists("shadow-none"); // false

@mixin shadow-none {
  box-shadow: none;
}

@debug meta.mixin-exists("shadow-none"); // true

meta.module-functions($module) //=> map

Compatibility: Dart Sass since 1.23.0 LibSass ✗ Ruby Sass ✗

返回模块中定义的所有函数，作为从函数名称到函数值的映射。

$module 参数必须是匹配当前文件中 @use 规则命名空间的字符串。

SCSS Syntax

// _functions.scss
@function pow($base, $exponent) {
  $result: 1;
  @for $_ from 1 through $exponent {
    $result: $result * $base;
  }
  @return $result;
}

@use "sass:map";
@use "sass:meta";

@use "functions";

@debug meta.module-functions("functions"); // ("pow": get-function("pow"))

@debug meta.call(map.get(meta.module-functions("functions"), "pow"), 3, 4); // 81

meta.module-variables($module) //=> map

Compatibility: Dart Sass since 1.23.0 LibSass ✗ Ruby Sass ✗

返回模块中定义的所有变量，作为从变量名(不带“$”)到这些变量值的映射。

$module 参数必须是匹配当前文件中 @use 规则命名空间的字符串。

SCSS Syntax

// _variables.scss
$hopbush: #c69;
$midnight-blue: #036;
$wafer: #e1d7d2;

@use "sass:meta";

@use "variables";

@debug meta.module-variables("variables");
// (
//   "hopbush": #c69,
//   "midnight-blue": #036,
//   "wafer": #e1d7d2
// )

meta.type-of($value)
type-of($value) //=> unquoted string

Returns the type of $value.

This can return the following values:

将来可能会添加新的可能值。它可能会为 () 返回 list 或 map，具体取决于它是否由 map 函数返回。

SCSS Syntax

@debug meta.type-of(10px); // number
@debug meta.type-of(10px 20px 30px); // list
@debug meta.type-of(()); // list

meta.variable-exists($name)
variable-exists($name) //=> boolean

返回当前 scope 中是否存在名为$name(不带$)的变量。

另见 meta.global-variable-exists()。

SCSS Syntax

@debug meta.variable-exists("var1"); // false

$var1: value;
@debug meta.variable-exists("var1"); // true

h1 {
  // $var2 is local.
  $var2: value;
  @debug meta.variable-exists("var2"); // true
}