Мигратор

Применение permalinkПрименение

Чтобы использовать Sass migrator, сообщите ему какую миграцию вы хотите запустить и какие файлы Sass вы хотите перенести:

sass-migrator <migration> <entrypoint.scss...>

По умолчанию мигратор изменяет только файлы, которые вы явно передаете в командной строке. Передача параметра --migrate-deps указывает мигратору также изменить все таблицы стилей, которые загружаются с использованием правила @use, правила @forward или правила @import. А если вы хотите выполнить тестовый запуск, чтобы увидеть, какие изменения будут внесены без их фактического сохранения, вы можете передать --dry-run --verbose (или -nv для краткости).

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

Установка permalinkУстановка

Вы можете установить Sass migrator почти из тех же мест, где вы можете установить Dart Sass:

Автономный permalinkАвтономный

Вы можете установить Sass migrator в Windows, Mac или Linux, загрузив пакет для своей операционной системы [из GitHub][] и добавив его в свой PATH.

npm permalinknpm

Если вы используете Node.js, вы также можете установить Sass мигратор с помощью npm, запустив

npm install -g sass-migrator

Chocolatey permalinkChocolatey

Если вы используете диспетчер пакетов Chocolatey для Windows, вы можете установить Sass migrator, запустив

choco install sass-migrator

Homebrew permalinkHomebrew

Если вы используете менеджер пакетов Homebrew для Mac OS X, вы можете установить Dart Sass, запустив

brew install sass/sass/migrator

Глобальные опции permalinkГлобальные опции

Эти параметры доступны для всех мигрантов.

–migrate-deps permalink--migrate-deps

Эта опция (сокращенно -d) указывает мигратору изменять не только таблицы стилей, которые явно передаются в командной строке, но также любые таблицы стилей, от которых они зависят, используя правило @use, правило @forward или правило @import.

$ sass-migrator module --verbose style.scss
Migrating style.scss
$ sass-migrator module --verbose --migrate-deps style.scss
Migrating style.scss
Migrating _theme.scss
Migrating _fonts.scss
Migrating _grid.scss

–load-path permalink--load-path

Эта опция (сокращенно -I) сообщает мигратору путь загрузки, где он должен искать таблицы стилей. Его можно передавать несколько раз, чтобы обеспечить несколько путей загрузки. Более ранние пути загрузки имеют приоритет над более поздними.

Предполагается, что зависимости, загруженные из путей загрузки, являются сторонними библиотеками, поэтому мигратор не будет их переносить, даже если передан параметр --migrate-deps.

–dry-run permalink--dry-run

Этот флаг (сокращенно -n) говорит мигратору не сохранять никаких изменений на диск. Вместо этого он печатает список файлов, которые он мог бы изменить. Обычно это используется вместе с параметром --verbose для вывода содержимого изменений, которые также были бы внесены.

$ sass-migrator module --dry-run --migrate-deps style.scss
Dry run. Logging migrated files instead of overwriting...

style.scss
_theme.scss
_fonts.scss
_grid.scss

–no-unicode permalink--no-unicode

Этот флаг указывает программе миграции Sass только передавать на терминал символы ASCII как часть сообщений об ошибках. По умолчанию или если передан --unicode, средство миграции будет выдавать для этих сообщений символы, отличные от ASCII. Этот флаг не влияет на вывод CSS.

$ sass-migrator --no-unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ,
1 | @import "typography";
  |         ^^^^^^^^^^^^
  '
Migration failed!
$ sass-migrator --unicode module style.scss
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'.
  ╷
1 │ @import "typography";
  │         ^^^^^^^^^^^^
  ╵
Migration failed!

–verbose permalink--verbose

Этот флаг (сокращенно -v) указывает мигратору вывести дополнительную информацию на консоль. По умолчанию он просто печатает имена файлов, которые были изменены, но в сочетании с параметром --dry-run он также печатает новое содержимое этих файлов.

$ sass-migrator module --verbose --dry-run style.scss
Dry run. Logging migrated files instead of overwriting...
<==> style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator module --verbose style.scss
Migrating style.scss

