吐司

Toast 是轻量级通知，旨在模仿移动和桌面操作系统中流行的推送通知。

Toast 旨在对您的访客或用户造成轻微中断，因此应包含最少、切中要点且无交互性的内容。请参阅下方的 无障碍提示 部分，了解重要的使用信息。

概述

为了鼓励可扩展且可预测的 Toast，我们建议提供标题和正文。Toast 标题使用样式 'display: flex'，借助 Bootstrap 的 边距和 flexbox 实用程序类，可以轻松对齐内容。

Toast 也略微透明，因此它们会与可能出现的任何内容融合在一起。对于支持 backdrop-filter CSS 属性的浏览器，它们还会尝试模糊 Toast 下方的元素。

<template>
  <div class="p-3 bg-secondary progress-bar-striped" style="min-height: 170px;">
    <b-button class="mb-2" variant="primary" @click="$bvToast.show('example-toast')">
      Show toast
    </b-button>
    <b-toast id="example-toast" title="BootstrapVue" static no-auto-hide>
      Hello, world! This is a toast message.
    </b-toast>
  </div>
</template>

<!-- toast-intro.vue -->

注意：我们在上面的示例中使用 static 属性在文档中就地呈现 Toast，而不是将其传输到 <b-toaster> 目标容器。并且我们已将类 bg-secondary 和 progress-bar-striped 添加到外部 <div>，仅为说明 Toast 透明度。

Toast 功能和说明

• 可以通过注入 this.$bvToast 对象按需生成 Toast，或使用 <b-toast> 组件手动创建。
• 标题是可选的，但应包括在内，标题在 <strong> 元素内呈现，除非使用 toast-title 插槽。
• 可以通过 no-close-button 属性移除 Toast 右上角的关闭按钮。
• 将显示标题栏，除非您不提供标题并设置 no-close-button 属性。
• 自动隐藏在 5000 毫秒后发生，可以通过 auto-hide-delay 属性进行更改，或通过 no-auto-hide 属性禁用。
• 当启用自动隐藏时，当您将鼠标悬停在 Toast 上时，自动隐藏倒计时将暂停。您可以通过将 no-hover-pause 属性设置为 true 来禁用此功能。
• 如果您禁用了自动隐藏功能，请避免隐藏关闭按钮，或者如果您隐藏关闭按钮，请确保允许 Toast 自动关闭。请参阅下方的 无障碍提示 部分，了解重要的使用信息。
• 可以通过将 solid 属性设置为 true 来禁用 Toast 透明度。
• Toast 将显示在命名的 <b-toaster> 目标组件内。BootstrapVue 带有几个预定义的吐司目标。Toast 将在显示之前检查文档中命名的吐司，如果找不到，将动态创建命名的吐司目标。
• 吐司目标完全由 CSS 定义，用于控制包含的 <b-toast> 组件的位置。
• Toast 可以针对任何命名的吐司。
• Toast 被包装在具有类 b-toast 的 <div> 中，以在吐司组件中显示时允许 Vue 列表转换支持。

BootstrapVue 使用 PortalVue 将 Toast 传输到吐司机中。

按需 Toast

通过 this.$bvToast Vue 组件实例注入，从应用程序中的任何位置生成动态 Toast，而无需在应用程序中放置 <b-toast> 组件。

使用 this.$bvToast.toast() 方法生成按需 Toast。该方法接受两个参数

• message: Toast 正文的内容（字符串或 VNodes 数组）。必需。消息为空的 Toast 将不会显示。有关将 VNodes 数组作为消息传递的示例，请参阅 高级用法 部分。
• options: 一个可选的选项对象，用于提供标题和/或其他配置选项。 title 选项可以是字符串或 VNodes 数组

options 参数接受 <b-toast> 组件接受的大多数属性（static 和 visible 除外），采用 camelCase 名称格式，而不是 kebab-case。

