冒泡推送(Toasts)

使用 <b-toast><b-toaster>组件,可轻松便利推送通知给访客,快速生成警报信息。

Toast是一种轻量级通知,一般是已被推送的通知,通过移动和桌面操作系统普及。

Toasts 会对访问者或用户造成小干扰,因此应该尽量少包含非交互式内容。有关重要的使用信息,请参阅下面的Accessibility tips部分。

Overview

为了促进可扩展和可预测的toast,我们建议提供一个header(title)和body。Toast头使用'display: flex'样式,由于Bootstrap的margin and flexbox utility classes,允许轻松对齐内容。

Toasts有点半透明,它们融合了所有可能出现的东西。对于支持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的进度,而不是将其传输到<b-toaster>目标容器。 并且,我们在外部<div>中添加了bg-secondary类和progress-bar-striped类,仅用于说明toast透明度。

Toast 功能和注意事项

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

BootstrapVue使用PortalVue将toasts传送到toasters中。

Toasts 需求

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

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

  • message: toast主体的内容(字符串或VNodes数组)。必填的。将不会显示带有空消息的Toasts。有关将VNodes数组作为消息传递的示例,请参阅Advanced usage部分。
  • options: 用于提供标题和/或附加配置选项的可选选项对象。title选项可以是字符串或VNodes数组

options参数接受<b-toast>组件以camelCase name格式而不是kebab case格式接受的大多数道具(staticvisible的除外)。

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

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

Notes:

  • 只有在使用完整的BootstrapVue插件或ToastPlugin插件时,this.$bvToast注入才可用。如果只导入b-toastb-toaster组件,则此选项不可用。要导入$bvToast注入,请使用BVToastPlugin插件。
  • 为每个Vue虚拟机实例(即每个实例化的组件)创建一个新的$bvToast注入(mixin),不能通过直接访问Vue.prototype来使用,因为它需要访问实例的this$root上下文。
  • 通过this生成的this.$bvToast.toast()是调用this.$bvToast.toast()方法的Vue实例的子级,如果该Vue实例(即您的组件或应用程序)也被销毁,则该实例将被隐藏并销毁。如果vm上下文位于<router-view>中,并且$route发生更改,toast也将被销毁(因为<router-view>的所有子节点都被销毁)。若要使按需烤面包机在路由器$route更改之间保持不变,请使用此this.$root.$bvToast.toast()将烤面包的父级设置为应用程序的根。
  • Toasts需要消息。带有空消息的Toasts将不会显示。

Options 选项

Toasts有多种选择,可以控制他们的风格和行为。选项既可用作<b-toast>组件的道具,也可用作传递给this.$bvToast.toast()的Options对象的属性。将选项传递到this.$bvToast.toast()时,请使用组件属性名称的camelCase版本,即使用noAutoHide而不是 no-auto-hide

Title 标题

通过title选项为您的toast添加标题title。就像toast消息message一样,标题可以是一个简单的字符串,也可以是一个VNodes数组。有关将vnode数组作为消息和标题传递的示例,请参见Advanced usage部分。

Transparency 透明度

默认情况下,Toasts的背景是半透明的。若要禁用默认透明度,只需将solid属性设置为true即可从背景色中移除alpha通道。

使用SCSS文件而不是CSS文件时,还可以通过BootstrapVue自定义SCSS变量$b-toast-background-opacity更改透明度。请参阅Theming参考部分。

Variants

BootstrapVue toasts提供自定义CSS来定义颜色变量。变量遵循标准引导v4变量名。如果您有自定义的SCSS定义的引导颜色主题变量,toast自定义SCSS将自动为您创建toast变量(请参阅Theming参考部分)。

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

Toaster target

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>

Notes:

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

Prepend and append 前置和附加

Toasts默认按创建顺序将自己放置在指定Toasts中显示的Toasts顶部。要在底部附加新的toast,请将append-toast属性设置为true

Auto-hide 自动隐藏

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

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

Toast roles 角色

Toasts的默认role属性为'alert',而aria-live属性为'assertive'。 对于需要临时通知的toasts,将is-status道具设置为true,这将分别将rolearia-live属性分别更改为 'status''polite'

有关详细信息,请参阅下面的Accessibility部分。

可选地分别通过href和to props将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>

<b-toast> component 部件

如果有一个自定义组件希望一次只显示一个toast,请使用<b-toast>组件。<b-toast>组件可以放置在自定义组件或应用程序中的任何位置,并且不呈现元素(它们呈现不会影响布局的注释占位符节点)。

toast可以通过v-model(绑定到visible prop)显示,或者使用组件的show()hide()实例方法显示,或者通过this.$bvToast.show(id)this.$bvToast.hide(id)方法显示(要求在<b-toast>组件上设置唯一的id)。

默认情况下,Toasts将进入b-toaster-top-right<b-toaster>组件。如果文档中不存在由toaster属性指定的toaster,则会根据需要创建该toaster。

通过将static prop设置为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 v-slot: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-title: 替换默认标题元素的内容。
  • default: toast的内容

