离画布
使用几个类和我们的 JavaScript 插件,将隐藏的侧边栏构建到您的项目中,用于导航、购物车等。
工作原理
Offcanvas 是一个侧边栏组件,可以通过 JavaScript 切换,使其从视口的左侧、右侧、顶部或底部边缘显示。按钮或锚点用作触发器,附加到您要切换的特定元素上,并且 data
属性用于调用我们的 JavaScript。
- Offcanvas 与模态共享一些相同的 JavaScript 代码。从概念上讲,它们非常相似,但它们是独立的插件。
- 类似地,Offcanvas 样式和尺寸的一些 源 Sass 变量继承自模态的变量。
- 显示时,Offcanvas 包含一个默认背景,可以单击该背景以隐藏 Offcanvas。
- 与模态类似,一次只能显示一个 Offcanvas。
注意!鉴于 CSS 处理动画的方式,您不能对 .offcanvas
元素使用 margin
或 translate
。相反,将该类用作独立的包装元素。
prefers-reduced-motion
媒体查询。请参阅 无障碍文档的减少运动部分。
示例
侧边栏组件
下面是一个默认显示的侧边栏示例(通过 .offcanvas
上的 .show
)。侧边栏支持带有关闭按钮的标题,以及用于一些初始 padding
的可选主体类。我们建议你尽可能在侧边栏标题中包含关闭操作,或提供明确的关闭操作。
离画布
<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 显示和隐藏侧边栏元素,该 JavaScript 在具有 .offcanvas
类的元素上切换 .show
类。
.offcanvas
隐藏内容(默认).offcanvas.show
显示内容
你可以使用具有 href
属性的链接,或具有 data-bs-target
属性的按钮。在这两种情况下,都需要 data-bs-toggle="offcanvas"
。
离画布
<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>
滚动。
带有主体滚动的侧边栏
尝试滚动页面的其余部分,以查看此选项的实际效果。
<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>
滚动。
带有滚动的背景
尝试滚动页面的其余部分,以查看此选项的实际效果。
<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>
静态背景
当背景设置为静态时,单击侧边栏外部不会关闭侧边栏。
离画布
<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
使用实用程序更改侧边栏的外观,以更好地匹配它们与不同上下文(如深色导航栏)的匹配。这里我们为 .offcanvas
添加 .text-bg-dark
,为 .btn-close
添加 .btn-close-white
,以便使用深色侧边栏进行适当的样式设置。如果您在内部有下拉菜单,请考虑还将 .dropdown-menu-dark
添加到 .dropdown-menu
。
data-bs-theme="dark"
。
离画布
在此处放置侧边栏内容。
<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
中的内容。
<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-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 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>
侧边栏右侧
<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>
侧边栏底部
<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>
辅助功能
由于侧边栏面板在概念上是一个模态对话框,请务必将 aria-labelledby="..."
(引用侧边栏标题)添加到 .offcanvas
。请注意,您无需添加 role="dialog"
,因为我们已通过 JavaScript 添加了它。
CSS
变量
已添加 v5.2.0作为 Bootstrap 不断发展的 CSS 变量方法的一部分,侧边栏现在在 .offcanvas
上使用本地 CSS 变量,以增强实时自定义。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};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};
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: 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.show
显示内容.offcanvas-start
在左侧隐藏侧边栏.offcanvas-end
在右侧隐藏侧边栏.offcanvas-top
在顶部隐藏侧边栏.offcanvas-bottom
在底部隐藏侧边栏
使用 data-bs-dismiss="offcanvas"
属性添加一个关闭按钮,它将触发 JavaScript 功能。请务必将 <button>
元素与它一起使用,以确保在所有设备上都能正常工作。
通过数据属性
切换
将 data-bs-toggle="offcanvas"
和 data-bs-target
或 href
添加到元素,以自动分配一个侧边栏元素的控制权。data-bs-target
属性接受一个 CSS 选择器,以将侧边栏应用于该选择器。请务必将 offcanvas
类添加到侧边栏元素。如果您希望它默认打开,请添加额外的类 show
。
关闭
可以通过在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>
通过 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 |
在 offcanvas 打开时在 body 上应用背景。或者,为不会在点击时关闭 offcanvas 的背景指定 static 。 |
keyboard |
布尔值 | true |
在按下 ESC 键时关闭 offcanvas。 |
scroll |
布尔值 | false |
在 offcanvas 打开时允许 body 滚动。 |
方法
将您的内容作为 offcanvas 元素激活。接受一个可选的选项 object
。
您可以使用构造函数创建 offcanvas 实例,例如
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 |
当侧边栏元素对用户隐藏时触发此事件(将等待 CSS 过渡完成)。 |
hidePrevented.bs.offcanvas |
当侧边栏显示、其背景为 static 并且在侧边栏外部单击时触发此事件。当按下 ESC 键且 keyboard 选项设置为 false 时也会触发此事件。 |
show.bs.offcanvas |
当调用 show 实例方法时立即触发此事件。 |
shown.bs.offcanvas |
当侧边栏元素对用户可见时触发此事件(将等待 CSS 过渡完成)。 |
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
// do something...
})