表单(Form)

BootstrapVue 表单组件和辅助组件,可以选择支持内联表单样式和验证状态。 将它们与其他 BootstrapVue 表单控件组件配对,可实现具有一致外观的轻松自定义,响应式布局。

表格和控件介绍

确保在所有输入上使用适当的 type【类型】(例如,电子邮件用于 email【电子邮件】地址或 number【数字】用于数字信息),以利用更新的输入控件,例如电子邮件验证,数字选择等。

这是一个演示 BootstrapVue 表单样式的简单示例。继续阅读有关受支持的组件,表单布局等的文档。

We'll never share your email with anyone else.
Form Data Result
{
  "email": "",
  "name": "",
  "food": null,
  "checked": []
}
<template>
  <div>
    <b-form @submit="onSubmit" @reset="onReset" v-if="show">
      <b-form-group
        id="input-group-1"
        label="Email address:"
        label-for="input-1"
        description="We'll never share your email with anyone else."
      >
        <b-form-input
          id="input-1"
          v-model="form.email"
          type="email"
          required
          placeholder="Enter email"
        ></b-form-input>
      </b-form-group>

      <b-form-group id="input-group-2" label="Your Name:" label-for="input-2">
        <b-form-input
          id="input-2"
          v-model="form.name"
          required
          placeholder="Enter name"
        ></b-form-input>
      </b-form-group>

      <b-form-group id="input-group-3" label="Food:" label-for="input-3">
        <b-form-select
          id="input-3"
          v-model="form.food"
          :options="foods"
          required
        ></b-form-select>
      </b-form-group>

      <b-form-group id="input-group-4">
        <b-form-checkbox-group v-model="form.checked" id="checkboxes-4">
          <b-form-checkbox value="me">Check me out</b-form-checkbox>
          <b-form-checkbox value="that">Check that out</b-form-checkbox>
        </b-form-checkbox-group>
      </b-form-group>

      <b-button type="submit" variant="primary">Submit</b-button>
      <b-button type="reset" variant="danger">Reset</b-button>
    </b-form>
    <b-card class="mt-3" header="Form Data Result">
      <pre class="m-0">{{ form }}</pre>
    </b-card>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        form: {
          email: '',
          name: '',
          food: null,
          checked: []
        },
        foods: [{ text: 'Select One', value: null }, 'Carrots', 'Beans', 'Tomatoes', 'Corn'],
        show: true
      }
    },
    methods: {
      onSubmit(evt) {
        evt.preventDefault()
        alert(JSON.stringify(this.form))
      },
      onReset(evt) {
        evt.preventDefault()
        // Reset our form values
        this.form.email = ''
        this.form.name = ''
        this.form.food = null
        this.form.checked = []
        // Trick to reset/clear native browser form validation state
        this.show = false
        this.$nextTick(() => {
          this.show = true
        })
      }
    }
  }
</script>

内联表格

使用 <b-form> 上的 inline(内联)属性在单个水平行上显示一系列标签,表单控件和按钮。 内联表单中的表单控件与其默认状态略有不同。

  • display: flex 控件,折叠任何 HTML 空格,并允许您使用 spacespace 和 flexbox 实用程序提供对齐控件。
  • 控件和输入组接收 width: auto 以覆盖 Bootstrap 默认宽度:100%。
  • 控件 仅在宽度至少为576像素的视口中内嵌显示 ,以解决移动设备上的视口狭窄的问题。

您可能需要使用 spacing utilities(间距实用程序)手动解决单个表单控件的宽度和对齐问题(如下所示)。最后,请确保始终在每个表单控件中包含一个 <label> ,即使您需要将其隐藏于 .sr-only 类的非屏幕阅读器访问者之外。

@
<div>
  <b-form inline>
    <label class="sr-only" for="inline-form-input-name">Name</label>
    <b-input
      id="inline-form-input-name"
      class="mb-2 mr-sm-2 mb-sm-0"
      placeholder="Jane Doe"
    ></b-input>

    <label class="sr-only" for="inline-form-input-username">Username</label>
    <b-input-group prepend="@" class="mb-2 mr-sm-2 mb-sm-0">
      <b-input id="inline-form-input-username" placeholder="Username"></b-input>
    </b-input-group>

    <b-form-checkbox class="mb-2 mr-sm-2 mb-sm-0">Remember me</b-form-checkbox>

    <b-button variant="primary">Save</b-button>
  </b-form>
</div>

还支持自定义表单控件和选择。

