LegacyStringOptions<sync>

如果傳入 data，Sass 將使用它作為樣式表的內容進行編譯。(If data is passed, Sass will use it as the contents of the stylesheet to compile.)

已棄用 (Deprecated)

這僅適用於舊版 render 和 renderSync API。請改用 StringOptions 搭配 compile、compileString、compileAsync 和 compileStringAsync。(This only works with the legacy render and renderSync APIs. Use StringOptions with compile, compileString, compileAsync, and compileStringAsync instead.)

類型參數 (Type Parameters)

sync extends "sync" | "async"

這讓 TypeScript 檢查器可以驗證 LegacyAsyncImporter 和 LegacyAsyncFunction 沒有傳遞給 renderSync。(This lets the TypeScript checker verify that LegacyAsyncImporters and LegacyAsyncFunctions aren't passed to renderSync.)

階層 (Hierarchy)

LegacySharedOptions<sync>
- LegacyStringOptions

輸入 (Input)

資料

資料: 字串

要編譯的樣式表內容。除非同時傳入檔案，否則樣式表的網址會被設定為 "stdin"。

預設情況下，此樣式表會被解析為 SCSS。可以使用縮排語法來控制。

範例

sass.renderSync({
  data: `
h1 {
  font-size: 40px;
}`
});

`選用` 檔案

檔案?: 字串

如果同時傳遞了 file 和 data，則 file 會被用作樣式表的檔案路徑，以供錯誤報告使用，但樣式表的內容則會使用 data。在這種情況下，不會使用 file 的副檔名來判斷樣式表的語法。

`選用` includePaths

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

`選用` indentedSyntax

indentedSyntax?: boolean

這個旗標控制是否將 data 解析為縮排語法。

範例

sass.renderSync({
  data: `
h1
  font-size: 40px`,
  indentedSyntax: true
});

預設值

false

輸出

`選用` 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 是否應該使用空格或Tab鍵進行縮排。

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 中，每個縮排層級應該使用多少空格或Tab鍵（取決於 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;
  // }
});

類型宣告

[key: string]: LegacyFunction<sync>

`選用` importer

importer?: LegacyImporter<sync> | LegacyImporter<sync>[]

Dart Sass: ✓
Node Sass: 自 3.0.0 版本起

3.0.0 之前的 Node Sass 版本不支援 importer 陣列，也不支援返回 Error 物件的 importer。

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

Dart Sass: 自 1.20.2 起
Node Sass: ✗

1.20.2 之前的 Dart Sass 版本傾向於使用 includePaths 解析匯入，而不是使用自訂 importer 解析它們。

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

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

導入器會取得 @import 或 @use 規則的網址，並返回一個 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: 網址架構的 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 將不會印出由依賴項引起的警告。「依賴項」定義為任何透過 includePaths 或 importer 載入的檔案。相對於入口點匯入的樣式表不被視為依賴項。

這對於讓您無法自行修復的棄用警告靜音很有用。但是，也請通知您的依賴項這些棄用，以便它們能盡快得到修復！

⚠️ 注意！

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

預設值

false

`選用` silenceDeprecations

silenceDeprecations?: DeprecationOrId[]

一組要忽略的已棄用功能。

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

⚠️ 注意！

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

相容性

dart: "1.78.0", node: 無

`選用` verbose

verbose?: boolean

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

預設情況下，Dart Sass 每次編譯只會印出五個相同的已棄用警告實例，以避免在控制台中出現大量雜訊。如果您將 verbose 設定為 true，它將會印出遇到的每個已棄用警告。

預設值

false

原始碼對應

`選用` 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 將寫入與 file 選項相同的目錄（如果已傳遞 file 選項）。

如果此選項為 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 原始碼檔案的連結之前。

已棄用 (Deprecated)

類型參數 (Type Parameters)

sync extends "sync" | "async"

階層 (Hierarchy)

索引 (Index)

輸入 (Input)

輸出

外掛程式

訊息

原始碼對應

輸入 (Input)

資料

範例

選用 檔案

選用 includePaths

選用 indentedSyntax

範例

預設值

輸出

選用 charset

選用 indentType

預設值

選用 indentWidth

預設值

選用 linefeed

預設值

選用 outputStyle

範例

外掛程式

選用 functions

⚠️ 注意！

範例

類型宣告

[key: string]: LegacyFunction<sync>

選用 importer

範例

選用 pkgImporter

範例

訊息

選用 fatalDeprecations

相容性

選用 futureDeprecations

相容性

選用 logger

選用 quietDeps

⚠️ 注意！

預設值

選用 silenceDeprecations

⚠️ 注意！

相容性

選用 verbose

預設值

原始碼對應

選用 omitSourceMapUrl

預設值

選用 outFile

⚠️ 注意！

選用 sourceMap

範例

預設值

選用 sourceMapContents

範例

預設值

選用 sourceMapEmbed

範例

預設值

選用 sourceMapRoot

`選用` 檔案

`選用` includePaths

`選用` indentedSyntax

`選用` charset

`選用` indentType

`選用` indentWidth

`選用` linefeed

`選用` outputStyle

`選用` functions

`選用` importer

`選用` pkgImporter

`選用` fatalDeprecations

`選用` futureDeprecations

`選用` logger

`選用` quietDeps

`選用` silenceDeprecations

`選用` verbose

`選用` omitSourceMapUrl

`選用` outFile

`選用` sourceMap

`選用` sourceMapContents

`選用` sourceMapEmbed

`選用` sourceMapRoot