弹出模式框(Modal)

Modals是流线型的,但是由JavaScript和CSS提供灵活的对话框提示。它们支持许多用例,从用户通知到完全定制的内容,并具有一些有用的子组件、大小、变体、可访问性等特性。

<div>
  <b-button v-b-modal.modal-1>Launch demo modal</b-button>

  <b-modal id="modal-1" title="BootstrapVue">
    <p class="my-4">Hello from modal!</p>
  </b-modal>
</div>

概述

<b-modal>在默认情况下,在页脚中有一个确认取消按钮。 可以通过在组件上设置各种属性来自定义这些按钮。您可以自定义按钮的大小、禁用按钮、隐藏取消按钮(即ok-only), 使用ok 变量cancel 变量属性选择变量(如红色“确定”按钮有危险), 使用ok 标题cancel 标题属性提供自定义按钮内容,或使用命名的插槽modal-okmodal-cancel

<b-modal>支持按ESC键关闭(默认启用)、 按背景关闭(默认启用)和页眉中的X关闭按钮(默认启用)。 通过分别设置“在esc上不关闭属性”, “在背景上不关闭属性”, 和 “隐藏标题关闭属性”,可以禁用这些功能。

您可以通过命名的槽 modal-title覆盖模式标题, 通过modal-header槽完全覆盖页眉, 并通过modal-footer槽完全覆盖页脚。

注意: 使用modal-footer 槽时,默认的确定 and 取消按钮将不存在。 此外,如果使用modal-header槽,则默认标题X关闭按钮将不存在, 也不能使用modal-title槽。

Modals不会在文档中呈现它们的内容,除非它们被显示(延迟呈现)。当Modals可见时,它将被附加到<body>元素中<b-modal>组件的位置不会影响布局, 因为它始终呈现为占位符注释节点(<!---->). 您可以通过使用static属性恢复到以前BootstrapVue版本的行为。

切换模式可见性

有几种方法可用于切换<b-modal>的可见性。

使用 v-b-modal 命令

其他元素可以使用v-b-modal 指令轻松显示模式。

<div>
  <!-- Using modifiers -->
  <b-button v-b-modal.my-modal>Show Modal</b-button>

  <!-- Using value -->
  <b-button v-b-modal="'my-modal'">Show Modal</b-button>

  <!-- The modal -->
  <b-modal id="my-modal">Hello From My Modal!</b-modal>
</div>

一旦模式关闭,此方法将自动将焦点返回到触发器元素(类似于默认的引导功能)。用于切换模式可见性的其他方法可能需要额外的代码来实现此可访问性功能。

有关详细信息,请参见下面的可访问性功能部分。

使用 this.$bvModal.show()this.$bvModal.hide()实例方法

当BootstrapVue作为插件安装或使用ModalPlugin插件时, BootstrapVue将向每个Vue实例(组件、应用程序)注入$bvModal对象。

方法 描述
this.$bvModal.show(id) 显示具有指定id的模式
this.$bvModal.hide(id) 隐藏具有指定id的模式

两个方法在被调用后立即返回。

<div>
  <b-button id="show-btn" @click="$bvModal.show('bv-modal-example')">Open Modal</b-button>

  <b-modal id="bv-modal-example" hide-footer>
    <template v-slot:modal-title>
      Using <code>$bvModal</code> Methods
    </template>
    <div class="d-block text-center">
      <h3>Hello From This Modal!</h3>
    </div>
    <b-button class="mt-3" block @click="$bvModal.hide('bv-modal-example')">Close Me</b-button>
  </b-modal>
</div>

this.$bvModal对象还用显示模式消息框

使用 show(), hide(), 和 toggle()组件方法

可以使用ref属性访问modal,然后调用show(), hide()toggle()方法。

<template>
  <div>
    <b-button id="show-btn" @click="showModal">Open Modal</b-button>
    <b-button id="toggle-btn" @click="toggleModal">Toggle Modal</b-button>

    <b-modal ref="my-modal" hide-footer title="Using Component Methods">
      <div class="d-block text-center">
        <h3>Hello From My Modal!</h3>
      </div>
      <b-button class="mt-3" variant="outline-danger" block @click="hideModal">Close Me</b-button>
      <b-button class="mt-2" variant="outline-warning" block @click="toggleModal">Toggle Me</b-button>
    </b-modal>
  </div>
</template>

<script>
  export default {
    methods: {
      showModal() {
        this.$refs['my-modal'].show()
      },
      hideModal() {
        this.$refs['my-modal'].hide()
      },
      toggleModal() {
        // We pass the ID of the button that we want to return focus to
        // when the modal has hidden
        this.$refs['my-modal'].toggle('#toggle-btn')
      }
    }
  }
</script>

hide()方法接受一个可选的字符串trigger器参数, 用于定义触发模式关闭的内容。有关详细信息,请参阅下面的“防止关闭”部分。

注意: 建议使用this.$bvModal.show()this.$bvModal.hide()()方法(在上一节中提到),而不要使用$ref方法。

使用 v-model 属性

v-model属性总是与<b-modal> 可见状态自动同步, 您可以使用v-model显示/隐藏。

<template>
  <div>
    <b-button @click="modalShow = !modalShow">Open Modal</b-button>

    <b-modal v-model="modalShow">Hello From Modal!</b-modal>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        modalShow: false
      }
    }
  }
</script>

使用v-model属性时,不要同时使用visible属性。

使用作用域插槽作用域方法

