表单

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

表单和控件简介

请务必在所有输入上使用适当的 type(例如,电子邮件地址的 email 或数字信息的 number),以利用更新的输入控件,如电子邮件验证、数字选择等。

这是一个快速示例,演示了 BootstrapVue 的表单样式。继续阅读以了解受支持组件、表单布局等的文档。

<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"
          placeholder="Enter email"
          required
        ></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"
          placeholder="Enter name"
          required
        ></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" v-slot="{ ariaDescribedby }">
        <b-form-checkbox-group
          v-model="form.checked"
          id="checkboxes-4"
          :aria-describedby="ariaDescribedby"
        >
          <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(event) {
        event.preventDefault()
        alert(JSON.stringify(this.form))
      },
      onReset(event) {
        event.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.vue -->

内联表单

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

  • 控件为 display: flex,折叠任何 HTML 空白,允许你使用间距和 flexbox 实用程序提供对齐控制。
  • 控件和输入组接收 width: auto 以覆盖 Bootstrap 默认宽度:100%。
  • 控件仅在至少 576 像素宽的视口中内联显示,以适应移动设备上的窄视口。

你可能需要使用 间距实用程序(如下所示)手动处理各个表单控件的宽度和对齐。最后,务必始终使用 <label> 包含每个表单控件,即使你需要使用类 .sr-only 对非屏幕阅读器访问者隐藏它。

<div>
  <b-form inline>
    <label class="sr-only" for="inline-form-input-name">Name</label>
    <b-form-input
      id="inline-form-input-name"
      class="mb-2 mr-sm-2 mb-sm-0"
      placeholder="Jane Doe"
    ></b-form-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-form-input id="inline-form-input-username" placeholder="Username"></b-form-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>

<!-- b-form-inline.vue -->

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

<div>
  <b-form inline>
    <label class="mr-sm-2" for="inline-form-custom-select-pref">Preference</label>
    <b-form-select
      id="inline-form-custom-select-pref"
      class="mb-2 mr-sm-2 mb-sm-0"
      :options="[{ text: 'Choose...', value: null }, 'One', 'Two', 'Three']"
      :value="null"
    ></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>

<!-- b-form-inline-custom.vue -->

注意: <b-form-group> 不支持 inline 表单,因为存在布局冲突。

隐藏标签的替代方法

如果你不为每个输入包含一个标签,则屏幕阅读器等辅助技术将无法处理你的表单。对于这些内联表单,你可以使用 .sr-only 类隐藏标签。还有其他为辅助技术提供标签的替代方法,例如 aria-labelaria-labelledbytitle 属性。如果这些属性都不存在,辅助技术可能会使用 placeholder 属性(如果存在),但请注意,不建议使用 placeholder 替换其他标签方法。

另请参见

表单帮助组件

以下帮助组件可与 Form 插件一起使用

  • <b-form-text> 输入的帮助文本块
  • <b-form-invalid-feedback> 输入 invalid 状态的无效反馈文本块
  • <b-form-valid-feedback> 输入 valid 状态的有效反馈文本块
  • <b-form-datalist> 轻松创建 <datalist> 以与 <b-form-input> 或普通 <input> 一起使用

表单文本帮助

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

提示:帮助文本应明确与它所关联的表单控件相关联,方法是使用 aria-describedby 属性。这将确保辅助技术(例如屏幕阅读器)在用户聚焦或进入控件时宣布此帮助文本。

<div>
  <b-form @submit.stop.prevent>
    <label for="text-password">Password</label>
    <b-form-input type="password" id="text-password" aria-describedby="password-help-block"></b-form-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-help-text.vue -->

反馈帮助

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

使用可选的布尔属性 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-form-input v-model="userId" :state="validation" id="feedback-user"></b-form-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>

<!-- b-form-feedback-example.vue -->

数据列表帮助程序

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

您还可以在 <b-form-datalist> 内手动提供 <option> 元素。它们将显示在从 options 属性生成的任何 <option> 元素下方。

<template>
  <div>
    <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>
  </div>
</template>

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

<!-- b-form-datalist-example.vue -->

<b-form-datalist> 也可通过 <b-datalist> 的较短别名获得。

另请参见

验证

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

<b-form> 上将 validated 属性设置为 true 以添加 Bootstrap v4 .was-validated 类到表单以触发验证状态

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

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

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

验证机制

在 BootstrapVue 中使用基于 Vue 的第三方验证库

其他资源

组件参考

属性

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

属性
类型
默认值
描述
id
字符串用于设置呈现内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
inline
布尔值false设置后,表单将处于内联模式,在单行水平行中显示标签、表单控件和按钮
novalidate
布尔值false设置后,禁用表单中控件上的浏览器原生 HTML5 验证
validated
布尔值false设置后,在表单上添加 Bootstrap 类 'was-validated',触发原生浏览器验证状态

插槽

名称
描述
default 放置在表单中的内容

事件

事件
参数
描述
submit
  1. event - 原生提交事件
在提交表单时发出

<b-form-text>

功能组件

属性

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

属性
类型
默认值
描述
id
字符串用于设置呈现内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
inline
布尔值false设置后,将帮助文本渲染为内联元素,而不是块元素
tag
字符串'small'指定要渲染的 HTML 标记,而不是默认标记
text-variant
字符串'muted'将一个 Bootstrap 主题颜色变体应用于文本

插槽

名称
描述
default 放置在表单文本中的内容

<b-form-invalid-feedback>

功能组件

属性

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

属性
类型
默认值
描述
aria-live
字符串当呈现的元素是 `aria-live` 区域(对于屏幕阅读器用户)时,设置为“礼貌”或“自信”
force-show
布尔值false显示反馈文本,无论“状态”属性的值如何
id
字符串用于设置呈现内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
role
字符串将 ARIA 属性 `role` 设置为特定值
state
布尔值null当明确为“false”时,强制显示反馈
tag
字符串'div'指定要渲染的 HTML 标记,而不是默认标记
tooltip
布尔值false以基本的工具提示样式呈现反馈文本

插槽

名称
描述
default 放置在表单无效反馈中的内容

<b-form-valid-feedback>

功能组件

属性

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

属性
类型
默认值
描述
aria-live
字符串当呈现的元素是 `aria-live` 区域(对于屏幕阅读器用户)时,设置为“礼貌”或“自信”
force-show
布尔值false显示反馈文本,无论“状态”属性的值如何
id
字符串用于设置呈现内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
role
字符串将 ARIA 属性 `role` 设置为特定值
state
布尔值null当明确为“true”时,强制显示反馈
tag
字符串'div'指定要渲染的 HTML 标记,而不是默认标记
tooltip
布尔值false以基本的工具提示样式呈现反馈文本

插槽

名称
描述
default 放置在表单有效反馈元素中的内容

<b-form-datalist>

组件别名

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

  • <b-datalist>

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

属性

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

属性
类型
默认值
描述
disabled-field
字符串'disabled'`options` 数组中应用于禁用状态的字段名称
html-field
谨慎使用
字符串'html'`options` 数组中应用于 html 标签(而不是文本字段)的字段名称
id
必需
字符串用于设置呈现内容的 `id` 属性,并用作根据需要生成任何其他元素 ID 的基础
options
ArrayObject[]在组件中呈现的项数组
text-field
字符串'text'`options` 数组中应用于文本标签的字段名称
value-field
字符串'value'`options` 数组中应用于值的字段名称

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

插槽

名称
描述
default 要放置在 datalist 中的内容

导入单个组件

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

组件
命名导出
导入路径
<b-form>BFormbootstrap-vue
<b-form-text>BFormTextbootstrap-vue
<b-form-invalid-feedback>BFormInvalidFeedbackbootstrap-vue
<b-form-valid-feedback>BFormValidFeedbackbootstrap-vue
<b-form-datalist>BFormDatalistbootstrap-vue

示例

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

作为 Vue.js 插件导入

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

命名导出
导入路径
FormPluginbootstrap-vue

示例

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