Sass

使用我們的 Sass 原始檔案，利用變數、對應、混合和函式，協助您更快建置並自訂專案。

在此頁面上

使用我們的 Sass 原始檔案，利用變數、對應、混合等更多功能。

檔案結構

在可能的情況下，避免修改 Bootstrap 的核心檔案。對於 Sass，這表示建立自己的樣式表，匯入 Bootstrap，以便修改並延伸它。假設您使用的是 npm 等套件管理員，您的檔案結構會如下所示

your-project/
├── scss/
│   └── custom.scss
└── node_modules/
│   └── bootstrap/
│       ├── js/
│       └── scss/
└── index.html

如果您已下載我們的原始檔案，且未使用套件管理員，您會想要手動建立一個類似於此結構的檔案，讓 Bootstrap 的原始檔案與您自己的檔案分開。

your-project/
├── scss/
│   └── custom.scss
├── bootstrap/
│   ├── js/
│   └── scss/
└── index.html

匯入

在您的 custom.scss 中，您將匯入 Bootstrap 的原始 Sass 檔案。您有兩種選擇：包含所有 Bootstrap，或選擇您需要的部分。我們鼓勵後者，但請注意我們的元件之間有一些需求和依賴關係。您還需要為我們的外掛程式包含一些 JavaScript。

// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won't be available)

@import "../node_modules/bootstrap/scss/bootstrap";

// Then add additional custom code here

// Custom.scss
// Option B: Include parts of Bootstrap

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../node_modules/bootstrap/scss/functions";

// 2. Include any default variable overrides here

// 3. Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. Include any default map overrides here

// 5. Include remainder of required parts
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Optionally include any other parts as needed
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";

// 7. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Add additional custom code here

有了這個設定，您就可以開始修改 custom.scss 中的任何 Sass 變數和對應。您也可以開始在 // Optional 區段下根據需要新增 Bootstrap 的部分。我們建議使用我們的 bootstrap.scss 檔案中的完整匯入堆疊作為您的起點。

編譯

為了在瀏覽器中將您的自訂 Sass 程式碼用作 CSS，您需要一個 Sass 編譯器。Sass 作為 CLI 套件提供，但您也可以使用其他建置工具（例如 Gulp 或 Webpack）或 GUI 應用程式來編譯它。有些 IDE 也內建 Sass 編譯器或作為可下載的擴充功能。

我們喜歡使用 CLI 來編譯我們的 Sass，但您可以使用您偏好的任何方法。從命令列執行下列動作

# Install Sass globally
npm install -g sass

# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css

在 sass-lang.com/install 和使用 VS Code 編譯中瞭解更多關於您的選項。

使用 Bootstrap 與其他建置工具？考慮閱讀我們的指南，了解如何使用 Webpack、Parcel 或 Vite 編譯。我們在 GitHub 上的範例儲存庫中也有可供生產使用的示範。

包含

編譯您的 CSS 後，您可以在 HTML 檔案中包含它。在您的 index.html 中，您需要包含已編譯的 CSS 檔案。如果您已變更編譯的 CSS 檔案，請務必更新路徑。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Custom Bootstrap</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

變數預設值

Bootstrap 中的每個 Sass 變數都包含 !default 標記，讓您可以在自己的 Sass 中覆寫變數的預設值，而無需修改 Bootstrap 的原始碼。視需要複製並貼上變數，修改其值，並移除 !default 標記。如果變數已指派，則 Bootstrap 中的預設值不會重新指派。

您可以在 scss/_variables.scss 中找到 Bootstrap 變數的完整清單。有些變數設為 null，這些變數不會輸出屬性，除非在您的組態中覆寫。

變數覆寫必須在匯入我們的函式後，但在其他匯入之前進行。

以下是一個範例，透過 npm 匯入並編譯 Bootstrap 時，變更 <body> 的 background-color 和 color

// Required
@import "../node_modules/bootstrap/scss/functions";

// Default variable overrides
$body-bg: #000;
$body-color: #111;

// Required
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

視需要重複執行此步驟，以修改 Bootstrap 中的任何變數，包括以下的全球選項。

使用我們的入門專案透過 npm 開始使用 Bootstrap！前往 Sass & JS 範例範本存放庫，了解如何在自己的 npm 專案中建置並自訂 Bootstrap。包含 Sass 編譯器、Autoprefixer、Stylelint、PurgeCSS 和 Bootstrap 圖示。

對應和迴圈

Bootstrap 包含少數 Sass 對應，也就是鍵值配對，可讓您更輕鬆地產生相關 CSS 家族。我們使用 Sass 對應來處理我們的顏色、格線斷點等。就像 Sass 變數一樣，所有 Sass 對應都包含 !default 標記，而且可以覆寫和延伸。

預設情況下，我們的某些 Sass 地圖會合併到空的 Sass 地圖中。這樣做是為了讓指定的 Sass 地圖容易擴充，但代價是讓從地圖中移除項目變得稍微困難一些。

修改地圖

$theme-colors 地圖中的所有變數都定義為獨立變數。若要修改 $theme-colors 地圖中的現有顏色，請將下列內容新增到您的自訂 Sass 檔案中