请参阅使用传递给作用域插槽的各种方法关闭模式的 使用插槽自定义呈现 部分。

在$root上发出事件

您可以在$root上发出bv::show::modal, bv::hide::modal,和 bv::toggle::modal事件,第一个参数设置为modal的id。可选的第二个参数可以指定在关闭modal后返回焦点的元素。第二个参数可以是CSS选择器、元素引用或组件引用(组件的根元素将被聚焦)。

<div>
  <b-button @click="showModal" ref="btnShow">Open Modal</b-button>
  <b-button @click="toggleModal" ref="btnToggle">Toggle Modal</b-button>

  <b-modal id="modal-1">
    <div class="d-block">Hello From My Modal!</div>
    <b-button @click="hideModal">Close Me</b-button>
    <b-button @click="toggleModal">Toggle Me</b-button>
  </b-modal>
</div>
export default {
  methods: {
    showModal() {
      this.$root.$emit('bv::show::modal', 'modal-1', '#btnShow')
    },
    hideModal() {
      this.$root.$emit('bv::hide::modal', 'modal-1', '#btnShow')
    },
    toggleModal() {
      this.$root.$emit('bv::toggle::modal', 'modal-1', '#btnToggle')
    }
  }
}

注意: 建议使用this.$bvModal.show()this.$bvModal.hide()方法(在上一节中提到)而不是发出$root事件。

防止关闭

以防止<b-modal>关闭(例如验证失败时)。 ok (确认 按钮), cancel (取消 按钮), close (模式头关闭按钮)和 hide 事件处理程序的事件对象的.preventDefault()方法。请注意, 使用时必须同步调用.preventDefault(),因为不支持异步。

Submitted Names:
--
<template>
  <div>
    <b-button v-b-modal.modal-prevent-closing>Open Modal</b-button>

    <div class="mt-3">
      Submitted Names:
      <div v-if="submittedNames.length === 0">--</div>
      <ul v-else class="mb-0 pl-3">
        <li v-for="name in submittedNames">{{ name }}</li>
      </ul>
    </div>

    <b-modal
      id="modal-prevent-closing"
      ref="modal"
      title="Submit Your Name"
      @show="resetModal"
      @hidden="resetModal"
      @ok="handleOk"
    >
      <form ref="form" @submit.stop.prevent="handleSubmit">
        <b-form-group
          :state="nameState"
          label="Name"
          label-for="name-input"
          invalid-feedback="Name is required"
        >
          <b-form-input
            id="name-input"
            v-model="name"
            :state="nameState"
            required
          ></b-form-input>
        </b-form-group>
      </form>
    </b-modal>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        name: '',
        nameState: null,
        submittedNames: []
      }
    },
    methods: {
      checkFormValidity() {
        const valid = this.$refs.form.checkValidity()
        this.nameState = valid
        return valid
      },
      resetModal() {
        this.name = ''
        this.nameState = null
      },
      handleOk(bvModalEvt) {
        // Prevent modal from closing
        bvModalEvt.preventDefault()
        // Trigger submit handler
        this.handleSubmit()
      },
      handleSubmit() {
        // Exit when the form isn't valid
        if (!this.checkFormValidity()) {
          return
        }
        // Push the name to submitted names
        this.submittedNames.push(this.name)
        // Hide the modal manually
        this.$nextTick(() => {
          this.$bvModal.hide('modal-prevent-closing')
        })
      }
    }
  }
</script>

注意: 事件ok, cancel,和 close分别由modal的内置OK, Cancel,和header close (X)按钮发出。 默认情况下,如果在modal-footer槽中提供了自己的按钮或隐藏了页脚, 则不会发出这些事件。在这种情况下,使用hide事件来控制取消模式关闭。 即使发出确定, 取消,和 关闭,也始终发出“事件隐藏”。

ok, cancel, closehide事件对象(BvModalEvent)包含几个属性和方法:

属性或方法 类型 描述
preventDefault() Method 调用时阻止模式关闭
trigger 属性 将是:ok (默认单击确定), cancel (默认单击取消), esc (如果按了ESC键), backdrop (如果单击了backdrop), headerclose (如果单击了header X按钮)、 提供给hide()方法的第一个参数,否则为null
target 属性 对模式元素的引用
vueTarget 属性 对模式的Vue VM实例的引用
componentId 属性 模式的ID

您可以通过向高级控件的组件hide()方法传递一个参数来设置trigger的值(即检测哪个按钮或操作触发了要隐藏的模式)。

注意: 仅当hide()的参数分别严格为ok, cancel,或 close时, 才会发出'ok', 'cancel', or 'headerclose'事件。 传递给hide()的参数将放入事件对象的trigger属性中。

使用网格

通过在模式体中嵌套<b-container fluid>来利用模式中的引导网格系统。然后, 像在其他地方一样,使用普通的网格系统<b-row> (或 <b-form-row>)和 <b-col>

工具提示和弹出窗口

工具提示和弹出窗口可以根据需要放置在modals中。关闭模式时,其中的任何工具提示和弹出窗口也会自动关闭。工具提示和弹出窗口将自动附加到模式元素(以确保正确的z索引),但您可以通过指定容器ID来覆盖它们的附加位置(有关详细信息,请参阅工具提示和弹出窗口文档)。

