Группа формы

Компонент <b-form-group> - самый простой способ добавить некоторую структуру к формам. Его цель состоит в том, чтобы объединить элементы управления формы с легендой или меткой и предоставить текст справки и невалидный/валидный текст обратной связи, а также визуальную (цветную) обратную связь с контекстным состоянием.

<template>
  <div>
    <b-form-group
      id="fieldset-1"
      description="Дайте нам знать ваше имя."
      label="Введите ваше имя"
      label-for="input-1"
      valid-feedback="Спасибо!"
      :invalid-feedback="invalidFeedback"
      :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
      },
      invalidFeedback() {
        if (this.name.length > 0) {
          return 'Введите не менее 4 символов.'
        }
        return 'Пожалуйста, введите что-нибудь.'
      }
    },
    data() {
      return {
        name: ''
      }
    }
  }
</script>

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

Label

Используйте свойство label, чтобы установить содержимое сгенерированного элемента <legend> или <label>, или, используя именованный слот label, вы можете при желании визуально скрыть текст метки, оставив его доступным для программы чтения с экрана, установив свойство label-sr-only.

<b-form-group> будет отображать <fieldset> с <legend>, если свойство label-for не установлено. Если для свойства label-for предоставлен входной идентификатор, то будет отображаться <div> с <label>.

Если вы предоставите входное значение id для свойства label-for (id должен существовать на входе, содержащемся внутри <b-form-group>), элемент <label> будет визуализируется вместо элемента <legend>, и для атрибута for будет задан указанный id. При указании идентификатора не добавляйте перед ним символ #. Свойство label-for следует использовать только тогда, когда у вас есть один ввод формы внутри компонента <b-form-group>. Не устанавливайте свойство label-for при использовании компонентов <b-form-radio-group>, <b-form-checkbox-group>, <b-form-radio>, <b-form-checkbox> или <b-form-file> (или при размещении нескольких входов в одной и той же группе форм), поскольку эти входы включают интегрированный элемент(ы) метки, а элемент <legend> более подходит.

Вы также можете применить к метке дополнительные классы с помощью свойства label-class, например вспомогательные классы адаптивного заполнения и выравнивания текста. Свойство label-class принимает либо строку, либо массив строк.

Горизонтальный макет

По умолчанию метка отображается над элементом (элементами) ввода, но вы можете при желании отобразить горизонтальную (метку слева от ввода) в различных стандартных контрольных точках Bootstrap.

Свойства label-cols и label-cols-{breakpoint} позволяют вам указать, сколько столбцов метка должна занимать в строке. Ввод заполнит оставшуюся часть ширины строки. Значение должно быть числом больше 0. Или вы можете установить свойство в значение true, чтобы каждая метка и вход (ы) занимали половину ширины отображаемой строки (это удобно, если у вас есть собственный Bootstrap с нечетным числом столбцов), или установите значение в 'auto', чтобы метка занимала только необходимую ширину.

Начиная с BootstrapVue v2.21.0, также можно указать, сколько столбцов содержимое должно занимать в строке с помощью свойств content-cols и content-cols-{breakpoint}.

При использовании обоих свойств: label-cols и content-cols, убедитесь, что общее количество столбцов не превышает 12.

Дополнительную информацию смотрите в документации Макет и Система сеток.

Свойство Описание
label-cols Применяется к контрольной точке выше xs
label-cols-sm Применяется к контрольной точке sm и выше
label-cols-md Применяется к контрольной точке md и выше
label-cols-lg Применяется к контрольной точке lg и выше
label-cols-xl Применяется к контрольной точке xl и выше
content-cols v2.21.0+ Применяется к контрольной точке выше xs
content-cols-sm v2.21.0+ Применяется к контрольной точке sm и выше
content-cols-md v2.21.0+ Применяется к контрольной точке md и выше
content-cols-lg v2.21.0+ Применяется к контрольной точке lg и выше
content-cols-xl v2.21.0+ Применяется к контрольной точке xl и выше
<div>
  <div>
    <b-form-group
      id="fieldset-horizontal"
      label-cols-sm="4"
      label-cols-lg="3"
      content-cols-sm
      content-cols-lg="7"
      description="Дайте нам знать ваше имя."
      label="Введите ваше имя"
      label-for="input-horizontal"
    >
      <b-form-input id="input-horizontal"></b-form-input>
    </b-form-group>
  </div>
