View on GitHub

Sass

執行我們的 Sass 源文件來運用 variables、maps、mixin 以及 functions，幫助您更快地建構和自定義您的項目。

六角學院的 Bootstrap 5 課程上線囉，立即與萬人一同學習最專業、最深入的 Bootstrap 5 課程。

On this page

執行我們的 Sass 原始檔案來使用 variables、maps、mixin 等。

檔案結構

盡可能避免修改 Bootstrap 的核心文件。對於 Sass，這代表在 Bootstrap 導入您自己創建的樣式表，以便您可以修改或擴展他。假設您正在使用像 npm 的管理程序，您將會擁有一個如下所示的檔案結構：

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

若您下載了我們的源文件且未使用管理程序，您將需要手動設置類似於該結構的內容，以保持 Bootstrap 的源文件與您的源文件分開。

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

匯入

在您的 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
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 4. Include any optional Bootstrap CSS 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";

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

// 6. Add additional custom code here

完成該設置後，您可以開始在您的 custom.scss 中修改任何 Sass 變數與 maps。您也可以根據需求，在 // Optional 下新增 Bootstrap 的各個部分。我們建議在一開始便使用 bootstrap.scss 文件完整載入。

預設變數

Bootstrap 的每個 Sass 變數都包含 !default 標誌，讓您可以在自己的 Sass 中覆蓋變數的預設值，而無需更動 Bootstrap 的原始碼。複製需要的變數並貼上，修改其數值，並刪除 !default 標誌。若已經分配好了變數，則他將不會被 Bootstrap 的預設值再度分配。

您可以在 scss/_variables.scss 中找到 Bootstrap 變數的完整列表。有些變數設置為 null ，除非在配置中被覆蓋，否則這些變數不會輸出其屬性。

同一 Sass 文件中的變數可以在預設變數之前或之後覆蓋。但是，當覆蓋橫跨 Sass 文件時，您必須在導入 Bootstrap 的 Sass 文件之前進行覆蓋。

以下是一個透過 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/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 快速入門開始使用 Bootstap！ 前往 twbs/bootstrap-npm-starter 樣板儲存庫了解你如何在自己的 npm 專案中建構與自訂 Bootstrap。裡面包含了 Sass 編譯器、Autoprefixer、Stylelint、PurgeCSS 和 Bootstrap 圖示。

Maps 與 loops

Bootstrap 包括幾個 Sass maps，關鍵值使生成相關系列 CSS 更加容易。我們將 Sass maps 用於我們的色彩、網格斷點等。就像 Sass 變數一樣，全部的 Sass map 包含 !default 標誌且都可以被覆蓋與擴展。

預設情況下，我們的一些 Sass maps 會合併為空集合。這樣做是為了輕鬆擴展已給定的 Sass map，但這樣做的代價是使從 map 上刪除項目變得更加困難。

修改 map

$theme-colors map 中的所有變數都定義為獨立變數。若要修改我們 $theme-colors map 中的現有顏色，請將以下內容添加到自定義 Sass 文件中：

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

接下來，這些變數被設置在 Bootstrap 的 $theme-colors map 中：

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

添加至 map

透過使用自定義數值創建新的 Sass map 且將其與原始 map 合併，來添加色彩至 $theme-colors 或任何其他地圖中。在這種情況下，我們將創建一個新的 $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 中刪除

要從 $theme-colors 或任何其他 map 中刪除顏色，請使用 map-remove。請注意，您必須將其插入我們的請求和選項之間：

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

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

// 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 maps 外，主題色彩也能作為獨立變數，例如 $primary。

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

您可以使用 Bootstrap 的 tint-color() 與 shade-color() 函數來加亮或加深顏色。這些函數將色彩與黑色或白色混合，與 Sass 本身的 lighten() 和 darken() 不同，後者為以固定量更改亮度，而這通常不會產生所需要的效果。

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

In practice, you’d call the function and pass in the color and weight parameters.

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

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

Color 對比

為了滿足 WCAG 2.0 色彩對比度的輔助功能，作者必須提供至少 4.5:1 的對比度，且少有例外。

我們在 Bootstrap 中包含的額外功能是色彩對比函數 color-contrast。它利用 WCAG 2.0 algorithm 根據 sRGB 色彩空間中的相對亮度去計算對比度，以指定的基礎色自動回到亮色、暗色或黑色的對比色。此函數對生成多個類別的 mixins 或 loops 特別有幫助。

例如，從我們的 $theme-colors map 中生成色版：

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

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

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

您也可以使用我們的 color map functions 來指定基本顏色：

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

Escape SVG

我們使用 escape-svg 函數來對 SVG 背景圖片的 <、> 與 # 字符進行轉義。使用 escape-svg 函數時，數據 URIs 必須保持不變。

增減 functions

我們使用 add 與 subtract 函數來包裝 CSS calc 函數。這些函數的主要目的是避免當“無單位” 0 數值傳遞給表達式 calc 時產生錯誤。儘管在數學上是正確的，但像 calc(10px - 0) 之類的表達式將會在所有瀏覽器中返回錯誤。

計算有效的範例：

$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);
}

計算無效的範例：

$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/ 資料夾中有大量的 mixin，它們為 Bootstrap 的部分提供支持，也可以在您自己的專案中使用。

Color schemes

prefers-color-scheme media query 的簡寫 mixin 可用於支持 light、dark 和自定義顏色方案。

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

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

  @include color-scheme(custom-named-scheme) {
    // Insert custom color scheme styles here
  }
}