<div>
  <b-button v-b-modal.modalPopover>Show Modal</b-button>

  <b-modal id="modalPopover" title="Modal with Popover" ok-only>
    <p>
      This
      <b-button v-b-popover="'Popover inside a modal!'" title="Popover">Button</b-button>
      triggers a popover on click.
    </p>
    <p>
      This <a href="#" v-b-tooltip title="Tooltip in a modal!">Link</a> will show a tooltip on
      hover.
    </p>
  </b-modal>
</div>

延迟加载和静态模式

默认情况下,modals在显示(延迟呈现)内容之前不会在文档中呈现内容。在可见时附加到<body>元素的模式。 <b-modal>组件不会影响布局,因为它们呈现为占位符注释节点(<!---->) 它们被放置在DOM位置。由于移植过程,可能需要两个或更多的$nextTick才能将内容的更改呈现到目标中。

通过将static prop设置为true,可以在文档中的适当位置呈现Modals(即<b-modal>组件位于文档中的位置)。 注意,即使statictrue时模态不可见/显示, 模态的内容也将在DOM中呈现。要使静态模式延迟呈现,还需要将lazy 属性设置 为true 。只有当模态可见时,它才会出现在文档中。注意,在静态模式下,<b-modal>组件的位置可能会影响文档和模式的布局。

如果属性static不为true, 则lazy属性将不起作用(非静态模式将始终延迟呈现)。

样式、选项和自定义

模态有三种可选sizes,可通过属性size。 这些大小在某些断点处启动,以避免在较窄的视口上出现水平滚动条。有效的可选尺寸为sm, lg,和 xl

<div>
  <b-button v-b-modal.modal-xl variant="primary">xl modal</b-button>
  <b-button v-b-modal.modal-lg variant="primary">lg modal</b-button>
  <b-button v-b-modal.modal-sm variant="primary">sm modal</b-button>

  <b-modal id="modal-xl" size="xl" title="Extra Large Modal">Hello Extra Large Modal!</b-modal>
  <b-modal id="modal-lg" size="lg" title="Large Modal">Hello Large Modal!</b-modal>
  <b-modal id="modal-sm" size="sm" title="Small Modal">Hello Small Modal!</b-modal>
</div>

size属性将大小映射到.modal-<size>类。

滚动长内容

当modals对于用户的视窗或设备太长时,它们会独立于页面本身滚动。试试下面的演示看看我们的意思。

<div>
  <b-button v-b-modal.modal-tall>Launch overflowing modal</b-button>

  <b-modal id="modal-tall" title="Overflowing Content">
    <p class="my-4" v-for="i in 20" :key="i">
      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-modal>
</div>

您还可以通过将属性scrollable设置为true来创建一个可滚动的模式,该模式允许模式体滚动。

<div>
  <b-button v-b-modal.modal-scrollable>Launch scrolling modal</b-button>

  <b-modal id="modal-scrollable" scrollable title="Scrollable Content">
    <p class="my-4" v-for="i in 20" :key="i">
      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-modal>
</div>

垂直居中模式

通过设置centered属性,在视口中垂直居中模式。

<div>
  <b-button v-b-modal.modal-center>Launch centered modal</b-button>

  <b-modal id="modal-center" centered title="BootstrapVue">
    <p class="my-4">Vertically centered modal!</p>
  </b-modal>
</div>

您可以随意将centeredscrollable的混合。

变量

通过设置header-bg-variant, header-text-variant, body-bg-variant, body-text-variant, footer-bg-variant,和 footer-text-variant属性来控制页眉、页脚和正文背景以及文本变量。 使用任何标准的引导变量,如danger, warning, info, success, dark, light等。

页眉下边框和页脚上边框的变体可以分别由header-border-variantfooter-border-variant属性控制。

<template>
  <div>
    <b-button @click="show=true" variant="primary">Show Modal</b-button>

    <b-modal
      v-model="show"
      title="Modal Variants"
      :header-bg-variant="headerBgVariant"
      :header-text-variant="headerTextVariant"
      :body-bg-variant="bodyBgVariant"
      :body-text-variant="bodyTextVariant"
      :footer-bg-variant="footerBgVariant"
      :footer-text-variant="footerTextVariant"
    >
      <b-container fluid>
        <b-row class="mb-1 text-center">
          <b-col cols="3"></b-col>
          <b-col>Background</b-col>
          <b-col>Text</b-col>
        </b-row>

        <b-row class="mb-1">
          <b-col cols="3">Header</b-col>
          <b-col>
            <b-form-select
              v-model="headerBgVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
          <b-col>
            <b-form-select
              v-model="headerTextVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
        </b-row>

        <b-row class="mb-1">
          <b-col cols="3">Body</b-col>
          <b-col>
            <b-form-select
              v-model="bodyBgVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
          <b-col>
            <b-form-select
              v-model="bodyTextVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
        </b-row>

        <b-row>
          <b-col cols="3">Footer</b-col>
          <b-col>
            <b-form-select
              v-model="footerBgVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
          <b-col>
            <b-form-select
              v-model="footerTextVariant"
              :options="variants"
            ></b-form-select>
          </b-col>
        </b-row>
      </b-container>

      <template v-slot:modal-footer>
        <div class="w-100">
          <p class="float-left">Modal Footer Content</p>
          <b-button
            variant="primary"
            size="sm"
            class="float-right"
            @click="show=false"
          >
            Close
          </b-button>
        </div>
      </template>
    </b-modal>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        show: false,
        variants: ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'light', 'dark'],
        headerBgVariant: 'dark',
        headerTextVariant: 'light',
        bodyBgVariant: 'light',
        bodyTextVariant: 'dark',
        footerBgVariant: 'warning',
        footerTextVariant: 'dark'
      }
    }
  }