</div>

<!-- b-form-group-horizontal.vue -->

В BootstrapVue версии v2.1.0 была добавлена возможность устанавливать для столбцов меток значение 'auto'.

Размер метки

Вы можете управлять размером текста метки в соответствии с размером ввода(ов) вашей формы с помощью необязательного свойства label-size. Значения могут быть 'sm' или 'lg' для маленькой или большой метки соответственно. Размеры подходят как для горизонтальных, так и для негоризонтальных групп форм.

<div>
  <b-form-group label-cols="4" label-cols-lg="2" label-size="sm" label="Маленькая" 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="По умолчанию" 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="Большая" label-for="input-lg">
    <b-form-input id="input-lg" size="lg"></b-form-input>
  </b-form-group>
</div>

<!-- b-form-group-label-size.vue -->

Выравнивание текста метки

Текст метки также может быть выровнен left, center или right, задав соответствующее значение с помощью свойства label-text-align и/или label-align-{breakpoint}.

Свойство Описание
label-align Применяется к контрольной точке выше xs
label-align-sm Применяется к контрольной точке sm и выше
label-align-md Применяется к контрольной точке md и выше
label-align-lg Применяется к контрольной точке lg и выше
label-align-xl Применяется к контрольной точке xl и выше

Выравнивание не действует, если задано свойство label-sr-only.

Описание

Необязательный описательный текст, который всегда отображается с классом .text-muted, задав свойство description или используя именованный слот description. Текст описания отображается с помощью подкомпонента формы <b-form-text>.

Вложенные группы форм

Не стесняйтесь вкладывать компоненты <b-form-group> для создания расширенных макетов форм и семантической группировки связанных элементов управления формой:

<div>
  <b-card bg-variant="light">
    <b-form-group
      label-cols-lg="3"
      label="Адрес доставки"
      label-size="lg"
      label-class="font-weight-bold pt-0"
      class="mb-0"
    >
      <b-form-group
        label="Улица:"
        label-for="nested-street"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-street"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Город:"
        label-for="nested-city"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-city"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Область:"
        label-for="nested-state"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-state"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Страна:"
        label-for="nested-country"
        label-cols-sm="3"
        label-align-sm="right"
      >
        <b-form-input id="nested-country"></b-form-input>
      </b-form-group>

      <b-form-group
        label="Доставить через:"
        label-cols-sm="3"
        label-align-sm="right"
        class="mb-0"
        v-slot="{ ariaDescribedby }"
      >
        <b-form-radio-group
          class="pt-2"
          :options="['Air', 'Courier', 'Mail']"
          :aria-describedby="ariaDescribedby"
        ></b-form-radio-group>
      </b-form-group>
    </b-form-group>
  </b-card>
</div>

<!-- b-form-group-nested.vue -->

Группа отключенных форм

Установка свойства disabled отключит отображаемый <fieldset> и в большинстве браузеров отключит все элементы ввода, содержащиеся в fieldset.

disabled не действует, если установлен label-for (поскольку элемент <fieldset> не отображается).

Обратная связь состояния валидации

Bootstrap включает стили состояния валидации valid и invalid для большинства элементов управления формой.

Вообще говоря, вы захотите использовать определенное состояние для определенных типов обратной связи:

  • false (обозначает недопустимое состояние) отлично подходит, когда есть блокирующее или обязательное поле. Пользователь должен правильно заполнить это поле, чтобы отправить форму.
  • true (обозначает действительное состояние) идеально подходит для ситуаций, когда у вас есть проверка по каждому полю во всей форме и вы хотите побудить пользователя пройти через остальные поля.
  • null Не отображает состояние проверки (ни действительное, ни недействительное)