两个插槽的作用域可选为以下作用域:

Method or property 方法或性质 Description 说明
hide() 被调用时隐藏吐司,如果您提供自己的关闭按钮,效果会很不错。

只有在使用<b-toast>组件时,插槽才可用。

<b-toaster> target component 目标组件

<b-toaster>组件提供了一个将出现toasts的容器(Toaster)。Toaster需要一个唯一的名称,Toaster可以出现在一个特定的命名Toaster。

在大多数情况下,您不需要直接使用此组件,因为如果在文档中找不到所需的烤面包机名称,则<b-toast>将自动插入一个<b-toaster>组件(附加到<body>)。但有时你可能想明确地在你的应用中放置一个toaster。

Toaster name将成为插入容器的ID,并将在呈现的toaster容器上使用类名。

Toaster的定位和Toaster内部的定位完全由CSS类(基于Toaster的名称)驱动。

BootstrapVue的自定义scs中定义了以下“内置”toaster名称(以及相关样式):

  • 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

上面的toasters将toasts以堆叠(柱形)的形式放置,固定在视口中(这意味着无论视口滚动位置如何,它们都将始终在视图中)。如果有超过视窗屏幕所能容纳的toasts,一些toasts将被视为隐藏在屏幕外,直到其他toasts被关闭/隐藏。

<b-toast>默认使用b-toaster-top-righttoaster。

Notes:

  • 如果文档中已存在同名的<b-toaster>(由<b-toast>this.$bvToast.toast()自动创建或手动放置),则<b-toaster>将只呈现空的<div>元素并发出控制台警告。
  • 如果手动放置一个<b-toaster>组件,请确保它作为最后一个元素放置在app根元素的底部,以便应用程序中的所有页面都可以使用它。
  • 如果显示针对Toasters名称的新Toasters,则会自动重新创建被销毁的Toasters。
  • 在大多数用例中,您不需要在应用程序中手动放置/创建<b-toaster>组件,因为它们将根据需要自动生成。但如果需要覆盖任何toaster默认设置,请确保将应用程序中的toaster放置在不会因路由更改而被破坏的位置。

Advanced usage 高级使用

当使用this.$bvToast.toast(...)方法生成toast时,您可能希望toast内容不仅仅是一个字符串消息。如上所诉,您可以将VNodes数组作为消息和标题传递给更复杂的内容。

切记toast的内容要简明扼要。避免将交互组件或元素放置在toasts中,因为这可能会给辅助技术的用户带来问题。请参阅下面的无障碍部分。

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

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

