`@use`

Dart Sass: 自 1.23.0 版本起
LibSass: ✗
Ruby Sass: ✗

目前只有 Dart Sass 支援 `@use`。其他實作的使用者必須使用 `@import` 規則。

`@use` 規則會從其他 Sass 樣式表載入 mixin、函式和變數，並將多個樣式表的 CSS 組合在一起。由 `@use` 載入的樣式表稱為「模組」。Sass 也提供內建模組，其中包含許多實用函式。

最簡單的 `@use` 規則寫成 `@use "";`，它會載入指定 URL 的模組。以這種方式載入的任何樣式，無論載入多少次，在編譯後的 CSS 輸出中都只會包含一次。

⚠️ 注意！

樣式表的 `@use` 規則必須在任何其他規則（`@forward` 除外）之前，包括樣式規則。但是，您可以在 `@use` 規則之前宣告變數，以便在設定模組時使用。

  SCSS

  Sass

  CSS
SCSS 語法// foundation/_code.scss
code {
  padding: .25em;
  line-height: 0;
}
// foundation/_lists.scss
ul, ol {
  text-align: left;

  & & {
    padding: {
      bottom: 0;
      left: 0;
    }
  }
}
// style.scss
@use 'foundation/code';
@use 'foundation/lists';
Sass 語法// foundation/_code.sass
code
  padding: .25em
  line-height: 0

// foundation/_lists.sass
ul, ol
  text-align: left

  & &
    padding:
      bottom: 0
      left: 0



// style.sass
@use 'foundation/code'
@use 'foundation/lists'
CSS 輸出code {
  padding: .25em;
  line-height: 0;
}

ul, ol {
  text-align: left;
}
ul ul, ol ol {
  padding-bottom: 0;
  padding-left: 0;
}

載入成員載入成員永久連結

您可以透過撰寫 <命名空間>.<變數>、<命名空間>.<函式>() 或 @include <命名空間>.<mixin>() 來存取來自另一個模組的變數、函式和 mixin。預設情況下，命名空間只是模組網址的最後一個組成部分。

使用 @use 載入的成員（變數、函式和 mixin）僅在載入它們的樣式表中可見。其他樣式表如果也想存取它們，則需要撰寫自己的 @use 規則。這有助於輕鬆地找出每個成員的確切來源。如果您想一次從多個檔案載入成員，可以使用 @forward 規則從一個共用檔案轉發它們。

💡 小知識

由於 @use 會將命名空間添加到成員名稱中，因此在撰寫樣式表時，可以安全地選擇非常簡單的名稱，例如 $radius 或 $width。這與舊的 @import 規則不同，舊規則鼓勵使用者撰寫長名稱，例如 $mat-corner-radius，以避免與其他函式庫衝突，這有助於保持樣式表的清晰易讀！

  SCSS

  Sass

  CSS
SCSS 語法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners";

.button {
  @include corners.rounded;
  padding: 5px + corners.$radius;
}
Sass 語法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners"

.button
  @include corners.rounded
  padding: 5px + corners.$radius

CSS 輸出.button {
  border-radius: 3px;
  padding: 8px;
}

選擇命名空間選擇命名空間永久連結

預設情況下，模組的命名空間只是其網址的最後一個組成部分，不包含檔案副檔名。但是，有時您可能想要選擇不同的命名空間 — 您可能想要為經常引用的模組使用較短的名稱，或者您可能正在載入具有相同檔案名的多個模組。您可以透過撰寫 @use "<url>" as <命名空間> 來執行此操作。

  SCSS

  Sass

  CSS
SCSS 語法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners" as c;

.button {
  @include c.rounded;
  padding: 5px + c.$radius;
}
Sass 語法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners" as c

.button
  @include c.rounded
  padding: 5px + c.$radius

CSS 輸出.button {
  border-radius: 3px;
  padding: 8px;
}

您甚至可以透過撰寫 @use "<url>" as * 來載入 *沒有* 命名空間的模組。不過，我們建議您僅對自己撰寫的樣式表執行此操作；否則，它們可能會引入新的成員，從而導致名稱衝突！

  SCSS

  Sass

  CSS
