View on GitHub

按鈕 (Buttons)

使用 Bootstrap 自定義的按鈕樣式來進行表單、對話方塊等操作，並支援多種大小、狀態等。

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

On this page

範例

Bootstrap 包括多個預先定義的按鈕樣式，每個都有自己的語義目的及更多的控制。

<button type="button" class="btn btn-primary">Primary</button>
<button type="button" class="btn btn-secondary">Secondary</button>
<button type="button" class="btn btn-success">Success</button>
<button type="button" class="btn btn-danger">Danger</button>
<button type="button" class="btn btn-warning">Warning</button>
<button type="button" class="btn btn-info">Info</button>
<button type="button" class="btn btn-light">Light</button>
<button type="button" class="btn btn-dark">Dark</button>

<button type="button" class="btn btn-link">Link</button>

Conveying meaning to assistive technologies

Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (e.g. the visible text), or is included through alternative means, such as additional text hidden with the .visually-hidden class.

禁止文字換行

可以在按鈕加入 .text-nowrap 來禁止按鈕文字換行，並可以在 Sass 裡設定 $btn-white-space: nowrap 以禁用每一個按鈕的文字換行。

按鈕標籤

.btn 被設計成需要與 <button> 元素一起使用。但是，您也可以在 <a> 或 <input> 元素上使用這些 Class（儘管有些瀏覽器可能會使用稍微不同的渲染）。

當在用於觸發頁面內功能（例如折疊內容），而不是連結到新頁面或當前頁面中某一部分的 <a> 元素上使用按鈕 class 時，這些連結應該被賦予 role="button" 以適當地傳達他們的目的到螢幕閱讀器等網頁親合性技術。

Link

<a class="btn btn-primary" href="#" role="button">Link</a>
<button class="btn btn-primary" type="submit">Button</button>
<input class="btn btn-primary" type="button" value="Input">
<input class="btn btn-primary" type="submit" value="Submit">
<input class="btn btn-primary" type="reset" value="Reset">

Outline 按鈕樣式

需要一個按鈕，但不是使用填滿的背景顏色？用 .btn-outline-* 替換預設修飾用的 Class，以移除任何按鈕上的所有背景色及背景圖。

<button type="button" class="btn btn-outline-primary">Primary</button>
<button type="button" class="btn btn-outline-secondary">Secondary</button>
<button type="button" class="btn btn-outline-success">Success</button>
<button type="button" class="btn btn-outline-danger">Danger</button>
<button type="button" class="btn btn-outline-warning">Warning</button>
<button type="button" class="btn btn-outline-info">Info</button>
<button type="button" class="btn btn-outline-light">Light</button>
<button type="button" class="btn btn-outline-dark">Dark</button>

一些按鈕樣式使用非常淺的前景色，並應該只被用於深色的背景中以形成足夠的對比。

尺寸

想要較大或較小的按鈕？加入 .btn-lg 或 .btn-sm 來套用尺寸。

<button type="button" class="btn btn-primary btn-lg">Large button</button>
<button type="button" class="btn btn-secondary btn-lg">Large button</button>

<button type="button" class="btn btn-primary btn-sm">Small button</button>
<button type="button" class="btn btn-secondary btn-sm">Small button</button>

禁用狀態

透過將 disabled 布林屬性添加到任何 <button> 元素中，使按鈕看起來處於禁用狀態。被禁用的按鈕具有 pointer-events: none，以防止觸發滑入以及啟用狀態。

<button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button>
<button type="button" class="btn btn-secondary btn-lg" disabled>Button</button>

使用 <a> 元素的禁用其行為與其他按鈕略有不同：

<a> 不支援 disabled 屬性，所以你必須添加 .disabled 使它在視覺上看起來被禁用。
加入一些友善的樣式，以禁用游標上的所有 pointer-events。
禁用按鈕應包含 aria-disabled="true" 屬性來向輔助性技術指示元素的狀態。
Disabled buttons using <a> should not include the href attribute.

Primary link Link

<a class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a>
<a class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a>

連結功能警告

為了涵蓋必須在禁用鏈接上保留 href 屬性的情況，.disabled 使用 pointer-events: none 來禁用 <a> 的連結功能。請注意，該 CSS 屬性尚未針對 HTML 標準化，但所有瀏覽器都支持。此外，即使在支持 pointer-events: none 的瀏覽器中，鍵盤導覽仍然不受影響，這意味著鍵盤使用者和輔助性技術的使用者仍然可以啟動這些連結。為了安全起見，除了 aria-disabled="true" 以外，也在這些連結上添加 tabindex="-1" 屬性防止他們套用 focus，並使用自定義的 JavaScript 來禁用它們的功能。

Primary link Link

<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>

區塊級別按鈕

混合使用 display 和 gap 通用類別，建立跟 Bootstrap 4 一樣的響應式、滿版的的區塊級別按鈕堆疊。透過使用通用類別而非指定 button class，你可以更好的控制間距、對齊以及響應式等行為。

<div class="d-grid gap-2">
  <button class="btn btn-primary" type="button">Button</button>
  <button class="btn btn-primary" type="button">Button</button>