</script>

您还可以分别通过code translate="no" class="notranslate text-nowrap">modal-class, content-class, header-class, body-classfooter-class属性将任意类应用于modal对话框容器、content(modal窗口本身)、header、body和footer。道具接受字符串或字符串数组。

隐藏背景

通过设置hide-backdrop属性隐藏模式的背景。

<div>
  <b-button v-b-modal.modal-no-backdrop>Open modal</b-button>

  <b-modal id="modal-no-backdrop" hide-backdrop content-class="shadow" title="BootstrapVue">
    <p class="my-2">
      We've added the utility class <code>'shadow'</code>
      to the modal content for added effect.
    </p>
  </b-modal>
</div>

请注意,即使背景被隐藏,单击模式外部仍将关闭模式。您可以通过将no-close-on-backdrop属性设置为<b-modal>来禁用此行为。

禁用打开和关闭动画

要在模式打开和关闭时禁用淡入淡出过渡/动画,只需在<b-modal>组件上设置属性no-fade

喜欢默认页脚中的较小或较大按钮吗? 只需将button-size属性的小按钮 设置为'sm',或将大按钮设置为'lg'

<div>
  <b-button v-b-modal.modal-footer-sm>Small Footer Buttons</b-button>
  <b-button v-b-modal.modal-footer-lg>Large Footer Buttons</b-button>

  <b-modal id="modal-footer-sm" title="BootstrapVue" button-size="sm">
    <p class="my-2">This modal has small footer buttons</p>
  </b-modal>

  <b-modal id="modal-footer-lg" title="BootstrapVue" button-size="lg">
    <p class="my-2">This modal has large footer buttons</p>
  </b-modal>
</div>

如果您已经通过modal-footer槽提供了自己的页脚,那么属性button-size将不起作用。

您可以通过编程方式禁用内置页脚按钮。

通过将cancel-disabledok-disabled属性分别设置为true, 可以分别禁用CancelOK按钮。将属性设置为false以重新启用按钮。

要同时禁用CancelOK按钮,只需将busy属性设置为 true。将其设置为false可重新启用两个按钮。

带插槽的自定义渲染

<b-modal>提供多个命名槽(其中一些槽的作用域是可选的),您可以使用这些槽自定义模式的各个部分的内容。

Slot 可选范围 说明
default Yes 模式的主要内容
modal-title Yes 放在情态词标题中的内容
modal-header Yes 要放在标题中的内容。替换整个标题,包括“关闭”按钮
modal-footer Yes 要放在页脚中的内容。替换包括按钮在内的整个页脚
modal-ok No 要放在页脚内的内容“确定”按钮
modal-cancel No 要放置在页脚中的内容“取消”按钮
modal-header-close No 放置在页眉关闭(x)按钮内的内容

支持可选作用域的插槽可用的作用域为:

方法或属性 说明
ok() 关闭模式并触发okhide事件,bvModalEvent.trigger = 'ok'
cancel() 关闭模式并启动cancelhide 事件,bvModalEvent.trigger = 'cancel'
close() 关闭模式并触发closehide事件,bvModalEvent.trigger = 'headerclose'
hide(trigger) 关闭模式并触发hide事件,bvModalEvent.trigger = trigger(trigger是可选的)
visible 模态的可见性状态。如果模态可见,则为true;如果不可见,则为false

使用自定义范围插槽的示例模式

<template>
  <b-button @click="$bvModal.show('modal-scoped')">Open Modal</b-button>

  <b-modal id="modal-scoped">
    <template v-slot:modal-header="{ close }">
      <!-- Emulate built in modal header close button action -->
      <b-button size="sm" variant="outline-danger" @click="close()">
        Close Modal
      </b-button>
      <h5>Modal Header</h5>
    </template>

    <template v-slot:default="{ hide }">
      <p>Modal Body with button</p>
      <b-button @click="hide()">Hide Modal</b-button>
    </template>

    <template v-slot:modal-footer="{ ok, cancel, hide }">
      <b>Custom Footer</b>
      <!-- Emulate built in modal footer ok and cancel button actions -->
      <b-button size="sm" variant="success" @click="ok()">
        OK
      </b-button>
      <b-button size="sm" variant="danger" @click="cancel()">
        Cancel
      </b-button>
      <!-- Button with custom close trigger value -->
      <b-button size="sm" variant="outline-secondary" @click="hide('forget')">
        Forget it
      </b-button>
    </template>
  </b-modal>
</template>

多模式支持

与本机引导v4不同,BootstrapVue支持同时打开多个modal。

要禁用特定模式的堆叠,只需在<b-modal>组件上设置 属性 no-stacking。这将在显示另一个模态之前隐藏该模态。

<div>
  <b-button v-b-modal.modal-multi-1>Open First Modal</b-button>

  <b-modal id="modal-multi-1" size="lg" title="First Modal" ok-only no-stacking>
    <p class="my-2">First Modal</p>
    <b-button v-b-modal.modal-multi-2>Open Second Modal</b-button>
  </b-modal>

  <b-modal id="modal-multi-2" title="Second Modal" ok-only>
    <p class="my-2">Second Modal</p>
    <b-button v-b-modal.modal-multi-3 size="sm">Open Third Modal</b-button>
  </b-modal>

  <b-modal id="modal-multi-3" size="sm" title="Third Modal" ok-only>
    <p class="my-1">Third Modal</p>
  </b-modal>
