LegacyFileOptions<sync>

如果在沒有 data 的情況下傳遞 file，Sass 將會載入位於 file 的樣式表並將其編譯成 CSS。

類型參數

sync extends "sync" | "async"

這讓 TypeScript 檢查器可以驗證 LegacyAsyncImporter 和 LegacyAsyncFunction 沒有被傳遞到 renderSync。

階層

LegacySharedOptions<sync>
- LegacyFileOptions

輸入

`選用` 資料

資料?: 未定義

請參閱檔案的說明文件，了解如何連同資料傳遞檔案。

檔案

檔案: 字串

Dart Sass: 自 1.11.0 版起
Node Sass: 部分

Node Sass 和舊版的 Dart Sass 支援載入副檔名為 .css 的檔案，但與規範相反，它們會被視為 SCSS 檔案處理，而不是被解析為 CSS。此行為已被棄用，不應再依賴。任何使用 Sass 功能的檔案都應使用 .scss 副檔名。

除此之外，所有版本的 Node Sass 和 Dart Sass 都支援如下所述的檔案選項。

Sass 要載入和編譯的檔案路徑。如果檔案的副檔名是 .scss，它將會被解析為 SCSS；如果它是 .sass，它將會被解析為縮排語法；如果它是 .css，它將會被解析為純 CSS。如果它沒有副檔名，它將會被解析為 SCSS。

範例

sass.renderSync({file: "style.scss"});

`選用` 包含路徑

includePaths?: string[]

Dart Sass: 從 1.15.0 版本開始
Node Sass: 從 3.9.0 版本開始

早期版本的 Dart Sass 和 Node Sass 不支援 SASS_PATH 環境變數。

這個字串陣列選項提供了載入路徑供 Sass 搜尋樣式表。較早的載入路徑會優先於較晚的載入路徑。

sass.renderSync({
  file: "style.scss",
  includePaths: ["node_modules/bootstrap/dist/css"]
});

如果設定了 SASS_PATH 環境變數，載入路徑也會從中載入。這個變數應該是以 ;（在 Windows 上）或 :（在其他作業系統上）分隔的路徑清單。 includePaths 選項中的載入路徑優先於 SASS_PATH 中的載入路徑。

$ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css

輸出

`選用` charset

charset?: boolean

Dart Sass: 從 1.39.0 版本開始
Node Sass: ✗

預設情況下，如果 CSS 文件包含非 ASCII 字元，Sass 會新增 @charset 宣告（在展開輸出模式下）或位元組順序標記（在壓縮模式下），以向瀏覽器或其他使用者指示其編碼。如果 charset 為 false，則會省略這些註釋。

`選用` indentType

indentType?: "space" | "tab"

Dart Sass: ✓
Node Sass: 從 3.0.0 版本開始

產生的 CSS 應該使用空格還是定位點進行縮排。

const result = sass.renderSync({
  file: "style.scss",
  indentType: "tab",
  indentWidth: 1
});

result.css.toString();
// "h1 {\n\tfont-size: 40px;\n}\n"

預設值

'space'

`選用` indentWidth

indentWidth?: number

Dart Sass: ✓
Node Sass: 從 3.0.0 版本開始

在產生的 CSS 中，每個縮排層級應該使用多少空格或定位點（取決於 indentType）。它必須介於 0 到 10 之間（含）。

預設值

2

`選用` linefeed

linefeed?: "cr" | "crlf" | "lf" | "lfcr"

Dart Sass: ✓
Node Sass: 從 3.0.0 版本開始

在生成的 CSS 中，每一行結尾使用的字元序列。它可以有以下值：

'lf' 使用 U+000A 換行符 (LINE FEED)。
'lfcr' 使用 U+000A 換行符 (LINE FEED) 後接著 U+000D 回車符 (CARRIAGE RETURN)。
'cr' 使用 U+000D 回車符 (CARRIAGE RETURN)。
'crlf' 使用 U+000D 回車符 (CARRIAGE RETURN) 後接著 U+000A 換行符 (LINE FEED)。

預設值

'lf'

`選用` outputStyle

outputStyle?: "expanded" | "compact" | "compressed" | "nested"

編譯後 CSS 的輸出樣式。共有四種可能的輸出樣式：

