@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 можно использовать для каждого модуля только один раз — при первой его загрузке. Это также позволяет с помощью конфигурации создавать «темы», применяемые ко всей компиляции:

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

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

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

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

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

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

/* CSS */
button {
  color: white;
  background-color: black;
}

С помощью миксинов

Настройка модулей с помощью @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 для поиска модулей упрощает эту задачу. Прежде всего, вам не нужно явно указывать расширение файла, который вы хотите загрузить: @use "variables" автоматически загрузит variables.scss, variables.sass или variables.css.

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

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

Однако модули всегда сначала загружаются относительно текущего файла. Пути загрузки используются только в том случае, если не найден соответствующий 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 используется в контексте множества языков программирования с разными соглашениями по управлению пакетами, URL pkg: практически не имеют единого значения. Вместо этого пользователям рекомендуется реализовывать собственные импортеры (с помощью API JS или протокола Embedded Sass), которые разрешают такие URL, используя логику соответствующего менеджера пакетов.

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

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

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

Помимо стандартных правил для пользовательских импортеров, импортер 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.

Если вы загружаете URL pkg:, импортер Node.js pkg: проверит файл package.json, чтобы определить, какой файл Sass загрузить. Он выполнит проверки в следующем порядке:

• Поле "exports" с условиями "sass", "style" и "default". В дальнейшем это рекомендуемый способ предоставления точек входа Sass для пакетов.

• Поле "sass" или "style", в котором должен быть указан путь к файлу Sass. Это работает, только если в URL pkg: нет подпути: pkg:library загрузит файл, указанный в поле "sass", а pkg:library/button загрузит button.scss из корневой папки пакета.

• Индексный файл в корневой папке пакета. Это также работает, только если в URL pkg: нет подпути.

Импортер 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 должно находиться в начале файла и не может быть вложено в правила стилей. Вложенные импорты можно заменить на вызовы миксинов или meta.load-css().

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

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