Migrator

VerwendungPermalien für Verwendung

Um den Sass-Migrator zu verwenden, teilen Sie ihm mit, welche Migration Sie ausführen möchten und welche Sass-Dateien Sie migrieren möchten.

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

Standardmäßig ändert der Migrator nur Dateien, die Sie explizit in der Befehlszeile angeben. Die Option --migrate-deps weist den Migrator an, auch alle Stylesheets zu ändern, die über die Regeln @use, @forward oder @import geladen werden. Und wenn Sie einen Testlauf durchführen möchten, um zu sehen, welche Änderungen vorgenommen werden, ohne sie tatsächlich zu speichern, können Sie --dry-run --verbose (oder kurz -nv) angeben.

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

InstallationInstallations-Permalink

Sie können den Sass-Migrator von den meisten Orten installieren, von denen aus Sie Dart Sass installieren können.

StandaloneStandalone-Permalink

Sie können den Sass-Migrator unter Windows, Mac oder Linux installieren, indem Sie das Paket für Ihr Betriebssystem von GitHub herunterladen und zu Ihrem PATH hinzufügen.

npmnpm-Permalink

Wenn Sie Node.js verwenden, können Sie den Sass-Migrator auch über npm installieren, indem Sie

npm install -g sass-migrator

ChocolateyChocolatey-Permalink

Wenn Sie den Chocolatey-Paketmanager für Windows verwenden, können Sie den Sass-Migrator durch Ausführung installieren

choco install sass-migrator

HomebrewHomebrew-Permalink

Wenn Sie den Homebrew-Paketmanager für Mac OS X verwenden, können Sie Dart Sass durch Ausführung installieren

brew install sass/sass/migrator

Globale OptionenGlobale Optionen-Permalink

Diese Optionen sind für alle Migratoren verfügbar.

--migrate-deps–migrate-deps-Permalink

Diese Option (abgekürzt -d) weist den Migrator an, nicht nur die explizit in der Befehlszeile angegebenen Stylesheets zu ändern, sondern auch alle Stylesheets, von denen sie über die Regeln @use, @forward oder @import abhängen.

$ 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-pathPermalien für –load-path

Diese Option (abgekürzt -I) teilt dem Migrator einen Load Path mit, nach dem er nach Stylesheets suchen soll. Sie kann mehrmals übergeben werden, um mehrere Load Paths anzugeben. Frühere Load Paths haben Vorrang vor späteren.

Von Load Paths geladene Abhängigkeiten werden als Drittanbieterbibliotheken betrachtet. Daher wird der Migrator diese nicht migrieren, auch wenn die Option --migrate-deps übergeben wird.

--dry-run–dry-run-Permalink

Dieses Flag (abgekürzt -n) weist den Migrator an, keine Änderungen auf der Festplatte zu speichern. Stattdessen gibt er eine Liste der Dateien aus, die er geändert hätte. Dies wird häufig mit der Option --verbose kombiniert, um auch den Inhalt der Änderungen auszugeben, die vorgenommen worden wären.

$ 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–no-unicode-Permalink

Dieses Flag weist den Sass-Migrator an, im Terminal nur ASCII-Zeichen als Teil von Fehlermeldungen auszugeben. Standardmäßig oder wenn --unicode übergeben wird, gibt der Migrator Nicht-ASCII-Zeichen für diese Meldungen aus. Dieses Flag hat keinen Einfluss auf die CSS-Ausgabe.

$ 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–verbose-Permalink

Dieses Flag (abgekürzt -v) weist den Migrator an, zusätzliche Informationen auf der Konsole auszugeben. Standardmäßig gibt er nur den Namen der geänderten Dateien aus, aber in Kombination mit der Option --dry-run gibt er auch den neuen Inhalt dieser Dateien aus.

$ 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

MigrationsMigrations-Permalink

FarbeFarbe-Permalink

Diese Migration konvertiert ältere Farbfunktionen in die neuen, farbraumkompatiblen Funktionen.

DivisionDivision-Permalink

Diese Migration konvertiert Stylesheets, die / als Division verwenden, so dass stattdessen die eingebaute Funktion math.div verwendet wird.

--pessimistic–pessimistic-Permalink

