侧边栏 | 组件 | BootstrapVue 组件库

BootstrapVue 的自定义 <b-sidebar> 组件也被称为离画布或侧边抽屉，是一个固定位置的可切换滑动弹出框，可用于导航、菜单、详细信息等。它可以放置在视口的左侧（默认）或右侧，并提供可选的背景支持。

自 v2.10.0 起在 BootstrapVue 中提供

概述

你几乎可以在 <b-sidebar> 可选作用域的默认插槽中放置任何内容，例如文本、按钮、表单、图像或垂直导航。

该组件支持标题和内置的关闭按钮，你可以选择禁用并提供自己的标题（如果需要），并且可以使用我们的 v-b-toggle 指令轻松切换。

此组件具有最小的默认样式，这为您在布局侧边栏内容时提供了极大的灵活性。

<template>
  <div>
    <b-button v-b-toggle.sidebar-1>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-1" title="Sidebar" shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar.vue -->

如果内容高于可用的视口高度，则将通过 CSS 在侧边栏的主体上自动启用垂直滚动。

样式

提供了多个属性来控制侧边栏的外观。

标题

侧边栏应该有一个标题（特别是出于可访问性原因）。可以通过 title 属性或 title 插槽轻松设置显示在标题中的标题。请注意，title 插槽优先于 title 属性。

如果设置了 no-header 属性，则 title 属性或 title 插槽均不起作用。

如果您没有提供标题，请使用 aria-label 或 aria-labelledby 属性为侧边栏提供一个可访问的标题。有关其他详细信息，请参阅下面的辅助功能部分。

放置

默认情况下，侧边栏将放置在视口的左侧。将 right 属性设置为 true，以使侧边栏显示在视口的右侧。

<template>
  <div>
    <b-button v-b-toggle.sidebar-right>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-right" title="Sidebar" right shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-right.vue -->

变体

使用属性 bg-variant 和 text-variant 分别控制背景和文本的主题颜色变体。或者，您可以应用样式或类来指定背景和文本颜色。

<template>
  <div>
    <b-button v-b-toggle.sidebar-variant>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-variant" title="Sidebar" bg-variant="dark" text-variant="light" shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-variant.vue -->

标准 Bootstrap 主题变体为 'white'、'light'、'dark'、'primary'、'secondary'、'success'、'danger'、'warning' 和 'info'。

默认背景变体为 'light'，默认文本变体为 'dark'。

阴影

喜欢带有背景阴影的侧边栏？将 shadow 属性设置为布尔值 true 以获得中等阴影，'sm' 以获得小阴影，或 'lg' 以获得更大的阴影。将其设置为 false（默认值）以无阴影。

边框

默认情况下，<b-sidebar> 没有边框。使用边框实用程序类向 <b-sidebar>（通过 sidebar-class 属性 2.12.0+）添加边框，或使用 CSS 样式覆盖。

<template>
  <div>
    <b-button v-b-toggle.sidebar-border>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-border" sidebar-class="border-right border-danger">
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-border.vue -->

宽度

默认情况下，<b-sidebar> 的宽度设置为 320px（在“xs”屏幕上为 100%）。只需通过 width 属性（即 '180px'、'20em' 等）提供一个值即可覆盖此默认值。最大宽度通过 CSS 设置为 100%。

填充

默认情况下，侧边栏没有填充。可以向组件应用填充实用程序类，或向侧边栏内容应用边距/填充实用程序类。

禁用幻灯片过渡

默认情况下，侧边栏在显示和隐藏时将使用滑动过渡。可以通过 no-slide 属性禁用幻灯片过渡。

注意：此组件的 BootstrapVue 定义的过渡效果取决于 prefers-reduced-motion 媒体查询。有关更多详细信息，请参阅无障碍文档的减少运动部分。

禁用幻灯片过渡时，可选背景的淡入淡出过渡也将被禁用。

Z 轴索引

侧边栏在 SCSS/CSS 中定义了默认 z-index。在某些情况下，可能需要使用不同的 z-index 来确保侧边栏出现在其他内容之上或之下。可以通过 CSS 样式或 z-index 属性来实现。

作用域默认插槽

default 插槽允许你为侧边栏提供正文内容。它可以是可选作用域。以下部分中的示例演示了默认插槽作用域的使用

