@use

Совместимость:

Dart Sass

с версии 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';

// SASS
// foundation/_code.sass
code
  padding: .25em
  line-height: 0

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

  & &
    padding:
      bottom: 0
      left: 0

// SASS
// 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>(). По умолчанию пространство имён — это просто последняя часть URL модуля.

Члены (переменные, функции и миксы), загруженные с помощью @use, видны только в файле стилей, который их загружает. Другим файлам стилей придётся писать свои правила @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;
}

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

@mixin rounded
  border-radius: $radius

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

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

// SASS
// 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 *. Однако мы рекомендуем делать это только для файлов стилей, созданных вами, иначе они могут добавить новые члены, вызывающие конфликты имён!

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

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

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

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

Закрытые члены

Как автору файла стилей, возможно, не все определённые вами члены должны быть доступны за пределами файла стилей. 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;
}

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

@mixin rounded
  border-radius: $-radius

// SASS
// 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>). Настроенные значения переопределят значения по умолчанию переменных.

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

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

С миксами

Настройка модулей с @use ... with может быть очень удобной, особенно при работе с библиотеками, которые изначально были написаны для работы с правилом @import. Но она не очень гибкая, и мы не рекомендуем её для более сложных случаев. Если вы хотите настроить сразу много переменных, передать массивы в качестве настроек или обновить настройки после загрузки модуля, подумайте о написании микса для настройки переменных и другого микса для вставки стилей.

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

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

Переназначение переменных

После загрузки модуля вы можете переназначить его переменные.

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

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

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

Это работает даже если вы импортируете модуль без имени пространства с помощью as *. Присвоение переменной имени, определённому в этом модуле, переопределит его значение в этом модуле.

Поиск модуля

Не хотелось бы каждый раз писать абсолютные URL для каждого загружаемого файла стилей, поэтому алгоритм Sass для поиска модулей несколько упрощает задачу. Вначале вам не нужно явно указывать расширение файла, который вы хотите загрузить; Sass автоматически загрузит variables.scss, variables.sass или variables.css.

Пути загрузки

Все реализации Sass позволяют пользователям указывать пути загрузки: пути на файловой системе, в которых Sass будет искать модули. Например, если вы передадите node_modules/susy/sass в качестве пути загрузки, вы можете использовать @use "susy" для загрузки node_modules/susy/sass/susy.scss (хотя pkg: URL являются лучшим способом обработки этого).

Модули всегда будут загружаться относительно текущего файла в первую очередь. Пути загрузки будут использоваться только в том случае, если не существует соответствующего файла относительно текущего, который соответствует URL модуля. Это гарантирует, что вы случайно не испортите свои относительные импорты при добавлении новой библиотеки.

Частичные файлы

В соответствии с соглашениями, файлы Sass, предназначенные только для загрузки в качестве модулей, а не для самостоятельной компиляции, начинаются с _ (как в _code.scss). Их называют частичными файлами, и они сообщают инструментам Sass не пытаться компилировать эти файлы самостоятельно. При импорте частичного файла вы можете опустить _.

Файлы-индексы

Если вы создадите файл _index.scss или _index.sass в папке, файл-индекс будет загружаться автоматически при загрузке URL самой папки.

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

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

  & &
    padding:
      bottom: 0
      left: 0

// SASS
// foundation/_index.sass
@use 'code'
@use 'lists'

// SASS
// 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: URL

Sass использует схему URL pkg: для загрузки стилей, распределяемых различными менеджерами пакетов. Поскольку Sass используется в контексте многих разных языков программирования с различными соглашениями по управлению пакетами, pkg: URL практически не имеют установленного смысла. Вместо этого пользователям рекомендуется реализовывать пользовательские импортеры (используя JS API или протокол встроенного Sass), которые разрешают эти URL с помощью логики родного менеджера пакетов.

Это позволяет pkg: URL и используемым с ними стилям быть портативными в различных экосистемах языков программирования. Будь вы устанавливаете библиотеку Sass через npm (для чего Sass предоставляет встроенный pkg: импортер) или самый необычный менеджер пакетов, который вы найдете, если вы напишете @use 'pkg:library', он сделает все правильно.

Правила для импортера pkg:

Существует несколько общих правил, которые Sass ожидает от всех импортеров pkg:. Эти правила помогают обеспечить согласованное обращение с pkg: URL во всех менеджерах пакетов, чтобы стили были максимально портативными.

В дополнение к стандартным правилам для пользовательских импортеров, импортер pkg: должен обрабатывать только неканонические URL, которые:

• имеют схему pkg, и
• путь которого начинается с имени пакета, и
• факультативно сопровождается путем, с сегментами пути, разделенными слешем.

Имя пакета может содержать слеши, в зависимости от того, поддерживает ли конкретный менеджер пакетов это. Например, npm допускает имена пакетов, такие как @namespace/name. Обратите внимание, что имена пакетов, содержащие не буквенно-цифровые символы, могут быть менее портативными в разных менеджерах пакетов.

Импортеры pkg: должны отклонять следующие шаблоны:

• URL, путь которого начинается с /.
• URL с непустым/нулевым именем пользователя, паролем, хостом, портом, запросом или фрагментом.

Если импортер pkg: встречает URL, который нарушает соглашения собственного менеджера пакетов, но не вышеуказанные правила, он должен просто отказаться загружать этот URL вместо выдачи ошибки. Это позволяет пользователям использовать несколько импортеров pkg: одновременно, если это необходимо.

Импортер пакетов 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 из корня пакета.

• Файл-индекс index file в корне пакета. Это также работает только если 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

В дополнение к загрузке файлов .sass и .scss, Sass может загружать обычные файлы .css.

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

// style.scss
@use 'code';

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

// SASS
// style.sass
@use 'code'

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

Файлы CSS, загруженные в качестве модулей, не допускают никаких специальных функций Sass и не могут экспонировать переменные, функции или миксины Sass. Чтобы убедиться, что авторы не случайно пишут Sass в своём CSS, все функции Sass, которые не являются также допустимыми для CSS, будут вызывать ошибки. В противном случае CSS будет отображаться как есть. Его даже можно расширить!

Отличия от @import

Правило @use предназначено для замены старого правила @import, но оно намеренно разработано по-другому. Вот некоторые основные различия между ними:

• @use делает переменные, функции и миксины доступными только в рамках текущего файла. Оно никогда не добавляет их в глобальную область видимости. Это облегчает определение источника каждой ссылки на имя в вашем файле Sass и позволяет использовать более короткие имена без риска конфликтов.

• @use загружает каждый файл только один раз. Это гарантирует, что вы случайно не дублируете зависимости CSS много раз.

• @use должно появляться в начале файла и не может быть вложенным в правила стилей.

• Каждое правило @use может иметь только один URL.

• @use требует кавычек вокруг URL, даже при использовании вложенного синтаксиса.