界面控制器方法

本章节我们介绍一些界面控制器基类的方法，可以直接在代码中调用或者重写。

所有界面都可用的方法

  • show() - 展示界面。该方法通常在创建界面之后调用，参阅 打开界面。

  • close() - 关闭界面，使用 StandardOutcome 枚举值或者 CloseAction 对象作为参数。示例：

    @Subscribe("closeBtn")
public void onCloseBtnClick(Button.ClickEvent event) {
    close(StandardOutcome.CLOSE);
}

    参数值也传递至 BeforeCloseEvent 和 AfterCloseEvent 事件中，因此在事件监听器中也能获取界面关闭的原因。参阅 界面关闭后执行代码以及返回值 了解更多使用这些监听器的方法。

  • getScreenData() - 返回 ScreenData 对象，该对象作为所有在界面 XML 描述中定义的 数据组件 的寄存器，因此可以使用其 loadAll() 方法为界面加载数据：

    @Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    getScreenData().loadAll();
}

StandardEditor 的方法

  • getEditedEntity() - 当界面展示时，返回编辑实体的实例。实例是 @EditedEntityContainer 注解内指定的数据容器中的实例。

    在 InitEvent 和 AfterInitEvent 事件监听器内，该方法会返回 null。在 BeforeShowEvent 事件监听器内，该方法会返回传递给界面用来编辑的实体（之后在界面打开的过程中，实体会重新加载，一个不同的实例会设置给数据容器）。

可以用下面的方法关闭编辑界面：

  • closeWithCommit() - 验证并保存数据，然后用 StandardOutcome.COMMIT 关闭界面。

  • closeWithDiscard() - 忽略任何未保存的数据并用 StandardOutcome.DISCARD 关闭界面。

如果界面的 DataContext 有未保存的改动，则会在界面关闭前弹出对应的消息对话框。可以用 jmix.ui.screen.use-save-confirmation 应用程序属性调整通知类型。如果用 closeWithDiscard() 或 close(StandardOutcome.DISCARD) 方法，则会忽略未保存的改动而且没有通知。

  • commitChanges() - 保存数据，但不关闭界面。 可以从自定义事件监听器调用该方法或者重写默认的 windowCommit 操作监听器，这样能在数据保存后做一些其他的事情，示例：

    @Override
protected void commit(Action.ActionPerformedEvent event) {
    commitChanges().then(() -> {
        commitActionPerformed = true; (1)
        // ... (2)
    });
}
    1 这个标记会在后续界面关闭时返回正确的结果。
    2 可以在保存数据后进行其他操作。

  • validateAdditionalRules() 方法可以重写，在保存数据前添加额外的数据验证。方法应该在传入的 ValidationErrors 对象中保存验证错误的信息。之后，此信息会与标准验证的错误信息一起展示。示例：

    private Pattern pattern = Pattern.compile("\\s");

@Override
protected void validateAdditionalRules(ValidationErrors errors) {
    if (getEditedEntity().getNum() != null) {
        if (pattern.matcher(getEditedEntity().getNum()).find()) {
            errors.add("Number cannot contain whitespaces");
        }
    }
    super.validateAdditionalRules(errors);
}

  • preventUnsavedChanges() 在界面关闭时调用，防止丢失未保存的数据。标准的实现会根据 jmix.ui.screen.use-save-confirmation 属性的设置调用 ScreenValidation bean 的 showUnsavedChangesDialog() 或 showSaveConfirmationDialog() 方法。

MasterDetailScreen 的方法

  • getEditedEntity() - 当界面在编辑模式时，返回正在编辑的实体实例。即表单组件数据容器中的实例。如果界面不在编辑模式，此方法会抛出 IllegalStateException

  • validateAdditionalRules() 方法可以重写，添加额外的数据验证，与上面 StandardEditor 介绍的一样。