formLayout 表单布局

formLayout 是一个响应式布局，内部组件按列排布。列的数量根据布局的宽度变化。

XML 元素	`formLayout`
Java 类	`FormLayout`
XML 属性	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
XML 内部元素	formItem - formRow - responsiveSteps

XML 元素

formLayout

Java 类

FormLayout

XML 属性

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

XML 内部元素

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>

当布局容器的宽度变小时，会自动调整为一列。

数据绑定

在线示例

数据绑定是指将组件与数据容器进行关联。

在 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` 实体的 `InstanceContainer` 容器。
2	将组件与数据容器和属性进行关联。`dataContainer` 属性使用 `userDc` 数据容器
3	内部的 `formLayout` 元素通过 `property` XML 属性定义绑定实体属性的可视化组件。组件的标签会基于实体属性的本地化名称自动创建。

自动响应模式

启用后，formLayout 会自动确定合适的列数。此计算会考虑列宽、间距以及可用的水平空间。

将 autoResponsive 属性设置为 true 来启用此模式。

当自动响应模式启用时，会忽略响应式列数。

表单行

在自动响应模式下，默认所有字段都显示在单列中。

如需将字段组织成多列，请使用以下方法之一：

手动分组字段：将相关字段放入 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 的字段。

启用自动分布：autoRows 属性设置为 true 时，布局会自动将字段放入可用列中，当前列满时换到新行。

rowSpacing 属性控制行之间的垂直间距。此设置适用于所有行之间的间距，无论是通过 formRow 手动创建的行，还是通过 autoRows 自动创建的行。

自动响应标签位置

默认情况下，标签渲染在其对应字段的上方。如需将标签放在字段旁边，请将字段包裹在 formItem 元素中，并在 formLayout 上添加 labelsAside="true" 属性。

使用标签侧置模式时，请将标签添加在 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>

当宽度足够时，上面的布局会自动调整以使用全部的 5 个列：

响应式列数标签位置

此布局可以可以支持在内部组件的旁边放置标签。将内部组件放置于 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>

响应式标签位置

在侧面显示标签的布局比在默认在组件顶部显示的布局需要更多的空间。与列排布类似，可以调整标签位置以适应可用空间。此时，不要将 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>

布局宽度改变时，列的数目和标签位置都会随之改变：

列展拓

用 colspan 属性控制内部组件可以跨越的列数目。

例如，可以配置一个按钮始终占据 2 列的宽度：

<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>

XML 属性

通用属性对所有组件都是一样的配置。下面是 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	当标签放在字段旁边时，定义标签与对应字段之间的间距。此属性仅在启用 autoResponsive 时有效。参阅自动响应标签位置。值必须使用 CSS 长度单位提供，例如 `1em`。
labelsPosition	设置布局内组件的标签位置。 - `ASIDE` - 标签位于组件侧边。 - `TOP` - 标签位于组件上方。	`TOP`
labelWidth	设置侧置标签的宽度。参阅自动响应标签位置和响应式列数标签位置。值必须使用 CSS 长度单位提供，例如 `1em`。
maxColumns	设置布局可以创建的最大列数。即使有足够空间，实际列数也不会超过此限制。此属性仅在启用 autoResponsive 时有效。参阅列管理。	10
minColumns	设置布局将创建的最小列数，无论容器宽度如何。此属性仅在启用 autoResponsive 时有效。参阅列管理。	1
rowSpacing	使用 CSS 长度单位定义行之间的间距。此属性仅在启用 autoResponsive 时有效。参阅列管理。

名称

描述

默认值

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

当标签放在字段旁边时，定义标签与对应字段之间的间距。此属性仅在启用 autoResponsive 时有效。参阅自动响应标签位置。值必须使用 CSS 长度单位提供，例如 1em。

labelsPosition

设置布局内组件的标签位置。

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

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

TOP

labelWidth

设置侧置标签的宽度。参阅自动响应标签位置和响应式列数标签位置。值必须使用 CSS 长度单位提供，例如 1em。

maxColumns

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

minColumns

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

rowSpacing

使用 CSS 长度单位定义行之间的间距。此属性仅在启用 autoResponsive 时有效。参阅列管理。

参考

Vaadin 文档

本页是否有帮助？

感谢您的反馈

出错啦~