3.6.4. 集合的标准行为(历史版本)

对于 ListComponent 的继承者们(TableGroupTableTreeTableTree),标准的行为是通过 ListActionType 枚举类型来定义的;这些操作的实现类在 com.haulmont.cuba.gui.components.actions 包。

在表格中使用标准行为的示例:

<table id="usersTable" width="100%">
  <actions>
      <action id="create"/>
      <action id="edit"/>
      <action id="remove"/>
      <action id="refresh"/>
  </actions>
  <buttonsPanel>
      <button action="usersTable.create"/>
      <button action="usersTable.edit"/>
      <button action="usersTable.remove"/>
      <button action="usersTable.refresh"/>
  </buttonsPanel>
  <rowsCount/>
  <columns>
      <column id="login"/>
      ...
  </columns>
  <rows datasource="usersDs"/>
</table>

下面详细介绍这些行为:

CreateAction - 创建

CreateAction – 使用 create 标识符的 action。用来创建新的实例并且打开编辑界面。如果在编辑界面成功的提交了一个新的实体实例到数据库,CreateAction 会将这个新的实例添加到表格的数据源,并且在界面上使这个实体成为选中状态。

CreateAction 类中定义了下面这些特殊的方法:

  • setOpenType() 可以设置新实体编辑界面的打开模式。默认 THIS_TAB - 当前标签页

    因为通过其它模式打开编辑界面的需求是很常见的(比如,DIALOG - 对话框 模式),可以在使用声明式方式创建 create 行为的时候,在 action 元素的 openType 属性指定需要的打开模式。通过这种方式可以避免在界面控制器获取 action 引用通过编程的方式设置。示例:

    <table id="usersTable">
      <actions>
          <action id="create" openType="DIALOG"/>
  • setWindowId() 可以设置实体编辑界面的标识符。默认情况下,使用 {entity_name}.edit,比如 sales$Customer.edit

  • setWindowParams() 可以设置传递给编辑界面的 init() 方法的参数。这些参数可以通过 @WindowParam 注解注入到界面控制器中,或者也可以在数据源查询中通过 param$ 前缀直接使用。

  • setWindowParamsSupplier()setWindowParams() 的不同之处在于,这个方法可以在 action 即将要被调用的时候修改编辑窗口的参数值。可以提供新的参数,新的参数会跟 setWindowParams() 方法中提供的参数合并,并且覆盖之前的参数。示例:

    createAction.setWindowParamsSupplier(() -> {
       Customer customer = metadata.create(Customer.class);
       customer.setCategory(/* some value dependent on the current state of the screen */);
       return ParamsMap.of("customer", customer);
    });
  • setInitialValues() 可以设置将要编辑的实体的属性初始化值。这个方法接收一个 Map 对象,键值是属性名称,值为属性值。示例:

    Map<String, Object> values = new HashMap<>();
    values.put("type", CarType.PASSENGER);
    carCreateAction.setInitialValues(values);

    使用创建操作做初始化 章节也提供一个使用 setInitialValues() 的例子。

  • setInitialValuesSupplier()setInitialValues() 的不同之处在于,这个方法可以在 action 即将要被调用的时候修改实体初始化的值。可以提供新的参数,新的参数会跟 setInitialValues() 方法中提供的参数合并,并且覆盖之前的参数。示例:

    carCreateAction.setInitialValuesSupplier(() ->
        ParamsMap.of("type", /* value depends on the current state of the screen */));
  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

    customersTableCreate.setBeforeActionPerformedHandler(() -> {
        showNotification("The new customer instance will be created");
        return isValid();
    });
  • afterCommit() 在新实体成功提交到数据库并且编辑界面关闭之后会调用此方法。这个方法本身没有实现,可以通过继承重写此方法来处理这个事件。

  • setAfterCommitHandler() 提供一个处理函数,在新实体成功提交到数据库并且编辑界面关闭之后会调用此函数。可以通过提供此函数避免创建 action 的子类并重写 afterCommit() 方法。示例:

    @Named("customersTable.create")
    private CreateAction customersTableCreate;
    
    @Override
    public void init(Map<String, Object> params) {
        customersTableCreate.setAfterCommitHandler(new CreateAction.AfterCommitHandler() {
            @Override
            public void handle(Entity entity) {
                showNotification("Committed", NotificationType.HUMANIZED);
            }
        });
    }
  • afterWindowClosed() 不管实体是否提交,只要关闭了编辑界面就会最后调用此方法。这个方法本身没有实现,可以通过继承重写此方法来处理这个事件。

  • setAfterWindowClosedHandler() 提供一个处理函数,不管实体是否提交,只要关闭了编辑界面就会最后调用此函数。可以通过提供此函数避免创建 action 的子类并重写 afterWindowClosed() 方法。

EditAction - 编辑

EditAction 是使用 edit 标识符的 action,用来为选中的实体实例打开编辑界面。如果编辑界面成功的将实例保存到数据库,EditAction 会更新表格数据源中的实例。

