界面控制器注解 - CUBA 框架开发者手册

3.5.1.1.1. 界面控制器注解

控制器上的类级别的注解用于向框架提供界面相关的信息。一部分注解适用于任何类型的界面，也有一部分仅用于实体编辑或查找界面。

以下示例演示了常见的界面注解的用法：

package com.company.demo.web.screens;

import com.haulmont.cuba.gui.screen.*;

@UiController("demo_FooScreen")
@UiDescriptor("foo-screen.xml")
@LoadDataBeforeShow
@MultipleOpen
@DialogMode(forceDialog = true)
public class FooScreen extends Screen {
}

@UiController 注解表示该类是一个界面控制器。注解的值是界面的 ID，可用于从主菜单或以编程方式打开界面时引用界面。

@UiDescriptor 注解将界面控制器连接到界面 XML 描述。注解的值指定描述文件的路径。如果该值仅包含文件名，则假定该文件与控制器类位于同一个包中。

@LoadDataBeforeShow 注解表示在显示界面之前应自动触发所有数据加载器。准确的说，数据会在调用所有的 BeforeShowEvent 监听器之后，但是在 AfterShowEvent 监听器之前加载。如果需要在界面显示之前的加载数据时刻执行某些操作，删除此注解或将其值设置为 false，这样可以在 BeforeShowEvent 事件监听器中使用 getScreenData().loadAll() 方法或个别加载器的 load() 方法来手动加载数据。可以考虑使用DataLoadCoordinator facet 来做细致的数据加载控制。

@MultipleOpen 注解表示可以从主菜单多次打开界面。默认情况下，当用户点击主菜单项时，框架会检查是否已在主窗口标签页上打开相同类和 ID 的界面。如果找到此类界面，则会关闭该界面，并在新标签页中打开新的界面实例。当存在 @MultipleOpen 注解时，不执行任何检查，只在新标签页中打开一个新的界面实例。

可以通过覆盖界面控制器中的 isSameScreen() 方法，提供自定义的界面实例同一性检查方法。

@DialogMode 注解允许指定界面以对话框窗口方式打开时的尺寸和行为。它对应于界面描述的 <dialogMode> 元素，可以替代使用。对于除 forceDialog 之外的所有参数，XML 中的设置优先于注解。forceDialog 参数会合并生效，即：只要在注解或 XML 其中之一将其设置为 true，界面就总是以对话框的方式打开。

针对查找界面的注解示例：

package com.company.demo.web.screens;

import com.haulmont.cuba.gui.screen.*;
import com.company.demo.entity.Customer;

// common annotations
@UiController("demo_Customer.browse")
@UiDescriptor("customer-browse.xml")
@LoadDataBeforeShow
// lookup-specific annotations
@LookupComponent("customersTable")
@PrimaryLookupScreen(Customer.class)
public class CustomerBrowse extends StandardLookup<Customer> {
}

@LookupComponent 注解指定一个 UI 组件的 ID，这个组件用于获取查找界面的返回值。

可以通过覆盖界面控制器的 getLookupComponent() 方法以编程方式指定查找界面，而不是使用注解。

@PrimaryLookupScreen 注解表示此界面是指定实体类型的默认查找界面。注解比 {entity_name}.lookup / {entity_name}.browse 名称约定具有更高的优先级。

编辑器界面特有的注解示例：

package com.company.demo.web.data.sort;

import com.haulmont.cuba.gui.screen.*;
import com.company.demo.entity.Customer;

// common annotations
@UiController("demo_Customer.edit")
@UiDescriptor("customer-edit.xml")
@LoadDataBeforeShow
// editor-specific annotations
@EditedEntityContainer("customerDc")
@PrimaryEditorScreen(Customer.class)
public class CustomerEdit extends StandardEditor<Customer> {
}

@EditedEntityContainer 注解指定一个数据容器，这个数据容器包含被编辑的实体。

不使用注解的话，可以通过覆盖界面控制器的 getEditedEntityContainer() 方法以编程方式指定容器。

@PrimaryEditorScreen 注解表示此界面是指定实体类型的默认编辑界面。注解比 {entity_name}.edit 名称约定具有更高的优先级。