可以通过 body-class 属性向正文部分应用任意类。

默认情况下，<b-sidebar> 具有一个带有可选标题和关闭按钮的页眉。你可以通过 title 属性或通过可选作用域槽 title 提供标题。

如果你想提供一个完全自定义的页眉，可以使用可选作用域 header 槽。

你可以通过 header-class 属性将任意类应用到页眉部分，以覆盖默认填充等。

隐藏默认页眉

你可以通过 no-header 属性禁用默认页眉（包括关闭按钮）。请注意，你需要提供一种关闭侧边栏的方法。default 槽具有作用域，其中包括可用于关闭侧边栏的 hide() 方法。

<template>
  <div>
    <b-button v-b-toggle.sidebar-no-header>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-no-header" aria-labelledby="sidebar-no-header-title" no-header shadow>
      <template #default="{ hide }">
        <div class="p-3">
          <h4 id="sidebar-no-header-title">Custom header sidebar</h4>
          <p>
            Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
            in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
          </p>
          <nav class="mb-3">
            <b-nav vertical>
              <b-nav-item active @click="hide">Active</b-nav-item>
              <b-nav-item href="#link-1" @click="hide">Link</b-nav-item>
              <b-nav-item href="#link-2" @click="hide">Another Link</b-nav-item>
            </b-nav>
          </nav>
          <b-button variant="primary" block @click="hide">Close Sidebar</b-button>
        </div>
      </template>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-no-header.vue -->

<b-sidebar> 提供一个 footer 槽（可选作用域），允许你在侧边栏底部提供内容。footer 槽具有作用域，其中包括可用于关闭侧边栏的 hide() 方法。

<template>
  <div>
    <b-button v-b-toggle.sidebar-footer>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-footer" aria-label="Sidebar with custom footer" no-header shadow>
      <template #footer="{ hide }">
       <div class="d-flex bg-dark text-light align-items-center px-3 py-2">
        <strong class="mr-auto">Footer</strong>
        <b-button size="sm" @click="hide">Close</b-button>
       </div>
      </template>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-footer.vue -->

你可以通过 footer-class 属性将任意类应用到页脚部分。

延迟渲染

在某些情况下，你可能不希望在侧边栏不可见时渲染内容。只需在 <b-sidebar> 上设置 lazy 属性。当 lazy 为 true 时，无论何时关闭侧边栏，都不会渲染正文和可选页脚（从 DOM 中删除）。

背景

2.12.0+

通过 backdrop 属性在侧边栏打开时添加一个基本背景。当设置为 true 时，侧边栏将显示一个不透明背景。除非 no-close-on-backdrop 属性设置为 true，否则单击背景将关闭侧边栏。

或者（从 BootstrapVue v2.15.0+ 开始），你可以使用 backdrop-variant 属性来控制背景的主题颜色变体。默认背景变体为 dark。

<template>
  <div>
    <b-button v-b-toggle.sidebar-backdrop>Toggle Sidebar</b-button>

    <b-sidebar
      id="sidebar-backdrop"
      title="Sidebar with backdrop"
      :backdrop-variant="variant"
      backdrop
      shadow
    >
      <div class="px-3 py-2">
        <b-form-group label="Backdrop variant" label-for="backdrop-variant">
          <b-form-select id="backdrop-variant" v-model="variant" :options="variants"></b-form-select>
        </b-form-group>
      </div>
    </b-sidebar>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        variant: 'dark',
        variants: [
          'transparent',
          'white',
          'light',
          'dark',
          'primary',
          'secondary',
          'success',
          'danger',
          'warning',
          'info',
        ]
      }
    }
  }
</script>

<!-- b-sidebar-backdrop.vue -->

请注意，当侧边栏打开时，仍然有可能滚动主体（与模态框的行为不同）。当启用背景时，焦点约束将尝试将焦点保持在侧边栏内。请注意，在极少数情况下，用户有可能将焦点移动到侧边栏外部的元素。

可见性控制

`v-b-toggle` 指令

使用 v-b-toggle 指令是打开侧边栏的首选方法，因为它会自动处理在触发元素上应用 aria-controls 和 aria-expanded 可访问性属性。

