@use

Dart Sass: 自 1.23.0 版本起
LibSass: ✗
Ruby Sass: ✗

目前只有 Dart Sass 支持 @use。其他实现的用户必须使用 @import 规则。

@use 规则从其他 Sass 样式表中加载 mixin、函数和变量，并将来自多个样式表的 CSS 合并在一起。通过 @use 加载的样式表称为“模块”。Sass 还提供内置模块，其中包含许多有用的函数。

最简单的 @use 规则写成 @use "<url>"，它加载给定 URL 处的模块。以这种方式加载的任何样式将被精确地包含在编译后的 CSS 输出中，无论这些样式被加载多少次。

⚠️ 注意！

样式表的 @use 规则必须位于除 @forward 之外的任何规则之前，包括样式规则。但是，您可以在 @use 规则之前声明变量，以便在配置模块时使用。

  SCSS

  Sass

  CSS
SCSS 语法// foundation/_code.scss
code {
  padding: .25em;
  line-height: 0;
}
// foundation/_lists.scss
ul, ol {
  text-align: left;

  & & {
    padding: {
      bottom: 0;
      left: 0;
    }
  }
}
// style.scss
@use 'foundation/code';
@use 'foundation/lists';
Sass 语法// foundation/_code.sass
code
  padding: .25em
  line-height: 0

// foundation/_lists.sass
ul, ol
  text-align: left

  & &
    padding:
      bottom: 0
      left: 0



// style.sass
@use 'foundation/code'
@use 'foundation/lists'
CSS 输出code {
  padding: .25em;
  line-height: 0;
}

ul, ol {
  text-align: left;
}
ul ul, ol ol {
  padding-bottom: 0;
  padding-left: 0;
}

加载成员加载成员链接

您可以通过编写 <namespace>.<variable>、<namespace>.<function>() 或 @include <namespace>.<mixin>() 来访问另一个模块中的变量、函数和 mixin。默认情况下，命名空间只是模块 URL 的最后一个组件。

使用 @use 加载的成员（变量、函数和 mixin）仅在加载它们的样式表中可见。其他样式表需要编写自己的 @use 规则才能访问它们。这有助于轻松地确定每个成员来自哪里。如果您想从多个文件加载成员，可以使用 @forward 规则将它们全部从一个共享文件中转发。

💡 趣闻

由于 @use 为成员名称添加了命名空间，因此在编写样式表时，选择 $radius 或 $width 这样简单的名称是安全的。这与旧的 @import 规则不同，它鼓励用户编写 $mat-corner-radius 这样的长名称以避免与其他库冲突，这有助于保持您的样式表清晰易读！

  SCSS

  Sass

  CSS
SCSS 语法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners";

.button {
  @include corners.rounded;
  padding: 5px + corners.$radius;
}
Sass 语法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners"

.button
  @include corners.rounded
  padding: 5px + corners.$radius

CSS 输出.button {
  border-radius: 3px;
  padding: 8px;
}

选择命名空间选择命名空间链接

默认情况下，模块的命名空间只是其 URL 的最后一个组件，不带文件扩展名。但是，有时您可能想要选择不同的命名空间——您可能希望为经常引用的模块使用更短的名称，或者您可能正在加载多个具有相同文件名的模块。您可以通过编写 @use "<url>" as <namespace> 来实现。

  SCSS

  Sass

  CSS
SCSS 语法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners" as c;

.button {
  @include c.rounded;
  padding: 5px + c.$radius;
}
Sass 语法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners" as c

.button
  @include c.rounded
  padding: 5px + c.$radius

CSS 输出.button {
  border-radius: 3px;
  padding: 8px;
}

您甚至可以通过编写 @use "<url>" as * 来加载没有命名空间的模块。我们建议您只对您自己编写的样式表这样做；否则，它们可能会引入新的成员，从而导致名称冲突！

  SCSS

  Sass

  CSS
SCSS 语法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners" as *;