SCSS 語法// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}
// style.scss
@use "src/corners" as *;

.button {
  @include rounded;
  padding: 5px + $radius;
}
Sass 語法// src/_corners.sass
$radius: 3px

@mixin rounded
  border-radius: $radius

// style.sass
@use "src/corners" as *

.button
  @include rounded
  padding: 5px + $radius

CSS 輸出.button {
  border-radius: 3px;
  padding: 8px;
}

私有成員私有成員永久連結

作為樣式表作者，您可能不希望所有定義的成員都在樣式表外部可用。Sass 可以輕鬆地定義私有成員，只需在其名稱前面加上 - 或 _ 即可。這些成員在定義它們的樣式表中將與普通成員一樣工作，但它們不會成為模組公開 API 的一部分。這表示載入您的模組的樣式表無法看到它們！

💡 小知識

如果您想讓成員對整個 *套件* 而不是單個模組私有，只需不要從套件的任何進入點（您告知使用者載入以使用套件的樣式表）轉發其模組即可。您甚至可以在轉發其模組其餘部分時隱藏該成員！

  SCSS

  Sass
SCSS 語法// src/_corners.scss
$-radius: 3px;

@mixin rounded {
  border-radius: $-radius;
}
// style.scss
@use "src/corners";

.button {
  @include corners.rounded;

  // This is an error! $-radius isn't visible outside of `_corners.scss`.
  padding: 5px + corners.$-radius;
}
Sass 語法// src/_corners.sass
$-radius: 3px

@mixin rounded
  border-radius: $-radius

// style.sass
@use "src/corners"

.button
  @include corners.rounded

  // This is an error! $-radius isn't visible outside of `_corners.scss`.
  padding: 5px + corners.$-radius

設定設定永久連結

樣式表可以使用 !default 旗標定義變數，使其可設定。要載入具有設定的模組，請撰寫 @use <url> with (<變數>: <值>, <變數>: <值>)。設定的值將會覆寫變數的預設值。

  SCSS

  Sass

  CSS
SCSS 語法// _library.scss
$black: #000 !default;
$border-radius: 0.25rem !default;
$box-shadow: 0 0.5rem 1rem rgba($black, 0.15) !default;

code {
  border-radius: $border-radius;
  box-shadow: $box-shadow;
}
// style.scss
@use 'library' with (
  $black: #222,
  $border-radius: 0.1rem
);
Sass 語法// _library.sass
$black: #000 !default
$border-radius: 0.25rem !default
$box-shadow: 0 0.5rem 1rem rgba($black, 0.15) !default

code
  border-radius: $border-radius
  box-shadow: $box-shadow

