Breaking Change: Legacy JS API

Migration der NutzungMigration der Nutzung Permalink

EntrypointsEntrypoints Permalink

Die Legacy JS API hatte zwei Entrypoints zum Kompilieren von Sass: render und renderSync, die ein Options-Objekt erhielten, das entweder file (zum Kompilieren einer Datei) oder data (zum Kompilieren eines Strings) enthielt. Die moderne API hat vier: compile und compileAsync zum Kompilieren einer Datei und compileString und compileStringAsync zum Kompilieren eines Strings. Diese Funktionen nehmen einen Pfad oder einen Quellstring als erstes Argument und dann ein Objekt aller anderen Optionen als zweites Argument. Im Gegensatz zu render, das einen Callback verwendete, geben compileAsync und compileStringAsync stattdessen ein Promise zurück .

Weitere Details finden Sie in der Nutzungsdokumentation .

ImportersImporters Permalink

Importers in der Legacy API bestanden aus einer einzigen Funktion, die die URL der Abhängigkeitsregel und die URL des enthaltenden Stylesheets (sowie einen done-Callback für asynchrone Importer) entgegennahm und ein Objekt mit entweder einem Dateipfad auf der Festplatte oder dem contents des zu ladenden Stylesheets zurückgab .

Moderne API Importer enthalten stattdessen zwei Methoden: canonicalize, die eine Regel- URL entgegennimmt und die kanonische Form dieser URL zurückgibt; und load, die eine kanonische URL entgegennimmt und ein Objekt mit dem Inhalt des geladenen Stylesheets zurückgibt. Diese Aufteilung stellt sicher, dass dasselbe Modul nur einmal geladen wird und relative URLs konsistent funktionieren. Asynchrone Importer lassen beide dieser Methoden Promises zurückgeben .

Es gibt auch einen speziellen FileImporter, der alle Ladevorgänge auf vorhandene Dateien auf der Festplatte umleitet, der verwendet werden sollte, wenn von Legacy-Importern migriert wird, die file anstelle von contents zurückgaben.

Benutzerdefinierte FunktionenBenutzerdefinierte Funktionen Permalink

In der Legacy JS API erhielten benutzerdefinierte Funktionen ein separates JS-Argument für jedes Sass-Argument, mit einem zusätzlichen done-Callback für asynchrone benutzerdefinierte Funktionen. In der modernen API erhalten benutzerdefinierte Funktionen stattdessen ein einzelnes JS-Argument, das eine Liste aller Sass-Argumente enthält, wobei asynchrone benutzerdefinierte Funktionen ein Promise zurückgeben .

Die moderne API verwendet außerdem eine wesentlich robustere Value-Klasse, die alle Sass-Werttypen, Typprüfungen und einfache Map- und Listen-Lookups unterstützt .

BundlerBundler Permalink

Wenn Sie einen Bundler oder ein anderes Tool verwenden, das die Sass API aufruft, anstatt sie direkt zu verwenden, müssen Sie möglicherweise die Konfiguration ändern, die Sie an dieses Tool übergeben, um es anzuweisen, die moderne API zu verwenden .

Webpack sollte die moderne API bereits standardmäßig verwenden. Wenn Sie jedoch Warnungen erhalten, setzen Sie api auf "modern" oder "modern-compiler". Weitere Details finden Sie in der Webpack-Dokumentation .

Vite verwendet immer noch standardmäßig die Legacy API. Sie können es jedoch ähnlich umschalten, indem Sie api auf "modern" oder "modern-compiler" setzen. Weitere Details finden Sie in der Vite-Dokumentation .

Prüfen Sie für andere Tools deren Dokumentation oder Issue-Tracker auf Informationen zur Unterstützung der modernen Sass API .

Warnungen unterdrückenWarnungen unterdrücken Permalink

Obwohl die Legacy JS API in Dart Sass 1.45.0 zusammen mit der Veröffentlichung der modernen API als veraltet markiert wurde, begannen wir ab Dart Sass 1.79.0 Warnungen für deren Verwendung auszugeben. Wenn Sie noch nicht in der Lage sind, auf die moderne API zu migrieren, aber die Warnungen vorerst unterdrücken möchten, können Sie legacy-js-api in der Option silenceDeprecations übergeben

const sass = require('sass');

const result = sass.renderSync({
  silenceDeprecations: ['legacy-js-api'],
  ...
});

Dies wird die Warnungen vorerst unterdrücken, aber die Legacy API wird in Dart Sass 2.0.0 vollständig entfernt. Sie sollten also immer noch planen, sie bald abzulösen .