.button {
  @include rounded;
  padding: 5px + $radius;
}
Sass 语法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners" as *

.button
  @include rounded
  padding: 5px + $radius

CSS 输出.button {
  border-radius: 3px;
  padding: 8px;
}

私有成员私有成员链接

作为样式表作者，您可能不希望您定义的所有成员都可以在样式表之外使用。Sass 使定义私有成员变得容易，只需将其名称以 - 或 _ 开头即可。这些成员在定义它们的样式表中将像普通成员一样工作，但它们不会是模块的公共 API 的一部分。这意味着加载您模块的样式表无法看到它们！

💡 趣闻

如果您想将成员设为整个包的私有成员，而不是单个模块的私有成员，只需不要从您的包的任何入口点（您告诉用户加载以使用您的包的样式表）转发其模块。您甚至可以在转发其余模块时隐藏该成员！

  SCSS

  Sass
SCSS 语法// src/_corners.scss
$-radius: 3px;

@mixin rounded {
  border-radius: $-radius;
}
// style.scss
@use "src/corners";

.button {
  @include corners.rounded;

  // This is an error! $-radius isn't visible outside of `_corners.scss`.
  padding: 5px + corners.$-radius;
}
Sass 语法// src/_corners.sass
$-radius: 3px

@mixin rounded
  border-radius: $-radius

// style.sass
@use "src/corners"

.button
  @include corners.rounded

  // This is an error! $-radius isn't visible outside of `_corners.scss`.
  padding: 5px + corners.$-radius

配置配置链接

样式表可以使用 !default 标志来定义变量，使其可配置。要使用配置加载模块，请编写 @use <url> with (<variable>: <value>, <variable>: <value>)。配置的值将覆盖变量的默认值。

  SCSS

  Sass

  CSS
SCSS 语法// _library.scss
$black: #000 !default;
$border-radius: 0.25rem !default;
$box-shadow: 0 0.5rem 1rem rgba($black, 0.15) !default;

code {
  border-radius: $border-radius;
  box-shadow: $box-shadow;
}
// style.scss
@use 'library' with (
  $black: #222,
  $border-radius: 0.1rem
);
Sass 语法// _library.sass
$black: #000 !default
$border-radius: 0.25rem !default
$box-shadow: 0 0.5rem 1rem rgba($black, 0.15) !default

code
  border-radius: $border-radius
  box-shadow: $box-shadow