<div>
  <b-form inline>
    <label class="mr-sm-2" for="inline-form-custom-select-pref">Preference</label>
    <b-form-select
      class="mb-2 mr-sm-2 mb-sm-0"
      :value="null"
      :options="{ '1': 'One', '2': 'Two', '3': 'Three' }"
      id="inline-form-custom-select-pref"
    >
      <template v-slot:first>
        <option :value="null">Choose...</option>
      </template>
    </b-form-select>

    <b-form-checkbox class="mb-2 mr-sm-2 mb-sm-0">Remember my preference</b-form-checkbox>

    <b-button variant="primary">Save</b-button>
  </b-form>
</div>

注意: 由于布局冲突,inline(内联)表单不支持 <b-form-group>

隐藏标签的替代方法

如果您没有为每个 input(输入)都包含标签,那么诸如屏幕阅读器之类的辅助技术将对您的表单造成麻烦。对于这些内联表单,您可以使用 .sr-only 类隐藏标签。 还有其他为辅助技术提供标签的替代方法,例如 aria-labelaria-labelledbytitle 属性。如果不存在任何一种,辅助技术可能会诉诸使用 placeholder (占位符)属性(如果存在),但是请注意,不建议使用 placeholder(占位符)代替其他标记方法。

另请参阅:

表单辅助组件

Form 插件提供了以下帮助器组件:

  • <b-form-text> 输入的帮助文本块
  • <b-form-invalid-feedback> 输入 invalid(无效)状态的无效反馈文本块
  • <b-form-valid-feedback> 输入 valid(有效)状态的有效反馈文本块
  • <b-form-datalist> 轻松创建用于 <b-form-input> 或纯 <input><datalist>

表单文本帮助

在具有 <b-form-text> 帮助器组件的输入下方显示帮助文本块。文本以柔和的颜色显示,并且字体大小稍小。

提示: 应该使用 aria-describedby 属性将帮助文本与与其相关的表单控件明确关联。 这将确保诸如屏幕阅读器之类的辅助技术将在用户聚焦或进入控件时宣布此帮助文本。

Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters, or emoji.
<div>
  <b-form @submit.stop.prevent>
    <label for="text-password">Password</label>
    <b-input type="password" id="text-password" aria-describedby="password-help-block"></b-input>
    <b-form-text id="password-help-block">
      Your password must be 8-20 characters long, contain letters and numbers, and must not
      contain spaces, special characters, or emoji.
    </b-form-text>
   </b-form>
</div>

反馈辅助

<b-form-valid-feedback><b-form-invalid-feedback> 帮助器组件将反馈(基于输入状态)显示为彩色文本块。 它们依赖于放置在输入(同级)之后,并将根据输入的浏览器本机验证状态显示。 若要强制显示,请将 force-show 属性设置为 true ,或将控件 state(状态)绑定到反馈帮助器的 state(状态)属性,,或在父元素(例如,表单)上设置 was-validated 类。 有关其他详细信息,请参见下面的 Validation(验证方式)部分。

使用可选的 Boolean 属性 tooltip(工具提示)将显示从块更改为静态工具提示样式。反馈通常将显示在表单控件下方。 启用此模式后,重要的是父容器必须具有 position: relative: css样式(或 position-relative 类)。请注意,由于工具提示样式的位置是静态的,因此可能会使其他输入,标签等模糊不清。

注意 某些表单控件,例如 <b-form-radio><b-form-checkbox> ,和 <b-form-file> 具有包装元素,这些元素将阻止自动显示反馈文本(因为反馈组件为 而不是表单控件输入的直接同级)。使用反馈组件的 state【状态】属性(绑定到表单控件的状态)或 force-show【强制显示】属性来显示反馈。

<template>
  <div>
    <b-form  @submit.stop.prevent>
      <label for="feedback-user">User ID</label>
      <b-input v-model="userId" :state="validation" id="feedback-user"></b-input>
      <b-form-invalid-feedback :state="validation">
        Your user ID must be 5-12 characters long.
      </b-form-invalid-feedback>
      <b-form-valid-feedback :state="validation">
        Looks Good.
      </b-form-valid-feedback>
     </b-form>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        userId: ''
      }
    },
    computed: {
      validation() {
        return this.userId.length > 4 && this.userId.length < 13
      }
    }
  }
</script>

数据列表帮助

对于支持 <datalist> 元素的浏览器,<b-form-datalist> 帮助器组件将允许您通过传递给 options 属性的数组快速创建 <datalist><option> 子元素

您也可以在 <b-form-datalist> 中手动提供 <option> 元素。它们将显示在 options 属性生成的所有 <option> 元素下方。