EditAction 类中定义了下面这些特殊的方法:

  • setOpenType() 可以设置实体编辑界面的打开模式。默认 THIS_TAB - 当前标签页

    因为通过其它模式打开编辑界面的需求是很常见的(比如,DIALOG - 对话框 模式),可以在使用声明式方式创建 edit 行为的时候,在 action 元素的 openType 属性指定需要的打开模式。通过这种方式可以避免在界面控制器获取 action 引用通过编程的方式设置。示例:

    <table id="usersTable">
      <actions>
          <action id="edit" openType="DIALOG"/>
  • setWindowId() 可以设置实体编辑界面的标识符。默认情况下,使用 {entity_name}.edit,比如 sales$Customer.edit

  • setWindowParams() 可以设置传递给编辑界面的 init() 方法的参数。这些参数可以通过 @WindowParam 注解注入到界面控制器中,或者也可以在数据源查询中通过 param$ 前缀直接使用。

  • setWindowParamsSupplier()setWindowParams() 的不同之处在于,这个方法可以在 action 即将要被调用的时候修改编辑窗口的参数值。可以提供新的参数,新的参数会跟 setWindowParams() 方法中提供的参数合并,并且覆盖之前的参数。示例:

    customersTableEdit.setWindowParamsSupplier(() ->
        ParamsMap.of("category", /* some value dependent on the current state of the screen */));
  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

    customersTableEdit.setBeforeActionPerformedHandler(() -> {
        showNotification("The customer instance will be edited");
        return isValid();
    });
  • afterCommit() 在新实体成功提交到数据库并且编辑界面关闭之后会调用此方法。这个方法本身没有实现,可以通过继承重写此方法来处理这个事件。

  • setAfterCommitHandler() 提供一个处理函数,在新实体成功提交到数据库并且编辑界面关闭之后会调用此函数。可以通过提供此函数避免创建 action 的子类并重写 afterCommit() 方法。示例:

    @Named("customersTable.edit")
    private EditAction customersTableEdit;
    
    @Override
    public void init(Map<String, Object> params) {
        customersTableEdit.setAfterCommitHandler(new EditAction.AfterCommitHandler() {
            @Override
            public void handle(Entity entity) {
                showNotification("Committed", NotificationType.HUMANIZED);
            }
        });
    }
  • afterWindowClosed() 不管实体是否提交,只要关闭了编辑界面就会最后调用此方法。这个方法本身没有实现,可以通过继承重写此方法来处理这个事件。

  • setAfterWindowClosedHandler() 提供一个处理函数,不管实体是否提交,只要关闭了编辑界面就会最后调用此函数。可以通过提供此函数避免创建 action 的子类并重写 afterWindowClosed() 方法。

  • getBulkEditorIntegration() 为表格批量编辑提供了可能性。表格需要设置 multiselect 属性启用。当表格选中多行的时候,如果触发 EditAction 行为,则会打开批量编辑器组件进行批量编辑。

    返回的 BulkEditorIntegration 实例可以通过下面的方法进行进一步处理:

    • setOpenType(),

    • setExcludePropertiesRegex(),

    • setFieldValidators(),

    • setModelValidators(),

    • setAfterEditCloseHandler().

    @Named("clientsTable.edit")
    private EditAction clientsTableEdit;
    
    @Override
    public void init(Map<String, Object> params) {
        super.init(params);
    
        clientsTableEdit.getBulkEditorIntegration()
            .setEnabled(true)
            .setOpenType(WindowManager.OpenType.DIALOG);
    }

RemoveAction - 删除

RemoveAction - 是使用 remove 标识符的 action,用来删除选中的实体实例。

RemoveAction 类中定义了下面这些特殊的方法:

  • setAutocommit() 可以控制从数据库删除的动作是否提交。默认情况下,在动作触发之后会调用 commit() 提交从数据库删除实体。可以通过 setAutocommit() 方法或者设置构造器中对应的参数将 autocommit 属性设置为 false 来禁用自动提交。这样的话,需要显式调用数据源的 commit() 方法来提交改动。

    autocommit 的值不会影响 Datasource.CommitMode.PARENT 模式下的数据源,比如,提供组合实体编辑的数据源。

  • setConfirmationMessage() 设置删除数据确认窗口的信息文本。

  • setConfirmationTitle() 设置删除确认窗口的标题。

  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

    customersTableRemove.setBeforeActionPerformedHandler(() -> {
        showNotification("The customer instance will be removed");
        return isValid();
    });
  • afterRemove() 当实体被成功删除之后,调用此方法。这个方法本身没有实现,可以通过继承重写此方法来处理这个事件。

  • setAfterRemoveHandler() 提供一个处理函数,在实体成功从数据库删除之后会调用此函数。可以通过提供此函数避免创建 action 的子类并重写 afterRemove() 方法。示例:

    @Named("customersTable.remove")
    private RemoveAction customersTableRemove;
    
    @Override
    public void init(Map<String, Object> params) {
        customersTableRemove.setAfterRemoveHandler(new RemoveAction.AfterRemoveHandler() {
            @Override
            public void handle(Set removedItems) {
                showNotification("Removed", NotificationType.HUMANIZED);
            }
        });
    }