// style.sass
@use 'library' with ($black: #222, $border-radius: 0.1rem)



CSS 輸出code {
  border-radius: 0.1rem;
  box-shadow: 0 0.5rem 1rem rgba(34, 34, 34, 0.15);
}

搭配 Mixins 使用搭配 Mixins 使用永久連結

使用 @use ... with 設定模組非常方便，尤其是在使用原本設計為搭配 @import 規則的函式庫時。但它並不是特別靈活，我們不建議將其用於更進階的用例。如果您發現自己想要一次設定許多變數、將映射 (map) 作為設定傳遞，或是在載入模組後更新設定，請考慮撰寫一個 mixin 來設定您的變數，以及另一個 mixin 來注入您的樣式。

  SCSS

  Sass

  CSS
SCSS 語法// _library.scss
$-black: #000;
$-border-radius: 0.25rem;
$-box-shadow: null;

/// If the user has configured `$-box-shadow`, returns their configured value.
/// Otherwise returns a value derived from `$-black`.
@function -box-shadow() {
  @return $-box-shadow or (0 0.5rem 1rem rgba($-black, 0.15));
}

@mixin configure($black: null, $border-radius: null, $box-shadow: null) {
  @if $black {
    $-black: $black !global;
  }
  @if $border-radius {
    $-border-radius: $border-radius !global;
  }
  @if $box-shadow {
    $-box-shadow: $box-shadow !global;
  }
}

@mixin styles {
  code {
    border-radius: $-border-radius;
    box-shadow: -box-shadow();
  }
}
// style.scss
@use 'library';

@include library.configure(
  $black: #222,
  $border-radius: 0.1rem
);

@include library.styles;
Sass 語法// _library.sass
$-black: #000
$-border-radius: 0.25rem
$-box-shadow: null

/// If the user has configured `$-box-shadow`, returns their configured value.
/// Otherwise returns a value derived from `$-black`.
@function -box-shadow()
  @return $-box-shadow or (0 0.5rem 1rem rgba($-black, 0.15))


@mixin configure($black: null, $border-radius: null, $box-shadow: null)
  @if $black
    $-black: $black !global
  @if $border-radius
    $-border-radius: $border-radius !global
  @if $box-shadow
    $-box-shadow: $box-shadow !global


@mixin styles
  code
    border-radius: $-border-radius
    box-shadow: -box-shadow()





// style.sass
@use 'library'
@include library.configure($black: #222, $border-radius: 0.1rem)
@include library.styles





CSS 輸出code {
  border-radius: 0.1rem;
  box-shadow: 0 0.5rem 1rem rgba(34, 34, 34, 0.15);
}

重新指定變數重新指定變數永久連結

載入模組後，您可以重新指定它的變數。

  SCSS

  Sass
SCSS 語法// _library.scss
$color: red;
// _override.scss
@use 'library';
library.$color: blue;
// style.scss
@use 'library';
@use 'override';
@debug library.$color;  //=> blue
Sass 語法// _library.sass
$color: red
// _override.sass
@use 'library'
library.$color: blue
// style.sass
@use 'library'
@use 'override'
@debug library.$color  //=> blue

即使您使用 as * 匯入沒有命名空間的模組，這也適用。指定該模組中定義的變數名稱將會覆寫該模組中的值。

⚠️ 注意！

內建模組變數（例如 math.$pi）無法重新指定。

尋找模組尋找模組永久連結

為每個載入的樣式表都寫出絕對網址並不好玩，因此 Sass 的模組尋找演算法讓這件事變得更容易一些。首先，您不必明確寫出要載入的檔案的副檔名；@use "variables" 會自動載入 variables.scss、variables.sass 或 variables.css。

⚠️ 注意！

為了確保樣式表在每個作業系統上都能運作，Sass 是透過 *URL* 而不是 *檔案路徑* 載入檔案。這表示即使在 Windows 上，您也需要使用正斜線而不是反斜線。

這也表示網址區分大小寫，因此即使您使用不區分大小寫的檔案系統，Sass 也會將 Styles.scss 和 styles.scss 視為不同的模組。請確保您的網址與磁碟上檔案的實際大小寫相符，否則您的樣式表可能會載入兩次，而且肯定無法在其他作業系統上運作。

載入路徑載入路徑永久連結

所有 Sass 實作都允許使用者提供 *載入路徑*：Sass 在尋找模組時會搜尋的檔案系統路徑。例如，如果您將 node_modules/susy/sass 作為載入路徑傳遞，則可以使用 @use "susy" 載入 node_modules/susy/sass/susy.scss（儘管 pkg: 網址是處理這個問題的更好方法）。

不過，模組總是會先相對於目前檔案載入。只有在沒有符合模組 URL 的相對檔案存在時，才會使用載入路徑。這可確保在新增函式庫時，您不會意外弄亂相對匯入。

💡 小知識

與其他一些語言不同，Sass 並不要求您使用 ./ 進行相對匯入。相對匯入始終可用。

局部檔案局部檔案永久連結

按照慣例，僅用於作為模組載入而非自行編譯的 Sass 檔案以 _ 開頭（例如 _code.scss）。這些稱為 *局部檔案*，它們會告知 Sass 工具不要自行編譯這些檔案。匯入局部檔案時，您可以省略 _。

索引檔案索引檔案永久連結

如果您在資料夾中撰寫 _index.scss 或 _index.sass，則在您載入資料夾本身的 URL 時，索引檔案將會自動載入。

  SCSS

  Sass

  CSS
SCSS 語法// foundation/_code.scss
code {
  padding: .25em;
  line-height: 0;
}
// foundation/_lists.scss
ul, ol {
  text-align: left;

  & & {
    padding: {
      bottom: 0;
      left: 0;
    }
  }
}
// foundation/_index.scss
@use 'code';
@use 'lists';
// style.scss
@use 'foundation';
Sass 語法// foundation/_code.sass
code
  padding: .25em
  line-height: 0

// foundation/_lists.sass
ul, ol
  text-align: left

  & &
    padding:
      bottom: 0
      left: 0



// foundation/_index.sass
@use 'code'
@use 'lists'
// style.sass
@use 'foundation'
CSS 輸出code {
  padding: .25em;
  line-height: 0;
}

ul, ol {
  text-align: left;
}
ul ul, ol ol {
  padding-bottom: 0;
  padding-left: 0;
}

`pkg:` 網址pkg: 網址永久連結

Sass 使用 pkg: URL 架構來載入由各種套件管理器分發的樣式表。由於 Sass 在許多不同程式語言環境中使用，而這些程式語言具有不同的套件管理慣例，因此 pkg: URL 幾乎沒有固定的意義。相反地，我們鼓勵使用者實作自訂匯入器（使用 JS API 或嵌入式 Sass 協定），以使用原生套件管理器的邏輯來解析這些 URL。

這使得 pkg: URL 和使用它們的樣式表可以在不同的語言生態系統之間移植。無論您是透過 npm（Sass 為其提供內建的 pkg: 匯入器）還是您能找到的最冷門的套件管理器安裝 Sass 函式庫，只要您撰寫 @use 'pkg:library'，它就會正常運作。

💡 小知識

pkg: URL 不僅適用於 @use。您可以在任何可以載入 Sass 檔案的地方使用它們，包括 @forward、meta.load-css()，甚至舊的 @import 規則。

`pkg:` 匯入器的規則`pkg:` 匯入器的規則永久連結

Sass 期望所有 pkg: 匯入器都遵循一些通用規則。這些規則有助於確保所有套件管理器都能一致地處理 pkg: URL，從而使樣式表盡可能地具有可攜性。

除了自訂匯入器的標準規則之外，pkg: 匯入器必須僅處理符合下列條件的非標準 URL：

架構為 pkg，且
其路徑以套件名稱開頭，且
後面可以選擇性地加上路徑，路徑區段以正斜線分隔。

套件名稱可能包含正斜線，取決於特定的套件管理器是否支援。例如，npm 允許使用 @namespace/name 之類的套件名稱。請注意，包含非英數字元的套件名稱在不同套件管理器之間的可攜性可能會降低。

pkg: 匯入器必須拒絕以下模式：

路徑以 / 開頭的 URL。
具有非空/null 使用者名稱、密碼、主機、埠、查詢或片段的 URL。

如果 pkg: 匯入器遇到違反其自身套件管理器慣例但*不*違反上述規則的 URL，它應該拒絕載入該 URL，而不是拋出錯誤。這允許使用者在必要時同時使用多個 pkg: 匯入器。

Node.js 套件匯入器Node.js 套件匯入器永久連結

Dart Sass: 自 1.71.0 版本起
LibSass: ✗
Ruby Sass: ✗

由於 Sass 最常與 Node.js 生態系統一起使用，因此它附帶了一個使用與 Node.js 相同的演算法來載入 Sass 樣式表的 pkg: 匯入器。這並非預設啟用，但很容易開啟：

如果您使用的是 JavaScript API，只需將 new NodePackageImporter() 加入 importers 選項即可。
如果您使用的是 Dart API，請將 NodePackageImporter() 加入 importers 選項。
如果您使用的是命令列，請傳遞 --pkg-importer=node。

如果您載入 pkg: URL，Node.js 的 pkg: 導入器會查看其 package.json 檔案以決定要載入哪個 Sass 檔案。它會依序檢查：

"exports" 欄位，條件為 "sass"、"style" 和 "default"。這是套件公開 Sass 進入點的建議方法。
"sass" 欄位或 "style" 欄位，其值應為 Sass 檔案的路徑。這僅在 pkg: URL 沒有子路徑時有效——pkg:library 會載入 "sass" 欄位中列出的檔案，但 pkg:library/button 會從套件的根目錄載入 button.scss。
套件根目錄的索引檔案。這也僅在 pkg: URL 沒有子路徑時有效。

Node.js 的 pkg: 導入器支援所有 "exports" 功能，因此您也可以為不同的子路徑指定不同的位置（請注意，鍵值必須包含檔案的副檔名）。

{
  "exports": {
    ".": {
      "sass": "styles/index.scss",
    },
    "./button.scss": {
      "sass": "styles/button.scss",
    },
    "./accordion.scss": {
      "sass": "styles/accordion.scss",
    }
  }
}

…甚至可以使用模式。

{
  "exports": {
    ".": {
      "sass": "styles/index.scss",
    },
    "./*.scss": {
      "sass": "styles/*.scss",
    },
  }
}

載入 CSS載入 CSS 的永久連結

除了載入 .sass 和 .scss 檔案之外，Sass 也可以載入普通的 .css 檔案。

  SCSS

  Sass

  CSS
SCSS 語法// code.css
code {
  padding: .25em;
  line-height: 0;
}
// style.scss
@use 'code';
Sass 語法// code.css
code {
  padding: .25em;
  line-height: 0;
}
// style.sass
@use 'code'
CSS 輸出code {
  padding: .25em;
  line-height: 0;
}

作為模組載入的 CSS 檔案不允許任何特殊的 Sass 功能，因此無法公開任何 Sass 變數、函式或 mixin。為了確保作者不會在他們的 CSS 中意外地寫入 Sass，所有不是有效 CSS 的 Sass 功能都會產生錯誤。否則，CSS 將會按原樣呈現。它甚至可以被繼承！

與 `@import` 的差異與 @import 的差異的永久連結

@use 規則旨在取代舊的 @import 規則，但它在設計上特意與之不同。以下是兩者之間的一些主要差異：

@use 只會讓變數、函式和 mixin 在目前檔案的範圍內可用。它永遠不會將它們添加到全域範圍。這使得您可以輕鬆地找出 Sass 檔案中每個名稱的來源，並且您可以使用較短的名稱而無需擔心衝突。
@use 只會載入每個檔案一次。這可確保您不會意外地多次重複相依項的 CSS。
@use 必須出現在檔案的開頭，且不能嵌套在樣式規則中。
每個 @use 規則只能有一個 URL。
@use 的 URL 需要用引號括起來，即使使用縮排語法也是如此。

`@use`

⚠️ 注意！

SCSS 語法

Sass 語法

CSS 輸出

載入成員載入成員 永久連結

💡 小知識

SCSS 語法

Sass 語法

CSS 輸出

選擇命名空間選擇命名空間 永久連結

SCSS 語法

Sass 語法

CSS 輸出

SCSS 語法

Sass 語法

CSS 輸出

私有成員私有成員 永久連結

💡 小知識

SCSS 語法

Sass 語法

設定設定 永久連結

SCSS 語法

Sass 語法

CSS 輸出

搭配 Mixins 使用搭配 Mixins 使用 永久連結

SCSS 語法

Sass 語法

CSS 輸出

重新指定變數重新指定變數永久連結

SCSS 語法

Sass 語法

⚠️ 注意！

尋找模組尋找模組永久連結

⚠️ 注意！

載入路徑載入路徑永久連結

💡 小知識

局部檔案局部檔案永久連結

索引檔案索引檔案永久連結

SCSS 語法

Sass 語法

CSS 輸出

pkg: 網址pkg: 網址永久連結

💡 小知識

pkg: 匯入器的規則pkg: 匯入器的規則 永久連結

Node.js 套件匯入器Node.js 套件匯入器 永久連結

載入 CSS載入 CSS 的永久連結

SCSS 語法

Sass 語法

CSS 輸出

與 @import 的差異與 @import 的差異的永久連結

載入成員載入成員永久連結

選擇命名空間選擇命名空間永久連結

私有成員私有成員永久連結

設定設定永久連結

搭配 Mixins 使用搭配 Mixins 使用永久連結

`pkg:` 網址pkg: 網址永久連結

`pkg:` 匯入器的規則`pkg:` 匯入器的規則永久連結

Node.js 套件匯入器Node.js 套件匯入器永久連結

與 `@import` 的差異與 @import 的差異的永久連結