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

側邊面板（Offcanvas）

使用幾個類別和我們的 JavaScript 外掛程式，為您的專案建立隱藏的側邊欄，用於導覽、購物車等功能。

本頁內容

運作原理（How it works）

側邊面板是一個側邊欄元件，可以透過 JavaScript 切換，從視窗的左側、右側、頂部或底部邊緣出現。按鈕或錨點作為觸發器，附加到您要切換的特定元素上，並使用 data 屬性來呼叫我們的 JavaScript。

  • 側邊面板與互動視窗共用部分相同的 JavaScript 程式碼。在概念上，它們非常相似，但它們是獨立的外掛程式。
  • 同樣地，側邊面板樣式和尺寸的一些原始碼 Sass 變數繼承自互動視窗的變數。
  • 顯示時，側邊面板包含一個預設的背景遮罩，可以點擊它來隱藏側邊面板。
  • 與互動視窗類似，一次只能顯示一個側邊面板。

請注意！ 由於 CSS 處理動畫的方式，您無法在 .offcanvas 元素上使用 margin 或 translate。相反地，請將該類別用作獨立的包裹元素。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們無障礙文件中的減少動態效果章節。

範例（Examples）

側邊面板元件（Offcanvas components）

以下是一個預設顯示的側邊面板範例（透過在 .offcanvas 上加入 .show）。側邊面板支援帶有關閉按鈕的標題區和可選的主體類別，用於設定一些初始 padding。我們建議您盡可能在側邊面板標題中包含關閉動作，或提供明確的關閉動作。

Offcanvas
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
html 
<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
  </div>
</div>

即時示範（Live demo）

使用下面的按鈕透過 JavaScript 顯示和隱藏側邊面板元素，它會在具有 .offcanvas 類別的元素上切換 .show 類別。

  • .offcanvas 隱藏內容（預設）
  • .offcanvas.show 顯示內容

您可以使用帶有 href 屬性的連結，或帶有 data-bs-target 屬性的按鈕。在這兩種情況下，都需要 data-bs-toggle="offcanvas"。

Link with href
Offcanvas
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
html 
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Button with data-bs-target
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
    </div>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Another action</a></li>
        <li><a class="dropdown-item" href="#">Something else here</a></li>
      </ul>
    </div>
  </div>
</div>

內文捲動（Body scrolling）

當側邊面板及其背景遮罩可見時，<body> 元素的捲動會被停用。使用 data-bs-scroll 屬性來啟用 <body> 捲動。

Offcanvas with body scrolling

Try scrolling the rest of the page to see this option in action.

html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

內文捲動與背景遮罩（Body scrolling and backdrop）

您也可以在顯示背景遮罩的同時啟用 <body> 捲動。

Backdrop with scrolling

Try scrolling the rest of the page to see this option in action.

html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

靜態背景遮罩（Static backdrop）

當背景遮罩設定為 static 時，點擊側邊面板外部不會關閉它。

Offcanvas
I will not close if you click outside of me.
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
  Toggle static offcanvas
</button>

<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      I will not close if you click outside of me.
    </div>
  </div>
</div>

深色側邊面板（Dark offcanvas）

Deprecated in v5.3.0 Added in v5.2.0

使用通用類別改變側邊面板的外觀，以更好地匹配不同的情境，如深色導覽列。這裡我們在 .offcanvas 上加入 .text-bg-dark，並在 .btn-close 上加入 .btn-close-white，以便與深色側邊面板正確配合。如果其中有下拉選單，請考慮也在 .dropdown-menu 上加入 .dropdown-menu-dark。

請注意！ 元件的深色變體在 v5.3.0 引入色彩模式後已被棄用。不要手動加入上述提到的類別，而是在根元素、父包裹器或元件本身上設定 data-bs-theme="dark"。

Offcanvas

Place offcanvas content here.

html 
<div class="offcanvas offcanvas-start show text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5>
    <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Place offcanvas content here.</p>
  </div>
</div>