Standardmäßig konvertiert der Migrator /-Operationen in math.div, auch wenn er sich nicht sicher ist, ob es sich um eine Division handelt, wenn sie ausgewertet wird. Er belässt sie nur dann unverändert, wenn er statisch bestimmen kann, dass sie etwas anderes tun (z. B. wenn keine SassScript beteiligt ist oder eines der Operanden eine Zeichenkette ist). Die Funktion math.div funktioniert derzeit identisch zum Operator /, daher ist dies sicher, kann aber zu neuen Warnungen führen, wenn eines der Argumente für math.div zur Laufzeit keine Zahl ist.

Wenn Sie dieses Verhalten vermeiden möchten, können Sie das Flag --pessimistic übergeben. Mit diesem Flag konvertiert der Migrator nur /-Operationen, von denen er sicher weiß, dass sie Divisionen sind. Dies verhindert unnötige math.div-Konvertierungen, lässt aber wahrscheinlich einige Divisionen unmigriert, wenn sie nicht statisch bestimmt werden können.

ModuleModule-Permalink

Diese Migration konvertiert Stylesheets, die die alte Regel @import zum Laden von Abhängigkeiten verwenden, so dass sie stattdessen das Sass-Modulsystem über die Regel @use nutzen. Sie ändert nicht nur naiv @imports in @uses – sie aktualisiert Stylesheets intelligent, damit sie weiterhin wie zuvor funktionieren, einschließlich

• Hinzufügen von Namespaces zu Verwendungen von Mitgliedern (Variablen, Mixins und Funktionen) aus anderen Modulen.

• Hinzufügen neuer @use-Regeln zu Stylesheets, die Mitglieder ohne deren Import verwendet haben.

• Konvertieren überschriebener Standardvariablen in with-Klauseln.

• Automatisches Entfernen von - und _ Präfixen von Mitgliedern, die aus anderen Dateien verwendet werden (da sie sonst als privat gelten und nur im Modul verwendet werden könnten, in dem sie deklariert sind).

• Konvertieren von verschachtelten Imports zur Verwendung des meta.load-css() Mixins.

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

Laden von AbhängigkeitenLaden von Abhängigkeiten-Permalink

Der Modul-Migrator muss in der Lage sein, alle Stylesheets zu lesen, von denen die migrierten abhängen, auch wenn die Option --migrate-deps nicht übergeben wird. Wenn der Migrator eine Abhängigkeit nicht finden kann, erhalten Sie eine Fehlermeldung.

$ 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

Wenn Sie beim Kompilieren Ihrer Stylesheets einen Load Path verwenden, stellen Sie sicher, dass Sie diesen mit der Option --load-path an den Migrator übergeben.

Leider unterstützt der Migrator keine benutzerdefinierten Importer, aber er hat eine eingebaute Unterstützung für die Auflösung von URLs, die mit ~ beginnen, indem er in node_modules sucht, ähnlich wie was Webpack unterstützt.

--remove-prefix–remove-prefix-Permalink

Diese Option (abgekürzt -p) nimmt ein Bezeichnerpräfix entgegen, das vom Anfang aller Variablen-, Mixin- und Funktionsnamen entfernt wird, wenn sie migriert werden. Mitglieder, die nicht mit diesem Präfix beginnen, bleiben unverändert.

Die Regel @import legte alle Top-Level-Mitglieder in einem globalen Geltungsbereich ab, sodass jeder, als dies die Standardmethode zum Laden von Stylesheets war, Anreize hatte, Präfixe zu all seinen Mitgliedsnamen hinzuzufügen, um versehentliche Neudefinitionen anderer Stylesheets zu vermeiden. Das Modulsystem löst dieses Problem, daher ist es nützlich, diese alten Präfixe automatisch zu entfernen, da sie nun unnötig sind.

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

Wenn Sie diese Option übergeben, generiert der Migrator auch ein nur-Import-Stylesheet, das alle Mitglieder mit dem Präfix wieder hinzugefügt weiterleitet, um die Abwärtskompatibilität für Benutzer zu gewährleisten, die die Bibliothek importierten.

Diese Option kann mehrmals oder mit mehreren durch Kommas getrennten Werten übergeben werden. Jedes Präfix wird von allen Mitgliedern entfernt, die es haben. Wenn ein Mitglied mit mehreren Präfixen übereinstimmt, wird das am längsten passende Präfix entfernt.

--forward–forward-Permalink

Diese Option teilt dem Migrator mit, welche Mitglieder über die Regel @forward weitergeleitet werden sollen. Sie unterstützt die folgenden Einstellungen:

