Importer<sync>

Ein Objekt, das eine benutzerdefinierte Sass-Ladelogik für @use Regeln und @import Regeln implementiert. Es kann an importers oder importer übergeben werden.

Für Importer, die einfach auf Dateien auf der Festplatte umleiten, wird die Verwendung der FileImporter-Schnittstelle empfohlen.

Auflösung eines Ladevorgangs

Dies ist der Prozess der Auflösung eines Ladevorgangs mithilfe eines benutzerdefinierten Importers.

  • Der Compiler stößt auf @use "db:foo/bar/baz".
  • Er ruft canonicalize mit "db:foo/bar/baz" auf.
  • canonicalize gibt new URL("db:foo/bar/baz/_index.scss") zurück.
  • Wenn der Compiler bereits ein Stylesheet mit dieser kanonischen URL geladen hat, wird das vorhandene Modul wiederverwendet.
  • Andernfalls ruft er load mit new URL("db:foo/bar/baz/_index.scss") auf.
  • load gibt ein ImporterResult zurück, das der Compiler als Inhalt des Moduls verwendet.

Weitere Details zur Auflösung von Ladevorgängen mithilfe mehrerer Importer und Lade pfade finden Sie unter importers.

Beispiel

sass.compile('style.scss', {
  // An importer for URLs like `bgcolor:orange` that generates a
  // stylesheet with the given background color.
  importers: [{
    canonicalize(url) {
      if (!url.startsWith('bgcolor:')) return null;
      return new URL(url);
    },
    load(canonicalUrl) {
      return {
        contents: `body {background-color: ${canonicalUrl.pathname}}`,
        syntax: 'scss'
      };
    }
  }]
});

Typenparameter

Hierarchie

  • Importer

Eigenschaften

nonCanonicalScheme?

Methoden

canonicalize load

Eigenschaften

Optional nonCanonicalScheme

nonCanonicalScheme?: string | string[]

Ein URL-Schema oder eine Menge von Schemata (ohne den :), die dieser Importer niemals für von canonicalize zurückgegebene URLs verspricht zu verwenden. Wenn er eine URL mit einem dieser Schemata zurückgibt, ist dies ein Fehler.

Wenn dies gesetzt ist, wird jeder Aufruf von canonicalize für eine URL mit einem nicht-kanonischen Schema an containingUrl übergeben, falls bekannt ist.

Diese Schemata dürfen nur Kleinbuchstaben des ASCII-Zeichensatzes, ASCII-Ziffern, +, - und . enthalten. Sie dürfen nicht leer sein.

Methoden