</div>

以下為一個響應式的範例，從垂直堆疊的按鈕群組開始，直到遇到 md 斷點才會把 .d-grid 替換為 .d-md-block，進而使 gap-2 通用類別無效化。縮放瀏覽器的大小以觀察它們的改變。

<div class="d-grid gap-2 d-md-block">
  <button class="btn btn-primary" type="button">Button</button>
  <button class="btn btn-primary" type="button">Button</button>
</div>

可以使用網格系統的欄 (column) 類別來調整區塊級別按鈕的寬度。舉例來說，可以用 .col-6 建立寬度 50% 的區塊級別按鈕，再用 .mx-auto 將其水平置中。

<div class="d-grid gap-2 col-6 mx-auto">
  <button class="btn btn-primary" type="button">Button</button>
  <button class="btn btn-primary" type="button">Button</button>
</div>

方向為水平時，可以添加通用類別來對齊、調整按鈕。以下用我們前一個響應式的範例進行修改，在按鈕上加入了一些 flex, margin 通用類別，使其在非堆疊的情況下對齊右邊。

<div class="d-grid gap-2 d-md-flex justify-content-md-end">
  <button class="btn btn-primary me-md-2" type="button">Button</button>
  <button class="btn btn-primary" type="button">Button</button>
</div>

按鈕插件

可以使用按鈕插件建立簡單的 on/off 切換按鈕。

視覺上，這些切換按鈕跟核取方塊切換按鈕是相同的。然而它們透過輔助性技術所傳遞的訊息是不一樣的: 核取方塊切換按鈕會被螢幕閱讀器傳達為 “勾選”/“未勾選” (因為就算它們外表為按鈕，本質上仍然是核取方塊); 然而本節的切換按鈕則會被傳達為 “按鈕”/“按下按鈕”。這兩種方法之間的選擇取決於你想要建立哪一種切換，以及此按鈕是被傳達為核取方塊還是實際按鈕這件事會不會對用戶造成影響。

切換狀態

加入 data-bs-toggle="button" 來切換按鈕的 active 狀態。如果想要預先切換按鈕狀態，則必須手動添加 .active 以及 aria-pressed="true" 以確保狀態有正確的傳達至輔助性技術。

<button type="button" class="btn btn-primary" data-bs-toggle="button" autocomplete="off">Toggle button</button>
<button type="button" class="btn btn-primary active" data-bs-toggle="button" autocomplete="off" aria-pressed="true">Active toggle button</button>
<button type="button" class="btn btn-primary" disabled data-bs-toggle="button" autocomplete="off">Disabled toggle button</button>

Toggle link Active toggle link Disabled toggle link

<a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
<a class="btn btn-primary disabled" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>

方法

可以使用按鈕建構函式來建立按鈕實例，舉例來說:

var button = document.getElementById('myButton')
var bsButton = new bootstrap.Button(button)

Method	Description
`toggle`	切換 push 狀態。讓按鈕具有已觸發的外觀。
`dispose`	破壞元素的按鈕。 (移除儲存在 DOM 元素上的數據)
`getInstance`	允許獲得與 DOM 元素相關按鈕實例的靜態方法，你可以像這樣使用它：`bootstrap.Button.getInstance(element)`
`getOrCreateInstance`	回傳與 DOM 元素相關按鈕實例的靜態方法，或者在未初始化的情況下，創建新的按鈕實例。你可以像這樣使用它：`bootstrap.Button.getOrCreateInstance(element)`

舉例來說，如果要切換所有按鈕:

var buttons = document.querySelectorAll('.btn')
buttons.forEach(function (button) {
  var button = new bootstrap.Button(button)
  button.toggle()
})

Sass

Variables

$btn-padding-y:               $input-btn-padding-y;
$btn-padding-x:               $input-btn-padding-x;
$btn-font-family:             $input-btn-font-family;
$btn-font-size:               $input-btn-font-size;
$btn-line-height:             $input-btn-line-height;
$btn-white-space:             null; // Set to `nowrap` to prevent text wrapping

$btn-padding-y-sm:            $input-btn-padding-y-sm;
$btn-padding-x-sm:            $input-btn-padding-x-sm;
$btn-font-size-sm:            $input-btn-font-size-sm;

$btn-padding-y-lg:            $input-btn-padding-y-lg;
$btn-padding-x-lg:            $input-btn-padding-x-lg;
$btn-font-size-lg:            $input-btn-font-size-lg;

$btn-border-width:            $input-btn-border-width;

$btn-font-weight:             $font-weight-normal;
$btn-box-shadow:              inset 0 1px 0 rgba($white, .15), 0 1px 1px rgba($black, .075);
$btn-focus-width:             $input-btn-focus-width;
$btn-focus-box-shadow:        $input-btn-focus-box-shadow;
$btn-disabled-opacity:        .65;
$btn-active-box-shadow:       inset 0 3px 5px rgba($black, .125);