"expanded"（Dart Sass 的預設值）將每個選擇器和宣告寫在自己的行上。
"compressed" 盡可能移除多餘的字元，並將整個樣式表寫在單行上。
"nested"（Node Sass 的預設值，Dart Sass 不支援）縮排 CSS 規則以符合 Sass 原始碼的巢狀結構。
"compact"（Dart Sass 不支援）將每個 CSS 規則放在自己的單行上。

範例

const source = `
h1 {
  font-size: 40px;
  code {
    font-face: Roboto Mono;
  }
}`;

let result = sass.renderSync({
  data: source,
  outputStyle: "expanded"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// h1 code {
//   font-face: Roboto Mono;
// }

result = sass.renderSync({
  data: source,
  outputStyle: "compressed"
});
console.log(result.css.toString());
// h1{font-size:40px}h1 code{font-face:Roboto Mono}

result = sass.renderSync({
  data: source,
  outputStyle: "nested"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px; }
//   h1 code {
//     font-face: Roboto Mono; }

result = sass.renderSync({
  data: source,
  outputStyle: "compact"
});
console.log(result.css.toString());
// h1 { font-size: 40px; }
// h1 code { font-face: Roboto Mono; }

外掛程式

`選用` functions

functions?: {
[key: string]: LegacyFunction<sync>;
}

在所有樣式表中可用的額外內建 Sass 函式。此選項接受一個物件，其鍵是 Sass 函式簽章，值是 LegacyFunction。每個函式應採用与其簽章相同的引數。

函式會傳遞 LegacyValue 的子類別，並且必須返回相同的值。

⚠️ 注意！

撰寫自訂函式時，確保所有引數皆為預期類型至關重要。否則，使用者的樣式表可能會以難以除錯的方式崩潰，或者更糟的是，編譯成無意義的 CSS。

範例

sass.render({
  data: `
h1 {
  font-size: pow(2, 5) * 1px;
}`,
  functions: {
    // This function uses the synchronous API, and can be passed to either
    // renderSync() or render().
    'pow($base, $exponent)': function(base, exponent) {
      if (!(base instanceof sass.types.Number)) {
        throw "$base: Expected a number.";
      } else if (base.getUnit()) {
        throw "$base: Expected a unitless number.";
      }

      if (!(exponent instanceof sass.types.Number)) {
        throw "$exponent: Expected a number.";
      } else if (exponent.getUnit()) {
        throw "$exponent: Expected a unitless number.";
      }

      return new sass.types.Number(
          Math.pow(base.getValue(), exponent.getValue()));
    },

    // This function uses the asynchronous API, and can only be passed to
    // render().
    'sqrt($number)': function(number, done) {
      if (!(number instanceof sass.types.Number)) {
        throw "$number: Expected a number.";
      } else if (number.getUnit()) {
        throw "$number: Expected a unitless number.";
      }

      done(new sass.types.Number(Math.sqrt(number.getValue())));
    }
  }
}, function(err, result) {
  console.log(result.css.toString());
  // h1 {
  //   font-size: 32px;
  // }
});

類型宣告 (Type Declaration)

[鍵 (key): 字串 (string)]: LegacyFunction<同步/非同步 (sync)>

`選用 (Optional)` 匯入器 (importer)

匯入器 (importer)?: LegacyImporter<同步/非同步 (sync)> | LegacyImporter<同步/非同步 (sync)>[]

Dart Sass: ✓
Node Sass: 從 3.0.0 版本開始

3.0.0 之前的 Node Sass 版本不支援匯入器陣列，也不支援傳回 Error 物件的匯入器。

2.0.0 之前的 Node Sass 版本完全不支援 importer 選項。

Dart Sass: 自 1.20.2 起
Node Sass: ✗

1.20.2 之前的 Dart Sass 版本傾向於使用 includePaths 解析匯入，然後才使用自訂匯入器。

目前所有版本的 Node Sass 都會先將匯入傳遞給匯入器，然後再根據 @import 出現的檔案的相對路徑載入它們。這種行為被認為是不正確的，不應該依賴它，因為它違反了*局部性*原則，該原則指出應該可以在不知道整個系統如何設置的情況下推斷樣式表。如果使用者嘗試根據另一個樣式表的相對路徑匯入樣式表，則該匯入*應該永遠*有效。其他地方的某些設定不應該使其失效。

當遇到 @use 規則或 @import 規則時，用於載入檔案的額外處理程式。它可以是單個 LegacyImporter 函式，也可以是 LegacyImporter 陣列。

匯入器會取得 @import 或 @use 規則的 URL，並傳回一個 LegacyImporterResult，指示如何處理該規則。如需更多詳細資訊，請參閱 LegacySyncImporter 和 LegacyAsyncImporter。

載入會按以下順序嘗試解析：

從 @use 或 @import 出現的檔案的相對路徑載入檔案。
每個自訂匯入器。
根據目前工作目錄的相對路徑載入檔案。
includePaths 中的每個載入路徑。
在 SASS_PATH 環境變數中指定的每個載入路徑，在 Windows 上應以分號分隔，在其他地方則以冒號分隔。

範例

sass.render({
  file: "style.scss",
  importer: [
    // This importer uses the synchronous API, and can be passed to either
    // renderSync() or render().
    function(url, prev) {
      // This generates a stylesheet from scratch for `@use "big-headers"`.
      if (url != "big-headers") return null;

      return {
        contents: `
h1 {
  font-size: 40px;
}`
      };
    },

    // This importer uses the asynchronous API, and can only be passed to
    // render().
    function(url, prev, done) {
      // Convert `@use "foo/bar"` to "node_modules/foo/sass/bar".
      const components = url.split('/');
      const innerPath = components.slice(1).join('/');
      done({
        file: `node_modules/${components.first}/sass/${innerPath}`
      });
    }
  ]
}, function(err, result) {
  // ...
});

`選用` pkgImporter

pkgImporter?: NodePackageImporter

Dart Sass: 自 2.0 版起
Node Sass: ✗

如果將此選項設定為 NodePackageImporter 的實例，Sass 將使用內建的 Node.js 套件導入器來解析帶有 pkg: URL 結構的 Sass 檔案。函式庫作者和使用者可以在 NodePackageImporter 文件中找到詳細資訊。

範例

sass.renderSync({
  data: '@use "pkg:vuetify";',
  pkgImporter: new sass.NodePackageImporter()
});

訊息

`選用` fatalDeprecations

fatalDeprecations?: (DeprecationOrId | Version)[]

一組被視為嚴重錯誤的棄用項目。

如果在編譯過程中遇到任何提供的棄用警告類型，編譯器將會報錯。

如果提供了 Version，則該編譯器版本中所有有效的棄用警告都將被視為嚴重錯誤。

相容性

dart: "1.78.0", node: 無

`選用` futureDeprecations

futureDeprecations?: DeprecationOrId[]

一組提前啟用的未來棄用項目。

此處傳遞的未來棄用項目將被編譯器視為有效，並在必要時發出警告。

相容性

dart: "1.78.0", node: 無

`選用` logger

logger?: Logger

Dart Sass: 自 1.43.0 版起
Node Sass: ✗

用於處理來自 Sass 的警告和/或除錯訊息的物件。

預設情況下，Sass 會將警告和除錯訊息發送到標準錯誤輸出。但是，如果設定了 warn 或 debug，則會改為呼叫它們。

特殊值 silent 可用於輕鬆地讓所有訊息靜音。

`選用` quietDeps

quietDeps?: 布林值

Dart Sass: 自 1.35.0 版本起
Node Sass: ✗

如果此選項設為 true，Sass 將不會顯示由 dependencies 引起的警告。「dependency」定義為任何透過 includePaths 或 importer 載入的檔案。相對於 entrypoint 匯入的樣式表不被視為 dependency。

這對於隱藏您無法自行修復的棄用警告很有用。但是，也請*通知*您的 dependencies 這些棄用警告，以便它們能盡快修復！

⚠️ 注意！

如果呼叫 render 或 renderSync 時沒有 file 或 file，它載入的*所有*樣式表都將被視為 dependencies。由於它沒有自己的路徑，因此它載入的所有內容都來自載入路徑，而不是相對匯入。

預設值

false (預設值)

`選用` silenceDeprecations

silenceDeprecations?: DeprecationOrId[]

要忽略的已啟用棄用警告集合。

如果在編譯期間遇到任何提供的棄用警告類型，編譯器將會忽略它。

⚠️ 注意！

您所依賴的已棄用功能最終將會失效。

相容性

dart: "1.78.0", node: 無

`選用` verbose

verbose?: 布林值

Dart Sass: 自 1.35.0 版本起
Node Sass: ✗

預設情況下，Dart Sass 每次編譯只會顯示五次相同的棄用警告，以避免在控制台中充斥大量訊息。如果您將 verbose 設為 true，它將會顯示遇到的每個棄用警告。

預設值

false (預設值)

來源對應 (Source Maps)

`選用` omitSourceMapUrl

omitSourceMapUrl?: boolean

如果設為 true，Sass 不會在產生的 CSS 中加入指向來源映射的連結。

const result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  omitSourceMapUrl: true
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }

預設值

false (預設值)

`選用` outFile

outFile?: string

Sass 預期儲存產生的 CSS 的位置。它用於決定從產生的 CSS 連結到來源映射，以及從來源映射連結到 Sass 原始碼檔案的 URL。

⚠️ 注意！

儘管名稱如此，Sass 並*不會*將 CSS 輸出寫入此檔案。呼叫者必須自行完成。

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /

`選用` sourceMap

sourceMap?: string | boolean

Sass 是否應該產生來源映射。如果產生，來源映射將以 map 的形式提供（除非 sourceMapEmbed 為 true）。

如果此選項是字串，則它是預期寫入來源映射的路徑，用於從產生的 CSS 連結到來源映射，以及從來源映射連結到 Sass 原始碼檔案。請注意，如果 sourceMap 是字串且未傳遞 outFile，Sass 會假設 CSS 將被寫入與檔案選項相同的目錄（如果已傳遞）。

如果此選項為 true，則假設路徑為 outFile，並在結尾加上 .map。如果它是 true 且未傳遞 outFile，則它沒有作用。

範例

let result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.map * /

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /

預設值

false (預設值)

`選用` sourceMapContents

sourceMapContents?: boolean

是否將產生 CSS 的所有 Sass 檔案的完整內容嵌入到來源映射中。這可能會產生非常大的來源映射，但它保證來源在任何電腦上都可用，無論 CSS 如何提供。

範例

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapContents: true
})

