formLayout 表单布局

formLayout 在响应式的列布局中排列表单字段。

XML 元素

formLayout

Java 类

JmixFormLayout

基本用法

在线示例

默认的响应式布局规则是，在宽度小于 40em 按一列布局，宽度在 40em 或以上按两列布局：

<formLayout>
    <textField label="TextField"/>
    <dateTimePicker label="DateTimePicker"/>
    <textArea label="TextArea"/>
    <checkbox label="Checkbox"/>
    <textArea label="TextArea with column span" colspan="2"/>
    <passwordField label="PasswordField"/>
    <emailField label="EmailField"/>
</formLayout>

数据感知的 formLayout

在线示例

在 formLayout 上设置 dataContainer 属性，可以将其内部字段与 实例容器 中的实体绑定。每个字段使用 property 选择显示的实体属性。

<data>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer"
                fetchPlan="_local">
        <loader id="customersLoader">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"/>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <select id="customerSelect" label="Customer" itemsContainer="customersDc"
            helperText="Select a customer to display"/>
    <formLayout dataContainer="customerDc">
        <textField property="name"/>
        <textField property="lastName"/>
        <integerField property="age"/>
        <checkbox property="active"/>
        <select property="grade"/>
    </formLayout>
</layout>

自动响应模式

在线示例

设置 autoResponsive="true" 时，formLayout 根据可用宽度、配置的列宽和空间来确定列数。每个 formRow 表示一个新行。如果其字段无法适配宽度，会自动换到下一行（为 formRow 保留的行）。

当自动响应模式启用时，会忽略 响应式列数。 
<formLayout id="formLayout" width="100%" classNames="form-layout" autoResponsive="true">
    <formRow>
        <formItem label="msg://firstName.label">
            <textField/>
        </formItem>
        <formItem label="msg://lastName.label">
            <textField/>
        </formItem>
        <formItem label="msg://rating.label">
            <comboBox id="ratingField"/>
        </formItem>
    </formRow>
    <formRow>
        <formItem label="msg://countryName.label">
            <textField/>
        </formItem>
        <formItem label="msg://birthDate.label">
            <datePicker/>
        </formItem>
        <formItem label="msg://email.label">
            <emailField/>
        </formItem>
    </formRow>
    <formRow>
        <formItem label="msg://status.label">
            <comboBox/>
        </formItem>
        <formItem label="msg://phoneNumber.label">
            <textField/>
        </formItem>
        <formItem label="msg://address.label">
            <textField/>
        </formItem>
    </formRow>
</formLayout>

对于没有显式配置 formRow 元素而需要自动分配时，请设置 autoRows="true"。minColumns、maxColumns、columnWidth、columnSpacing、rowSpacing、expandColumns 和 expandFields 元素可以微调生成的网格如何使用可用空间。

响应式档位模式

在线示例

使用内部的 responsiveStep 元素指定在特定的最小宽度时，需显示的列数和标签位置。通过可用的档位控制布局的呈现。

<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"/>
        <responsiveStep minWidth="60em" columns="4" labelsPosition="TOP"/>
    </responsiveSteps>
    <formItem label="TextField">
        <textField/>
    </formItem>
    <formItem label="DateTimePicker">
        <dateTimePicker/>
    </formItem>
    <formItem label="TextArea">
        <textArea/>
    </formItem>
    <formItem label="Checkbox">
        <checkbox/>
    </formItem>
    <formItem label="TextArea with column span" colspan="2">
        <textArea/>
    </formItem>
    <formItem label="PasswordField">
        <passwordField/>
    </formItem>
    <formItem label="EmailField">
        <emailField/>
    </formItem>
</formLayout>

XML 属性

通用属性 对所有组件都是一样的配置。 下面是 formLayout 的特殊属性：

名称 描述 默认值

autoResponsive

布局根据其容器的可用宽度自动计算和调整列数。参阅 自动响应模式。

false

autoRows

配置布局是否应自动将字段分布到各列，顺序填充每行后再换到下一行。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

false

columnWidth

为所有列定义固定宽度。值必须是有效的 CSS 长度单位（例如 "100px"、"10em"）。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

12em

columnSpacing

使用 CSS 长度单位定义列之间的间距。

—

expandColumns

启用后，列会均匀分布以填充初始列计算后剩余的水平空间。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

false

expandFields

启用后，字段会拉伸以填充其所在列的所有可用宽度。这也适用于包裹在 formItem 元素中的字段。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

false

labelsAside

指定布局中的 formItem 元素应将其标签放在相关字段的旁边而不是上方。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

false（标签位于字段上方）

labelSpacing

当标签放在字段旁边时，定义标签与对应字段之间的间距（CSS 长度）。例如 1em。

—

labelsPosition

为默认响应式档位配置标签位置，也应用于不带 labelsPosition 的 responsiveStep 元素。

- ASIDE - 标签位于组件侧边。

- TOP - 标签位于组件上方。

TOP

labelWidth

设置侧置标签的宽度（CSS 长度）。例如 1em。

—

maxColumns

设置布局可以创建的最大列数。即使有足够空间，实际列数也不会超过此限制。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

10

minColumns

设置布局将创建的最小列数，无论容器宽度如何。此属性仅在启用 autoResponsive 时有效。参阅 自动响应模式。

1

rowSpacing

定义行之间的间距（ CSS 长度）。

—

事件和处理器

下面是 formLayout 的特殊事件和处理器：

名称 描述

clickListener

当用户点击布局时触发。

singleClickListener

用户点击后，当确认不是双击时触发。

doubleClickListener

当用户双击布局时触发。

下面是 formLayout 支持的其他通用事件：

AttachEvent - DetachEvent

XML 内部元素

一个 formLayout 可以直接包含字段组件或由 formItem 和 formRow 元素包裹的字段组件。responsiveSteps 元素及其内部的 responsiveStep 定义 响应式档位。

参考