<template>
  <div>
    <b-button @click="makeToast()">Show Toast</b-button>
    <b-button @click="makeToast(true)">Show Toast (appended)</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        toastCount: 0
      }
    },
    methods: {
      makeToast(append = false) {
        this.toastCount++
        this.$bvToast.toast(`This is toast number ${this.toastCount}`, {
          title: 'BootstrapVue Toast',
          autoHideDelay: 5000,
          appendToast: append
        })
      }
    }
  }
</script>

<!-- toasts-bv-toast-example.vue -->

使用 this.$bvToast.toast() 生成的 Toast 被隐藏后，它将自动被销毁并从文档中删除。

注意

• 仅在使用完整的 BootstrapVue 插件或 ToastPlugin 插件时，才可以使用 this.$bvToast 注入。如果仅导入 b-toast 或 b-toaster 组件，则无法使用它。要仅导入 $bvToast 注入，请使用 BVToastPlugin 插件。
• 为每个 Vue 虚拟机实例（即每个实例化组件）创建了一个新的 $bvToast 注入（混合），并且无法通过直接访问 Vue.prototype 来使用它，因为它需要访问实例的 this 和 $root 上下文。
• 通过 this.$bvToast.toast() 生成的 Toast 是调用 this.$bvToast.toast() 方法的 Vue 实例的子项，并且如果该 Vue 实例（即您的组件或应用程序）也被销毁，它们将被隐藏并销毁。如果 vm 上下文位于 <router-view> 中，并且 $route 发生更改，则 Toast 也将被销毁（因为 <router-view> 的所有子项都将被销毁。要使按需 Toast 在路由 $route 更改后仍然存在，请改用 this.$root.$bvToast.toast()，以便将 Toast 的父项设为您的应用程序的根目录。
• Toast 需要一条消息。按需显示的 Toast 如果没有消息，则会静默地不显示。

选项

Toast 具有各种选项，可以控制它们的样式和行为。选项既可用作 <b-toast> 组件上的属性，也可用作传递给 this.$bvToast.toast() 的选项对象的属性。当将选项传递给 this.$bvToast.toast() 时，请使用组件属性名称的 camelCase 版本，即使用 noAutoHide 而不是 no-auto-hide。

标题

通过 title 选项为您的 Toast 添加标题。就像 Toast message 一样，标题可以是简单的字符串，也可以是 VNode 数组。有关将 VNode 数组作为消息和标题传递的示例，请参阅 高级用法 部分。

透明度

默认情况下，Toast 具有半透明背景。若要禁用默认透明度，只需将 solid 属性设置为 true，即可从背景色中移除 Alpha 通道。

当使用 SCSS 文件（而非 CSS 文件）时，还可以通过 BootstrapVue 自定义 SCSS 变量 $b-toast-background-opacity 更改透明度。请参阅 主题 参考部分。

变体

BootstrapVue Toast 提供自定义 CSS 来定义颜色变体。变体遵循标准 Bootstrap v4 变体名称。如果您有自定义的 SCSS 定义的 Bootstrap 颜色主题变体，则 Toast 自定义 SCSS 将自动为您创建 Toast 变体（请参阅 主题 参考部分）。

<template>
  <div>
    <b-button @click="makeToast()" class="mb-2">Default</b-button>
    <b-button variant="primary" @click="makeToast('primary')" class="mb-2">Primary</b-button>
    <b-button variant="secondary" @click="makeToast('secondary')" class="mb-2">Secondary</b-button>
    <b-button variant="danger" @click="makeToast('danger')" class="mb-2">Danger</b-button>
    <b-button variant="warning" @click="makeToast('warning')" class="mb-2">Warning</b-button>
    <b-button variant="success" @click="makeToast('success')" class="mb-2">Success</b-button>
    <b-button variant="info" @click="makeToast('info')" class="mb-2">Info</b-button>
  </div>
</template>

<script>
  export default {
    methods: {
      makeToast(variant = null) {
        this.$bvToast.toast('Toast body content', {
          title: `Variant ${variant || 'default'}`,
          variant: variant,
          solid: true
        })
      }
    }
  }
</script>