Чтобы применить один из значков контекстного состояния к <b-form-group> установите для свойства state значение false (для недопустимого), true (для действительного) или null (состояние проверки отсутствует).

Bootstrap v4 использует родственные CSS-селекторы инпутов :invalid или :valid для отображения текста отзыва. Некоторые элементы управления формы (такие как флажки, радио и входные данные файлов или входные данные внутри групп ввода) заключены в дополнительную разметку, которая больше не будет делать текст обратной связи аналогом ввода, и, следовательно, обратная связь не будет отображаться. В этих ситуациях вам нужно будет установить значение state для <b-form-group> а также в инпуте.

Обратная связь будет показана, если родительский компонент <b-form> не имеет свойство novalidate, установленное (или имеет значение false) вместе с набором свойств validated (и ввод не выполняется или проходит проверку в собственном браузере. ограничения, такие как required). Обратитесь к Bootstrap v4 Компонент формы для получения подробной информации о методах проверки.

Вы всегда должны предоставлять контент через свойство invalid-feedback (или слот), чтобы помочь пользователям использовать вспомогательные технологии при установке контекстного состояния invalid.

Невалидная обратная связь

Показать необязательный текст обратной связи о недопустимом состоянии, чтобы обеспечить текстовую обратную связь о состоянии (поддерживается HTML), установив свойство invalid-feedback или используя именованный слот invalid-feedback.

Недопустимая обратная связь отображается с помощью подкомпонента формы <b-form-invalid-feedback>.

Валидная обратная связь

Показать необязательный действительный текст обратной связи о состоянии, чтобы обеспечить текстовую обратную связь о состоянии (поддерживается HTML), установив свойство valid-feedback или используя именованный valid-feedback.

Правильная обратная связь отображается с помощью подкомпонента формы<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>, установка недопустимого (или допустимого) состояния state на input не будет вызывает отображение недопустимой (или действительной) обратной связи (из-за ограничений, связанных с новым CSS для проверки Bootstrap v4). Чтобы обойти это, вы также должны установить недопустимое/допустимое состояние state в <b-form-group>. Встроенная проверка браузера не вызовет недопустимую обратную связь, отображаемую при использовании одного из вышеупомянутых элементов управления формой.

Доступность

По умолчанию, когда значение label-for не указано, <b-form-group> отображает элементы управления вводом внутри элемента HTML <fieldset> с содержимым метки, помещенным внутри поля элемента <legend>. По характеру этой разметки содержимое легенды автоматически связывается с содержащими элементами управления вводом.

Настоятельно рекомендуется предоставить уникальное свойство id для элемента ввода и установить свойство label-for для этого идентификатора, если у вас есть только один ввод в группе <b-form-group>.

Когда несколько элементов управления формы помещаются внутри <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>.

Когда для <b-form-group> задано свойство label-for, атрибут aria-describedbyбудет автоматически назначен входу. Если в группе форм есть несколько элементов управления, убедитесь, что вы установили атрибут для каждого элемента управления самостоятельно, используя значение свойства ariaDescribedby из необязательного слота default с областью действия.

Справочник по компонентам

<b-form-group>

Свойства

Все значения свойств по умолчанию настраиваются глобально.