<script>
  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      popToast() {
        // 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>

Alerts versus toasts

在某些情况下,您可能只需要一个简单的警报样式消息(即cookie使用通知等)。在这些情况下,通过在<b-alert>组件上应用一些引导 使用程序类和少量自定义样式,通常最好使用固定位置警报而不是toast:

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

我们使用类位置固定来设置用户视窗内的固定位置,并且类固定底部固定顶部来将警报定位在视窗的底部或顶部。类m-0删除警报周围的默认边距,rounded-0删除默认圆角。我们还将z-index设置为一个大值,以确保警报出现在页面上的任何其他内容上(fixed-topfixed-bottom的默认值是1030)。您可能需要为您的特定布局调整z-index

由于警报标记保留在放置<b-alert>组件的DOM中,因此屏幕阅读器和仅使用键盘的用户可以轻松访问其标签序列(用于访问关闭按钮)。

Accessibility

Toasts是为了给你的访客或用户带来小小的干扰,所以为了帮助那些有屏幕阅读器和类似辅助技术的用户,祝酒被包裹在一个aria live区域中。对活动区域的更改(例如注入/更新toast组件)由屏幕阅读器自动宣布,而无需移动用户的焦点或以其他方式中断用户。此外,aria-atomic="true"被自动设置为确保整个toast始终作为单个(原子)单元宣布,而不是宣布更改的内容(如果您只更新toast的部分内容,或者在稍后的时间点显示相同的toast内容,则可能导致问题)。

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

Accessibility tips

通常,toast消息应该显示一行或两行不需要用户交互的非关键消息。如果不采取额外的措施,toasts会有许多无障碍问题,可能会产生影响。下面的列表虽然不完整,但提供了使用toasts时的一般指南。

  • 如果所需信息对流程很重要,例如表单中的错误列表,则使用<b-alert>组件而不是<b-toast>
  • <b-toast>默认情况下,将attributes role设置为'alert',将aria-live设置为'assertive'。如果是错误之类的重要消息,则此默认设置是适当的,否则将prop is-status设置为true,这会将attributes role更改为'status'aria-live更改为'polite'
  • 避免在页面加载时弹出toast消息。在页面加载时执行意外操作对于屏幕阅读器用户来说非常混乱。如果在页面加载或路由更改时需要toast,请延迟几秒钟显示toast,以便屏幕阅读器在toast不中断的情况下完成当前页面的信息发布。
  • 将prop no-auto-hide设置为true时,必须有一个“关闭”按钮,以允许用户解除toast。如果您还将prop no-close-button设置为true,则必须提供自己的close按钮或通过其他方式解除toast。Toasts的标签索引为0,因此只能由键盘用户访问。
  • 避免快速连续地启动许多toast,因为屏幕阅读器可能会中断当前祝酒词的阅读并宣布新的toast,从而导致错过上一个toast的上下文。
  • 对于文本内容较长的toast,请将自动隐藏延迟调整为较大的超时,以便用户有时间阅读toast的内容。一个很好的保持信息的时间长度是4秒加上每100个单词额外1秒,四舍五入。这大概是普通人阅读的速度。这意味着作为最佳实践应该使用的最短默认值是5秒(5000ms)。除了一个合理的默认超时之外,您还可以允许用户选择他们希望toast的时间。大多数人天生就知道自己是快读者还是慢读者。如果用户登录时有一个配置文件设置,则当消息消失得太快时,慢速读卡器可以选择更长的时间,而当消息停留得太久时,快速读卡器可以选择较短的时间。
  • 为了解释记忆丧失、注意力分散以及与丢失相关的问题,例如ADHD,最佳实践是实现一个位置,用户可以在该位置引用已显示的过去祝酒词消息列表。最好这个列表应该是可排序的,默认是按时间顺序排列的。

Internet Explorer screen reader support 屏幕阅读器支持

不幸的是,IE 11在与NVDAJAWS屏幕阅读器一起使用时,出现时不会正确地宣布/语音toast。如果使用IE 11的用户群很大,则可能需要为IE 11浏览器(在页面加载时创建)创建一个附加的屏幕外aria-live区域,其中除了显示toast外,还动态放置toast消息文本的副本。

组件引用

<b-toast>

属性

属性 (Click to sort Ascending) 类型 默认值 描述
id String 用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础
title String toast的标题文本
toaster String 'b-toaster-top-right' 要在其中呈现toast的toaster目标的名称
visible v-model Boolean false 如果是真的,显示toast
variant String 将一个引导主题颜色变体应用于组件
is-status Boolean false 当设置为“true”时,使toast具有aria live=polite和role=status。当“false”aria live变为“assertive”时,role变为“alert”
append-toast Boolean false 如果为true,则toast将附加到可见的toast的底部,否则将预先准备好
no-auto-hide Boolean false 设置后,将禁止toast自动解除其自身
auto-hide-delay Number or String 5000 toast自动解除其自身之前的毫秒数
no-close-button Boolean false 设置后,隐藏toast标题中的“关闭”按钮
no-fade Boolean false 当设置为“true”时,禁用组件上的淡入动画/过渡
no-hover-pause Boolean false 设置后,当鼠标悬停toast时禁用自动隐藏延迟的暂停
solid Boolean false 设置后,使用纯色背景而不是半透明背景渲染toast
toast-class String or Object or Array 要添加到toast包装器元素的CSS类
header-class String or Object or Array 添加到toast header元素的CSS类
body-class String or Object or Array 添加到toast body元素的CSS类
href String 表示标准a链接的链接的目标URL
to String or Object 路由器链接属性:表示链接的目标路由。单击时,to prop的值将在内部传递给router.push(),因此该值可以是字符串或位置描述符对象
static Boolean false 在DOM中就地呈现组件的内容,而不是将其移植到body元素中

<b-toast>支持生成<router-link><nuxt-link>组件(如果使用nuxt.js)。有关路由器链接(或nuxt链接)特定属性的更多详细信息,请参阅路由器支持参考部分。

v-model

属性 事件
visible change

插槽

插槽名称 描述 范围
toast-title Toast标题,可选范围
default Toast身体内容物。可选范围。事件。

事件

事件 参数 描述
change
  1. visible - true if toast is visible, false otherwise.
Toast可见性状态。用于更新v模型。
show
  1. bvEvt - BvEvent object.
总是在toast前发出。
shown
  1. bvEvt - BvEvent object.
toast时总是发出。
hide
  1. bvEvt - BvEvent object.
总是在toast隐藏起来之前发出。
hidden
  1. bvEvt - BvEvent object.
toast被藏起来后总是发出

<b-toaster>

Properties

属性 Type Default Description
name Required String toaster的目标名称
aria-live String 当呈现的元素是aria活动区域(对于屏幕阅读器用户)时,设置为'polite'或'assertive'
aria-atomic String 当屏幕阅读器应读出全部内容(设置为字符串“true”)或仅读出更改(设置为字符串“false”)。大多数情况下留空
role String 将ARIA属性“role”设置为特定值

导入单个组件

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

组件 命名输出 导入路径
<b-toast> BToast bootstrap-vue
<b-toaster> BToaster bootstrap-vue

示例:

import { BToast } from 'bootstrap-vue'
Vue.component('b-toast', BToast)

导入为Vue.js插件

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

命名输出 导入路径
ToastPlugin bootstrap-vue

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

  • BVToastPlugin

示例:

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