響應式（Responsive）

Added in v5.2.0

響應式側邊面板類別會在指定的中斷點及以下隱藏視窗外的內容。在該中斷點以上，其中的內容將正常顯示。例如，.offcanvas-lg 會在 lg 中斷點以下將內容隱藏在側邊面板中，但在 lg 中斷點以上顯示內容。響應式側邊面板類別適用於每個中斷點。

  • .offcanvas
  • .offcanvas-sm
  • .offcanvas-md
  • .offcanvas-lg
  • .offcanvas-xl
  • .offcanvas-xxl

要建立響應式側邊面板，請將 .offcanvas 基礎類別替換為響應式變體，並確保您的關閉按鈕具有明確的 data-bs-target。

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas

This is content within an .offcanvas-lg.

html 
<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button>

<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div>

<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p>
  </div>
</div>

位置（Placement）

側邊面板元件沒有預設位置，因此您必須加入以下修飾類別之一。

  • .offcanvas-start 將側邊面板放在視窗的左側（如上所示）
  • .offcanvas-end 將側邊面板放在視窗的右側
  • .offcanvas-top 將側邊面板放在視窗的頂部
  • .offcanvas-bottom 將側邊面板放在視窗的底部

嘗試下面的頂部、右側和底部範例。

Offcanvas top
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button>

<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Offcanvas right
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>
Offcanvas bottom
...
html 
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>

<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

無障礙（Accessibility）

由於側邊面板在概念上是一個對話框，請確保在 .offcanvas 上加入 aria-labelledby="..."——參照側邊面板標題。請注意，您不需要加入 role="dialog"，因為我們已經透過 JavaScript 加入了它。

CSS

變數（Variables）

Added in v5.2.0

作為 Bootstrap 持續演進的 CSS 變數方法的一部分，側邊面板現在在 .offcanvas 上使用區域 CSS 變數，以增強即時自訂能力。CSS 變數的值透過 Sass 設定，因此仍然支援 Sass 自訂。

scss/_offcanvas.scss 
--#{$prefix}offcanvas-zindex: #{$zindex-offcanvas};
--#{$prefix}offcanvas-width: #{$offcanvas-horizontal-width};
--#{$prefix}offcanvas-height: #{$offcanvas-vertical-height};
--#{$prefix}offcanvas-padding-x: #{$offcanvas-padding-x};
--#{$prefix}offcanvas-padding-y: #{$offcanvas-padding-y};
--#{$prefix}offcanvas-color: #{$offcanvas-color};
--#{$prefix}offcanvas-bg: #{$offcanvas-bg-color};
--#{$prefix}offcanvas-border-width: #{$offcanvas-border-width};
--#{$prefix}offcanvas-border-color: #{$offcanvas-border-color};
--#{$prefix}offcanvas-box-shadow: #{$offcanvas-box-shadow};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};

Sass 變數（Sass variables）

