View on GitHub

Offcanvas (畫布)

使用一些類別和我們的 JavaScript 套件，將隱藏的側邊欄建構到你的專案中，用於導航、購物車等等。

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

立即上課去

On this page

如何運作

Offcanvas 是一個側邊欄元件，可以通過 JavaScript 切換以從視窗的左側、右側或底部邊緣顯示。按鈕或錨點作為附加到你切換的特定元素觸發器，data 屬性用於調用我們的 JavaScript.

Offcanvas 與互動視窗共享一些相同的 JavaScript 程式碼。從概念上講，他們非常相似，但他們是獨立的元件。
類似地，offcanvas 樣式和尺寸的一些 source Sass 變數是從互動視窗的變數繼承的。
顯示時，offcanvas 包含一個預設背景，可以點擊以隱藏 offcanvas。
和互動視窗相似，一次只能顯示一個 offcanvas。

小心! 鑑於 CSS 處理動畫的方式，你不能在 .offcanvas 元素上使用 margin 或 translate。相反，將此類別作為獨立的包裝元素。

該元件的動畫效果取決於 prefers-reduced-motion media queries。請參考 reduced motion section of our accessibility documentation

範例

Offcanvas 元件

下方是一個預設顯示的 offcanvas 範例 (通過 .offcanvas 上的 .show )。Offcanvas 支援包括帶有關閉按鈕的標題和一些初始 padding 的 optional body class。我們建議您盡可能在 offcanvas header 包含關閉操作，或是提供明確的關閉操作。

Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.

<div class="offcanvas offcanvas-start" 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 text-reset" 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>

動態範例

使用下面的按鈕顯示和隱藏 offcanvas 通過 JavaScript 切換 .offcanvas 上的 .show 類別。

.offcanvas 隱藏內容 (預設)
.offcanvas.show 顯示內容

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

Link with href

Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.

<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 text-reset" 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" id="dropdownMenuButton" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
        <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>

位置

Offcanvas 元件沒有預設位置，因此你必須添加以下其中一個類別：

.offcanvas-start 將 offcanvas 放在視窗的左側 (如上所式)
.offcanvas-end 將 offcanvas 放在視窗的右側
.offcanvas-top 將 offcanvas 放在視窗的頂部
.offcanvas-bottom 將 offcanvas 放在視窗的底部

嘗試下方的 top、right 以及 bottom 範例。

...

<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 id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

<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 id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

<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 text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

背景

當 Offcanvas 和它的背景顯示時，<body> 元素禁止滾動。使用 data-bs-scroll 屬性切換 <body> 滾動和使用 data-bs-backdrop 切換背景。

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

.....

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

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBackdrop" aria-controls="offcanvasWithBackdrop">Enable backdrop (default)</button>
<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" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Colored with scrolling</h5>
    <button type="button" class="btn-close text-reset" 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>
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasWithBackdrop" aria-labelledby="offcanvasWithBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBackdropLabel">Offcanvas with backdrop</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>.....</p>
  </div>
</div>
<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 text-reset" 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>

無障礙

由於 Offcanvas 面板在概念上是一個互動對話框視窗，請務必將 aria-labelledby="..."—引用 Offcanvas 標題—添加到 .offcanvas。請注意，你不需要加上 role="dialog"，因為我們已經通過 JavaScript 添加了。

Sass

Variables

$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:                $modal-content-bg;
$offcanvas-color:                   $modal-content-color;
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

Usage

Offcanvas 利用一些類別和屬性處理繁重的工作：

.offcanvas 隱藏內容
.offcanvas.show 顯示內容
.offcanvas-start 隱藏左側的 offcanvas
.offcanvas-end 隱藏右側的 offcanvas
.offcanvas-bottom 隱藏底部的 offcanvas

添加一個帶有 data-bs-dismiss="offcanvas" 屬性的關閉按鈕，它會觸發 JavaScript 功能。確保將 <button> 元素和它一起使用，以便在所有設備上正確運行。

通過 data 屬性

Toggle

向元素添加 data-bs-toggle="offcanvas" 和 data-bs-target 或 href 以自動分配一個 offcanvas 元素的控制權。data-bs-target 屬性接受一個 CSS 選擇器來應用 offcanvas。確保將 offcanvas 類別添加到 offcanvas 元素。如果你希望它預設打開，請添加 show 類別。

Dismiss

Dismissal can be achieved with the data attribute on a button within the offcanvas as demonstrated below:

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

or on a button outside the offcanvas using the data-bs-target as demonstrated below:

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

雖然兩種方式都支援關閉 offcanvas，但請記住從 offcanvas 外部關閉與 the WAI-ARIA modal dialog design pattern 不匹配。這樣做的風險由您自己承擔。

透過 JavaScript

手動啟用：

var offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
  return new bootstrap.Offcanvas(offcanvasEl)
})

選項

可以透過資料屬性或 JavaScript 傳遞選項。對於資料屬性，將選項名稱附加到 data-bs-，如 data-bs-backdrop=""。

Name	Type	Default	Description
`backdrop`	boolean	`true`	當 offcanvas 打開時應用背景
`keyboard`	boolean	`true`	按下 ESC 鍵時關閉 offcanvas
`scroll`	boolean	`false`	當 offcanvas 打開時允許 body 滾動

方法

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

將你的內容作為 offcanvas 元素啟用。接受一個可選的選項 object。

你可以使用一個 constructor 創建一個 offcanvas 實例，例如：

var myOffcanvas = document.getElementById('myOffcanvas')
var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)

Method	Description
`toggle`	將 offcanvas 切換為顯示或隱藏。在 offcanvas 元素實際顯示或隱藏之前回傳給調用者 (即在 `shown.bs.offcanvas` 或 `hidden.bs.offcanvas` 事件發生之前)。
`show`	顯示一個 offcanvas 元素。在 offcanvas 元素實際顯示之前回傳給調用者 (即在 `shown.bs.offcanvas` 事件發生之前)。
`hide`	隱藏一個 offcanvas 元素。在 offcanvas 元素實際隱藏之前回傳給調用者 (即在 `hidden.bs.offcanvas` 事件發生之前)。
`getInstance`	靜態方法，可以讓你獲取與 DOM 元素相關聯的 offcanvas 實例。
`getOrCreateInstance`	靜態方法，允許獲取與 DOM 元素相關聯的 offcanvas 實例，或者在未初始化的情況下創建一個新實例。

事件

Bootstrap 的 offcanvas 類別公開了一些用於 hooking into offcanvas 功能的事件

Event type	Description
`show.bs.offcanvas`	當呼叫 `show` 實例方法時立即觸發此事件。
`shown.bs.offcanvas`	當 offcanvas 元素顯示時將會觸發此事件 (等待 CSS transition 完成)。
`hide.bs.offcanvas`	當呼叫 `hide` 方法時，將會立即觸發此事件。
`hidden.bs.offcanvas`	當 offcanvas 元素隱藏時會觸發此事件 (等待 CSS transition 完成)。

var myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', function () {
  // do something...
})