使用一些类和我们的 JavaScript 插件将隐藏的侧边栏构建到您的项目中,用于导航、购物车等。
它是如何运作的
Offcanvas 是一个侧边栏组件,可以通过 JavaScript 切换以从视口的左侧、右侧、顶部或底部边缘显示。 按钮或锚点用作附加到您切换的特定元素的触发器,而 data
属性用于调用我们的 JavaScript。
- Offcanvas 与 modals 共享一些相同的 JavaScript 代码。 从概念上讲,它们非常相似,但它们是独立的插件。
- 类似地,一些用于 offcanvas 样式和尺寸的资源 Sass 变量继承自 modal 的变量。
- 显示时,offcanvas 包含一个默认背景,单击该背景可以隐藏 offcanvas。
- 与 modals 类似,一次只能显示一个 offcanvas。
请注意!鉴于 CSS 处理动画的方式,您不能在 .offcanvas
元素上使用 margin
或 translate
。 相反,将类用作独立的包装元素。
prefers-reduced-motion
媒体查询。 请参阅辅助功能文档的减少运动部分。
例子
画布外组件
下面是一个默认显示的 offcanvas 示例(通过 .offcanvas
上的 .show
)。 Offcanvas 支持带有关闭按钮的标题和一些初始 padding
的可选正文类。 我们建议您尽可能在关闭操作中包含 offcanvas 标头,或提供明确的关闭操作。
《铁崖乐府》
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel"> <div class="offcanvas-header"> <h5 class="offcanvas-title" id="offcanvasLabel">《铁崖乐府》</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> 中国古籍,杨维桢著作。尤以乐府擅名,号铁崖体,在元季文坛独领风骚40余年。 </div> </div>
现场演示
使用下面的按钮通过 JavaScript 显示和隐藏 offcanvas 元素,该元素在具有 .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"> 使用链接的href </a> <button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample"> 使用按钮的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">《越绝书》</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> <div class=""> 以春秋末年至战国初期吴越争霸的历史事实为主干,上溯夏禹,下迄两汉,旁及诸侯列国,对这一历史时期吴越地区的汉民族政治、经济、军事、天文、地理、历法、语言等多有所涉及,被誉为“地方志鼻祖”。 </div> <div class="dropdown mt-3"> <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown"> 古文典籍 </button> <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton"> <li><a class="dropdown-item" href="#">《千字文》</a></li> <li><a class="dropdown-item" href="#">《孟子》</a></li> <li><a class="dropdown-item" href="#">《菜根谭》</a></li> </ul> </div> </div> </div>
放置方式
offcanvas 组件没有默认放置,因此您必须添加以下修饰符类之一;
.offcanvas-start
将 offcanvas 放置在视口的左侧(如上所示).offcanvas-end
将 offcanvas 放置在视口的右侧.offcanvas-top
将 offcanvas 放置在视口的顶部.offcanvas-bottom
将 offcanvas 放置在视口底部
试试下面的顶部、右侧和底部示例。
顶部Offcanvas
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">切换顶部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</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> ... </div> </div>
右侧Offcanvas
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">切换右侧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</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> ... </div> </div>
底部Offcanvas
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">切换底部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</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body small"> ... </div> </div>
背景
当 offcanvas 及其背景可见时,滚动 <body>
元素将被禁用。 使用 data-bs-scroll
属性来切换 滚动,使用
data-bs-backdrop
来切换背景。
带正文滚动的 Offcanvas
尝试滚动页面的其余部分以查看此选项的实际效果。
带背景的 Offcanvas
.....
带滚动的背景
尝试滚动页面的其余部分以查看此选项的实际效果。
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">启用正文滚动</button> <button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBackdrop" aria-controls="offcanvasWithBackdrop">启用背景(默认)</button> <button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">同时启用滚动和背景</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</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> <p>尝试滚动页面的其余部分以查看此选项的实际效果。</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</h5> <button type="button" class="btn-close" 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">带滚动的背景</h5> <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button> </div> <div class="offcanvas-body"> <p>尝试滚动页面的其余部分以查看此选项的实际效果。</p> </div> </div>
可访问性
由于 offcanvas 面板在概念上是一个模态对话框,因此请务必将 aria-labelledby="..."
(引用 offcanvas 标题)添加到 .offcanvas
。 请注意,您不需要添加 role="dialog"
,因为我们已经通过 JavaScript 添加了它。
用法
offcanvas 插件利用一些类和属性来处理繁重的工作:
.offcanvas
隐藏内容.offcanvas.show
显示内容.offcanvas-start
将 offcanvas 隐藏在左侧.offcanvas-end
将 offcanvas 隐藏在右侧.offcanvas-top
将 offcanvas 隐藏在顶部.offcanvas-bottom
将 offcanvas 隐藏在底部
添加一个带有 data-bs-dismiss="offcanvas"
属性的关闭按钮,它会触发 JavaScript 功能。 请务必将 <button>
元素与它一起使用,以确保在所有设备上都能正常运行。
通过数据属性
Toggle将 data-bs-toggle=“offcanvas”
和 data-bs-target
或 href
添加到元素以自动分配控制权 画布外元素。 data-bs-target
属性接受一个 CSS 选择器来应用 offcanvas。 请务必将类 offcanvas
添加到 offcanvas 元素。 如果您希望它默认打开,请添加附加类 show
。
可以通过 offcanvas 内的按钮上的 data
属性来实现解雇,如下所示:
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
或使用 data-bs-target
在 offcanvas 之外的按钮 上,如下所示:
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>
通过 JavaScript
手动启用:
var offcanvasElementList = Array.prototype.slice.call(document.querySelectorAll('.offcanvas')) var offcanvasList = offcanvasElementList.map(function (offcanvasEl) { return new bootstrap.Offcanvas(offcanvasEl) })
选项
选项可以通过数据属性或 JavaScript 传递。 对于数据属性,将选项名称附加到 data-bs-
,如 data-bs-backdrop=""
。
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
backdrop |
boolean | true |
在画布打开时在身体上应用背景 |
keyboard |
boolean | true |
按下退出键时关闭画布 |
scroll |
boolean | false |
在 offcanvas 打开时允许正文滚动 |
方法
所有 API 方法都是异步并启动transition。 它们会在过渡开始后但在过渡结束之前返回给调用者。 此外,转换组件上的方法调用将被忽略。
将您的内容激活为画布元素。 接受可选选项object
。
您可以使用构造函数创建一个 offcanvas 实例,例如:
var myOffcanvas = document.getElementById('myOffcanvas') var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)
方法 | 描述 |
---|---|
toggle
|
将 offcanvas 元素切换为显示或隐藏。
在 offcanvas 元素实际显示或隐藏之前返回给调用者(即在 shown.bs.offcanvas 或 hidden.bs.offcanvas 事件发生)。
|
show
|
显示一个 offcanvas 元素。
在 offcanvas 元素实际显示之前返回调用者(即在 shown.bs.offcanvas 事件发生之前)。
|
hide
|
隐藏 offcanvas 元素。
在 offcanvas 元素真正被隐藏之前返回给调用者(即在 hidden.bs.offcanvas 事件发生)。
|
getInstance
|
static方法,允许您获取与 DOM 元素关联的 offcanvas 实例。 |
getOrCreateInstance
|
static方法,允许您获取与 DOM 元素关联的 offcanvas 实例,或创建一个新实例以防它未初始化。 |
事件
Bootstrap 的 offcanvas 类公开了一些用于挂钩到 offcanvas 功能的事件。
事件类型 | 描述 |
---|---|
show.bs.offcanvas |
此事件在调用 show 实例方法时立即触发。 |
shown.bs.offcanvas |
当 offcanvas 元素对用户可见时触发此事件(将等待 CSS 转换完成)。 |
hide.bs.offcanvas |
当调用 hide 方法时,会立即触发此事件。 |
hidden.bs.offcanvas |
当一个 offcanvas 元素对用户隐藏时触发此事件(将等待 CSS 转换完成)。 |
var myOffcanvas = document.getElementById('myOffcanvas') myOffcanvas.addEventListener('hidden.bs.offcanvas', function () { // do something... })