本页的大多数示例都使用 v-b-toggle 指令。

`v-model`

v-model 反映侧边栏的当前可见性状态。虽然它可以用来控制侧边栏的可见性状态，但建议使用 v-b-toggle 指令来显示侧边栏，以满足可访问性要求。如果你确实使用 v-model 来显示侧边栏，你应该在触发元素上放置 aria-controls="id" 属性（其中 id 是侧边栏的 ID），并将 aria-expanded 属性（也在触发元素上）设置为字符串 'true'（如果侧边栏打开）或 'false'（如果侧边栏关闭）。

v-model 在内部绑定到 visible 属性，而 change 事件更新 v-model。

在 $route 更改时关闭

默认情况下，<b-sidebar> 将在 $route 更改时自行关闭（包括查询和哈希的完整路径）。如果侧边栏放置在 <router-view> 之外并用于导航，这可能会特别方便。

你可以通过将 no-close-on-route-change 属性设置为 true 来禁用此行为。

事件

侧边栏将在打开后发出 shown 事件，并在关闭后发出 hidden 事件。

change 事件用于更新 v-model，并且在侧边栏的可见性状态发生变化时发出。

辅助功能

<b-sidebar> 提供了多种辅助功能。

当侧边栏打开时，整个侧边栏将获得焦点，这对于屏幕阅读器和仅使用键盘的用户来说是理想的。当侧边栏关闭时，在侧边栏打开之前具有焦点的元素将重新获得焦点。

在某些情况下，您可能需要完全禁用强制焦点功能。您可以通过设置 prop no-enforce-focus 来执行此操作，尽管出于辅助功能原因，通常不建议这样做。

当侧边栏打开时，用户可以按 Esc 关闭侧边栏。要禁用此功能，请将 no-close-on-esc prop 设置为 true。启用背景时，您可以使用 prop no-close-on-backdrop 禁用在背景上单击关闭的功能。

当 backdrop prop 为 true 时，侧边栏将尝试在侧边栏内限制焦点，并且侧边栏将具有属性 aria-modal="true"。

当您隐藏标题或没有侧边栏标题时，将 aria-label 设置为描述侧边栏的字符串，或将 aria-labelledby 设置为包含标题的元素的 ID。当使用 lazy prop 并且没有标题时，使用 aria-label prop 为侧边栏提供一个合适的字符串标签。

实现说明

BootstrapVue 的自定义 SCSS/CSS 对于侧边栏的正确样式和定位是必需的。

Bootstrap v4 背景（'bg-*'）和文本（'text-*'）实用程序类分别用于控制背景和字体颜色。

<b-sidebar> 的一些默认样式可以通过使用 SASS 变量进行自定义。有关其他详细信息，请参阅主题文档。

另请参阅

组件参考

v2.10.0+

查看源代码

<b-sidebar> 属性
<b-sidebar> v-model
<b-sidebar> 插槽
<b-sidebar> 事件

所有属性默认值均可全局配置。

