跳至主要內容 跳至文件導覽
View on GitHub

Sass

使用我們的原始 Sass 檔案來善用變數、maps、mixins 和函式，幫助您更快速地建構並自訂您的專案。

本頁內容

使用我們的原始 Sass 檔案來善用變數、maps、mixins 等功能。

使用最新版本的 Dart Sass 編譯原始 Sass 檔案時，會顯示 Sass 棄用警告。這不會阻止編譯或使用 Bootstrap。我們正在研究長期解決方案，但目前可以忽略這些棄用通知。

檔案結構（File structure）

盡可能避免修改 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

引入（Importing）

在您的 custom.scss 中，您將引入 Bootstrap 的原始 Sass 檔案。您有兩個選項：引入全部 Bootstrap，或選擇您需要的部分。我們建議後者，但請注意我們的元件之間有一些必要條件和相依性。您還需要為我們的外掛引入一些 JavaScript。

// Custom.scss
// 選項 A：引入全部 Bootstrap

// 在此處引入任何預設變數覆寫（但函式將不可用）

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

// 然後在此處添加額外的自訂程式碼

// Custom.scss
// 選項 B：引入部分 Bootstrap

// 1. 首先引入函式（這樣您可以操作顏色、SVG、calc 等）
@import "../node_modules/bootstrap/scss/functions";

// 2. 在此處引入任何預設變數覆寫

// 3. 引入其餘必要的 Bootstrap 樣式表（包括任何獨立的色彩模式樣式表）
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. 在此處引入任何預設 map 覆寫

// 5. 引入其餘必要部分
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. 根據需要引入其他可選的樣式表部分；以下列表並非包含所有可用的樣式表
@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. 可選地最後引入 utilities API，以根據 `_utilities.scss` 中的 Sass map 產生類別
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. 在此處添加額外的自訂程式碼

完成此設定後，您可以開始在 custom.scss 中修改任何 Sass 變數和 maps。您還可以根據需要在 // Optional 區段下開始添加 Bootstrap 的部分。我們建議使用 bootstrap.scss 檔案中的完整引入堆疊作為起點。

編譯（Compiling）

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

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

# 全域安裝 Sass
npm install -g sass

# 監控您的自訂 Sass 變更並編譯為 CSS
sass --watch ./scss/custom.scss ./css/custom.css

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

使用 Bootstrap 搭配其他建構工具？ 請考慮閱讀我們關於 Webpack、Parcel 或 Vite 編譯的指南。我們也在 GitHub 上的範例儲存庫中提供了可用於生產環境的示範。

引入（Including）

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>

變數預設值（Variable defaults）

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 Icons。

Maps 與迴圈（Maps and loops）

Bootstrap 包含一些 Sass maps，即鍵值對，可以更輕鬆地產生相關 CSS 的系列。我們將 Sass maps 用於顏色、格線中斷點等。就像 Sass 變數一樣，所有 Sass maps 都包含 !default 標記，可以被覆寫和擴充。

我們的一些 Sass maps 預設會合併到空的 maps 中。這樣做是為了方便擴充給定的 Sass map，但代價是從 map 中「移除」項目稍微困難一些。

修改 map（Modify map）

$theme-colors map 中的所有變數都定義為獨立變數。要修改 $theme-colors map 中的現有顏色，請在自訂 Sass 檔案中添加以下內容：

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

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

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

新增至 map（Add to map）

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

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

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

從 map 移除（Remove from map）

要從 $theme-colors 或任何其他 map 移除顏色，請使用 map-remove。請注意，您必須在 variables 中定義 $theme-colors 之後、在 maps 中使用之前插入它：

// 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

必要鍵值（Required keys）

Bootstrap 假設 Sass maps 中存在某些特定鍵值，因為我們自己使用和擴充這些。當您自訂包含的 maps 時，可能會遇到使用特定 Sass map 鍵值的錯誤。

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

函式（Functions）

顏色（Colors）

除了我們擁有的 Sass maps 外，主題顏色也可以作為獨立變數使用，如 $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%);
}

色彩對比（Color contrast）

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

為了幫助實現這一點，我們在 Bootstrap 中包含了 color-contrast 函式。它使用 WCAG 對比度演算法根據 sRGB 色彩空間中的相對亮度計算對比度閾值，以根據指定的基礎色彩自動回傳淺色 (#fff)、深色 (#212529) 或黑色 (#000) 對比色。這個函式對於 mixins 或迴圈特別有用，在這些情況下您需要產生多個類別。

例如，從我們的 $theme-colors map 產生色塊：

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

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

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

您還可以使用我們的色彩 map 函式指定基礎色彩：

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

跳脫 SVG（Escape SVG）

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

加法和減法函式（Add and Subtract functions）

我們使用 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);
}

Mixins

我們的 scss/mixins/ 目錄有大量的 mixins，它們為 Bootstrap 的各個部分提供動力，也可以在您自己的專案中使用。

色彩配置（Color schemes）

提供了 prefers-color-scheme 媒體查詢的簡寫 mixin，支援 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
  }
}