标准操作 - LookupAction - 《CUBA 框架开发者手册 Version 7.2》

3.5.5.2.8. LookupAction

3.5.5.2.8. LookupAction

LookupAction 是选取器控件操作设计用来从查找界面选取实体实例并设置给选取器。

该操作通过 com.haulmont.cuba.gui.actions.picker.LookupAction 类实现，在 XML 中需要使用操作属性 type="picker_lookup" 定义。可以用 action 元素的 XML 属性定义通用的操作参数，参阅声明式操作了解细节。下面我们介绍 LookupAction 类特有的参数。

下列参数可以通过 XML 或 Java 的方式设置：

openMode - 查找界面的打开模式，要求是 OpenMode 枚举类型的一个值：NEW_TAB、DIALOG 等。默认情况下，LookupAction 用 THIS_TAB 模式打开查找界面。
screenId - 查找界面的字符串 id。LookupAction 默认会使用带有 @PrimaryLookupScreen 注解的界面，或 <entity_name>.lookup、<entity_name>.browse 格式的界面标识符，比如， demo_Customer.browse。
screenClass - 查找界面控制器的 Java 类。比 screenId 有更高的优先级。

示例，需要以对话框方式打开一个特定的查找界面，可以在 XML 中这样配置操作：

<action id="lookup" type="picker_lookup">
    <properties>
        <property name="openMode" value="DIALOG"/>
        <property name="screenClass" value="com.company.sales.web.customer.CustomerBrowse"/>
    </properties>
</action>

或者，可以在界面控制器注入该操作，然后用 setter 配置：

@Named("customerField.lookup")
private LookupAction customerFieldLookup;
@Subscribe
public void onInit(InitEvent event) {
    customerFieldLookup.setOpenMode(OpenMode.DIALOG);
    customerFieldLookup.setScreenClass(CustomerBrowse.class);
}

现在我们看看那些只能用 Java 代码配置的参数。如果要为这些参数生成带正确注解的方法桩代码，可以用 Studio 中 Component Inspector 工具窗口的 Handlers 标签页功能。

screenOptionsSupplier - 返回 ScreenOptions 对象的处理器，返回值可以传递给打开的查找界面。示例：

@Install(to = "customerField.lookup", subject = "screenOptionsSupplier")
private ScreenOptions customerFieldLookupScreenOptionsSupplier() {
    return new MapScreenOptions(ParamsMap.of("someParameter", 10));
}

返回的 ScreenOptions 对象可以通过打开界面的 InitEvent 访问。

screenConfigurer - 接收查找界面作为参数并能在打开之间初始化界面的处理器。示例：
```
@Install(to = "customerField.lookup", subject = "screenConfigurer")
private void customerFieldLookupScreenConfigurer(Screen screen) {
    ((CustomerBrowse) screen).setSomeParameter(10);
}
```
注意，界面 configurer 会在界面已经初始化但是还未显示时生效，即在界面的 InitEvent 和 AfterInitEvent 事件之后，但是在 BeforeShowEvent 之前。

selectValidator - 当用户在查找界面点击 Select 时调用的一个处理器。接收包含选中条目集合的对象作为参数。集合的第一个条目会设置给该选取器。可以用这个处理器检查选中的条目是否满足某些条件。处理器必须返回 true 才能继续关闭查找界面。示例：

@Install(to = "customerField.lookup", subject = "selectValidator")
private boolean customerFieldLookupSelectValidator(LookupScreen.ValidationContext<Customer> validationContext) {
    boolean valid = validationContext.getSelectedItems().size() == 1;
    if (!valid) {
        notifications.create().withCaption("Select a single customer").show();
    }
    return valid;
}

transformation - 在查找界面选择实体并验证之后调用的处理器。接收选中的实体集合作为参数。集合的第一个条目会设置给该选取器。可以用这个处理器对选中的实体做一些处理，然后再传递给选取器。示例：
```
@Install(to = "customerField.lookup", subject = "transformation")
private Collection<Customer> customerFieldLookupTransformation(Collection<Customer> collection) {
    return reloadCustomers(collection);
}
```

afterCloseHandler - 在查找界面关闭后调用的处理器。AfterCloseEvent 事件会传递给该处理器。示例：

@Install(to = "customerField.lookup", subject = "afterCloseHandler")
private void customerFieldLookupAfterCloseHandler(AfterCloseEvent event) {
    if (event.closedWith(StandardOutcome.SELECT)) {
        System.out.println("Selected");
    }
}

如果需要在该操作执行前做一些检查或者与用户做一些交互，可以订阅操作的 ActionPerformedEvent 事件并按需调用操作的 execute() 方法。操作会使用你为它定义的所有参数进行调用。下面的例子中，我们在执行操作前展示了一个确认对话框：

@Named("customerField.lookup")
private LookupAction customerFieldLookup;
@Subscribe("customerField.lookup")
public void onCustomerFieldLookup(Action.ActionPerformedEvent event) {
    dialogs.createOptionDialog()
            .withCaption("Please confirm")
            .withMessage("Do you really want to select a customer?")
            .withActions(
                    new DialogAction(DialogAction.Type.YES)
                            .withHandler(e -> customerFieldLookup.execute()), // execute action
                    new DialogAction(DialogAction.Type.NO)
            )
            .show();
}

另外，还可以先订阅 ActionPerformedEvent，但是不调用操作的 execute() 方法，而是使用 ScreenBuilders API 直接打开查找界面。此时，会忽略所有的操作参数和行为，只能用其通用参数，比如 caption, icon 等。示例：

@Inject
private ScreenBuilders screenBuilders;
@Inject
private LookupPickerField<Customer> customerField;
@Subscribe("customerField.lookup")
public void onCustomerFieldLookup(Action.ActionPerformedEvent event) {
    screenBuilders.lookup(customerField)
            .withOpenMode(OpenMode.DIALOG)
            .withScreenClass(CustomerBrowse.class)
            .withSelectValidator(customerValidationContext -> {
                boolean valid = customerValidationContext.getSelectedItems().size() == 1;
                if (!valid) {
                    notifications.create().withCaption("Select a single customer").show();
                }
                return valid;
            })
            .build()
            .show();
}