</div>

注意事项:

  • 避免将<b-modal> 嵌套在另一个<b-modal> 中, 因为它可能会被“约束”到父模式对话框的边界(特别是在使用静态模式时)。
  • 对于打开的每个模式,不透明背景将逐渐变暗。这是预期的行为,因为每个背景是打开超过其他模式和背景。

BootstrapVue在公开的this.$bvModal对象上提供了一些内置的消息框方法。 这些方法提供了一种从应用程序中的任何位置生成简单的“确定”和“确认”样式模式消息的方法,而无需在页面中显式放置<b-modal>组件。

方法 说明
this.$bvModal.msgBoxOk(message, options) 打开一个包含message和一个OK按钮的模式
this.$bvModal.msgBoxConfirm(message, options) 打开一个以message为内容的模式,然后单击“取消”和“确定”按钮

options 参数是用于添加标题和设置消息框模式样式的可选配置对象。 对象属性对应于<b-modal>属性,但以camelCase格式而不是kebab格式除外。

这两个方法都返回一个 Promise(需要IE 11的polyfill和更旧的浏览器支持), 当模式隐藏时,该Promise将解析为一个值。.msgBoxOk()始终解析为值true, 而.msgBoxConfirm()解析为 true (单击“确定”按钮), false (单击“取消”按钮),或 null (如果通过背景单击、按ESC C键或其他方式关闭了模式)。

如果未提供message,两个方法将立即返回undefined的值。

您可以使用.then(..).catch(...)或asyncawait代码样式 (async await需要现代浏览器或transpiler)。

确定消息框

示例OK消息框

Return value:
Return value:
<template>
  <div>
    <div class="mb-2">
     <b-button @click="showMsgBoxOne">Simple msgBoxOk</b-button>
     Return value: {{ String(boxOne) }}
    </div>
    <div class="mb-1">
     <b-button @click="showMsgBoxTwo">msgBoxOk with options</b-button>
     Return value: {{ String(boxTwo) }}
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        boxOne: '',
        boxTwo: ''
      }
    },
    methods: {
      showMsgBoxOne() {
        this.boxOne = ''
        this.$bvModal.msgBoxOk('Action completed')
          .then(value => {
            this.boxOne = value
          })
          .catch(err => {
            // An error occurred
          })
      },
      showMsgBoxTwo() {
        this.boxTwo = ''
        this.$bvModal.msgBoxOk('Data was submitted successfully', {
          title: 'Confirmation',
          size: 'sm',
          buttonSize: 'sm',
          okVariant: 'success',
          headerClass: 'p-2 border-bottom-0',
          footerClass: 'p-2 border-top-0',
          centered: true
        })
          .then(value => {
            this.boxTwo = value
          })
          .catch(err => {
            // An error occurred
          })
      }
    }
  }
</script>

确认消息框

确认消息框示例

Return value:
Return value:
<template>
  <div>
    <div class="mb-2">
     <b-button @click="showMsgBoxOne">Simple msgBoxConfirm</b-button>
     Return value: {{ String(boxOne) }}
    </div>
    <div class="mb-1">
     <b-button @click="showMsgBoxTwo">msgBoxConfirm with options</b-button>
     Return value: {{ String(boxTwo) }}
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        boxOne: '',
        boxTwo: ''
      }
    },
    methods: {
      showMsgBoxOne() {
        this.boxOne = ''
        this.$bvModal.msgBoxConfirm('Are you sure?')
          .then(value => {
            this.boxOne = value
          })
          .catch(err => {
            // An error occurred
          })
      },
      showMsgBoxTwo() {
        this.boxTwo = ''
        this.$bvModal.msgBoxConfirm('Please confirm that you want to delete everything.', {
          title: 'Please Confirm',
          size: 'sm',
          buttonSize: 'sm',
          okVariant: 'danger',
          okTitle: 'YES',
          cancelTitle: 'NO',
          footerClass: 'p-2',
          hideHeaderClose: false,
          centered: true
        })
          .then(value => {
            this.boxTwo = value
          })
          .catch(err => {
            // An error occurred
          })
      }
    }
  }
</script>

消息框注释

  • this.$bvModal注入仅在使用完整的BootstrapVue插件或 ModalPlugin插件时可用。如果仅导入b-modal组件, 则此选项不可用。要导入注入,请使用BVModalPlugin插件。
  • 为每个Vue虚拟机(即每个实例化组件)创建一个新的$bvModal注入(mixin), 并且不能通过直接访问Vue.prototype来使用,因为它需要访问实例的this$root上下文。
  • 消息框需要浏览器中的Promise支持。如果你的应用是针对较老的浏览器,如IE 11, 请包括一个提供Promise支持的polyfill。 如果未检测到Promise支持,则消息框方法将立即返回undefined
  • 消息框是<b-modal>组件的扩展,因此支持大多数<b-modal>属性 (使用camelCase格式),但以下属性除外:lazy, static, busy, visible, noStacking, okOnly, okDisabled,和 cancelDisabled
  • 如果选项中没有提供title (或titleHtml),则不会显示标题。
  • 当选项中提供title(或titleHtml)时, 默认情况下不显示标题关闭按钮。通过在选项中设置hideHeaderClose: false,可以启用标题关闭按钮。
  • 如果消息框在隐藏之前被关闭/销毁,则会抛出错误(拒绝承诺)。如果使用异步await样式的代码,则始终包含.catch(errHandler)拒绝处理程序、事件。
  • 使用Vue路由器(或类似路由器)时,如果在隐藏模式之前更改了路由,则消息框将关闭并拒绝。如果希望在路由更改时消息框保持打开状态, 请使用this.$root.$bvModal而不是this.$bvModal
  • 在服务器端呈现(SSR)期间无法生成消息框。
  • 消息框message当前不支持HTML字符串,但是,可以将VNodes数组 作为message传递,以便对标记进行细粒度控制。 您可以使用Vue的this.$createElement 方法生成Vnode。也可以对模式标题(通过将VNodes传递给title选项)、OK按钮文本 (通过okTitle选项)和CANCEL按钮文本(通过cancelTitle选项)执行此操作。