<!-- toast-variants.vue -->

Toaster 目标

BootstrapVue 随附以下“内置”Toaster 名称（以及在 SCSS 中定义的相关样式）

• b-toaster-top-right
• b-toaster-top-left
• b-toaster-top-center
• b-toaster-top-full
• b-toaster-bottom-right
• b-toaster-bottom-left
• b-toaster-bottom-center
• b-toaster-bottom-full

<template>
  <div>
    <b-button @click="toast('b-toaster-top-right')" class="mb-2">b-toaster-top-right</b-button>
    <b-button @click="toast('b-toaster-top-left')" class="mb-2">b-toaster-top-left</b-button>
    <b-button @click="toast('b-toaster-top-center')" class="mb-2">b-toaster-top-center</b-button>
    <b-button @click="toast('b-toaster-top-full')" class="mb-2">b-toaster-top-full</b-button>
    <b-button @click="toast('b-toaster-bottom-right', true)" class="mb-2">b-toaster-bottom-right</b-button>
    <b-button @click="toast('b-toaster-bottom-left', true)" class="mb-2">b-toaster-bottom-left</b-button>
    <b-button @click="toast('b-toaster-bottom-center', true)" class="mb-2">b-toaster-bottom-center</b-button>
    <b-button @click="toast('b-toaster-bottom-full', true)" class="mb-2">b-toaster-bottom-full</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        counter: 0
      }
    },
    methods: {
      toast(toaster, append = false) {
        this.counter++
        this.$bvToast.toast(`Toast ${this.counter} body content`, {
          title: `Toaster ${toaster}`,
          toaster: toaster,
          solid: true,
          appendToast: append
        })
      }
    }
  }
</script>

<!-- toast-targets.vue -->

注意

• 在 CSS 中未定义的 Toaster 目标名称将在文档底部呈现，堆叠且未定位（附加到 <body> 中的 <b-toaster>，类名和 ID 设置为 Toaster 目标名称）。Toaster 唯一默认样式是 z-index 为 1100。
• 避免在您的应用程序中同时使用 b-toaster-top-* Toaster 或 b-toaster-bottom-* Toaster，因为在小屏幕（例如 xs）上通知可能会被遮挡/重叠。

前置和后置

Toast 默认将自己前置到指定 Toaster 中显示的 Toast 顶部，按创建顺序排列。若要将新 Toast 附加到底部，请将 append-toast 属性设置为 true。

自动隐藏

通过 auto-hide-delay 属性更改自动隐藏延迟时间（值以毫秒为单位），默认为 5000（最小值 1000）。或者，通过将 no-auto-hide 属性设置为 true，完全禁用自动隐藏功能。

启用自动隐藏时，将鼠标悬停在 Toast 上将暂停自动隐藏计时器。当您将鼠标移出 Toast 时，自动隐藏计时器将恢复。您可以通过将 no-hover-pause 属性设置为 true 来禁用此功能。

关闭按钮

默认情况下，Toast 有一个关闭按钮，可通过点击使用来隐藏它们。将 no-close-button 属性设置为 true 将阻止此操作，并创建一个没有默认关闭按钮的 Toast。

仍然可以通过提供一个唯一 ID 并使用 this.$bvToast.hide(id) 方法来隐藏特定 Toast，为 Toast 创建一个自定义关闭按钮

<template>
  <div>
    <b-button @click="showToast">Show Toast</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      showToast() {
        // Use a shorter name for `this.$createElement`
        const h = this.$createElement
        // Create a ID with a incremented count
        const id = `my-toast-${this.count++}`

        // Create the custom close button
        const $closeButton = h(
          'b-button',
          {
            on: { click: () => this.$bvToast.hide(id) }
          },
          'Close'
        )

        // Create the toast
        this.$bvToast.toast([$closeButton], {
          id: id,
          title: `Toast ${this.count}`,
          noCloseButton: true
        })
      }
    }
 }
</script>

<!-- toasts-advanced.vue -->

Toast 角色