属性 (点击按升序排列)	类型 (点击按升序排列)	默认值	描述
`aria-label`	`字符串`		设置渲染元素上 `aria-label` 属性的值
`aria-labelledby`	`字符串`		为该组件提供标签的元素的 ID。用作 `aria-labelledby` 属性的值
`backdrop` v2.12.0+	`布尔值`	`false`	当为 `true` 时，侧边栏打开时显示一个背景
`backdrop-variant` v2.15.0+	`字符串`	`'dark'`	侧边栏背景的主题变体颜色。默认为“dark”
`bg-variant`	`字符串`	`'light'`	侧边栏背景的主题变体颜色
`body-class`	`Array` 或 `Object` 或 `String`		应用于侧边栏主体（默认插槽）的类或类
`close-label`	`字符串`		应用于内置关闭按钮的 `aria-label`。默认为“关闭”
`footer-class`	`Array` 或 `Object` 或 `String`		应用于可选 `footer` 插槽的类或类
`footer-tag` v2.22.0+	`字符串`	`'footer'`	指定要渲染的 HTML 标签，而不是页脚的默认标签
`header-class`	`Array` 或 `Object` 或 `String`		应用于内置页眉的类或类。如果设置了 prop `no-header`，则不起作用
`header-tag` v2.22.0+	`字符串`	`'header'`	指定要渲染的 HTML 标签，而不是页脚的默认标签
`id`	`字符串`		用于设置渲染内容上的 `id` 属性，并用作根据需要生成任何其他元素 ID 的基础
`lazy`	`布尔值`	`false`	当设置为 `true` 时，侧边栏的内容仅在侧边栏打开时才渲染
`no-close-on-backdrop` v2.12.0+	`布尔值`	`false`	当设置为 `true` 时，禁用用户单击背景时关闭侧边栏。要求设置 prop `backdrop`
`no-close-on-esc`	`布尔值`	`false`	设置为 `true` 时，禁用在用户按下 ESC 时关闭侧边栏
`no-close-on-route-change`	`布尔值`	`false`	设置为 `true` 时，禁用在路由更改时关闭侧边栏
`no-enforce-focus` v2.17.0+	`布尔值`	`false`	禁用强制聚焦例程，该例程在侧边栏内保持焦点
`no-header`	`布尔值`	`false`	设置为 `true` 时，禁用渲染默认标题（包括关闭按钮）
`no-header-close`	`布尔值`	`false`	设置为 `true` 时，禁用渲染标题关闭按钮
`no-slide`	`布尔值`	`false`	设置时，禁用默认滑动动画
`right`	`布尔值`	`false`	当为 `true` 时，将侧边栏定位在视口的右侧
`shadow`	`Boolean` 或 `String`	`false`	设置为布尔值 `true` 表示中等阴影，“sm”表示小阴影，“lg”表示大阴影，或者布尔值 `false` 表示无阴影。默认值为无阴影
`sidebar-class` v2.12.0+	`Array` 或 `Object` 或 `String`		应用于侧边栏内容包装器的类或类
`tag`	`字符串`	`'div'`	指定要渲染的 HTML 标签，而不是默认标签
`text-variant`	`字符串`	`'dark'`	侧边栏文本的主题变体颜色
`title`	`字符串`		放置在默认标题中的文本内容。`title` 插槽优先
`visible` v-model	`布尔值`	`false`	当为 `true` 时，打开侧边栏。这是 `v-model`
`width`	`字符串`		侧边栏的 CSS 宽度。默认为 SCSS/CSS 定义的“320px”
`z-index`	`Number` 或 `String`		指定一个任意 z-index 值以覆盖 SCSS/CSS 定义的值

属性	事件
`visible`	`change`

名称	作用域	描述
`default`		放置在侧边栏主体中的内容
`footer`		放置在可选页脚中的内容
`header` v2.21.0+		放置在标题中的内容
`header-close`	否	标题关闭按钮的内容。默认为 `<b-icon-x>`
`title`		内置标题中要放置的内容。优先于 `title` 属性

事件	参数	描述
`change`	`visible` - 如果侧边栏打开，则为 `true`，如果关闭（或正在关闭），则为 `false`	每当侧边栏的可见性发生变化时都会发出。用于更新 `v-model`
`hidden`		在侧边栏被隐藏时发出
`shown`		在侧边栏打开时发出

导入单个组件

你可以通过以下命名导出将单个组件导入到你的项目中

组件	命名导出	导入路径
`<b-sidebar>`	`BSidebar`	`bootstrap-vue`

示例

import { BSidebar } from 'bootstrap-vue'
Vue.component('b-sidebar', BSidebar)

作为 Vue.js 插件导入

此插件包含上面列出的所有单个组件。插件还包括任何组件别名。

命名导出	导入路径
`SidebarPlugin`	`bootstrap-vue`

此插件还自动包含以下插件

VBTogglePlugin

示例

import { SidebarPlugin } from 'bootstrap-vue'
Vue.use(SidebarPlugin)

概述

样式

标题

放置

变体

阴影

边框

宽度

填充

禁用幻灯片过渡

Z 轴索引

作用域默认插槽

页眉

隐藏默认页眉

页脚

延迟渲染

背景

可见性控制

v-b-toggle 指令

v-model

在 $route 更改时关闭

事件

辅助功能

实现说明

另请参阅

组件参考

属性

v-model

插槽

事件

导入单个组件

作为 Vue.js 插件导入

`v-b-toggle` 指令

`v-model`

`v-model`