預設值

false (預設值)

`選用` sourceMapEmbed

sourceMapEmbed?: boolean

是否將來源映射檔案的內容嵌入到產生的 CSS 中，而不是建立一個單獨的檔案並從 CSS 連結到它。

範例

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapEmbed: true
});

預設值

false (預設值)

`選用` sourceMapRoot

sourceMapRoot?: string

如果傳入此參數，它會被添加到來源映射到 Sass 來源檔案的所有連結之前。

類型參數

sync extends "sync" | "async"

階層

索引

輸入

輸出

外掛程式

訊息

來源對應 (Source Maps)

輸入

選用 資料

檔案

範例

選用 包含路徑

輸出

選用 charset

選用 indentType

預設值

選用 indentWidth

預設值

選用 linefeed

預設值

選用 outputStyle

範例

外掛程式

選用 functions

⚠️ 注意！

範例

類型宣告 (Type Declaration)

[鍵 (key): 字串 (string)]: LegacyFunction<同步/非同步 (sync)>

選用 (Optional) 匯入器 (importer)

範例

選用 pkgImporter

範例

訊息

選用 fatalDeprecations

相容性

選用 futureDeprecations

相容性

選用 logger

選用 quietDeps

⚠️ 注意！

預設值

選用 silenceDeprecations

⚠️ 注意！

相容性

選用 verbose

預設值

來源對應 (Source Maps)

選用 omitSourceMapUrl

預設值

選用 outFile

⚠️ 注意！

選用 sourceMap

範例

預設值

選用 sourceMapContents

範例

預設值

選用 sourceMapEmbed

範例

預設值

選用 sourceMapRoot

`選用` 資料

`選用` 包含路徑

`選用` charset

`選用` indentType

`選用` indentWidth

`選用` linefeed

`選用` outputStyle

`選用` functions

`選用 (Optional)` 匯入器 (importer)

`選用` pkgImporter

`選用` fatalDeprecations

`選用` futureDeprecations

`選用` logger

`選用` quietDeps

`選用` silenceDeprecations

`選用` verbose

`選用` omitSourceMapUrl

`選用` outFile

`選用` sourceMap

`選用` sourceMapContents

`選用` sourceMapEmbed

`選用` sourceMapRoot