View on GitHub

Sass

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

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";

// 4. Include any optional Bootstrap components as you like
@import "../node_modules/bootstrap/scss/root";
@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";

// 5. 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";

// Bootstrap and its default variables

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

對 Bootstrap 中的任何變數進行必要的重複，包含以下的全域選項。

Get started with Bootstrap via npm with our starter project! Head to the twbs/bootstrap-npm-starter template repository to see how to build and customize Bootstrap in your own npm project. Includes Sass compiler, Autoprefixer, Stylelint, PurgeCSS, and Bootstrap Icons.

Maps and 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";

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

// Optional
@import "../node_modules/bootstrap/scss/root";
@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

Our scss/mixins/ directory has a ton of mixins that power parts of Bootstrap and can also be used across your own project.

Color schemes

A shorthand mixin for the prefers-color-scheme media query is available with support for light, dark, and custom color schemes.

@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
  }
}