RefreshAction - 刷新

RefreshAction - 是使用 refresh 标识符的 action。用来更新(重新加载)实体集合。当触发时,这个动作会调用相应组件绑定的数据源中的 refresh() 方法。

RefreshAction 类中定义了下面这些特殊的方法:

  • setRefreshParams() 可以设置传递给 CollectionDatasource.refresh() 方法的参数,这些参数之后会用在数据源查询中。默认情况不会带任何参数。

  • setRefreshParamsSupplier()setRefreshParams() 的不同之处在于,这个方法可以在 action 即将要被调用的时候修改编辑窗口的参数值。可以提供新的参数,新的参数会跟 setRefreshParams() 方法中提供的参数合并,并且覆盖之前的参数。示例:

    customersTableRefresh.setRefreshParamsSupplier(() ->
        ParamsMap.of("number", /* some value dependent on the current state of the screen */));

AddAction - 添加

AddAction – 是使用 add 标识符的 action,用来选择一个已存在的实体并添加到集合中。当触发时,会打开实体的查找界面

AddAction 类中定义了下面这些特殊的方法:

  • setOpenType() 可以设置实体选择界面的打开模式。默认 THIS_TAB - 当前标签页

    因为通过其它模式打开查找界面的需求是很常见的(比如,DIALOG - 对话框 模式),可以在使用声明式方式创建 add 行为的时候,在 action 元素的 openType 属性指定需要的打开模式。通过这种方式可以避免在界面控制器获取 action 引用通过编程的方式设置。示例:

    <table id="usersTable">
        <actions>
            <action id="add" openType="DIALOG"/>
  • setWindowId() 可以设置实体查找界面的标识符。默认情况下,使用 {entity_name}.lookup,比如 sales$Customer.lookup。如果不存在这种类型的界面,则会尝试打开 {entity_name}.browse 界面,比如 sales$Customer.browse

  • setWindowParams() 可以设置传递给查找界面的 init() 方法的参数。这些参数可以通过 @WindowParam 注解注入到界面控制器中,或者也可以在数据源查询中通过 param$ 前缀直接使用。

  • setWindowParamsSupplier()setWindowParams() 的不同之处在于,这个方法可以在 action 即将要被调用的时候修改编辑窗口的参数值。可以提供新的参数,新的参数会跟 setWindowParams() 方法中提供的参数合并,并且覆盖之前的参数。示例:

    tableAdd.setWindowParamsSupplier(() ->
        ParamsMap.of("customer", getItem()));
  • setHandler() 可以设置一个实现了 Window.Lookup.Handler 接口的对象,这个对象会传递给查找界面。默认情况下,会使用 AddAction.DefaultHandler 对象。

  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

    customersTableAdd.setBeforeActionPerformedHandler(() -> {
        notifications.create()
                .withCaption("The new customer will be added")
                .show();
        return isValid();
    });

ExcludeAction - 排除

ExcludeAction - 是使用 exclude 标识符的 action。允许用户从一个实体集合中排除实体实例,而并不会从数据库删除。这个 action 的类是继承于 RemoveAction,但是在触发这个动作的时候调用的是 CollectionDatasource 里的 excludeItem() 而不是 removeItem()。此外,对于嵌套数据源中的实体,ExcludeAction 动作会将子实体跟父实体的连接断开。因此这个 action 可以用来编辑一对多的关联关系。

除了 RemoveAction 里面的方法外,ExcludeAction 类中定义了下面这些特殊的方法:

  • setConfirm() – 定义是否要显示确认删除窗口。也可以通过 action 的构造器设置这个参数。默认值是 false

  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

customersTableExclude.setBeforeActionPerformedHandler(() -> {
    showNotification("The selected customer will be excluded");
    return isValid();
});

ExcelAction - 导出 Excel

ExcelAction - 是使用 excel 标识符的 action。用来将表格数据导出成 XLS 格式的文件,并且下载。只能在 TableGroupTableTreeTable 组件添加此行为。

当通过编程的方式创建这个行为的时候,可以用实现了 ExportDisplay 接口的类为文件下载设置 display 参数。默认情况下使用标准的实现类。

ExcelAction 类中定义了下面这些特殊的方法:

  • setFileName() - 设置 Excel 文件名称,不包含文件名后缀。

  • getFileName() - 返回 Excel 文件名称,不包含文件名后缀。

  • setBeforeActionPerformedHandler() 可以提供一个处理函数,这个函数在 action 执行之前调用。这个函数返回值是 true 的话,action 会继续执行;返回 false 终止执行。示例:

    customersTableExcel.setBeforeActionPerformedHandler(() -> {
        showNotification("The selected data will ve downloaded as an XLS file");
        return isValid();
    });