Миграции permalinkМиграции

Разделение permalinkРазделение

Эта миграция преобразует таблицы стилей, которые используют / как разделение, чтобы использовать вместо этого встроенная функция math.div.

–pessimistic permalink--pessimistic

По умолчанию, средство миграции преобразует операции / в math.div, даже если он не уверен, что это будет деление при оценке. Он оставляет их как есть только тогда, когда он может статически определить, что они делают что-то еще (например, когда не задействован SassScript или когда один из операндов является строкой). Функция math.div в настоящее время функционирует идентично оператору /, поэтому это безопасно, но может привести к новым предупреждениям, если один из аргументов math.div во время выполнения не является числом.

Если вы хотите избежать такого поведения, вы можете передать флаг --pessimistic. С этим флагом мигратор будет преобразовывать только операции /, которые, как он точно знает, выполняют деление. Это предотвратит любые ненужные преобразования math.div, но, вероятно, оставит какое-то деление не мигрированным, если его нельзя определить статически.

Модуль permalinkМодуль

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

• Добавление пространств имен для использования участников (переменных, миксинов и функций) из других модулей.

• Добавление новых правил @use в таблицы стилей, которые использовали элементы, без их импорта.

• Преобразование переопределенных переменных по умолчанию в предложения with.

• Автоматическое удаление префиксов - и _ из участников, которые используются из других файлов (потому что в противном случае они будут считаться частными и могут использоваться только в том модуле, который они объявлены).

• Преобразование вложенного импорта для использования вместо него миксины meta.load-css().

$ cat style.scss
$body-bg: #000;
$body-color: #111;

@import "bootstrap";

@include media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
  $body-bg: #000,
  $body-color: #111
);

@include bootstrap.media-breakpoint-up(sm) {
  .navbar {
    display: block;
  }
}

Загрузка зависимостей permalinkЗагрузка зависимостей

Мигратор модуля должен иметь возможность читать все таблицы стилей, зависящие от тех, которые он мигрирует, даже если параметр --migrate-deps не передан. Если мигратору не удается найти зависимость, вы получите сообщение об ошибке.

$ ls .
style.scss  node_modules
$ sass-migrator module style.scss
Error: Could not find Sass file at 'dependency'.
  ,
1 | @import "dependency";
  |         ^^^^^^^^^^^^
  '
  style.scss 1:9  root stylesheet
Migration failed!
$ sass-migrator --load-path node_modules module style.scss

Если вы используете путь загрузки при компиляции таблиц стилей, не забудьте передать его в программу миграции с помощью параметра --load-path.

К сожалению, переносчик не поддерживает настраиваемые импортеры, но он имеет встроенную поддержку для разрешения URL-адресов, начинающихся с ~, путем поиска в node_modules, аналогично что поддерживает Webpack.

–remove-prefix permalink--remove-prefix

Эта опция (сокращенно -p) принимает префикс идентификатора, который удаляется из начала всех имен переменных, миксинов и функций при их переносе. Участники, которые не начинаются с этого префикса, останутся без изменений.

Правило @import помещает все элементы верхнего уровня в одну глобальную область видимости, поэтому, когда это был стандартный способ загрузки таблиц стилей, каждый был мотивирован добавлять префиксы ко всем именам своих участников, чтобы избежать случайного переопределения некоторых других таблиц стилей. Модульная система решает эту проблему, поэтому теперь полезно автоматически удалять старые префиксы, когда они не нужны.

$ cat style.scss
@import "theme";

@mixin app-inverted {
  color: $app-bg-color;
  background-color: $app-color;
}
$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss
$ cat style.scss
@import "theme";

@mixin inverted {
  color: theme.$bg-color;
  background-color: theme.$color;
}

Когда вы передаете эту опцию, мигратор также сгенерирует таблицу стилей только для импорта, которая пересылает всех участников с добавленным префиксом обратно, чтобы сохранить обратную совместимость для пользователей, которые импортировали библиотеку.

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