Toast 使用默认 role 属性 'alert' 和 aria-live 属性 'assertive' 渲染。对于用于普通通知的 Toast，将 is-status 属性设置为 true，这将更改 role 和 aria-live 属性，分别为 'status' 和 'polite'。

有关更多信息，请参阅下面的 辅助功能 部分。

链接

可以选择通过 href 和 to 属性将 Toast 正文转换为链接 (<a>) 或 <router-link>（或 <nuxt-link>）。设置后，整个 Toast 正文将变为一个链接。

<template>
  <div>
    <b-button @click="toast()">Toast with link</b-button>
  </div>
</template>

<script>
  export default {
    methods: {
      toast() {
        this.$bvToast.toast(`Toast with action link`, {
          href: '#foo',
          title: 'Example'
        })
      }
    }
  }
</script>

<!-- toast-link.vue -->

<b-toast> 组件

当您有一个自定义组件希望一次只显示一个 Toast 时，请使用 <b-toast> 组件。 <b-toast> 组件可以放置在自定义组件或应用程序中的任何位置，并且不渲染元素（它们渲染一个不会影响布局的注释占位符节点）。

可以通过 v-model（与 visible 属性相关联）使 Toast 可见，或使用组件的 show() 和 hide() 实例方法显示，或通过 this.$bvToast.show(id) 和 this.$bvToast.hide(id) 方法（要求在 <b-toast> 组件上设置一个唯一 ID）。

默认情况下，Toast 会按顺序放入 b-toaster-top-right <b-toaster> 组件中。如果文档中不存在 toaster 属性指定的 toaster，则会按需创建该 toaster。

可以通过将 static 属性设置为 true，强制 <b-toast> 就地显示在文档中。您仍然需要显示和隐藏 toast，但它不会传输到 toaster 组件中。

<template>
  <div>
    <b-button @click="$bvToast.show('my-toast')">Show toast</b-button>

    <b-toast id="my-toast" variant="warning" solid>
      <template #toast-title>
        <div class="d-flex flex-grow-1 align-items-baseline">
          <b-img blank blank-color="#ff5555" class="mr-2" width="12" height="12"></b-img>
          <strong class="mr-auto">Notice!</strong>
          <small class="text-muted mr-2">42 seconds ago</small>
        </div>
      </template>
      This is the content of the toast.
      It is short and to the point.
    </b-toast>
  </div>
</template>

<!-- toast-component.vue -->

插槽

• toast-title：替换默认标题元素的内容。
• default：toast 正文的内容

两个插槽都可选择使用以下范围进行限定

仅在使用 <b-toast> 组件时提供插槽。

<b-toaster> 目标组件

<b-toaster> 组件提供了一个容器，其中将显示 toast（“Toaster”）。Toaster 需要一个唯一名称，并且可以将 toast 定位为显示在特定的命名 toaster 中。

在大多数情况下，您无需直接使用此组件，因为 <b-toast> 会自动插入一个 <b-toaster> 组件（追加到 <body>），其中包含请求的 toaster 名称（如果在文档中找不到该名称）。但有时您可能希望在应用中明确放置一个 toaster。

Toaster name 成为插入容器的 ID，还将用作渲染的 toaster 容器上的类名。

Toaster 的定位和 toaster 内 toast 的定位完全由 CSS 类（基于 toaster 的名称）驱动

以下“内置”toaster 名称（及相关样式）在 BootstrapVue 的自定义 SCSS 中定义

• b-toaster-top-right
• b-toaster-top-left
• b-toaster-top-center
• b-toaster-top-full
• b-toaster-bottom-right
• b-toaster-bottom-left
• b-toaster-bottom-center
• b-toaster-bottom-full

上述的吐司将吐司放置在堆叠（列格式）中，固定在视口中（这意味着它们将始终在视图中，而不管视口滚动位置如何）。如果吐司多于视口屏幕所能容纳的数量，一些吐司将在其他吐司关闭/隐藏之前在视觉上隐藏在屏幕外。

<b-toast> 默认使用 b-toaster-top-right 吐司。