canonicalize

  • Wenn die url von diesem Importer erkannt wird, wird ihr kanonisches Format zurückgegeben.

    Wenn Sass bereits ein Stylesheet mit der zurückgegebenen kanonischen URL geladen hat, wird der vorhandene Parse-Baum (und das geladene Modul für @use) wiederverwendet. Das bedeutet, dass Importer **sicherstellen müssen**, dass dieselbe kanonische URL immer auf dasselbe Stylesheet verweist, *auch über verschiedene Importer hinweg*. Daher wird empfohlen, dass Importer eindeutige URL-Schemata verwenden, um sich voneinander zu unterscheiden und klarzustellen.

    Nach Möglichkeit sollten benutzerdefinierte Importer URLs genauso kanonisieren wie der integrierte Dateisystem- Importer.

    • Der Importer sollte nach Stylesheets suchen, indem er dem Basisnamen der URL das Präfix _ voranstellt und die Erweiterungen .sass und .scss hinzufügt, falls die URL noch keine dieser Erweiterungen hat. Wenn die URL beispielsweise foo/bar/baz wäre, würde der Importer nach

      • foo/bar/baz.sass
      • foo/bar/baz.scss
      • foo/bar/_baz.sass
      • foo/bar/_baz.scss

      suchen. Wenn die URL foo/bar/baz.scss wäre, würde der Importer nur nach

      • foo/bar/baz.scss
      • foo/bar/_baz.scss

      suchen. Wenn der Importer ein Stylesheet unter mehr als einer dieser URLs findet, sollte er eine Ausnahme auslösen, die besagt, dass die URL mehrdeutig ist. Beachten Sie, dass, wenn die Erweiterung explizit angegeben ist, ein Stylesheet mit der umgekehrten Erweiterung existieren darf darf.

    • Wenn keiner der möglichen Pfade gültig ist, sollte der Importer die gleiche Auflösung für die URL gefolgt von /index durchführen. Im obigen Beispiel würde er nach

      • foo/bar/baz/index.sass
      • foo/bar/baz/index.scss
      • foo/bar/baz/_index.sass
      • foo/bar/baz/_index.scss

      suchen. Wie oben gilt: Wenn der Importer ein Stylesheet unter mehr als einer dieser URLs findet, sollte er eine Ausnahme auslösen, die besagt, dass der Import mehrdeutig ist.

    Wenn keine Stylesheets gefunden werden, sollte der Importer null zurückgeben.

    Mehrfache Aufrufe von canonicalize mit derselben URL müssen dasselbe Ergebnis liefern. Ein Aufruf von canonicalize mit einer URL, die von einem vorherigen Aufruf von canonicalize zurückgegeben wurde, muss diese URL zurückgeben.

    Relative Ladevorgänge in Stylesheets, die von einem Importer geladen wurden, werden gehandhabt, indem die geladene URL relativ zur kanonischen URL des Stylesheets, das sie enthält, aufgelöst und diese URL zurück an die Methode canonicalize des Importers übergeben wird. Angenommen zum Beispiel, das Beispiel "Auflösung eines Ladevorgangs" oben gab ein Stylesheet zurück, das @use "mixins" enthielt.

    • Der Compiler löst die URL mixins relativ zur kanonischen URL db:foo/bar/baz/_index.scss des aktuellen Stylesheets auf, um db:foo/bar/baz/mixins zu erhalten.
    • Er ruft canonicalize mit "db:foo/bar/baz/mixins" auf.
    • canonicalize gibt new URL("db:foo/bar/baz/_mixins.scss") zurück.

    Aus diesem Grund muss canonicalize ein sinnvolles Ergebnis zurückgeben, wenn es mit einer URL aufgerufen wird, die relativ zu einer früheren Rückgabe von canonicalize ist.

    Wirft

    beliebig - Wenn dieser Importer url erkennt, aber feststellt, dass sie ungültig ist, kann er eine Ausnahme auslösen, die von Sass umschlossen wird. Wenn das Ausnahmeobjekt eine Eigenschaft message hat, wird diese als Nachricht der umschlossenen Ausnahme verwendet; andernfalls wird die Methode toString() des Ausnahmeobjekts verwendet. Das bedeutet, dass es für Importer sicher ist, einfache Strings auszulösen.

    Parameter

    • url: string

      Die geladene URL. Da dies relativ sein kann, wird es als String und nicht als URL- Objekt dargestellt.

    • context: CanonicalizeContext

    Gibt PromiseOr<null | URL, sync> zurück

    Eine absolute URL, wenn dieser Importer die url erkennt, oder null, wenn nicht. Wenn null zurückgegeben wird, können andere Importer oder load paths den Ladevorgang behandeln.

    Dies kann auch ein Promise zurückgeben, aber wenn dies der Fall ist, kann der Importer nur an compileAsync und compileStringAsync übergeben werden, nicht an compile oder compileString.

load

  • Lädt den Sass-Text für die gegebene canonicalUrl, oder gibt null zurück, wenn dieser Importer das referenzierte Stylesheet nicht finden kann kann.

    Wirft

    beliebig - Wenn dieser Importer ein Stylesheet unter url findet, aber aus irgendeinem Grund nicht laden kann, oder wenn url eindeutig mit diesem Importer verknüpft ist, aber nicht auf ein echtes Stylesheet verweist, kann der Importer eine Ausnahme auslösen, die von Sass umschlossen wird. Wenn das Ausnahmeobjekt eine Eigenschaft message hat, wird diese als Nachricht der umschlossenen Ausnahme verwendet; andernfalls wird die Methode toString() des Ausnahmeobjekts verwendet. Das bedeutet, dass es für Importer sicher ist, einfache Strings auszulösen.

    Parameter

    • canonicalUrl: URL

      Die kanonische URL des zu ladenden Stylesheets. Diese stammt garantiert von einem Aufruf von canonicalize, obwohl nicht jeder Aufruf von canonicalize zu einem Aufruf von load führt.

    Gibt PromiseOr<null | ImporterResult, sync> zurück

    Der Inhalt des Stylesheets unter canonicalUrl, wenn es geladen werden kann, oder null, wenn es nicht geladen werden kann.

    Dies kann auch ein Promise zurückgeben, aber wenn dies der Fall ist, kann der Importer nur an compileAsync und compileStringAsync übergeben werden, nicht an compile oder compileString.