4. 使用枚举

在前面的章节中,我们实现了对入职步骤和部门的管理。通过模板创建的应用程序也带有默认的用户管理功能。

本节中,我们将为 User 实体添加 onboardingStatus 属性并在 UI 展示。该属性可能是这三个值:Not startedIn progressCompleted

创建枚举

枚举类型是由一组在设计时定义的常量组成,运行时用户无法修改。

我们先创建一个用在 onboardingStatus 属性的枚举类型。

如果你的应用程序正在运行,先通过主工具栏的 Stopsuspend)按钮停止运行。

Jmix 工具窗口中,点击 Newadd)→ Enumeration

enum 1

New Jmix Enumeration 窗口中,Class 字段输入 OnboardingStatus,并在 Id type 单选按钮组中选择 Integer

enum 2

点击 OK

Studio 会展示枚举设计器:

enum 3

通过点击 Values 表格顶部工具栏中的 Add Valueadd)按钮添加需要的枚举值:NOT_STARTEDIN_PROGRESSCOMPLETED

enum 4

这里的 Value 是 Java 枚举的具体值,对应于枚举实体的 Id 属性,并保存在数据库中。例如,对于表中的第二项,数据库不会存储 IN_PROGRESS 字符串或者它的序号(1),而是保存数字 20

我们建议一般情况下都使用 String 类型的枚举,除非需要对枚举常量进行排序。这里,OnboardingStatus 就是一个很好的需要排序的例子:我们需要以流程的步骤顺序展示枚举选项。

切换至 Text 标签页可以查看枚举的源码:

enum 5

添加枚举属性

我们为 User 实体添加 onboardingStatus 属性:

Jmix 工具窗口双击 User 实体并选择其最后一个属性(我们要在最后添加新属性):

attribute 1

Attributes 工具栏中,点击 Addadd)。弹出的 New Attribute 对话框中,Name 字段填写 onboardingStatusAttribute type 下拉框选择 ENUM,然后在 Type 下拉框中选择 OnboardingStatus

attribute 2

点击 OK

然后选中 onboardingStatus 属性,在 Attributes 工具栏中点击 Add to Screensadd attribute to screens)按钮:

attribute 3

出现的对话框中会显示所有用于展示 User 实体的界面。我们选择 User.editUser.browse 界面:

attribute 4

点击 OK

Studio 会在 User.browse 界面的表格组件和 User.edit 界面的表单组件中添加 onboardingStatus 属性。

运行应用程序

点击主工具栏中的 Debugstart debugger)按钮启动应用程序。

在运行应用程序之前,Studio 会生成 Liquibase 更改日志:

run app 1

可以看到,更改日志包含了一条增加 USER_ONBOARDING_STATUS 列的语句。列类型为 INT,与枚举的 id 类型一致。

点击 OK

Studio 会先执行更改日志,再构建和运行应用程序。

在浏览器打开 http://localhost:8080 并使用 admin / admin 凭证登录。

点击主菜单的 ApplicationUsers,打开 User.browse 界面,可以看到 Onboarding status 列:

run app 2

可以隐藏不需要的列,为新属性腾出空间。将光标悬停在表头的右上角,则会显示表格控制按钮(table column control button),点击该按钮根据需要取消不想展示的列:

run app 3

点击 Create 按钮创建新用户。会在表单的最底部展示新的属性选择控件。

run app 4

设置属性的初始值

对于新创建的用户,onboardingStatus 属性应该自动设置为 Not started。本小节中,我们将学习如何配置 User.edit 界面初始化该属性。

打开 UserEdit.java 类,并找到 onInitEntity() 方法:

init attr 1

该方法是一个由 Jmix 框架调用的事件处理器,当打开编辑界面创建新实体时会调用该方法。传入的 event 对象包含新实体。

在方法最后添加下列内容:

@Subscribe
public void onInitEntity(InitEntityEvent<User> event) {
    usernameField.setEditable(true);
    passwordField.setVisible(true);
    confirmPasswordField.setVisible(true);
    isNewEntity = true;

    User user = event.getEntity();
    user.setOnboardingStatus(OnboardingStatus.NOT_STARTED);
}

然后切换至运行中的程序,关闭用户编辑界面并重新点击 Create,可以看到 Onboarding status 已经支持自动初始化了:

init attr 2

如需从头创建处理器方法,在代码编辑器的顶部操作面板中点击 Generate Handler,然后在树的 Controller handlers 部分选择 InitEntityEvent

init attr 3

小结

本节中,我们为 User 实体添加了 Onboarding status 属性。该属性是枚举类型,支持三个选项:Not startedIn progressCompleted

学习内容:

  • 枚举 表示一组在设计时定义的常量。

  • Jmix 中,一个枚举常量具有值和 id,数据库中保存的是枚举的 id。

  • 新添加的实体属性可以通过实体设计器中 Attributes 工具栏的 Add to Screensadd attribute to screens)按钮很容易地添加到已有的界面中。

  • InitEntityEvent 处理方法可以用来在编辑界面初始化新实体。方法的桩代码可以通过代码编辑器顶部的 Generate Handler 自动生成。