LegacySharedOptions<sync>

render 和 renderSync 的選項，這些選項在 LegacyFileOptions 和 LegacyStringOptions 之間共用。

已棄用

這僅適用於舊版 render 和 renderSync API。請改用 Options 搭配 compile、compileString、compileAsync 和 compileStringAsync。

類型參數

sync extends "sync" | "async"

這讓 TypeScript 檢查器可以驗證 LegacyAsyncImporter 和 LegacyAsyncFunction 未傳遞至 renderSync。

階層

LegacySharedOptions
- LegacyFileOptions
- LegacyStringOptions

輸入

`選用` 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

輸出

`選用` 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;
  // }
});

類型宣告

[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 都會先將匯入傳遞給 importer，然後再載入相對於 @import 出現所在檔案的檔案。這種行為被認為是不正確的，不應該被依賴，因為它違反了「局部性」原則，該原則指出應該可以在不知道整個系統如何設置的情況下推斷樣式表。如果使用者嘗試將樣式表相對於另一個樣式表匯入，則該匯入應*始終*有效。不應該讓其他地方的某些設定將其破壞。

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

Importer 接收 @import 或 @use 規則的網址，並傳回 LegacyImporterResult，指示如何處理該規則。如需更多詳細資訊，請參閱 LegacySyncImporter 和 LegacyAsyncImporter。

載入會按以下順序解析：

從磁碟載入相對於 @use 或 @import 出現所在檔案的檔案。
每個自訂 importer。
載入相對於目前工作目錄的檔案。
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: false

`選用` futureDeprecations

futureDeprecations?: DeprecationOrId[]

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

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

相容性

dart: "1.78.0", node: false

`選用` logger

logger?: Logger

Dart Sass: 自 1.43.0 起
Node Sass: ✗

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

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

特殊值 silent 可用於輕鬆地隱藏所有訊息。

`選用` quietDeps

quietDeps?: boolean

Dart Sass: 自 1.35.0 起
Node Sass: ✗

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

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

⚠️ 注意！

如果在呼叫 render 或 renderSync 時沒有提供 file 或 file 參數，它載入的 *所有* 樣式表都會被視為相依檔案。由於它本身沒有路徑，它載入的所有內容都來自載入路徑，而不是相對引入。

預設值

false

`Optional` silenceDeprecations

silenceDeprecations?: DeprecationOrId[]

一組要忽略的已棄用警告類型。

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

⚠️ 注意！

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

相容性

dart: "1.78.0", node: false

`Optional` verbose

verbose?: boolean

Dart Sass: 自 1.35.0 起
Node Sass: ✗

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

預設值

false

來源對應圖 (Source Maps)

`Optional` 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

`Optional` 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)

輸入

選用 includePaths

輸出

選用 charset

選用 indentType

預設值

選用 indentWidth

預設值

選用 linefeed

預設值

選用 outputStyle

範例

外掛程式

選用 functions

⚠️ 注意！

範例

類型宣告

[key: string]: LegacyFunction<sync>

選用 importer

範例

選用 pkgImporter

範例

訊息

選用 fatalDeprecations

相容性

選用 futureDeprecations

相容性

選用 logger

選用 quietDeps

⚠️ 注意！

預設值

Optional silenceDeprecations

⚠️ 注意！

相容性

Optional verbose

預設值

來源對應圖 (Source Maps)

Optional omitSourceMapUrl

預設值

Optional outFile

⚠️ 注意！

選用 sourceMap

範例

預設值

選用 sourceMapContents

範例

預設值

選用 sourceMapEmbed

範例

預設值

選用 sourceMapRoot

`選用` includePaths

`選用` charset

`選用` indentType

`選用` indentWidth

`選用` linefeed

`選用` outputStyle

`選用` functions

`選用` importer

`選用` pkgImporter

`選用` fatalDeprecations

`選用` futureDeprecations

`選用` logger

`選用` quietDeps

`Optional` silenceDeprecations

`Optional` verbose

`Optional` omitSourceMapUrl

`Optional` outFile

`選用` sourceMap

`選用` sourceMapContents

`選用` sourceMapEmbed

`選用` sourceMapRoot