3.5.2.1.19. 表单

最低版本7.0

在线示例

API 文档

Form 组件被用于多个实体属性的联合显示和编辑。它是一个类似于GridLayout的简单容器，可以有一定数量的嵌套列，嵌套字段的类型在 XML 中以声明方式定义，字段的标题位于字段的左侧。与 GridLayout 的主要区别在于 Form 能够将所有嵌套字段绑定到一个数据容器中。

从平台版本 7.0 开始，生成的编辑界面默认使用 Form 代替FieldGroup。

gui Form 1

该组件对应的 XML 名称：form

下面是在界面 XML 描述中定义一组字段的示例：

  1. <data>
  2.     <instance id="orderDc" class="com.company.sales.entity.Order" view="order-edit">
  3.         <loader/>
  4.     </instance>
  5. </data>
  6. <layout>
  7.     <form id="form" dataContainer="orderDc">
  8.         <dateField property="date"/>
  9.         <textField property="amount" description="Total amount"/>
  10.         <pickerField property="customer"/>
  12.         <field id="statusField" property="status"/>
  13.     </form>
  14. </layout>

在上面的例子中，form 组件显示了加载到 orderDc 数据容器中的实体属性。嵌套的 form 元素使用 property 这个 XML 属性定义了绑定到实体属性的可视化组件。会根据实体属性的本地化名称自动创建标题。嵌套的组件可以有任意的普通或者特定属性，比如例子中的 description。

除了具体的可视化组件外，表单还能包含用嵌套的 field 元素定义的通用控件。框架会根据相应的实体属性和组件生成策略选择合适的可视化组件。field 元素可以有多个普通属性，比如 description、contextHelpText 等。

如果要在界面控制器注入嵌套的组件，可以在 XML 中指定其 id 属性。组件会使用其具体的类型进行注入，比如 TextField。如果在界面中注入了一个通用控件，则其会是 Field 类型，该类是表单能展示的所有可视化组件的父类。

form 组件支持 colspan 和 rowspan 属性。这些属性用来设置对应的内嵌组件占据的列数和行数。下面的例子演示 Field1 如何占据两列：

  1. <form>
  2.     <column width="250px">
  3.         <textField caption="Field 1" colspan="2" width="100%"/>
  4.         <textField caption="Field 2"/>
  5.     </column>
  6.     <column width="250px">
  7.         <textField caption="Field 3"/>
  8.     </column>
  9. </form>

组件会按照下面的方式排布：

gui Form 2

类似的，Field 1 也可以扩展至两行：

  1. <form>
  2.     <column width="250px">
  3.         <textField caption="Field 1" rowspan="2" height="100%"/>
  4.     </column>
  5.     <column width="250px">
  6.         <textField caption="Field 2"/>
  7.         <textField caption="Field 3"/>
  8.     </column>
  9. </form>

组件会按照下面的方式排布：

gui Form 3

form 的属性：

  • childrenCaptionWidth – 为所有嵌套列及其子元素指定固定标题宽度。设置 -1 使用自动大小。
  • childrenCaptionAlignment – 定义内嵌所有子组件标题的对齐方式。有两个可选项：LEFT 和 RIGHT。默认值为 LEFT。只有当captionPosition设置为 LEFT 是才能有效。
  • captionPosition - 定义字段的标题位置：TOP 或 LEFT。

form 的元素：

  • column – 可选元素，允许将字段放置在多列。为此，嵌套字段不应该直接放在 form 元素中，而应放在 column 中。例如：

    1. <form id="form" dataContainer="orderDc">
    2.     <column width="250px">
    3.         <dateField property="date"/>
    4.         <textField property="amount"/>
    5.     </column>
    6.     <column width="400px">
    7.         <pickerField property="customer"/>
    8.         <textArea property="info"/>
    9.     </column>
    10. </form>

    在这种情况下，字段将排列成两列; 第一列所有字段的宽度为 250px，第二列所有字段的宽度为 400px。

    column 的属性：

    • id – 一个可选的列标识符，允许在界面扩展时引用它。
  1. -   `width` – 指定列的字段宽度。默认情况下，字段的宽度为 `200px`。在此属性中，可以以像素为单位指定宽度，也可以以列的水平宽度的百分比指定宽度。
  4. -   `childrenCaptionWidth` – 为嵌套字段指定固定的标题宽度。设置 `-1` 使用自动大小。
  7. -   `childrenCaptionAlignment` – 定义内嵌字段标题的对齐方式。有两个可选项：`LEFT` 和 `RIGHT`。默认值为 `LEFT`。只有当[captionPosition](#gui_Form_captionPosition)设置为 `LEFT` 是才能有效。

Form 接口的方法：

  • add() - 允许在向 Form 添加字段。它接受一个 Component 实例作为参数，也可以通过添加 column 和 row 索引来定义新字段的位置。另外，还有一个重载方法可以使用 rowspan 和 colspan 作为参数。

    框架不会为使用编程方式添加的组件指定数据容器，所以需要使用 setValueSource() 方法进行数据绑定。

    示例，声明一个带有 name 字段的表单：

    1. <data>
    2.     <instance id="customerDc" class="com.company.demo.entity.Customer">
    3.         <loader/>
    4.     </instance>
    5. </data>
    6. <layout>
    7.     <form id="form" dataContainer="customerDc">
    8.         <column>
    9.             <textField id="nameField" property="name"/>
    10.         </column>
    11.     </form>
    12. </layout>

    如下例所示，可以在界面控制器中使用编程的方式添加 email 字段：

    1. @Inject
    2. private UiComponents uiComponents;
    3. @Inject
    4. private InstanceContainer<Customer> customerDc;
    5. @Inject
    6. private Form form;
    8. @Subscribe
    9. private void onInit(InitEvent event) {
    10.     TextField<String> emailField = uiComponents.create(TextField.TYPE_STRING);
    11.     emailField.setCaption("Email");
    12.     emailField.setWidthFull();
    13.     emailField.setValueSource(new ContainerValueSource<>(customerDc, "email"));
    14.     form.add(emailField);
    15. }

  • setChildrenCaptionAlignment(CaptionAlignment alignment) – 设置所有列中子组件的标题对齐方式。

  • setChildrenCaptionAlignment(int column, CaptionAlignment alignment) – 设置给定 index 列的子组件标题对齐方式。

form 的属性

align - box.expandRatio - caption - captionAsHtml - captionPosition - childrenCaptionAlignment - childrenCaptionWidth - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - height - icon - id - responsive - rowspan - stylename - visible - width

column 的属性

childrenCaptionAlignment - childrenCaptionWidth - id - width

API

add - setChildrenCaptionAlignment