$primary: #0074d9;
$danger: #ff4136;

稍後，這些變數會設定在 Bootstrap 的 $theme-colors 地圖中

$theme-colors: (
  "primary": $primary,
  "danger": $danger
);

新增到地圖

透過建立一個包含自訂值的新 Sass 地圖，並將其與原始地圖合併，來將新顏色新增到 $theme-colors 或任何其他地圖中。在此情況下，我們將建立一個新的 $custom-colors 地圖，並將其與 $theme-colors 合併。

// Create your own map
$custom-colors: (
  "custom-color": #900
);

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

從地圖中移除

若要從 $theme-colors 或任何其他地圖中移除顏色，請使用 map-remove。請注意，您必須在 variables 中定義 $theme-colors 之後，並在 maps 中使用之前，將 $theme-colors 插入到我們的需求之間

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Optional
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

必要的鍵

由於我們使用並自行延伸 Sass 地圖，因此 Bootstrap 假設 Sass 地圖中存在某些特定鍵。當您自訂包含的地圖時，您可能會遇到特定 Sass 地圖的鍵正在使用的錯誤。

例如，我們使用 $theme-colors 中的 primary、success 和 danger 鍵值來設定連結、按鈕和表單狀態。替換這些鍵值的數值應該不會造成問題，但移除它們可能會導致 Sass 編譯問題。在這些情況下，您需要修改使用這些數值的 Sass 程式碼。

函數

顏色

除了 Sass 地圖之外，主題顏色也可以當作獨立變數使用，例如 $primary。

.custom-element {
  color: $gray-100;
  background-color: $dark;
}

您可以使用 Bootstrap 的 tint-color() 和 shade-color() 函數來調亮或調暗顏色。這些函數會將顏色與黑色或白色混合，與 Sass 原生的 lighten() 和 darken() 函數不同，後者會以固定的量改變亮度，這通常無法達到預期的效果。

shift-color() 結合了這兩個函數，如果權重為正數，則會調暗顏色；如果權重為負數，則會調亮顏色。

scss/_functions.scss

// Tint a color: mix a color with white
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// Shade a color: mix a color with black
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// Shade the color if the weight is positive, else tint it
@function shift-color($color, $weight) {
  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
}

實際上，您會呼叫函數並傳入顏色和權重參數。

.custom-element {
  color: tint-color($primary, 10%);
}

.custom-element-2 {
  color: shade-color($danger, 30%);
}

.custom-element-3 {
  color: shift-color($success, 40%);
  background-color: shift-color($success, -60%);
}

顏色對比

為了符合網路內容無障礙指引 (WCAG) 的對比度要求，作者必須提供最低 4.5:1 的文字顏色對比度和最低 3:1 的非文字顏色對比度，只有極少數例外情況。

為了協助這件事，我們在 Bootstrap 中納入了 color-contrast 函數。它使用 WCAG 對比率演算法計算對比閾值，根據 sRGB 色彩空間中的相對亮度自動傳回淺色 (#fff)、深色 (#212529) 或黑色 (#000) 對比色，根據指定的基礎色。這個函數對於混合或迴圈特別有用，您可以在其中產生多個類別。

例如，從我們的 $theme-colors 地圖產生色票

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-contrast($value);
  }
}

它也可以用於一次性的對比需求

.custom-element {
  color: color-contrast(#000); // returns `color: #fff`
}

您也可以使用我們的色彩對應函數指定基礎色

.custom-element {
  color: color-contrast($dark); // returns `color: #fff`
}

Escape SVG

我們使用 escape-svg 函數來 escape SVG 背景圖片的 <、> 和 # 字元。使用 escape-svg 函數時，資料 URI 必須加上引號。

加法和減法函數

我們使用 add 和 subtract 函數來包裝 CSS calc 函數。這些函數的主要目的是在將「無單位」0 值傳遞到 calc 運算式時避免錯誤。像 calc(10px - 0) 這樣的運算式在所有瀏覽器中都會傳回錯誤，儘管在數學上是正確的。

calc 有效的範例

$border-radius: .25rem;
$border-width: 1px;

.element {
  // Output calc(.25rem - 1px) is valid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output the same calc(.25rem - 1px) as above
  border-radius: subtract($border-radius, $border-width);
}

calc 無效的範例

$border-radius: .25rem;
$border-width: 0;

.element {
  // Output calc(.25rem - 0) is invalid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output .25rem
  border-radius: subtract($border-radius, $border-width);
}

混合

我們的 scss/mixins/ 目錄有許多混合，可以強化 Bootstrap 的部分，也可以用於您自己的專案。

色彩配置

提供一個簡寫的 mixin，適用於 prefers-color-scheme 媒體查詢，並支援 light 和 dark 色彩配置。請參閱色彩模式文件，以取得有關色彩模式 mixin 的資訊。

scss/mixins/_color-scheme.scss

@mixin color-scheme($name) {
  @media (prefers-color-scheme: #{$name}) {
    @content;
  }
}

.custom-element {
  @include color-scheme(light) {
    // Insert light mode styles here
  }

  @include color-scheme(dark) {
    // Insert dark mode styles here
  }
}