注意

• 如果文档中已经存在一个具有相同名称的 <b-toaster>（由 <b-toast>、this.$bvToast.toast() 自动创建，或手动放置），那么 <b-toaster> 将只渲染一个空的 <div> 元素并发出控制台警告。
• 如果手动放置 <b-toaster> 组件，请确保将其放置在应用根元素底部的最后一个元素中，以便应用中的所有页面都可以使用它。
• 如果针对吐司名称显示的新吐司，则将自动重新创建被销毁的吐司。
• 在大多数用例中，你不应该需要在应用中手动放置/创建 <b-toaster> 组件，因为它们将在需要时按需自动生成。但是，如果你需要覆盖任何吐司默认设置，请确保将吐司放置在应用中不会因路由更改而被销毁的位置。

高级用法

当使用 this.$bvToast.toast(...) 方法生成吐司时，你可能希望吐司内容不仅仅是一个字符串消息。如上文 按需吐司 部分所述，你可以将 VNodes 数组作为消息和标题传递，以获得更复杂的内容。

请记住，吐司内容应简单明了。避免在吐司中放置交互式组件或元素，因为这可能会给辅助技术的用户带来问题。请参阅下文的 无障碍性 部分。

下面是一个使用 Vue 的 this.$createElement() 方法生成更复杂吐司内容的示例

<template>
  <div>
    <b-button @click="showToast">Show Toast with custom content</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      showToast() {
        // Use a shorter name for this.$createElement
        const h = this.$createElement
        // Increment the toast count
        this.count++
        // Create the message
        const vNodesMsg = h(
          'p',
          { class: ['text-center', 'mb-0'] },
          [
            h('b-spinner', { props: { type: 'grow', small: true } }),
            ' Flashy ',
            h('strong', 'toast'),
            ` message #${this.count} `,
            h('b-spinner', { props: { type: 'grow', small: true } })
          ]
        )
        // Create the title
        const vNodesTitle = h(
          'div',
          { class: ['d-flex', 'flex-grow-1', 'align-items-baseline', 'mr-2'] },
          [
            h('strong', { class: 'mr-2' }, 'The Title'),
            h('small', { class: 'ml-auto text-italics' }, '5 minutes ago')
          ]
        )
        // Pass the VNodes as an array for message and title
        this.$bvToast.toast([vNodesMsg], {
          title: [vNodesTitle],
          solid: true,
          variant: 'info'
        })
      }
    }
 }
</script>

<!-- toasts-advanced.vue -->

警报与吐司

在某些情况下，你可能只需要一个简单的警报样式消息（例如，Cookie 使用通知等）。在这些情况下，通常最好使用固定位置警报而不是吐司，方法是在 <b-alert> 组件上应用一些 Bootstrap 实用程序类 和一些自定义样式

<template>
  <div>
    <b-button size="sm" @click="showBottom = !showBottom">
      {{ showBottom ? 'Hide' : 'Show' }} Fixed bottom Alert
    </b-button>
    <b-alert
      v-model="showBottom"
      class="position-fixed fixed-bottom m-0 rounded-0"
      style="z-index: 2000;"
      variant="warning"
      dismissible
    >
      Fixed position (bottom) alert!
    </b-alert>

    <b-button size="sm" @click="showTop = !showTop">
      {{ showTop ? 'Hide' : 'Show' }} Fixed top Alert
    </b-button>
    <b-alert
      v-model="showTop"
      class="position-fixed fixed-top m-0 rounded-0"
      style="z-index: 2000;"
      variant="success"
      dismissible
    >
      Fixed position (top) alert!
    </b-alert>
  </div>
</template>

<script>
export default {
  data() {
    return {
      showBottom: false,
      showTop: false
    }
  }
}
</script>

<!-- fixed-position-alerts.vue -->