–forward permalink--forward

Эта опция сообщает мигратору, какие элементы перенаправлять с помощью правила @forward. Он поддерживает следующие настройки:

• none (по умолчанию) не пересылает участников.

• all перенаправляет все элементы, кроме тех, которые начинались с - или _ в исходной таблице стилей, поскольку это обычно использовалось для обозначения закрытого члена пакета до того, как была введена модульная система.

• prefixed пересылает только те элементы, которые начинаются с префикса, переданного в параметр --remove-prefix. Этот параметр можно использовать только вместе с параметром --remove-prefix.

Все файлы, которые явно передаются в командной строке, будут перенаправлять элементы, которые транзитивно загружаются этими файлами с использованием правила @import. Файлы, загруженные с использованием параметра --migrate-deps, не будут пересылать новых участников. Этот параметр особенно полезен при миграции библиотеки Sass, поскольку он гарантирует, что пользователи этой библиотеки по-прежнему будут иметь доступ ко всем членам, которые она определяет.

$ cat _index.scss
@import "theme";
@import "typography";
@import "components";
$ sass-migrator --migrate-deps module --forward=all style.scss
$ cat _index.scss
@forward "theme";
@forward "typography";
@forward "components";

Пространство имен permalinkПространство имен

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

–rename permalink--rename

Вы можете указать мигратору, какие пространства имен вы хотите изменить, передав выражения в параметр --rename.

Эти выражения имеют форму от <old-namespace> до <new-namespace> или url <rule-url> до <new-namespace>. В этих выражениях, <old-namespace> и <rule-url> являются регулярными выражениями, которые совпадают со всем существующим пространством имен или URL-адресом правила @use, соответственно.

Для простых случаев использования это выглядит как --rename 'old to new', которое переименовало бы правило @use с пространством имен old в new.

Однако вы также можете сделать это для выполнения более сложных переименований. Например, предположим, что ранее у вас была таблица стилей, которая выглядела так:

@import "components/button/lib/mixins";
@import "components/input/lib/mixins";
@import "components/table/lib/mixins";
// ...

Поскольку все эти URL-адреса будут иметь пространство имен по умолчанию mixins при миграции на правила @use, модуль миграции модуля может в конечном итоге сгенерировать что-то вроде этого:

@use "components/button/lib/mixins" as button-lib-mixins;
@use "components/input/lib/mixins" as input-lib-mixins;
@use "components/table/lib/mixins" as table-lib-mixins;
// ...

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

Если мы запустим средство переноса пространства имен с помощью --rename 'url components/(\w+)/lib/mixins to \1', мы получим:

@use "components/button/lib/mixins" as button;
@use "components/input/lib/mixins" as input;
@use "components/table/lib/mixins" as table;
// ...

Сценарий переименования здесь говорит, что нужно найти все правила @use URL-адреса которых выглядят как components/(\w+)/lib/mixins (\w+ в регулярном выражении означает соответствие любому слову из одного или нескольких символов). \1 в предложении вывода означает замену содержимого первого набора круглых скобок в регулярном выражении (вызываемом группа).

Если вы хотите применить несколько переименований, вы можете передать параметр --rename несколько раз или разделить их точкой с запятой или разрывом строки. Будет использовано только первое переименование, применимое к данному правилу, поэтому вы можете передать что-то вроде --rename 'a to b; b to a', чтобы поменять местами пространства имён a и b.

–force permalink--force

По умолчанию, если два или более правил @use имеют одно и то же пространство имен после миграции, мигратор завершится ошибкой и никакие изменения не будут внесены.

В этом случае вы обычно хотите изменить свой сценарий --rename, чтобы избежать конфликтов, но если вы предпочитаете принудительную миграцию, вы можете вместо этого передать --force.

С помощью --force, если возникают какие-либо конфликты, первое правило @use получит свое предпочтительное пространство имен, тогда как последующие правила @use с тем же предпочтительным пространством имен вместо этого будут иметь добавленный числовой суффикс.