跳到主要內容 跳到文檔導航
Check
in English

畫布外

使用一些類和我們的 JavaScript 插件將隱藏的側邊欄構建到您的項目中，用於導航、購物車等。

在本頁面

這個怎麼運作

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

  • Offcanvas 與 modals 共享一些相同的 JavaScript 代碼。從概念上講，它們非常相似，但它們是獨立的插件。
  • 類似地，offcanvas 的樣式和尺寸的一些源 Sass變量繼承自 modal 的變量。
  • 顯示時，offcanvas 包含一個默認背景，單擊該背景可以隱藏 offcanvas。
  • 與 modals 類似，一次只能顯示一個 offcanvas。

小心！鑑於 CSS 處理動畫的方式，您不能在元素上使用marginor 。相反，將類用作獨立的包裝元素。translate.offcanvas

該組件的動畫效果依賴於 prefers-reduced-motion媒體查詢。請參閱 我們可訪問性文檔的減少運動部分。

例子

畫布外組件

下面是一個默認顯示的畫布示例（通過.showon .offcanvas）。Offcanvas 包括對帶有關閉按鈕的標題和一些初始的可選正文類的支持padding。我們建議您盡可能在關閉操作中包含 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 元素，該元素通過類切換.show元素上的.offcanvas類。

  • .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>當 offcanvas 及其背景可見時，禁用滾動元素。使用該data-bs-scroll屬性啟用<body>滾動。

帶正文滾動的 Offcanvas

嘗試滾動頁面的其餘部分以查看此選項的實際效果。

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.2.0 中添加

使用實用程序更改畫布外的外觀，以更好地將它們與不同的上下文（如深色導航欄）匹配。在這裡，我們添加.text-bg-dark到.offcanvasand .btn-close-whiteto.btn-close以使用深色 offcanvas 進行適當的造型。如果您有下拉菜單，請考慮添加.dropdown-menu-dark到.dropdown-menu.

畫布外

將畫佈內容放在這裡。

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 類從指定的斷點向下隱藏視口之外的內容。在該斷點之上，其中的內容將照常運行。例如，.offcanvas-lg在斷點下方隱藏畫布中lg的內容，但在斷點上方顯示內容lg。

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

這是.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
  • .offcanvas-sm
  • .offcanvas-md
  • .offcanvas-lg
  • .offcanvas-xl
  • .offcanvas-xxl

放置

offcanvas 組件沒有默認放置，因此您必須添加以下修飾符類之一。

  • .offcanvas-start將 offcanvas 放置在視口的左側（如上所示）
  • .offcanvas-end將 offcanvas 放置在視口的右側
  • .offcanvas-top將 offcanvas 放置在視口的頂部
  • .offcanvas-bottom將 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>
畫布右
...
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>
帆布底
...
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 現在使用本地 CSS 變量.offcanvas來增強實時自定義。CSS 變量的值是通過 Sass 設置的，因此仍然支持 Sass 自定義。

  --#{$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};

Sass 變量

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

用法

offcanvas 插件利用一些類和屬性來處理繁重的工作：

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

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

通過數據屬性

切換

向元素添加data-bs-toggle="offcanvas"和data-bs-target或href以自動分配對一個 offcanvas 元素的控制。該data-bs-target屬性接受一個 CSS 選擇器來應用 offcanvas。請務必將類添加offcanvas到 offcanvas 元素。如果您希望它默認打開，請添加附加類show。

解僱

可以使用offcanvasdata中按鈕上的屬性來實現解僱，如下所示：

<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並且單獨的數據屬性將覆蓋給定的值 on data-bs-config。此外，現有數據屬性能夠容納 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

姓名 類型 默認 描述
backdrop 布爾值或字符串static true 在畫布打開時在身體上應用背景。或者，指定static單擊時不關閉畫布的背景。
keyboard 布爾值 true 按下退出鍵時關閉畫布。
scroll 布爾值 false 在 offcanvas 打開時允許正文滾動。

方法

異步方法和轉換

所有 API 方法都是異步的並開始一個轉換。他們在轉換開始但在結束之前立即返回給調用者。此外，過渡組件上的方法調用將被忽略。

有關更多信息，請參閱我們的 JavaScript 文檔。

將您的內容激活為畫布元素。接受一個可選選項object。

您可以使用構造函數創建一個 offcanvas 實例，例如：

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
方法 描述
getInstance 允許您獲取與 DOM 元素關聯的 offcanvas 實例的靜態方法。
getOrCreateInstance 靜態方法，允許您獲取與 DOM 元素關聯的 offcanvas 實例，或創建一個新實例以防它未初始化。
hide 隱藏畫布外元素。在 offcanvas 元素實際被隱藏之前（即在事件發生之前）返回給調用者。hidden.bs.offcanvas
show 顯示一個 offcanvas 元素。在 offcanvas 元素實際顯示之前（即在事件發生之前）返回給調用者。shown.bs.offcanvas
toggle 將 offcanvas 元素切換為顯示或隱藏。在 offcanvas 元素實際顯示或隱藏之前（即在or事件發生之前）返回給調用者。shown.bs.offcanvashidden.bs.offcanvas

活動

Bootstrap 的 offcanvas 類公開了一些用於掛鉤 offcanvas 功能的事件。

事件類型 描述
hide.bs.offcanvas hide調用該方法時立即觸發此事件。
hidden.bs.offcanvas 當一個 offcanvas 元素對用戶隱藏時觸發此事件（將等待 CSS 轉換完成）。
hidePrevented.bs.offcanvas 當顯示 offcanvas 時觸發此事件，其背景是static並且執行 offcanvas 外部的單擊。當按下退出鍵並且keyboard選項設置為時，也會觸發該事件false。
show.bs.offcanvas show調用實例方法時立即觸發此事件。
shown.bs.offcanvas 當 offcanvas 元素對用戶可見時觸發此事件（將等待 CSS 轉換完成）。 
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})