3.6.4. 集合的标准行为(历史版本)
对于 ListComponent
的继承者们(Table,GroupTable,TreeTable 和 Tree),标准的行为是通过 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 格式的文件,并且下载。只能在 Table,GroupTable 和 TreeTable 组件添加此行为。
当通过编程的方式创建这个行为的时候,可以用实现了 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(); });