• none (Standard) leitet keine Mitglieder weiter.

• all leitet alle Mitglieder weiter, außer denen, die mit - oder _ begannen, da dies vor der Einführung des Modulsystems häufig verwendet wurde, um ein paketinternes Mitglied zu kennzeichnen.

• prefixed leitet nur Mitglieder weiter, die mit dem an die Option --remove-prefix übergebenen Präfix beginnen. Diese Option kann nur in Verbindung mit der Option --remove-prefix verwendet werden.

Alle Dateien, die explizit in der Befehlszeile übergeben werden, leiten Mitglieder weiter, die transitiv von diesen Dateien über die Regel @import geladen werden. Dateien, die mit der Option --migrate-deps geladen werden, leiten keine neuen Mitglieder weiter. Diese Option ist besonders nützlich bei der Migration einer Sass-Bibliothek, da sie sicherstellt, dass Benutzer dieser Bibliothek weiterhin auf alle Mitglieder zugreifen können, die sie definiert.

$ 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";

NamespaceNamespace-Permalink

Diese Migration ermöglicht es Ihnen, die Namespaces der @use-Regeln in einem Stylesheet einfach zu ändern. Dies ist nützlich, wenn die vom Modul-Migrator zur Auflösung von Konflikten generierten Namespaces nicht ideal sind, oder wenn Sie den Standard-Namespace, den Sass basierend auf der Regel-URL bestimmt, nicht verwenden möchten.

--rename–rename-Permalink

Sie können dem Migrator mitteilen, welche Namespaces er ändern soll, indem Sie Ausdrücke an die Option --rename übergeben.

Diese Ausdrücke haben das Format <alter-namespace> to <neuer-namespace> oder url <regel-url> to <neuer-namespace>. In diesen Ausdrücken sind <alter-namespace> und <regel-url> reguläre Ausdrücke, die gegen den gesamten bestehenden Namespace oder die @use-Regel-URL abgeglichen werden.

Für einfache Anwendungsfälle sieht dies einfach so aus: --rename 'alt to neu', was eine @use-Regel mit dem Namespace alt in neu umbenennen würde.

Sie können dies jedoch auch tun, um kompliziertere Umbenennungen durchzuführen. Nehmen wir zum Beispiel an, Sie hatten zuvor ein Stylesheet, das wie folgt aussah

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

Da alle diese URLs bei der Migration zu @use-Regeln den Standard-Namespace mixins hätten, könnte der Modul-Migrator etwas wie folgt generieren

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

Dies ist gültiger Code, da die Namespaces nicht kollidieren, aber sie sind viel komplizierter als nötig. Der relevante Teil der URL ist die Komponente, daher können wir den Namespace-Migrator verwenden, um diesen Teil zu extrahieren.

Wenn wir den Namespace-Migrator mit --rename 'url components/(\w+)/lib/mixins to \1' ausführen, erhalten wir

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

Das Umbenennungsskript hier besagt, dass alle @use-Regeln gefunden werden sollen, deren URLs wie components/(\w+)/lib/mixins aussehen (\w+ in einem regulären Ausdruck bedeutet, dass jedes Wort mit einem oder mehreren Zeichen abgeglichen wird). Das \1 in der Ausgabe bedeutet, dass der Inhalt der ersten Klammergruppe im regulären Ausdruck (eine Gruppe genannt) eingefügt wird.

Wenn Sie mehrere Umbenennungen anwenden möchten, können Sie die Option --rename mehrmals übergeben oder sie durch ein Semikolon oder einen Zeilenumbruch trennen. Nur die erste Umbenennung, die auf eine bestimmte Regel angewendet wird, wird verwendet. Sie könnten also etwas wie --rename 'a to b; b to a' übergeben, um die Namespaces a und b zu vertauschen.

--force–force-Permalink

Standardmäßig, wenn zwei oder mehr @use-Regeln nach der Migration denselben Namespace haben, schlägt der Migrator fehl und es werden keine Änderungen vorgenommen.

In diesem Fall möchten Sie normalerweise Ihr --rename-Skript anpassen, um Konflikte zu vermeiden, aber wenn Sie die Migration erzwingen möchten, können Sie stattdessen --force übergeben.

Mit --force erhält die erste @use-Regel bei auftretenden Konflikten ihren bevorzugten Namespace, während nachfolgende @use-Regeln mit demselben bevorzugten Namespace einen numerischen Suffix erhalten.