Свойство
(Click to sort ascending)
Тип
(Click to sort ascending)
По умолчанию
Описание
content-cols
v2.21.0+
Boolean или Number или StringКоличество колонок для контента ширины экрана 'xs' и выше
content-cols-lg
v2.21.0+
Boolean или Number или StringКоличество колонок для контента ширины экрана 'lg' и выше
content-cols-md
v2.21.0+
Boolean или Number или StringКоличество колонок для контента ширины экрана 'md' и выше
content-cols-sm
v2.21.0+
Boolean или Number или StringКоличество колонок для контента ширины экрана 'sm' и выше
content-cols-xl
v2.21.0+
Boolean или Number или StringКоличество колонок для контента ширины экрана 'xl' и выше
description
StringТекст для размещения в текстовой области справки группы форм
disabled
BooleanfalseОтключен элемент fieldset, который, в свою очередь, отключает элементы управления формой (в браузерах, поддерживающих отключенные наборы полей). Не действует, если установлен `label-for`
feedback-aria-live
String'assertive'Значение для атрибута `aria-live` в тексте отзыва
id
StringИспользуется для установки атрибута `id` для визуализированного контента и используется в качестве основы для генерации любых дополнительных идентификаторов элементов по мере необходимости.
invalid-feedback
StringТекст, отображаемый, когда группа форм имеет недопустимое состояние
label
StringТекст для размещения в метке/легенде группы форм
label-align
StringВыравнивание текста 'left', 'center', 'right' для метки экранов 'xs' и выше
label-align-lg
StringВыравнивание текста 'left', 'center', 'right' для метки экранов 'lg' и выше
label-align-md
StringВыравнивание текста 'left', 'center', 'right' для метки экранов 'md' и выше
label-align-sm
StringВыравнивание текста 'left', 'center', 'right' для метки экранов 'sm' и выше
label-align-xl
StringВыравнивание текста 'left', 'center', 'right' для метки экранов 'xl' и выше
label-class
Array или Object или StringКласс (или классы) CSS для добавления к элементу метки/легенды
label-cols
Boolean или Number или StringКоличество колонок для метки label ширины экрана 'xs' и выше
label-cols-lg
Boolean или Number или StringКоличество колонок для метки label ширины экрана 'lg' и выше
label-cols-md
Boolean или Number или StringКоличество колонок для метки label ширины экрана 'md' и выше
label-cols-sm
Boolean или Number или StringКоличество колонок для метки label ширины экрана 'sm' и выше
label-cols-xl
Boolean или Number или StringКоличество колонок для метки label ширины экрана 'xl' и выше
label-for
StringЗадайте идентификатор элемента управления единственной формы в группе форм. Не устанавливайте значение, если в группе более одного элемента управления формой
label-size
StringУстанавливает размер текста метки label: 'sm', 'md' (по умолчанию) или 'lg'. Используйте это свойство, чтобы размер этикетки соответствовал размеру элемента управления формы
label-sr-only
BooleanfalseВизуально скрывает содержимое ярлыка, но делает его доступным для пользователей программ чтения с экрана
state
BooleannullУправляет состоянием проверки обратной связи. `true` форсированно показывает валидную обратную связь, `false` форсированно показывает недопустимую обратную связь, `null` не заставляет показывать обратную связь
tooltip
BooleanfalseОтображает текст обратной связи в элементарном стиле всплывающей подсказки
valid-feedback
StringТекст, показывающий, когда группа форм имеет допустимое состояние
validated
BooleanfalseЕсли установлено, добавляет класс триггера проверки Bootstrap 'was-validated' в компонент

Слоты

Наименование
Область
Описание
default Контент для размещения в группе форм
description НетКонтент для размещения в области описания. Переопределяет свойство `description`
invalid-feedback НетКонтент для размещения в недействительной области обратной связи. Переопределяет свойство `invalid-feedback`
label НетКонтент для размещения внутри элемента метки. Переопределяет свойство `label`
valid-feedback НетКонтент для размещения в действующей области обратной связи. Переопределяет свойство `valid-feedback`

Импорт отдельных компонентов

Вы можете импортировать отдельные компоненты в свой проект с помощью следующих именованных экспортов:

Компонент
Именованный экспорт
Путь импорта
<b-form-group>BFormGroupbootstrap-vue

Пример:

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

Импортировать как плагин Vue.js

Этот плагин включает в себя все перечисленные выше отдельные компоненты. Плагины также включают псевдонимы любых компонентов.

Именованный экспорт
Путь импорта
FormGroupPluginbootstrap-vue

Пример:

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