// style.sass
@use 'library' with ($black: #222, $border-radius: 0.1rem)



CSS 输出code {
  border-radius: 0.1rem;
  box-shadow: 0 0.5rem 1rem rgba(34, 34, 34, 0.15);
}

使用 Mixin使用 Mixin 链接

使用 @use ... with 配置模块非常方便，尤其是在使用最初编写为与 @import 规则一起使用的库时。但它并不是特别灵活，我们不建议将其用于更高级的用例。如果您发现自己想一次配置多个变量，请将映射作为配置传递，或者在加载模块后更新配置，请考虑编写一个 mixin 来设置您的变量，以及另一个 mixin 来注入您的样式。

  SCSS

  Sass

  CSS
SCSS 语法// _library.scss
$-black: #000;
$-border-radius: 0.25rem;
$-box-shadow: null;

/// If the user has configured `$-box-shadow`, returns their configured value.
/// Otherwise returns a value derived from `$-black`.
@function -box-shadow() {
  @return $-box-shadow or (0 0.5rem 1rem rgba($-black, 0.15));
}

@mixin configure($black: null, $border-radius: null, $box-shadow: null) {
  @if $black {
    $-black: $black !global;
  }
  @if $border-radius {
    $-border-radius: $border-radius !global;
  }
  @if $box-shadow {
    $-box-shadow: $box-shadow !global;
  }
}

@mixin styles {
  code {
    border-radius: $-border-radius;
    box-shadow: -box-shadow();
  }
}
// style.scss
@use 'library';

@include library.configure(
  $black: #222,
  $border-radius: 0.1rem
);

@include library.styles;
Sass 语法// _library.sass
$-black: #000
$-border-radius: 0.25rem
$-box-shadow: null

/// If the user has configured `$-box-shadow`, returns their configured value.
/// Otherwise returns a value derived from `$-black`.
@function -box-shadow()
  @return $-box-shadow or (0 0.5rem 1rem rgba($-black, 0.15))


@mixin configure($black: null, $border-radius: null, $box-shadow: null)
  @if $black
    $-black: $black !global
  @if $border-radius
    $-border-radius: $border-radius !global
  @if $box-shadow
    $-box-shadow: $box-shadow !global


@mixin styles
  code
    border-radius: $-border-radius
    box-shadow: -box-shadow()





// style.sass
@use 'library'
@include library.configure($black: #222, $border-radius: 0.1rem)
@include library.styles





CSS 输出code {
  border-radius: 0.1rem;
  box-shadow: 0 0.5rem 1rem rgba(34, 34, 34, 0.15);
}

重新分配变量重新分配变量链接

加载模块后，您可以重新分配其变量。

  SCSS

  Sass
SCSS 语法// _library.scss
$color: red;
// _override.scss
@use 'library';
library.$color: blue;
// style.scss
@use 'library';
@use 'override';
@debug library.$color;  //=> blue
Sass 语法// _library.sass
$color: red
// _override.sass
@use 'library'
library.$color: blue
// style.sass
@use 'library'
@use 'override'
@debug library.$color  //=> blue

即使您使用 as * 导入没有命名空间的模块，这也适用。将值分配给在该模块中定义的变量名称将覆盖该模块中的其值。

⚠️ 注意！

内置模块变量（例如 math.$pi）不能重新分配。

查找模块查找模块链接

为每个加载的样式表都写出绝对 URL 不会很有趣，因此 Sass 的查找模块算法使其更轻松一些。首先，您不必明确写出要加载的文件的扩展名；@use "variables" 将自动加载 variables.scss、variables.sass 或 variables.css。

⚠️ 注意！

为了确保样式表在所有操作系统上都能正常工作，Sass 通过URL 加载文件，而不是通过文件路径。这意味着您需要使用正斜杠，而不是反斜杠，即使在 Windows 上也是如此。

这也意味着 URL 区分大小写，因此 Sass 会将 Styles.scss 和 styles.scss 视为不同的模块，即使您使用的是不区分大小写的文件系统。确保您的 URL 与磁盘上文件的实际大小写匹配，否则您的样式表可能会加载两次，并且肯定不会在其他操作系统上正常工作。

加载路径加载路径链接

所有 Sass 实现都允许用户提供加载路径：Sass 在查找模块时将查找的文件系统上的路径。例如，如果您传递 node_modules/susy/sass 作为加载路径，则可以使用 @use "susy" 来加载 node_modules/susy/sass/susy.scss（尽管 pkg: URL 是处理这种情况的更好方法）。

但是，模块始终会首先相对于当前文件加载。只有在不存在与模块 URL 匹配的相对文件时，才会使用加载路径。这确保了在添加新库时，您不会意外地弄乱相对导入。

💡 趣闻

与其他一些语言不同，Sass 不需要您对相对导入使用 ./。相对导入始终可用。

部分部分链接

按照惯例，仅用于作为模块加载而不能独立编译的 Sass 文件以 _ 开头（例如 _code.scss）。这些被称为部分，它们告诉 Sass 工具不要尝试独立编译这些文件。导入部分时，您可以省略 _。

索引文件索引文件链接

如果您在文件夹中编写了 _index.scss 或 _index.sass，则当您加载文件夹本身的 URL 时，索引文件将被自动加载。

  SCSS

  Sass

  CSS
SCSS 语法// foundation/_code.scss
code {
  padding: .25em;
  line-height: 0;
}
// foundation/_lists.scss
ul, ol {
  text-align: left;

  & & {
    padding: {
      bottom: 0;
      left: 0;
    }
  }
}
// foundation/_index.scss
@use 'code';
@use 'lists';
// style.scss
@use 'foundation';
Sass 语法// foundation/_code.sass
code
  padding: .25em
  line-height: 0

// foundation/_lists.sass
ul, ol
  text-align: left

  & &
    padding:
      bottom: 0
      left: 0



// foundation/_index.sass
@use 'code'
@use 'lists'
// style.sass
@use 'foundation'
CSS 输出code {
  padding: .25em;
  line-height: 0;
}

ul, ol {
  text-align: left;
}
ul ul, ol ol {
  padding-bottom: 0;
  padding-left: 0;
}

`pkg:` URLpkg: URL 链接

Sass 使用 pkg: URL 方案加载由各种包管理器分发的样式表。由于 Sass 在许多使用不同包管理约定的不同编程语言环境中使用，因此 pkg: URL 几乎没有固定的含义。相反，鼓励用户使用自定义导入程序（使用 JS API 或嵌入式 Sass 协议）来解析这些 URL，方法是使用本机包管理器的逻辑。

这使得 pkg: URL 和使用它们的样式表可以跨不同语言生态系统移植。无论您是通过 npm 安装 Sass 库（Sass 为其提供了内置的 pkg: 导入程序）还是通过最晦涩的包管理器，如果您编写 @use 'pkg:library'，它都会执行正确操作。

💡 趣闻

pkg: URL 不仅用于 @use。您可以在任何可以加载 Sass 文件的地方使用它们，包括 @forward、meta.load-css()，甚至旧的 @import 规则。

`pkg:` 导入器的规则`pkg:` 导入器的规则永久链接

Sass 期望所有 pkg: 导入器遵循一些常见的规则。这些规则有助于确保 pkg: URL 在所有包管理器中得到一致的处理，从而使样式表尽可能地可移植。

除了自定义导入器的标准规则外，pkg: 导入器必须仅处理非规范 URL，这些 URL

具有方案 pkg，并且
其路径以包名称开头，并且
可选地后跟路径，路径段用正斜杠分隔。

包名称可能包含正斜杠，具体取决于特定包管理器是否支持。例如，npm 允许诸如 @namespace/name 之类的包名称。请注意，包含非字母数字字符的包名称在不同的包管理器之间可能不太可移植。

pkg: 导入器必须拒绝以下模式

路径以 / 开头的 URL。
具有非空/空用户名、密码、主机、端口、查询或片段的 URL。

如果 pkg: 导入器遇到违反其自身包管理器约定但不违反上述规则的 URL，它应该只是拒绝加载该 URL，而不是抛出错误。这允许用户在必要时同时使用多个 pkg: 导入器。

Node.js 包导入器Node.js 包导入器永久链接

Dart Sass: 自 1.71.0 起
LibSass: ✗
Ruby Sass: ✗

由于 Sass 在 Node.js 生态系统中最广泛使用，因此它附带了一个 pkg: 导入器，该导入器使用与 Node.js 相同的算法来加载 Sass 样式表。这在默认情况下不可用，但很容易打开。

如果您使用的是 JavaScript API，只需将 new NodePackageImporter() 添加到 importers 选项中。
如果您使用的是 Dart API，请将 NodePackageImporter() 添加到 importers 选项中。
如果您使用的是命令行，请传递 --pkg-importer=node。

如果您加载 pkg: URL，Node.js pkg: 导入器将查看其 package.json 文件以确定要加载哪个 Sass 文件。它将按以下顺序检查

"exports" 字段，条件为 "sass"、"style" 和 "default"。这是包从现在开始公开 Sass 入口点的推荐方法。
"sass" 字段或 "style" 字段，它应该是 Sass 文件的路径。这仅在 pkg: URL 没有子路径时才有效——pkg:library 将加载 "sass" 字段中列出的文件，但 pkg:library/button 将加载包根目录下的 button.scss。
包根目录下的索引文件这也仅在 pkg: URL 没有子路径时才有效。

Node.js pkg: 导入器支持 "exports" 的全部功能，因此您还可以为不同的子路径指定不同的位置（请注意，键必须包含文件扩展名）

{
  "exports": {
    ".": {
      "sass": "styles/index.scss",
    },
    "./button.scss": {
      "sass": "styles/button.scss",
    },
    "./accordion.scss": {
      "sass": "styles/accordion.scss",
    }
  }
}

……甚至模式

{
  "exports": {
    ".": {
      "sass": "styles/index.scss",
    },
    "./*.scss": {
      "sass": "styles/*.scss",
    },
  }
}

加载 CSS加载 CSS 永久链接

除了加载 .sass 和 .scss 文件外，Sass 还可以加载普通的 .css 文件。

  SCSS

  Sass

  CSS
SCSS 语法// code.css
code {
  padding: .25em;
  line-height: 0;
}
// style.scss
@use 'code';
Sass 语法// code.css
code {
  padding: .25em;
  line-height: 0;
}
// style.sass
@use 'code'
CSS 输出code {
  padding: .25em;
  line-height: 0;
}

作为模块加载的 CSS 文件不允许任何特殊的 Sass 功能，因此无法公开任何 Sass 变量、函数或 mixin。为了确保作者不会意外地在他们的 CSS 中编写 Sass，所有非法的 CSS 的 Sass 功能都会产生错误。否则，CSS 将按原样呈现。它甚至可以扩展！

与 `@import` 的区别与 @import 的区别永久链接

@use 规则旨在替换旧的 @import 规则，但它被有意设计为以不同的方式工作。以下是两者之间的一些主要区别。

@use 仅在当前文件的范围内提供变量、函数和 mixin。它永远不会将它们添加到全局范围。这使得很容易确定 Sass 文件引用的每个名称的来源，并且意味着您可以使用更短的名称，而无需担心冲突。
@use 仅加载每个文件一次。这确保您不会意外地多次重复依赖项的 CSS。
@use 必须出现在文件的开头，并且不能嵌套在样式规则中。
每个 @use 规则只能有一个 URL。
@use 要求在它的 URL 周围使用引号，即使使用缩进语法也是如此。

@use

⚠️ 注意！

SCSS 语法

Sass 语法

CSS 输出

加载成员加载成员 链接

💡 趣闻

SCSS 语法

Sass 语法

CSS 输出

选择命名空间选择命名空间 链接

SCSS 语法

Sass 语法

CSS 输出

SCSS 语法

Sass 语法

CSS 输出

私有成员私有成员 链接

💡 趣闻

SCSS 语法

Sass 语法

配置配置 链接

SCSS 语法

Sass 语法

CSS 输出

使用 Mixin使用 Mixin 链接

SCSS 语法

Sass 语法

CSS 输出

重新分配变量重新分配变量 链接

SCSS 语法

Sass 语法

⚠️ 注意！

查找模块查找模块 链接

⚠️ 注意！

加载路径加载路径 链接

💡 趣闻

部分部分 链接

索引文件索引文件 链接

SCSS 语法

Sass 语法

CSS 输出

pkg: URLpkg: URL 链接

💡 趣闻

pkg: 导入器的规则pkg: 导入器的规则 永久链接

Node.js 包导入器Node.js 包导入器 永久链接

加载 CSS加载 CSS 永久链接

SCSS 语法

Sass 语法

CSS 输出

与 @import 的区别与 @import 的区别 永久链接

加载成员加载成员链接

选择命名空间选择命名空间链接

私有成员私有成员链接

配置配置链接

重新分配变量重新分配变量链接

查找模块查找模块链接

加载路径加载路径链接

部分部分链接

索引文件索引文件链接

`pkg:` URLpkg: URL 链接

`pkg:` 导入器的规则`pkg:` 导入器的规则永久链接

Node.js 包导入器Node.js 包导入器永久链接

与 `@import` 的区别与 @import 的区别永久链接