<template>
  <label for="input-with-list">Input with datalist</label>
  <b-form-input list="input-list" id="input-with-list"></b-form-input>
  <b-form-datalist id="input-list" :options="options"></b-form-datalist>
</template>

<script>
export default {
  data() {
    return {
      options: ['Apple', 'Banana', 'Grape', 'Kiwi', 'Orange']
    }
  }
}
</script>

也可以通过 <b-datalist> 的较短别名来使用 <b-form-datalist>

另请参阅:

验证方式

通过在 <b-form> 上将 novalidate 属性设置为 true 来禁用浏览器本地 HTML5 验证。

<b-form> 上的验证道具设置为 true ,以将Bootstrap v4 .was-validated 类添加到窗体中以触发 validated【验证】状态

所有的表单控件都支持 state【状态】属性,该属性可以用于将表单控件设置为以下三种上下文状态之一:

  • false (表示无效状态)非常适合存在阻塞或必填字段的情况。用户必须正确填写此字段才能提交表单。
  • true (表示有效状态)非常适合在整个表单中都进行逐字段验证并希望鼓励用户遍历其余字段的情况。
  • null 不显示验证状态(无效或无效)

有关新的 Bootstrap v4 验证状态的详细信息,请参阅 Bootstrap v4 表单验证文档

验证机制

在 BootstrapVue 中使用基于 3rd【第三方】Vue的验证库:

其他资源:

组件引用

属性

属性 类型 默认值 描述
id String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础
inline Boolean false 设置后,表单将处于内联模式,在单个水平行上显示标签,表单控件和按钮
novalidate Boolean false 设置后,将禁用表单中控件上的浏览器本机HTML5验证
validated Boolean false 设置后,在表单上添加Bootstrap类“was-validated”,触发本机浏览器验证状态

事件

事件 参数 描述
submit
  1. event - 本机提交事件。
提交表单时发出

<b-form-text>

功能组件

属性

属性 类型 默认值 描述
id String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础
tag String 'small' 指定要渲染的HTML标签,而不是默认标签
text-variant String 'muted' 将 Bootstrap 主题颜色变量之一应用于文本
inline Boolean false 设置后,将帮助文本渲染为内联元素而不是块元素

<b-form-invalid-feedback>

功能组件

属性

属性 类型 默认值 描述
id String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础
tag String 'div' 指定要渲染的HTML标签,而不是默认标签
tooltip Boolean false 以基本的工具提示样式渲染反馈文本
force-show Boolean false 显示反馈文本,与“ state”属性的值无关
state Boolean 当显式为“ false”时,强制反馈显示
aria-live String 当渲染的元素是aria实时区域(适用于屏幕阅读器用户)时,请设置为'polite' 或 'assertive'
role String 将 ARIA 属性“role”【角色】设置为特定值

<b-form-valid-feedback>

功能组件

属性

属性 类型 默认值 描述
id String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础
tag String 'div' 指定要渲染的 HTML 标签,而不是默认标签
tooltip Boolean false 以基本的工具提示样式渲染反馈文本
force-show Boolean false 显示反馈文本,与“state”属性的值无关
state Boolean 当明确为“true”时,强制反馈显示
aria-live String 当渲染的元素是aria实时区域(适用于屏幕阅读器用户)时,请设置为 'polite' 或 'assertive'
role String 将 ARIA 属性“role”【角色】设置为特定值

<b-form-datalist>

组件别名

<b-form-datalist> 也可以通过以下别名使用:

  • <b-datalist>

注意:组件别名仅在导入所有 BootstrapVue 或使用组件组插件时可用。

属性

属性 类型 默认值 描述
options Array or Object [] 要在组件中渲染的项目数组
value-field String 'value' 'options'【选项】数组中的字段名称,该字段名称应用于该值
text-field String 'text' 'options'【选项】数组中应用于文本标签的字段名称
html-field String 'html' 'options'【选项】数组中的字段名称,应该用于html标签而不是文本字段。请谨慎使用。
disabled-field String 'disabled' 'options'【选项】数组中应用于禁用状态的字段名称
id Required String 用于在渲染的内容上设置“ id”属性,并用作根据需要生成任何其他元素ID的基础

导入单个组件

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

组件 命名输出 导入路径
<b-form> BForm bootstrap-vue
<b-form-text> BFormText bootstrap-vue
<b-form-invalid-feedback> BFormInvalidFeedback bootstrap-vue
<b-form-valid-feedback> BFormValidFeedback bootstrap-vue
<b-form-datalist> BFormDatalist bootstrap-vue

示例:

import { BForm } from 'bootstrap-vue'
Vue.component('b-form', BForm)

导入为Vue.js插件

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

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

示例:

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