首页
中文手册
组件
表单组合
表单组合(Form group)
<b-form-group>
组件是向表单添加某些结构的最简单方法。 其目的是将表单控件与图例或标签配对,并提供帮助文本和无效/有效的反馈文本,以及可视(彩色)上下文状态反馈。
Show page table of contents
<template >
<div >
<b-form-group
id ="fieldset-1"
description ="Let us know your name."
label ="Enter your name"
label-for ="input-1"
:invalid-feedback ="invalidFeedback"
:valid-feedback ="validFeedback"
:state ="state"
>
<b-form-input id ="input-1" v-model ="name" :state ="state" trim > </b-form-input >
</b-form-group >
</div >
</template >
<script >
export default {
computed : {
state() {
return this .name.length >= 4 ? true : false
},
invalidFeedback() {
if (this .name.length > 4 ) {
return ''
} else if (this .name.length > 0 ) {
return 'Enter at least 4 characters'
} else {
return 'Please enter something'
}
},
validFeedback() {
return this .state === true ? 'Thank you' : ''
}
},
data() {
return {
name : ''
}
}
}
</script >
标签
使用 label
【标签】属性设置生成的 <legend>
或 <label>
元素的内容,或者通过使用命名的 label
插槽,您可以选择在视觉上隐藏标签文本,同时仍然通过仅设置 label-sr-only
属性使其可用于屏幕阅读器。
<b-form-group>
将使用 <legend>
呈现 <fieldset>
,如果未设置 label-for
属性。如果为 label-for
属性提供了一个输入ID,那么将呈现一个带有 <label>
的 <div>
。
如果为 label-for
属性提供输入 id
值(该 id
必须存在于 <b-form-group>
中包含的输入中),则将呈现 <label>
元素而不是 <legend>
元素,并且 将 for
属性设置为指定的 id
。指定 id 时,请勿 在其前面加上 #
。仅当在 <b-form-group>
组件内有单个表单输入时,才应使用 label-for
属性。使用 <b-form-radio-group>
,<b-form-checkbox-group>
,<b-form-radio>
,<b-form-checkbox>
或 <b-form-file>
组件时,请勿设置 label-for
属性(或将多个输入放置在同一表单组中),因为这些输入包括集成的标签元素,并且 <legend>
元素更合适。
还可以通过 label-class
属性将其他类应用于标签,例如响应填充和文本对齐实用程序类。label-class
属性接受字符串或字符串数组。
水平布局
默认情况下,标签显示在输入元素的上方,但是您可以选择在各种标准 Bootstrap 断点处渲染水平(标签在输入的左侧)。
label-cols
和 label-cols-{breakpoint}
允许您指定标签应在行中占据多少列。输入将填充其余的行宽。该值必须是一个大于 0
的数字。或者,您可以将属性设置为 true
,以使标签和输入每个都占据呈现的行的宽度的一半(如果您的自定义 Bootstrap 的列数为奇数,则非常有用 ),或将值设置为 'auto'
,以便标签仅占据所需的宽度。
属性
描述
label-cols
适用于断点 xs
上
label-cols-sm
适用于断点 sm
及以上
label-cols-md
适用于断点 md
及以上
label-cols-lg
适用于断点 lg
及以上
label-cols-xl
适用于断点 xl
及以上
<div >
<div >
<b-form-group
id ="fieldset-horizontal"
label-cols-sm ="4"
label-cols-lg ="3"
description ="Let us know your name."
label ="Enter your name"
label-for ="input-horizontal"
>
<b-form-input id ="input-horizontal" > </b-form-input >
</b-form-group >
</div >
</div >
在 BootstrapVue 版本 2.1.0 中添加了将标签 cols 设置为 'auto'
的功能。
标签尺寸
您可以通过可选的 label-size
属性控制标签文本的大小与表单输入的大小相匹配。小标签或大标签的值分别可以是 'sm'
或 'lg'
。大小适用于水平和非水平表单组。
<div >
<b-form-group label-cols ="4" label-cols-lg ="2" label-size ="sm" label ="Small" label-for ="input-sm" >
<b-form-input id ="input-sm" size ="sm" > </b-form-input >
</b-form-group >
<b-form-group label-cols ="4" label-cols-lg ="2" label ="Default" label-for ="input-default" >
<b-form-input id ="input-default" > </b-form-input >
</b-form-group >
<b-form-group label-cols ="4" label-cols-lg ="2" label-size ="lg" label ="Large" label-for ="input-lg" >
<b-form-input id ="input-lg" size ="lg" > </b-form-input >
</b-form-group >
</div >
标签文字对齐
标签文本也可以通过 label-text-align
属性和/或 label-align-{breakpoint}
属性设置各自的值来选择 left
,center
或 right
对齐。
属性
描述
label-align
适用于断点 xs
上
label-align-sm
适用于断点 sm
及以上
label-align-md
适用于断点 md
及以上
label-align-lg
适用于断点 lg
及以上
label-align-xl
适用于断点 xl
及以上
如果设置了 label-sr-only
属性,则对齐方式无效。
描述
可选的描述性文本,总是通过设置 description
【描述】属性或使用命名的 description
【描述】插槽与 .text-muted
类一起显示。描述文本是使用 <b-form-text>
表单子组件渲染的。
随意嵌套 <b-form-group>
组件,以生成高级表单布局和相关表单控件的语义分组:
<div >
<b-card bg-variant ="light" >
<b-form-group
label-cols-lg ="3"
label ="Shipping Address"
label-size ="lg"
label-class ="font-weight-bold pt-0"
class ="mb-0"
>
<b-form-group
label-cols-sm ="3"
label ="Street:"
label-align-sm ="right"
label-for ="nested-street"
>
<b-form-input id ="nested-street" > </b-form-input >
</b-form-group >
<b-form-group
label-cols-sm ="3"
label ="City:"
label-align-sm ="right"
label-for ="nested-city"
>
<b-form-input id ="nested-city" > </b-form-input >
</b-form-group >
<b-form-group
label-cols-sm ="3"
label ="State:"
label-align-sm ="right"
label-for ="nested-state"
>
<b-form-input id ="nested-state" > </b-form-input >
</b-form-group >
<b-form-group
label-cols-sm ="3"
label ="Country:"
label-align-sm ="right"
label-for ="nested-country"
>
<b-form-input id ="nested-country" > </b-form-input >
</b-form-group >
<b-form-group
label-cols-sm ="3"
label ="Ship via:"
label-align-sm ="right" class ="mb-0"
>
<b-form-radio-group
class ="pt-2"
:options ="['Air', 'Courier', 'Mail']"
> </b-form-radio-group >
</b-form-group >
</b-form-group >
</b-card >
</div >
设置 disabled
属性将禁用渲染的 <fieldset>
,并且在大多数浏览器中,将禁用该fieldset中包含的所有输入元素。
设置 label-for
时,disabled
无效(因为未呈现 <fieldset>
元素)。
验证状态反馈
Bootstrap包括大多数表单控件上 valid
【有效】和 invalid
【无效】状态的验证样式。
一般来说,您需要针对特定类型的反馈使用特定状态:
false
(表示无效状态)非常适合存在阻塞或必填字段的情况。用户必须正确填写此字段才能提交表单。
true
(表示有效状态)非常适合在整个表单中都进行逐字段验证并希望鼓励用户遍历其余字段的情况。
null
不显示验证状态(既不有效也不无效)
要在 <b-form-group>
上应用上下文状态图标之一,请将 state
属性设置为 false
(对于无效),true
(对于有效)或 null
(无验证状态)。
Bootstrap v4使用 :invalid
或 :valid
输入的同级 CSS 选择器来显示反馈文本。一些表单控件(例如复选框,单选框和文件输入,或输入组内部的输入)被包装在其他标记中,这些标记将不再使反馈文本成为输入的同级,因此将不会显示反馈。 在这些情况下,您将需要在 <b-form-group>
以及 输入上设置有效性 state
【状态】。
如果父 <b-form>
组件 没 有 novalidate
属性(或将其设置为 false
)以及 validated
属性(输入失败或通过原生浏览器验证约束,如 required
),将显示反馈。有关验证方法的详细信息,请参阅 Bootstrap v4 的 Form component 【表单组件】文档。
您应该始终通过 invalid-feedback
【无效反馈】属性(或插槽)提供内容,以帮助用户在设置上下文 invalid
【无效】状态时使用辅助技术。
无效反馈
显示可选的无效状态反馈文本,以通过设置 invalid-feedback
属性或使用命名的 invalid-feedback
插槽提供文本状态反馈(支持html)。
使用 <b-form-invalid-feedback>
表单子组件呈现了无效的反馈。
有效反馈
显示可选的有效状态反馈文本,以通过设置 valid-feedback
【有效反馈】或使用命名的插槽 valid-feedback
【有效反馈】来提供文本状态反馈(支持html)。
有效反馈使用 <b-form-valid-feedback>
表单子组件呈现。
反馈方式
默认情况下,可见时,反馈(有效或无效)将显示为文本块。您可以通过将 tooltip
【工具提示】属性设置为 true
来更改反馈,使其在可见时显示为静态工具提示。
反馈限制
注意: 使用 <b-input-group>
,<b-form-file>
,<b-form-radio-group>
,<b-form-radio>
,<b-form-checkbox-group>
或 <b-form-checkbox>
中的 <b-form-group>
,仅在 input
上设置无效(或有效)state
不会 触发显示无效(或有效)反馈(由于新的 Bootstrap v4 验证 CSS 的限制))。要解决此问题,您还必须 在 <b-form-group>
上设置无效/有效 state
【状态】。使用上述表单控件之一时,本机浏览器验证 不会 触发显示无效反馈。
辅助功能
要启用 aria-*
属性的自动生成,应为 <b-form-group>
提供唯一的 id
属性。 这会将帮助文本和反馈文本关联到 <b-form-group>
,并间接关联到其输入控件。
默认情况下,当未提供 label-for
值时,<b-form-group>
会将输入控件呈现在HTML <fieldset>
元素内,标签内容置于 fieldset 的 <legend>
元素内。通过此标记的性质,图例内容自动与包含的输入控件相关联。
强烈建议 您在 <b-form-group>
中只有一个输入的情况下,在输入元素上提供唯一的 id
属性,并为该ID设置 label-for
属性。
当在 <b-form-group>
内放置多个表单控件(即一系列或单选或复选框输入,或一系列相关输入)时,请勿设置 label-for
属性,因为标签只能与 单输入。最好使用默认的呈现标记,该标记产生一个 <fieldset>
+ <legend>
来描述输入组。
当在 <b-form-group>
内放置多个表单控件时(并且您不嵌套 <b-form-group>
组件),建议为每个控件赋予其自己的关联 <label>
(可使用 ( .sr-only
类),并将属性标签设置为 for
【关联】的输入控件的 id
。或者,您可以在每个输入控件上设置 aria-label
属性,而不使用 <label>
。对于 <b-form-radio>
和 <b-form-checkbox>
(或组版本),您不需要设置单个标签,因为这些类型的输入的呈现标记已经包含 <label>
元素。
组件引用
属性 (Click to sort Ascending)
类型
默认值
描述
id
String
用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础
state
Boolean
控制反馈的验证状态。'true'强制显示有效反馈,'false'强制显示无效反馈,'null'不强制显示反馈
label
String
放置在表单组的标签/图例中的文本
label-for
String
设置为表单组中单个表单控件的ID。如果组中有多个表单控件,则不要设置值。
label-size
String
设置标签的文本大小:“sm”,“md”(默认)或“lg”。 使用此道具可使标签尺寸与表格控件尺寸匹配
label-sr-only
Boolean
false
可视地隐藏标签内容,但可让屏幕阅读器用户使用
label-cols
Number or String or Boolean
标签宽度 xs 屏幕及以上的列数
label-cols-sm
Number or String or Boolean
false
标签宽度 sm 屏幕及以上的列数
label-cols-md
Number or String or Boolean
false
标签宽度 md 屏幕及以上的列数
label-cols-lg
Number or String or Boolean
false
标签宽度 lg 屏幕及以上的列数
label-cols-xl
Number or String or Boolean
false
标签宽度 xl 屏幕及以上的列数
label-align
String
标签 xs 屏幕和上方的文本对齐方式'left', 'center', 'right'
label-align-sm
String
标签 sm 屏幕和上方的文本对齐方式'left', 'center', 'right'
label-align-md
String
标签 md 屏幕和上方的文本对齐方式'left', 'center', 'right'
label-align-lg
String
标签 lg 屏幕和上方的文本对齐方式'left', 'center', 'right'
label-align-xl
String
标签 xl 屏幕和上方的文本对齐方式'left', 'center', 'right'
label-class
String or Array or Object
CSS类(或多个类)添加到 label / legend 元素
description
String
放置在表单组的帮助文本区域中的文本
invalid-feedback
String
表单组处于无效状态时显示的文本
valid-feedback
String
在表单组处于有效状态时显示的文本
tooltip
Boolean
false
以基本的工具提示样式呈现反馈文本
feedback-aria-live
String
'assertive'
用于反馈文本上“aria-live”属性的值
validated
Boolean
false
设置后,在组件上添加 Bootstrap 验证触发器类 'was-validated'
disabled
Boolean
false
禁用 fieldset 元素,这又禁用了表单控件(在支持禁用的 fieldset 的浏览器上)。如果设置了 'label-for' ,则无效
插槽名称
描述
label
要放置在 <label> 元素内的内容。
description
要放置在描述区域中的内容。
invalid-feedback
要放置在无效反馈区域中的内容
valid-feedback
要放置在有效反馈区域中的内容
导入单个组件
您可以通过以下指定的导出将各个组件导入到您的项目中:
组件
命名输出
导入路径
<b-form-group>
BFormGroup
bootstrap-vue
示例:
import { BFormGroup } from 'bootstrap-vue'
Vue.component('b-form-group' , BFormGroup)
作为Vue.js插件导入
这个插件包含了上面列出的所有组件。插件还包括任何组件别名。
命名输出
导入路径
FormGroupPlugin
bootstrap-vue
示例:
import { FormGroupPlugin } from 'bootstrap-vue'
Vue.use(FormGroupPlugin)