同步/非同步匯入器 (Importer<sync>)

一個實作 Sass 自訂載入邏輯的物件，適用於 @use 規則和 @import 規則。它可以傳遞給 importers 或 importer。

建議僅重新導向至磁碟上檔案的匯入器使用 `FileImporter` 介面。

解析載入

這是使用自訂匯入器解析載入的過程。

  • 編譯器遇到 @use "db:foo/bar/baz"。
  • 它使用 "db:foo/bar/baz" 呼叫 canonicalize。
  • canonicalize 返回 new URL("db:foo/bar/baz/_index.scss")。
  • 如果編譯器已經載入了具有此標準 URL 的樣式表，它會重複使用現有的模組。
  • 否則，它會使用 new URL("db:foo/bar/baz/_index.scss") 呼叫 load。
  • load 返回一個 ImporterResult，編譯器將其用作模組的內容。

有關使用多個匯入器和載入路徑解析載入方式的更多詳細資訊，請參閱 importers。

範例

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'
      };
    }
  }]
});

類型參數

階層結構

  • 匯入器

屬性

nonCanonicalScheme？

方法

canonicalize load

屬性

選用 nonCanonicalScheme

nonCanonicalScheme?: string | string[]

此導入器承諾絕不會用於 canonicalize 返回的網址的網址格式（或一組格式）（不含 :）。如果它確實返回了使用這些格式的網址，則表示發生錯誤。

如果設定了此項，則任何對具有非正規格式的網址呼叫 canonicalize 時，如果已知，將會傳遞 containingUrl。

這些格式只能包含小寫 ASCII 字母、ASCII 數字、`+`、`-` 和 `.`。它們不能為空。

方法

canonicalize

  • 如果這個匯入器辨識出 url，則返回其標準格式。

    如果 Sass 已經載入具有返回標準 URL 的樣式表，它會重複使用現有的解析樹（以及已載入的 @use 模組）。這表示匯入器**必須確保**相同的標準 URL 始終指向相同的樣式表，*即使在不同的匯入器之間也是如此*。因此，鼓勵匯入器使用唯一的 URL 結構來區分彼此。

    盡可能地，自訂匯入器應該以與內建檔案系統匯入器相同的方式將 URL 標準化。

    • 匯入器應該透過在 URL 的基本名稱前加上前綴 _，並在 URL 尚未具有 .sass 和 .scss 副檔名時新增這些副檔名，來尋找樣式表。例如，如果 URL 為 foo/bar/baz，匯入器會尋找：

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

      如果 URL 為 foo/bar/baz.scss，匯入器只會尋找：

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

      如果匯入器在多個 URL 中找到樣式表，它應該拋出一個例外，指出 URL 不明確。請注意，如果明確指定了副檔名，則允許存在具有相反副檔名的樣式表。

    • 如果所有可能的路徑都無效，匯入器應該對 URL 後跟 /index 執行相同的解析。在上面的範例中，它會尋找：

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

      如上所述，如果匯入器在多個 URL 中找到樣式表，它應該拋出一個例外，指出匯入不明確。

    如果找不到樣式表，匯入器應該返回 null。

    使用相同的 URL 多次呼叫 canonicalize 必須返回相同的結果。使用先前呼叫 canonicalize 返回的 URL 呼叫 canonicalize 必須返回該 URL。

    從匯入器載入的樣式表中的相對載入，是透過將載入的 URL 解析為包含它的樣式表的標準 URL 的相對路徑，並將該 URL 傳回匯入器的 canonicalize 方法來處理。例如，假設「解析載入」範例上方返回了一個包含 @use "mixins" 的樣式表。

    • 編譯器會將 URL mixins 解析為目前樣式表的標準 URL db:foo/bar/baz/_index.scss 的相對路徑，以取得 db:foo/bar/baz/mixins。
    • 它會使用 "db:foo/bar/baz/mixins" 呼叫 canonicalize。
    • canonicalize 會回傳 new URL("db:foo/bar/baz/_mixins.scss")。

    因此，canonicalize 在以先前呼叫 canonicalize 所回傳的 URL 作為相對路徑的 URL 作為參數呼叫時，必須回傳有意義的結果。

    拋出錯誤

    any - 如果此導入器辨識 url 但判斷其無效，它可能會拋出 Sass 會包裝的例外。如果例外物件具有 message 屬性，它將被用作包裝後例外的訊息；否則，將使用例外物件的 toString()。這表示導入器可以安全地拋出純字串。

    參數

    • url: string

      已載入的 URL。由於這可能是相對路徑，因此它以字串而非 URL 物件表示。

    • context: CanonicalizeContext

    回傳 PromiseOr<null | URL, sync>

    如果此導入器辨識 url，則回傳絕對 URL，否則回傳 null。如果回傳 null，其他導入器或 載入路徑 可能會處理載入。

    這也可能回傳 Promise，但如果它這樣做，則導入器可能只會傳遞給 compileAsync 和 compileStringAsync，而不是 compile 或 compileString。

load

  • 載入給定 canonicalUrl 的 Sass 文字，或者如果此導入器找不到它所參考的樣式表，則回傳 null。

    拋出錯誤

    any - 如果此導入器在 url 找到樣式表，但由於某些原因無法載入，或者如果 url 與此導入器唯一關聯但不參考實際的樣式表，則導入器可能會拋出 Sass 會包裝的例外。如果例外物件具有 message 屬性，它將被用作包裝後例外的訊息；否則，將使用例外物件的 toString()。這表示導入器可以安全地拋出純字串。

    參數

    • canonicalUrl：URL

      要載入的樣式表的標準 URL。這保證來自對 canonicalize 的呼叫，儘管並非每次對 canonicalize 的呼叫都會導致對 load 的呼叫。

    回傳 PromiseOr<null | ImporterResult, sync>

    如果可以載入，則為 canonicalUrl 中樣式表的內容，如果無法載入，則為 null。

    這也可能回傳 Promise，但如果它這樣做，則導入器可能只會傳遞給 compileAsync 和 compileStringAsync，而不是 compile 或 compileString。