@use

Compatibility:

Dart Sass

since 1.23.0

LibSass

✗

Ruby Sass

✗

➤

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

// 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';

// 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'

code {
  padding: .25em;
  line-height: 0;
}

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

加载成员加载成员 permalink

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

使用 @use 加载的成员（变量、函数和 mixins）仅在加载它们的样式表中可见。其他样式表如果也想访问它们，需要编写自己的 @use 规则。 这有助于准确地找出每个成员的来源。如果你想一次性从多个文件加载成员，可以使用 @forward 规则将它们全部从一个共享文件转发。

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners";

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

// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

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

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

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

选择命名空间选择命名空间 permalink

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

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

// 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

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

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

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners" as *;

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

// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

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

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

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

私有成员私有成员 permalink

作为样式表作者，你可能不希望定义的所有成员都在样式表外部可用。Sass 通过以 - 或 _ 开头的名称轻松定义私有成员。 这些成员在定义它们的样式表中的工作方式与普通成员完全相同，但它们不是模块的公共 API 的一部分。这意味着加载你的模块的样式表看不到它们！

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

// 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

ConfigurationConfiguration permalink

A stylesheet can define variables with the !default flag to make them configurable. To load a module with configuration, write @use <url> with (<variable>: <value>, <variable>: <value>). The configured values will override the variables’ default values.

// _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
);

// _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)

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

A module will keep the same configuration (or lack of configuration) even if it’s loaded multiple times. Because of this, @use ... with can only be used once per module, the first time that module is loaded. This also makes it possible to use configuration to create "themes" that apply throughout a compilation:

// components/_button.scss
@use "../theme";

button {
  color: theme.$text-color;
  background-color: theme.$background-color;
}

// _theme.scss
$text-color: black !default;
$background-color: white !default;

// dark.scss
@use "theme" with (
  $text-color: white,
  $background-color: black,
);

@use "components/button";
// More components are usually imported here.

// components/_button.scss
@use "../theme"

button
  color: theme.$text-color
  background-color: theme.$background-color

// _theme.scss
$text-color: black !default
$background-color: white !default

// dark.scss
@use "theme" with (
  $text-color: white,
  $background-color: black,
)

@use "components/button"
// More components are usually imported here.

button {
  color: white;
  background-color: black;
}

With MixinsWith Mixins permalink

Configuring modules with @use ... with can be very handy, especially when using libraries that were originally written to work with the @import rule. But it’s not particularly flexible, and we don’t recommend it for more advanced use-cases. If you find yourself wanting to configure many variables at once, pass maps as configuration, or update the configuration after the module is loaded, consider writing a mixin to set your variables instead and another mixin to inject your styles.

// _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;

// _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

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

Reassigning VariablesReassigning Variables permalink

After loading a module, you can reassign its variables.

// _library.scss
$color: red;

// _override.scss
@use 'library';
library.$color: blue;

// style.scss
@use 'library';
@use 'override';
@debug library.$color;  //=> blue

// _library.sass
$color: red

// _override.sass
@use 'library'
library.$color: blue

// style.sass
@use 'library'
@use 'override'
@debug library.$color  //=> blue

This even works if you import a module without a namespace using as *. Assigning to a variable name defined in that module will overwrite its value in that module.

Finding the ModuleFinding the Module permalink

It wouldn’t be any fun to write out absolute URLs for every stylesheet you load, so Sass’s algorithm for finding a module makes it a little easier. For starters, you don’t have to explicitly write out the extension of the file you want to load; @use "variables" will automatically load variables.scss, variables.sass, or variables.css.

Load PathsLoad Paths permalink

All Sass implementations allow users to provide load paths: paths on the filesystem that Sass will look in when locating modules. For example, if you pass node_modules/susy/sass as a load path, you can use @use "susy" to load node_modules/susy/sass/susy.scss (although pkg: URLs are a better way to handle that).

Modules will always be loaded relative to the current file first, though. Load paths will only be used if no relative file exists that matches the module’s URL. This ensures that you can’t accidentally mess up your relative imports when you add a new library.

PartialsPartials permalink

As a convention, Sass files that are only meant to be loaded as modules, not compiled on their own, begin with _ (as in _code.scss). These are called partials, and they tell Sass tools not to try to compile those files on their own. You can leave off the _ when importing a partial.

Index FilesIndex Files permalink

If you write an _index.scss or _index.sass in a folder, the index file will be loaded automatically when you load the URL for the folder itself.

