跳至主要內容 跳至文件瀏覽
在 GitHub 上檢視

側邊欄

使用幾個類別和我們的 JavaScript 外掛程式，將隱藏側邊欄建置到您的專案中，以進行導覽、購物車等操作。

在此頁面上

運作方式

Offcanvas 是一個側邊欄元件，可透過 JavaScript 切換，以從視窗的左側、右側、上方或下方邊緣顯示。按鈕或錨點用作觸發器，附加到您切換的特定元素，並使用 data 屬性來呼叫我們的 JavaScript。

  • Offcanvas 與對話框共用一些相同的 JavaScript 程式碼。在概念上，它們非常相似，但它們是獨立的外掛程式。
  • 同樣地，一些 原始 Sass 變數會從 modal 的變數繼承 offcanvas 的樣式和尺寸。
  • 顯示時，offcanvas 會包含一個預設背景，可以按一下來隱藏 offcanvas。
  • 類似於 modal，一次只能顯示一個 offcanvas。

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

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱 無障礙文件中的減少動作部分。

範例

Offcanvas 元件

以下是預設顯示的 offcanvas 範例（透過 .offcanvas 上的 .show）。Offcanvas 支援包含關閉按鈕的標題，以及一些初始 padding 的選用主體類別。我們建議您盡可能在 offcanvas 標題中包含解除動作，或提供明確的解除動作。

側邊欄
offcanvas 的內容放在這裡。您可以在這裡放置任何 Bootstrap 元件或自訂元素。
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>

線上展示

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

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

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

具有 href 的連結
側邊欄
一些文字作為佔位符。在實際情況中，您可以擁有您選擇的元素。例如，文字、圖片、清單等。
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> 元素。使用 data-bs-scroll 屬性來啟用 <body> 捲動。

具有主體捲動的畫布外側

嘗試捲動頁面的其他部分，以查看此選項的實際作用。

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> 捲動。

具有捲動的背景

嘗試捲動頁面的其他部分，以查看此選項的實際作用。

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>

靜態背景

當背景設為靜態時，畫布外側在點選其外部時不會關閉。

側邊欄
如果您點選我的外部，我不會關閉。
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>

深色畫布外側

已在 v5.3.0 中棄用 已在 v5.2.0 中新增

使用工具變更離畫布的外觀，以更好地將它們與不同的情境相匹配，例如深色導覽列。在此，我們將 .text-bg-dark 新增至 .offcanvas，以及將 .btn-close-white 新增至 .btn-close，以使用深色離畫布進行適當的樣式設定。如果您有下拉式選單，請考慮也將 .dropdown-menu-dark 新增至 .dropdown-menu。

請注意！在 v5.3.0 中，元件的深色變體已棄用，並引入了色彩模式。請勿手動新增上述類別，而是在根元素、父包裝器或元件本身上設定 data-bs-theme="dark"。
側邊欄

在此放置離畫布內容。

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>

回應式

在 v5.2.0 中新增

回應式離畫布類別會隱藏從指定中斷點向下視窗外的內容。在該中斷點以上，內容將會像平常一樣運作。例如，.offcanvas-lg 會在 lg 中斷點以下隱藏離畫布中的內容，但在 lg 中斷點以上顯示內容。

調整瀏覽器大小以顯示回應式離畫布切換。
回應式離畫布

這是 .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>

回應式離畫布類別可供每個中斷點使用。

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

配置

離畫布元件沒有預設配置，因此您必須新增以下其中一個修飾詞類別。

  • .offcanvas-start 將離畫布配置在視窗的左側（如上所示）
  • .offcanvas-end 將離畫布配置在視窗的右側
  • .offcanvas-top 將 offcanvas 放置在視窗的頂部
  • .offcanvas-bottom 將 offcanvas 放置在視窗的底部

在下方嘗試頂部、右側和底部範例。

頂部 offcanvas
...
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
...
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
...
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>

輔助功能

由於 offcanvas 面板在概念上是一個模態對話方塊，請務必將 aria-labelledby="..."（參照 offcanvas 標題）新增至 .offcanvas。請注意，您不需要新增 role="dialog"，因為我們已透過 JavaScript 新增。

CSS

變數

在 v5.2.0 中新增

作為 Bootstrap 不斷發展的 CSS 變數方法的一部分，offcanvas 現在在 .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 變數

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;

使用方式

offcanvas 外掛程式使用一些類別和屬性來處理繁重的工作

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

使用 data-bs-dismiss="offcanvas" 屬性新增一個關閉按鈕，觸發 JavaScript 功能。請務必搭配使用 <button> 元素，以確保在所有裝置上都能正常運作。

透過資料屬性

切換

將 data-bs-toggle="offcanvas" 和 data-bs-target 或 href 新增到元素，以自動指定一個側邊欄元素的控制權。data-bs-target 屬性接受 CSS 選擇器，以將側邊欄套用於該選擇器。請務必將 class offcanvas 新增到側邊欄元素。如果你希望它預設為開啟狀態，請新增額外的 class show。

關閉

關閉功能可以使用 側邊欄內的 按鈕上的 data-bs-dismiss 屬性達成，如下所示

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

或使用 側邊欄外的 按鈕上的 data-bs-target 屬性達成，如下所示

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
雖然支援這兩種關閉側邊欄的方式，但請注意，從側邊欄外關閉不符合 ARIA 編寫實務指南對話框（模式）模式。請自行承擔風險執行此操作。

透過 JavaScript

使用手動啟用

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

選項

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

從 Bootstrap 5.2.0 開始，所有元件都支援一個實驗性保留資料屬性 data-bs-config，它可以將簡單的元件設定作為 JSON 字串儲存。當一個元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最後的 title 值將會是 456，而個別資料屬性將會覆寫 data-bs-config 上提供的數值。此外，現有的資料屬性能夠儲存 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最後的設定物件是 data-bs-config、data-bs- 和 js 物件 的合併結果，其中最後提供的鍵值會覆寫其他鍵值。

名稱 類型 預設值 說明
backdrop 布林值或字串 static true 在側邊欄開啟時，在主體上套用背景。或者，指定 static 以取得在按一下時不會關閉側邊欄的背景。
keyboard 布林值 true 在按下 ESC 鍵時關閉側邊欄。
scroll 布林值 false 在側邊欄開啟時允許主體捲動。

方法

所有 API 方法都是非同步的，並會開始轉場。它們會在轉場開始後立即傳回呼叫者，但會在轉場結束前傳回。此外，對轉場中元件的方法呼叫將會被忽略。在我們的 JavaScript 文件中了解更多資訊。

將您的內容啟用為離畫布元素。接受一個選用的選項 物件。

您可以使用建構函式建立離畫布實例，例如

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 事件發生之前）。

事件

Bootstrap 的離畫布類別公開了一些事件，可供掛入離畫布功能。

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