消息框高级用法

使用this.$bvModal.msgBoxOk(...)this.$bvModal.msgBoxConfirm(...)方法生成模式时, 您可能希望模式内容不仅仅是字符串消息。如上面的消息框注释 部分所述,可以将vnode数组作为更复杂内容的消息和标题传递。

使用Vue的this.$createElement方法生成vnode。

<template>
  <div>
    <b-button @click="showMsgOk">Show OK message box with custom content</b-button>
  </div>
</template>

<script>
  export default {
    methods: {
      showMsgOk() {
        const h = this.$createElement
        // Using HTML string
        const titleVNode = h('div', { domProps: { innerHTML: 'Title from <i>HTML<i> string' } })
        // More complex structure
        const messageVNode = h('div', { class: ['foobar'] }, [
          h('p', { class: ['text-center'] }, [
            ' Flashy ',
            h('strong', 'msgBoxOk'),
            ' message ',
          ]),
          h('p', { class: ['text-center'] }, [h('b-spinner')]),
          h('b-img', {
            props: {
              src: 'https://picsum.photos/id/20/250/250',
              thumbnail: true,
              center: true,
              fluid: true, rounded: 'circle'
            }
          })
        ])
        // We must pass the generated VNodes as arrays
        this.$bvModal.msgBoxOk([messageVNode], {
          title: [titleVNode],
          buttonSize: 'sm',
          centered: true, size: 'sm'
        })
      }
    }
  }
</script>

通过$root事件监听模式更改

要监听任何模式打开,请使用:

export default {
  mounted() {
    this.$root.$on('bv::modal::show', (bvEvent, modalId) => {
      console.log('Modal is about to be shown', bvEvent, modalId)
    })
  }
}

有关发出的事件的完整列表,请参阅本文档的事件部分。

可访问性

<b-modal>提供了一些辅助功能, 包括自动对焦、返回对焦、键盘(选项卡)对焦控制和自动aria-*属性。

在大多数情况下,aria-labelledbyaria-describedby属性将自动出现在模式上。

  • 如果隐藏了头,或者提供了自己的头,或者没有提供模式标题,aria-labelledby属性将存在。 建议为您的modals提供一个标题(当使用内置头文件时)。您可以直观地隐藏标题标题, 但仍然可以通过设置title-sr-only属性使其对屏幕阅读器可用。 如果没有头,则可以通过向aria-label属性传递字符串来为模态提供标签。
  • aria-describedby属性将始终指向模态的正文内容。
  • 如果使用字符串值指定aria-label属性,则将不会呈现aria-labelledby属性,即使您有模式的标题/标题。

在2.0.0-rc.27版本中添加了aria-labeltitle-sr-only属性。

打开时自动聚焦

<b-modal>打开时将自动对焦模态容器。

您可以通过监听显示的<b-modal>事件来预聚焦<b-modal> 中的元素,并调用该元素的focus()方法。<b-modal> 不会尝试自动对焦,如果元素已在<b-modal>中具有焦点。

<b-modal @shown="focusMyElement">
  <div>
    <b-button>I Don't Have Focus</b-button>
  </div>

  <div>
    <b-form-input></b-form-input>
  </div>

  <div>
    <!-- Element to gain focus when modal is opened -->
    <b-form-input ref="focusThis"></b-form-input>
  </div>

  <div>
    <b-form-input></b-form-input>
  </div>
</b-modal>
export default {
  methods: {
    focusMyElement() {
      this.$refs.focusThis.focus()
    }
  }
}

或者,如果使用b-form-*表单控件, 则可以在模式打开时使用autofocus属性autofocus表单控件。 注意,如果在lazy属性集的情况下使用static属性, 则autofocus属性将无法与b-model一起使用,因为在DOM中安装b-form-*控件时会发生autofocus。

如果要自动对焦其中一个内置模式按钮(ok, cancelclose按钮),可以将属性auto-focus-button设置为 'ok', 'cancel''close'并且 <b-modal>将对焦指定的按钮(如果存在)。此功能也可用于模式消息框。

注意: 出于可访问性的原因,不建议将输入或控件自动对焦到模式内部,因为屏幕阅读器用户将不知道输入位置的上下文(可能不会声明该模式)。 最好让 <b-modal>聚焦模态的容器,允许模态信息与用户对话,然后允许用户在输入中使用tab键。

将焦点返回到触发元素

出于可访问性的原因,希望在模式关闭时将焦点返回到触发模式打开的元素。

<b-modal> 将尝试并自动确定在打开模态之前哪个元素具有焦点,如果可能,将在模态已隐藏时将焦点返回给该元素。但是,提供了一些方法和选项,允许您指定在模态隐藏后要将焦点返回到的元素。