// 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';

// 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'

code {
  padding: .25em;
  line-height: 0;
}

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

pkg: URLspkg: URLs permalink

Sass uses the pkg: URL scheme to load stylesheets distributed by various package managers. Since Sass is used in the context of many different programming languages with different package management conventions, pkg: URLs have almost no set meaning. Instead, users are encouraged to implement custom importers (using the JS API or the Embedded Sass protocol) that resolve these URLs using the native package manager’s logic.

This allows pkg: URLs and the stylesheets that use them to be portable across different language ecosystems. Whether you’re installing a Sass library via npm (for which Sass provides a built-in pkg: importer) or the most obscure package manager you can find, if you write @use 'pkg:library' it’ll do the right thing.

Rules for a pkg: ImporterRules for a pkg: Importer permalink

There are a few common rules that Sass expects all pkg: importers to follow. These rules help ensure that pkg: URLs are handled consistently across all package managers, so that stylesheets are as portable as possible.

In addition to the standard rules for custom importers, a pkg: importer must only handle non-canonical URLs that:

• have the scheme pkg, and
• whose path begins with a package name, and
• are optionally followed by a path, with path segments separated with a forward slash.

The package name may contain forward slashes, depending on whether the particular package manager supports that. For example, npm allows package names like @namespace/name. Note that package names that contain non-alphanumeric characters may be less portable across different package managers.

pkg: importers must reject the following patterns:

• A URL whose path begins with /.
• A URL with non-empty/null username, password, host, port, query, or fragment.

If pkg: importer encounters a URL that violates its own package manager’s conventions but not the above rules, it should just decline to load that URL rather than throwing an error. This allows users to use multiple pkg: importers at once if necessary.

Node.js Package ImporterNode.js Package Importer permalink

Compatibility:

Dart Sass

since 1.71.0

LibSass

✗

Ruby Sass

✗

Because Sass is most widely-used alongside the Node.js ecosystem, it comes with a pkg: importer that uses the same algorithm as Node.js to load Sass stylesheets. This isn’t available by default, but it’s easy to turn on:

• If you’re using the JavaScript API, just add new NodePackageImporter() to the importers option.

• If you’re using the Dart API, add NodePackageImporter() to the importers option.

• If you’re using the command line, pass --pkg-importer=node.

If you load a pkg: URL, the Node.js pkg: importer will look at its package.json file to determine which Sass file to load. It will check in order:

• The "exports" field, with the conditions "sass", "style", and "default". This is the recommended way for packages to expose Sass entrypoints going forward.

• The "sass" field or the "style" field, which should be a path to a Sass file. This only works if the pkg: URL doesn’t have a subpath—pkg:library will load the file listed in the "sass" field, but pkg:library/button will load button.scss from the root of the package.

• The index file at the root of the package This also only works if the pkg: URL doesn’t have a subpath.

The Node.js pkg: importer supports the full range of "exports" features, so you can also specify different locations for different subpaths (note that the key must include the file extension):

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

…or even patterns:

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

Loading CSSLoading CSS permalink

In addition to loading .sass and .scss files, Sass can load plain old .css files.

// code.css
code {
  padding: .25em;
  line-height: 0;
}

// style.scss
@use 'code';

// code.css
code {
  padding: .25em;
  line-height: 0;
}

// style.sass
@use 'code'

code {
  padding: .25em;
  line-height: 0;
}

CSS files loaded as modules don’t allow any special Sass features and so can’t expose any Sass variables, functions, or mixins. In order to make sure authors don’t accidentally write Sass in their CSS, all Sass features that aren’t also valid CSS will produce errors. Otherwise, the CSS will be rendered as-is. It can even be extended!

Differences From @importDifferences From @import permalink

The @use rule is intended to replace the old @import rule, but it’s intentionally designed to work differently. Here are some major differences between the two:

• @use only makes variables, functions, and mixins available within the scope of the current file. It never adds them to the global scope. This makes it easy to figure out where each name your Sass file references comes from, and means you can use shorter names without any risk of collision.

• @use only ever loads each file once. This ensures you don’t end up accidentally duplicating your dependencies’ CSS many times over.

• @use must appear at the beginning your file, and cannot be nested in style rules. Nested imports can be migrated to mixin calls or meta.load-css().

• Each @use rule can only have one URL.

• @use requires quotes around its URL, even when using the indented syntax.