formLayout

ДЕМО

Адаптивный контейнер, который располагает компоненты в колонках. Количество колонок изменяется в зависимости от ширины контейнера.

XML-элемент

formLayout

Java-класс

FormLayout

Атрибуты

id - alignSelf - autoResponsive - autoRows - classNames - clickShortcut - colspan - columnSpacing - columnWidth - css - dataContainer - enabled - expandColumns - expandFields - height - labelsAside - labelSpacing - labelsPosition - labelWidth - maxColumns - maxHeight - maxWidth - minColumns - minHeight - minWidth - rowSpacing - visible - width

Обработчики

AttachEvent - clickListener - doubleClickListener - singleClickListener - DetachEvent

Элементы

formItem - formRow - responsiveSteps

Основы

По умолчанию компоненты располагаются в две колонки.

<formLayout>
    <textField placeholder="City" label="Where from?"/>
    <textField placeholder="City" label="Where to?"/>
    <datePicker label="Depart"/>
    <datePicker label="Return"/>
    <button text="Search tickets"/>
</formLayout>
form layout basic 1

При уменьшении ширины контейнера он автоматически перестраивается в одну колонку.

form layout basic 2

Привязка данных

ДЕМО

Привязка данных означает связывание визуального компонента с контейнером данных.

В компоненте formLayout это достигается путем установки атрибута dataContainer, который ссылается на контейнер данных.

<data>
    <instance id="userDc"
              class="com.company.onboarding.entity.User"/> (1)
</data>
<layout>
    <formLayout dataContainer="userDc"> (2)
        <textField property="firstName"/> (3)
        <textField property="lastName"/>
        <textField property="username"/>
        <textField property="email"/>
    </formLayout>
</layout>
1 Контейнер экземпляра для сущности User.
2 Привязка компонента к контейнеру данных. Атрибут dataContainer содержит ссылку на контейнер данных userDc.
3 Вложенные элементы formLayout определяют визуальные компоненты, привязанные к атрибутам сущности с помощью XML-атрибута property. Надписи будут созданы автоматически на основе локализованных имен атрибутов сущности.

Автоматический адаптивный режим

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

Чтобы включить этот режим, установите атрибут autoResponsive в значение true.

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

Строки формы

В автоматическом адаптивном режиме по умолчанию все поля отображаются в одном столбце.

Чтобы организовать поля в несколько столбцов, используйте один из следующих подходов:

  1. Сгруппируйте поля вручную: поместите связанные поля в элемент formRow, чтобы создать явную многоколоночную группу.

    <formLayout autoResponsive="true">
    <formRow>
        <textField label="Where from?" placeholder="City"/>
        <textField placeholder="City" label="Where to?"/>
        <datePicker label="Depart"/>
    </formRow>
    <formRow>
        <datePicker label="Return"/>
        <button text="Search tickets"/>
    </formRow>
</formLayout>

    Каждый элемент formRow всегда начинается с новой строки. Поля, которые не помещаются в доступные столбцы, переносятся на новую строку, которая затем остается зарезервированной исключительно для полей этого formRow.

  2. Включите автоматическое распределение: установите атрибут autoRows в значение true, чтобы контейнер автоматически размещал поля в доступных столбцах, перенося их на новую строку при заполнении текущей.

Атрибут rowSpacing управляет вертикальным промежутком между строками. Эта настройка применяется к промежутку между всеми строками, независимо от того, созданы они вручную через formRow или автоматически через autoRows.

Позиционирование надписей

По умолчанию надписи отображаются над соответствующими полями. Чтобы расположить надписи рядом с полями, оберните поля в элементы formItem и активируйте атрибут labelsAside="true" в formLayout.

При использовании режима "надписи сбоку", применяйте надпись к элементу formItem, а не к самому полю.

В примере ниже показано, как расположить надписи рядом с полями:

<formLayout autoResponsive="true" labelsAside="true">
    <formRow>
        <formItem label="Where from?">
            <textField placeholder="City"/>
        </formItem>
        <formItem label="Where to?">
            <textField placeholder="City"/>
        </formItem>
        <formItem label="Depart">
            <datePicker/>
        </formItem>
    </formRow>
    <formRow>
        <formItem label="Return">
            <datePicker/>
        </formItem>
        <button text="Search tickets"/>
    </formRow>
</formLayout>

Если ширина formLayout недостаточна для отображения надписей рядом с полями, он автоматически возвращается к поведению по умолчанию, отображая надписи над полями.

Атрибут labelSpacing определяет расстояние между надписью и полем, когда надписи расположены сбоку. Используйте этот атрибут для настройки горизонтального интервала с целью достижения оптимального макета.

Управление столбцами

В автоматическом адаптивном режиме столбцы имеют фиксированную ширину, задаваемую атрибутом columnWidth. Макет автоматически создает столбцы в пределах указанных ограничений на основе доступной ширины контейнера.

Макет динамически регулирует количество столбцов в зависимости от доступного пространства, соблюдая границы minColumns и maxColumns. Атрибут minColumns гарантирует создание минимального количества столбцов, в то время как maxColumns устанавливает верхний предел, предотвращая чрезмерное увеличение их числа. Визуальное расстояние между этими столбцами регулируется атрибутом columnSpacing с использованием единиц измерения CSS.

Для оптимального использования пространства доступно два режима расширения. Когда включен параметр expandFields, поля - включая те, что находятся внутри элементов formItem - растягиваются по горизонтали, заполняя свои столбцы. Альтернативно, параметр expandColumns позволяет всем столбцам пропорционально расширяться и совместно заполнять любое оставшееся доступное пространство в макете после первоначального расчета столбцов.

<formLayout autoResponsive="true"
            columnWidth="150px"
            minColumns="2"
            maxColumns="4"
            columnSpacing="3em"
            expandColumns="true"
            expandFields="true">
    <formRow>
        <textField placeholder="City" label="Where to?"/>
        <textField placeholder="City" label="Where from?"/>
    </formRow>
    <formRow>
        <datePicker label="Return"/>
        <datePicker label="Depart"/>
    </formRow>
    <formRow>
        <button text="Search tickets"/>
    </formRow>
</formLayout>

Режим адаптивных шагов

ДЕМО

Элемент responsiveSteps предоставляет способ определения количества колонок на основе доступного пространства.

<formLayout>
    <responsiveSteps>
        <responsiveStep minWidth="0" columns="1"/>
        <responsiveStep minWidth="30em" columns="2"/>
        <responsiveStep minWidth="40em" columns="3"/>
        <responsiveStep minWidth="50em" columns="4"/>
        <responsiveStep minWidth="60em" columns="5"/>
    </responsiveSteps>
    <textField placeholder="City" label="Where from?"/>
    <textField placeholder="City" label="Where to?"/>
    <datePicker label="Depart"/>
    <datePicker label="Return"/>
    <button text="Search tickets"/>
</formLayout>

Когда ширина становится достаточно большой, контейнер автоматически перестраивается на использование всех пяти колонок:

form layout columns

Позиция надписи

Контейнер позволяет использовать боковое расположение надписей для вложенных компонентов. Оберните компонент элементом formItem, указав его надпись, и задайте желаемое положение с помощью атрибута labelsPosition:

formItem может оборачивать только один компонент. 
<formLayout labelsPosition="ASIDE">
    <formItem label="Where from?">
        <textField placeholder="City"/>
    </formItem>
    <formItem label="Where to?">
        <textField placeholder="City"/>
    </formItem>
    <formItem label="Depart">
        <datePicker/>
    </formItem>
    <formItem label="Return">
        <datePicker/>
    </formItem>
    <formItem>
        <button text="Search tickets"/>
    </formItem>
</formLayout>
form layout labels aside

Адаптивное положение надписи

Контейнеры, отображающие надписи сбоку, требуют больше места, чем те, у которых надписи расположены по умолчанию сверху над компонентами. Аналогично количеству колонок, положение надписи можно настроить в соответствии с доступным пространством. Вместо добавления атрибута labelsPosition к контейнеру, добавьте его к отдельным элементам responsiveSteps:

<formLayout>
    <responsiveSteps>
        <responsiveStep minWidth="0" columns="1" labelsPosition="TOP"/>
        <responsiveStep minWidth="30em" columns="1" labelsPosition="ASIDE"/>
        <responsiveStep minWidth="40em" columns="2" labelsPosition="TOP"/>
        <responsiveStep minWidth="50em" columns="2" labelsPosition="ASIDE"/>
    </responsiveSteps>
    <formItem label="Where from?">
        <textField placeholder="City"/>
    </formItem>
    <formItem label="Where to?">
        <textField placeholder="City"/>
    </formItem>
    <formItem label="Depart">
        <datePicker/>
    </formItem>
    <formItem label="Return">
        <datePicker/>
    </formItem>
    <formItem colspan="2">
        <button text="Search tickets"/>
    </formItem>
</formLayout>

Изменение ширины контейнера повлияет как на количество колонок, так и на позиционирование надписей:

form layout responsive labels position

Объединение колонок

Используйте атрибут colspan, чтобы контролировать, сколько колонок должен занимать вложенный компонент.

Например, можно сделать так, чтобы кнопка всегда занимала две колонки, даже когда другие компоненты этого не делают:

<formLayout id="abc">
    <textField placeholder="City" label="Where from?"/>
    <textField placeholder="City" label="Where to?"/>
    <datePicker label="Depart"/>
    <datePicker label="Return"/>
    <button text="Search tickets" colspan="2"/>
</formLayout>
form layout

Атрибуты

В Jmix есть множество общих атрибутов, которые выполняют одну и ту же функцию для всех компонентов.

Ниже приведены атрибуты, специфичные для formLayout.

Название

Описание

Значение по умолчанию

autoResponsive

Включает автоматический расчет и адаптацию количества столбцов на основе доступной ширины контейнера. Смотрите Автоматический адаптивный режим.

false

autoRows

Настраивает автоматическое распределение полей по столбцам, с последовательным заполнением строк перед переносом на следующую. Работает только при включенном autoResponsive. Смотрите Автоматический адаптивный режим.

false

columnWidth

Задает фиксированную ширину для всех столбцов в допустимых CSS-единицах измерения (например, "100px", "10em"). Работает только при включенном autoResponsive. Смотрите Управление столбцами.

13em

columnSpacing

Определяет расстояние между столбцами в CSS-единицах. Работает только при включенном autoResponsive. Смотрите Управление столбцами.

expandColumns

При включении столбцы равномерно распределяются для заполнения оставшегося горизонтального пространства. Работает только при включенном autoResponsive. Смотрите Управление столбцами.

false

expandFields

При включении поля растягиваются на всю доступную ширину столбца (включая поля в formItem). Работает только при включенном autoResponsive. Смотрите Управление столбцами.

false

labelsAside

Размещает надписи formItem рядом с полями, а не над ними. Работает только при включенном autoResponsive. Смотрите Позиционирование надписей.

false (надписи располагаются над полями)

labelSpacing

Задает расстояние между надписью и полем в боковом расположении (в CSS-единицах, например, 1em). Работает только при включенном autoResponsive. Смотрите Позиционирование надписей.

labelsPosition

Определяет позицию надписей для компонентов:

- ASIDE - сбоку от компонентов.

- TOP - над компонентами.

TOP

labelWidth

Задает ширину боковых надписей (в CSS-единицах, например, 1em). Смотрите Позиционирование надписей и Позиция надписи.

maxColumns

Максимальное количество столбцов (не превышается даже при наличии места). Работает только при включенном autoResponsive. Смотрите Управление столбцами.

10

minColumns

Минимальное количество столбцов (создается даже при недостатке места). Работает только при включенном autoResponsive. Смотрите Управление столбцами.

1

rowSpacing

Определяет расстояние между строками в CSS-единицах. Работает только при включенном autoResponsive. Смотрите Строки формы.

Смотрите также

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