$btn-link-color:              $link-color;
$btn-link-hover-color:        $link-hover-color;
$btn-link-disabled-color:     $gray-600;

// Allows for customizing button radius independently from global border radius
$btn-border-radius:           $border-radius;
$btn-border-radius-sm:        $border-radius-sm;
$btn-border-radius-lg:        $border-radius-lg;

$btn-transition:              color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out;

$btn-hover-bg-shade-amount:       15%;
$btn-hover-bg-tint-amount:        15%;
$btn-hover-border-shade-amount:   20%;
$btn-hover-border-tint-amount:    10%;
$btn-active-bg-shade-amount:      20%;
$btn-active-bg-tint-amount:       20%;
$btn-active-border-shade-amount:  25%;
$btn-active-border-tint-amount:   10%;

Mixins

按鈕共有三種 mixin：button 和 button outline variant mixins (均基於 $theme-colors)，以及 button size mixin。

@mixin button-variant(
  $background,
  $border,
  $color: color-contrast($background),
  $hover-background: if($color == $color-contrast-light, shade-color($background, $btn-hover-bg-shade-amount), tint-color($background, $btn-hover-bg-tint-amount)),
  $hover-border: if($color == $color-contrast-light, shade-color($border, $btn-hover-border-shade-amount), tint-color($border, $btn-hover-border-tint-amount)),
  $hover-color: color-contrast($hover-background),
  $active-background: if($color == $color-contrast-light, shade-color($background, $btn-active-bg-shade-amount), tint-color($background, $btn-active-bg-tint-amount)),
  $active-border: if($color == $color-contrast-light, shade-color($border, $btn-active-border-shade-amount), tint-color($border, $btn-active-border-tint-amount)),
  $active-color: color-contrast($active-background),
  $disabled-background: $background,
  $disabled-border: $border,
  $disabled-color: color-contrast($disabled-background)
) {
  color: $color;
  @include gradient-bg($background);
  border-color: $border;
  @include box-shadow($btn-box-shadow);

  &:hover {
    color: $hover-color;
    @include gradient-bg($hover-background);
    border-color: $hover-border;
  }

  .btn-check:focus + &,
  &:focus {
    color: $hover-color;
    @include gradient-bg($hover-background);
    border-color: $hover-border;
    @if $enable-shadows {
      @include box-shadow($btn-box-shadow, 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5));
    } @else {
      // Avoid using mixin so we can pass custom focus shadow properly
      box-shadow: 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5);
    }
  }

  .btn-check:checked + &,
  .btn-check:active + &,
  &:active,
  &.active,
  .show > &.dropdown-toggle {
    color: $active-color;
    background-color: $active-background;
    // Remove CSS gradients if they're enabled
    background-image: if($enable-gradients, none, null);
    border-color: $active-border;

    &:focus {
      @if $enable-shadows {
        @include box-shadow($btn-active-box-shadow, 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5));
      } @else {
        // Avoid using mixin so we can pass custom focus shadow properly
        box-shadow: 0 0 0 $btn-focus-width rgba(mix($color, $border, 15%), .5);
      }
    }
  }

  &:disabled,
  &.disabled {
    color: $disabled-color;
    background-color: $disabled-background;
    // Remove CSS gradients if they're enabled
    background-image: if($enable-gradients, none, null);
    border-color: $disabled-border;
  }
}

@mixin button-outline-variant(
  $color,
  $color-hover: color-contrast($color),
  $active-background: $color,
  $active-border: $color,
  $active-color: color-contrast($active-background)
) {
  color: $color;
  border-color: $color;

  &:hover {
    color: $color-hover;
    background-color: $active-background;
    border-color: $active-border;
  }

  .btn-check:focus + &,
  &:focus {
    box-shadow: 0 0 0 $btn-focus-width rgba($color, .5);
  }

  .btn-check:checked + &,
  .btn-check:active + &,
  &:active,
  &.active,
  &.dropdown-toggle.show {
    color: $active-color;
    background-color: $active-background;
    border-color: $active-border;

    &:focus {
      @if $enable-shadows {
        @include box-shadow($btn-active-box-shadow, 0 0 0 $btn-focus-width rgba($color, .5));
      } @else {
        // Avoid using mixin so we can pass custom focus shadow properly
        box-shadow: 0 0 0 $btn-focus-width rgba($color, .5);
      }
    }
  }

  &:disabled,
  &.disabled {
    color: $color;
    background-color: transparent;
  }
}

@mixin button-size($padding-y, $padding-x, $font-size, $border-radius) {
  padding: $padding-y $padding-x;
  @include font-size($font-size);
  // Manually declare to provide an override to the browser default
  @include border-radius($border-radius, 0);
}

Loops

按鈕變化 (對於一般和 outline 按鈕) 使用它們各自的 mixin 和 $theme-colors map 來生成 scss/_buttons.scss中的修飾符類別。

@each $color, $value in $theme-colors {
  .btn-#{$color} {
    @include button-variant($value, $value);
  }
}

@each $color, $value in $theme-colors {
  .btn-outline-#{$color} {
    @include button-outline-variant($value);
  }
}