通过返回焦点属性指定返回焦点元素

当模式关闭时,还可以通过将 返回焦点属性设置为以下之一来指定要返回焦点的元素:

  • CSS查询选择器字符串(或以#开头的元素ID)
  • 组件引用(安装在可聚焦元素上,如<b-button>
  • 对可聚焦的DOM元素的引用

如果传入的元素不可聚焦,那么浏览器将确定哪些元素具有焦点(通常<body>,这是不可取的)

当您使用 <b-modal>方法 show()hide()v-model属性时,返回焦点的方法非常方便。注意,此属性优先于指定返回焦点元素的其他方法。

自动返回焦点

当通过元素的v-b-modal指令打开<b-modal>时,<b-modal> 关闭时焦点将自动返回到该元素,除非通过返回焦点属性指定了元素。

通过事件指定返回焦点

使用bv::show::modal事件(在$root上发出)时, 可以指定第二个参数,该参数是要返回焦点的元素。此参数接受与返回焦点属性相同的类型。

this.$root.$emit('bv::show::modal', 'modal-1', '#focusThisOnClose')

Tip: if using a click event (or similar) to trigger modal to open, pass the event's target property:

<div>
  <b-button @click="$root.$emit('bv::show::modal', 'modal-1', $event.target)">Open Modal</b-button>
</div>

注意: 如果<b-modal>设置了返回焦点属性,则通过事件指定的元素将被忽略。

键盘导航

当在<b-modal>中的元素之间切换时,如果focus试图将该模式保留到文档中,则它将返回到模式中。

避免将模式中元素的tabindex设置为除0-1之外的任何值。这样做将使依赖辅助技术的人很难导航和操作页面内容,并可能使一些元素无法通过键盘导航访问。

如果模式之外的某些元素需要可聚焦(即对于TinyMCE),可以将它们作为CSS选择器添加到ignore-enforce-focus-selector属性 2.4.0+,例如:

<b-modal
  id="some-modal-id"
  title="Modal with TinyMCE Editor"
  ignore-enforce-focus-selector=".tox-tinymce-aux, .moxman-window, .tam-assetmanager-root"
>
  <!-- Modal content with TinyMCE editor here -->
</b-modal>

在某些情况下,可能需要完全禁用“强制聚焦”功能。您可以通过设置属性 no-enforce-focus来实现这一点, 尽管出于可访问性的原因,这是非常不可取的。

v-b-modal 指令可访问性

关于 v-b-modal指令可访问性的说明:

  • 如果元素不是<button>(或呈现<button>的组件), 则ARI角色将设置为button, 并将添加ENTERSPACE的keydown事件监听器以及click监听器。
  • 如果元素不是<button><a>(或呈现两者的组件), 那么将向元素添加0tabindex以确保可访问性, 除非已经设置了tabindex

组件引用

<b-modal>

属性

属性 (Click to sort Ascending) 类型 默认值 描述
id String 用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础
size String 'md' 设置模式宽度的大小sm、md(默认)、“lg”或“xl”
centered Boolean false 在视口中垂直居中模式
scrollable Boolean false 启用模式体的滚动
button-size String 内置页脚按钮的大小:“sm”、“md”(默认)或“lg”
no-stacking Boolean false 防止其他模态叠加在这个模态上
no-fade Boolean false 设置为“true”时,禁用组件上的淡入动画/过渡
no-close-on-backdrop Boolean false 通过单击背景禁用关闭模式的功能
no-close-on-esc Boolean false 通过按ESC键禁用关闭模式的功能
no-enforce-focus Boolean false 禁用强制焦点例程,该例程在模式中维护焦点
ignore-enforce-focus-selector v2.4.0+ Array or String 忽略强制焦点例程中由css选择器指定的某些元素
title String 要放置在标题中的文本内容
title-html Use with caution String 要放置在标题中的HTML字符串内容。慎用
title-tag String 'h5' 指定要呈现的HTML标记,而不是标题的默认标记
title-class String or Array or Object 应用于标题的CSS类
title-sr-only Boolean false 将标题包装在“.sr only”包装中
aria-label String 为模态显式提供“aria label”属性。应在模态没有标题时设置。如果未设置“aria labelledby”,则会指向模态的标题
header-bg-variant String 将一个引导主题颜色变体应用于标题背景
header-border-variant String 将一个引导主题颜色变体应用于标题边框
header-text-variant String 将引导主题颜色变体之一应用于标题文本
header-close-variant String 应用于标题关闭按钮的文本主题颜色变体
header-class String or Array or Object 应用于“.modal header”包装元素的CSS类
body-bg-variant String 将一个引导主题颜色变体应用于主体背景
body-text-variant String 将引导主题颜色变体之一应用于正文文本
modal-class String or Array or Object 应用于“.modal”包装元素的CSS类
dialog-class String or Array or Object 应用于“.modal dialog”包装元素的CSS类
content-class String or Array or Object 应用于“.modal content”包装元素的CSS类
body-class String or Array or Object 应用于“.modal body”包装元素的CSS类
hide-header Boolean false 禁用模式头的呈现
hide-header-close Boolean false 禁用模式头的“关闭”按钮的呈现
hide-backdrop Boolean false 禁用模式背景的呈现
ok-only Boolean false 禁用呈现默认页脚取消按钮
ok-disabled Boolean false 将默认页脚“确定”按钮置于禁用状态
cancel-disabled Boolean false 将默认页脚取消按钮置于禁用状态
visible v-model Boolean false 模态的当前可见性状态
return-focus HTMLElement or String or Object 当模式关闭时返回焦点的HTML元素引用、CSS选择器或组件引用。如果未设置,则将焦点返回到模式打开之前最后具有焦点的元素
header-close-content v2.3.0+ String '&times;' 标题关闭按钮的内容
header-close-label String 'Close' 标题关闭按钮上的“aria label”值
cancel-title String 'Cancel' 要放置在默认页脚取消按钮中的文本字符串
cancel-title-html Use with caution String 要放置在默认页脚取消按钮中的HTML字符串。慎用
ok-title String 'OK' 要放置在默认页脚中的文本字符串“确定”按钮
ok-title-html Use with caution String 要放置在默认页脚“确定”按钮中的HTML字符串。慎用
cancel-variant String 'secondary' 应用于默认页脚取消按钮的按钮颜色主题变量
ok-variant String 'primary' 按钮颜色主题变量应用于默认页脚“确定”按钮
lazy Boolean false 当模态设置了“static”属性时,将惰性地呈现模态内容
busy Boolean false 将内置的默认页脚“确定”和“取消”按钮置于禁用状态
static Boolean false 在DOM中就地呈现组件的内容,而不是将其移植到body元素中
auto-focus-button v2.0.0+ String 指定模式打开后要聚焦的内置按钮:“确定”、“取消”或“关闭”

警告: 当传递原始用户提供的值时,支持HTML字符串(*-html)的属性可能容易受到 跨站点脚本 (XSS) attacks 攻击。必须先正确 清理 用户输入!

v-model

属性 事件
visible change

插槽

插槽名称 描述 范围
modal-header 整个模式头容器内容。同时删除右上角的“X关闭”按钮。可选范围。
modal-title 模态标题。如果使用了模态头槽,则不会显示此槽。可选范围。
modal-header-close 模式标题关闭按钮的内容。如果使用了模态头槽,则不会显示此槽。
modal-ok 模式确定按钮内容。
modal-cancel 模式取消按钮内容。
modal-backdrop 模式背景内容。
default 情态体的内容。可选范围。

事件

事件 参数 描述
change
  1. isVisible - 如果模态可见,则为true;否则为false
新模态可见性状态。用于更新v模型
show
  1. bvModalEvt - BvModalEvent对象。调用bvModalEvt.preventDefault()取消显示
总是在模态显示之前发出。可取消
shown
  1. bvModalEvt - BvModalEvent对象
显示模态时始终发出
hide
  1. bvModalEvt - BvModalEvent对象。调用bvModalEvt.preventDefault()取消隐藏
总是在模态隐藏之前发出。可取消(只要模态没有被强制隐藏)
hidden
  1. bvModalEvt - BvModalEvent对象
总是在模态被隐藏后发出
ok
  1. bvModalEvt - BvModalEvent对象。调用bvModalEvt.preventDefault()取消隐藏
当按下默认的OK按钮时,就在模态隐藏之前。可取消
cancel
  1. bvModalEvt - BvModalEvent对象。调用bvModalEvt.preventDefault()取消隐藏
当按下默认的取消按钮时,就在模态隐藏之前。可取消
close
  1. bvModalEvt - BvModalEvent对象。调用bvModalEvt.preventDefault()取消隐藏
当按下默认的标题关闭按钮时,就在模态隐藏之前。可取消
bv::modal::show
  1. bvModalEvt - BvModalEvent对象。调用bvEvt.preventDefault()取消显示
  2. modalId - modal ID
当modal即将显示时在$root上发出。可取消
bv::modal::shown
  1. bvModalEvt - BvModalEvent对象
  2. modalId - modal ID
显示modal时在$root上发出
bv::modal::hide
  1. bvModalEvt - BvModalEvent对象。调用bvEvt.preventDefault()取消隐藏
  2. modalId - modal ID
当modal即将隐藏时在$root上发出。可取消(只要模态没有被强制隐藏)
bv::modal::hidden
  1. bvModalEvt - BvModalEvent对象
  2. modalId - modal ID
隐藏模态时在$root上发出

$root事件侦听器

您可以通过在$root上发出以下事件来控制<b-modal>

事件 参数 描述
bv::show::modal

modalId - 要显示的模态ID

elIDtoFocusOnClose - (可选择的),指定元素引用或CSS选择器,以便在关闭模式后将焦点返回到

在$root上发出此事件时,显示具有指定ID的模态
bv::hide::modal

modalId - 要隐藏的模态ID

在$root上发出此事件时隐藏具有指定ID的模态
bv::toggle::modal

modalId - 切换可见性的模态ID

elIDtoFocusOnClose - (可选择的), 指定元素引用或CSS选择器,以便在关闭模式后将焦点返回到

根据模态的ID切换其可见性

导入单个组件

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

组件 命名输出 导入路径
<b-modal> BModal bootstrap-vue

示例:

import { BModal } from 'bootstrap-vue'
Vue.component('b-modal', BModal)

导入单个指令

可以通过以下命名导出将单个指令导入到项目中:

指令 命名导出 导入路径
v-b-modal VBModal bootstrap-vue

示例:

import { VBModal } from 'bootstrap-vue'
// Note: Vue automatically prefixes the directive name with 'v-'
Vue.directive('b-modal', VBModal)

导入为Vue.js插件

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

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

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

  • BVModalPlugin

示例:

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