scss/_variables.scss 
$offcanvas-padding-y:               $modal-inner-padding;
$offcanvas-padding-x:               $modal-inner-padding;
$offcanvas-horizontal-width:        400px;
$offcanvas-vertical-height:         30vh;
$offcanvas-transition-duration:     .3s;
$offcanvas-border-color:            $modal-content-border-color;
$offcanvas-border-width:            $modal-content-border-width;
$offcanvas-title-line-height:       $modal-title-line-height;
$offcanvas-bg-color:                var(--#{$prefix}body-bg);
$offcanvas-color:                   var(--#{$prefix}body-color);
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

使用方式（Usage）

側邊面板外掛程式使用一些類別和屬性來處理主要工作：

  • .offcanvas 隱藏內容
  • .offcanvas.show 顯示內容
  • .offcanvas-start 將側邊面板隱藏在左側
  • .offcanvas-end 將側邊面板隱藏在右側
  • .offcanvas-top 將側邊面板隱藏在頂部
  • .offcanvas-bottom 將側邊面板隱藏在底部

加入帶有 data-bs-dismiss="offcanvas" 屬性的關閉按鈕，它會觸發 JavaScript 功能。請確保與 <button> 元素一起使用，以確保在所有裝置上的正確行為。

透過 data 屬性（Via data attributes）

切換（Toggle）

在元素上加入 data-bs-toggle="offcanvas" 和 data-bs-target 或 href，以自動指派對一個側邊面板元素的控制。data-bs-target 屬性接受 CSS 選擇器以套用到側邊面板。請確保在側邊面板元素上加入 offcanvas 類別。如果您希望它預設開啟，請加入額外的 show 類別。

關閉（Dismiss）

可以透過 offcanvas 內部按鈕上的 data-bs-dismiss 屬性來實現關閉功能，如下所示： 

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

或者透過 offcanvas 外部的按鈕，使用額外的 data-bs-target，如下所示： 

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>

雖然兩種關閉側邊面板的方式都受支援，但請記住，從側邊面板外部關閉不符合 ARIA 編寫實踐指南對話框（互動視窗）模式。請自行承擔風險。

透過 JavaScript（Via JavaScript）

手動啟用：

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))

選項（Options）

由於選項可以透過 data 屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過 data 屬性傳遞選項時，請確保將選項名稱的大小寫類型從「camelCase」更改為「kebab-case」。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援實驗性的保留 data 屬性 data-bs-config，可以將簡單的元件配置作為 JSON 字串存放。當元素同時具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最終的 title 值將是 456，個別的 data 屬性將覆寫 data-bs-config 中給定的值。此外，現有的 data 屬性也能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

名稱類型預設值說明
backdrop布林值或字串 statictrue在側邊面板開啟時在 body 上套用背景遮罩。或者，指定 static 以建立點擊時不會關閉側邊面板的背景遮罩。
keyboard布林值true當按下 Escape 鍵時關閉側邊面板。
scroll布林值false在側邊面板開啟時允許 body 捲動。

方法（Methods）

所有 API 方法都是非同步的，並會啟動一個過渡效果。 它們會在過渡開始後立即回傳給呼叫者，但在過渡結束之前。此外，對正在過渡中的元件進行方法呼叫將被忽略。在我們的 JavaScript 文件中了解更多。

將您的內容啟用為側邊面板元素。接受可選的選項 object。

您可以使用建構函式建立側邊面板實例，例如：

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
方法說明
dispose銷毀元素的側邊面板。
getInstance靜態方法，允許您取得與 DOM 元素關聯的側邊面板實例。
getOrCreateInstance靜態方法，允許您取得與 DOM 元素關聯的側邊面板實例，如果未初始化則建立一個新的。
hide隱藏側邊面板元素。在側邊面板元素實際隱藏之前傳回給呼叫者（即在 hidden.bs.offcanvas 事件發生之前）。
show顯示側邊面板元素。在側邊面板元素實際顯示之前傳回給呼叫者（即在 shown.bs.offcanvas 事件發生之前）。
toggle切換側邊面板元素的顯示或隱藏。在側邊面板元素實際顯示或隱藏之前傳回給呼叫者（即在 shown.bs.offcanvas 或 hidden.bs.offcanvas 事件發生之前）。

事件（Events）

Bootstrap 的側邊面板類別公開了幾個事件，用於掛接側邊面板功能。

事件類型說明
hide.bs.offcanvas當呼叫 hide 方法時立即觸發此事件。
hidden.bs.offcanvas當側邊面板元素對使用者隱藏後觸發此事件（會等待 CSS 過渡完成）。
hidePrevented.bs.offcanvas當側邊面板顯示、其背景遮罩為 static 且在側邊面板外部執行點擊時觸發此事件。當按下 Escape 鍵且 keyboard 選項設定為 false 時也會觸發此事件。
show.bs.offcanvas當呼叫 show 實例方法時立即觸發此事件。
shown.bs.offcanvas當側邊面板元素對使用者可見時觸發此事件（會等待 CSS 過渡完成）。
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})