我们使用类 position-fixed 将定位设置为固定在用户的视口中，并使用类 fixed-bottom 或 fixed-top 将警报定位在视口的底部或顶部。类 m-0 删除警报周围的默认边距，rounded-0 删除默认圆角。我们还将 z-index 设置为一个较大的值，以确保警报显示在页面上的任何其他内容之上（fixed-top 和 fixed-bottom 的默认值为 1030）。你可能需要根据你的特定布局调整 z-index。

由于警报标记保留在放置 <b-alert> 组件的 DOM 中，因此其标签序列（用于访问关闭按钮）对于屏幕阅读器和仅使用键盘的用户来说很容易访问。

辅助功能

吐司旨在对您的访问者或用户造成轻微的干扰，因此为了帮助那些使用屏幕阅读器和类似辅助技术的人，吐司被包装在 aria-live 区域中。屏幕阅读器会自动播报实时区域的更改（例如注入/更新吐司组件），而无需移动用户的焦点或以其他方式中断用户。此外，aria-atomic="true" 会自动设置，以确保始终将整个吐司作为单个（原子）单元播报，而不是播报已更改的内容（如果您只更新吐司内容的一部分，或者稍后显示相同的吐司内容，这可能会导致问题）。

如果您只需要在用户窗口的底部或顶部显示一条简单的消息，请改用 固定位置 <b-alert>。

辅助功能提示

通常，吐司消息应显示一到两行非关键消息，这些消息不要求用户交互。如果不采取额外措施，吐司可能会出现许多辅助功能问题，这些问题可能会影响残疾人和非残疾人。以下列表虽然不完整，但提供了使用吐司时的通用准则。

• 如果所需的信息对于流程很重要，例如表单中的错误列表，请使用 <b-alert> 组件，而不是 <b-toast>。
• <b-toast> 默认情况下，将属性 role 设置为 'alert'，将 aria-live 设置为 'assertive'。如果它是一条重要消息，例如错误，则此默认设置是合适的，否则将 prop is-status 设置为 true，这将更改属性 role 为 'status'，将 aria-live 设置为 'polite'。
• 避免在页面加载时弹出吐司消息。在页面加载时执行意外操作会让屏幕阅读器用户非常困惑。如果在页面加载或路由更改时需要吐司，请延迟几秒钟显示吐司，以便屏幕阅读器完成播报有关当前页面的信息，而不会被吐司中断。
• 在将 prop no-auto-hide 设置为 true 时，必须有一个关闭按钮，以便用户关闭提示。如果您还将 prop no-close-button 设置为 true，则必须提供您自己的关闭按钮或通过其他方式关闭提示。提示的标签索引为 0，以便仅键盘用户可以访问它们。
• 避免快速连续地启动多个提示，因为屏幕阅读器可能会中断当前提示的阅读并宣布新提示，导致错过前一个提示的上下文。
• 对于具有较长文本内容的提示，将 auto-hide-delay 调整为较长的超时时间，以便用户有时间阅读提示的内容。普通人每分钟阅读约 200 个单词，因此显示消息的最佳时间长度为 5 秒，外加每个单词 300 毫秒。作为最佳实践，应使用的最短默认时间为 5 秒（5000 毫秒）。除了合理的默认超时时间外，您还可以允许用户选择提示显示多长时间。大多数人天生就知道自己是快读者还是慢读者。将个人资料设置作为用户登录的一部分，将允许慢读者在消息消失得太快时选择更长的时间，而快读者在消息显示得太久时选择较短的时间。
• 为了解决记忆力丧失和注意力分散以及与残疾相关的 ADHD 等问题，最佳做法是实现一个位置，用户可以在其中查看已显示的过去提示消息列表。最好此列表是可排序的，默认情况下按时间顺序排列。

Internet Explorer 屏幕阅读器支持

不幸的是，IE 11 在与 NVDA 或 JAWS 屏幕阅读器一起使用时，不会在出现时正确播报/朗读提示。如果您有大量使用 IE 11 的视障用户群，您可能需要为仅限 IE 11 浏览器（在页面加载时创建）创建一个额外的非屏幕 aria-live 区域，除了显示提示之外，还可以动态放置提示消息文本的副本。