4. 使用枚举

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

本节中，我们将为 User 实体添加 onboardingStatus 属性并在 UI 展示。该属性可能是这三个值：Not started、In progress、Completed。

创建枚举

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

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

如果你的应用程序正在运行，先通过主工具栏的 Stop（suspend）按钮停止运行。

在 Jmix 工具窗口中，点击 New（add）→ Enumeration：

enum 1

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

enum 2

点击 OK。

Studio 会展示枚举设计器：

enum 3

通过点击 Values 表格顶部工具栏中的 Add Value（add）按钮添加需要的枚举值：NOT_STARTED、IN_PROGRESS、COMPLETED。

enum 4

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

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

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

enum 5

添加枚举属性

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

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

attribute 1

在 Attributes 工具栏中，点击 Add（add）。弹出的 New Attribute 对话框中，Name 字段填写 onboardingStatus，Attribute type 下拉框选择 ENUM，然后在 Type 下拉框中选择 OnboardingStatus：

attribute 2

点击 OK。

然后选中 onboardingStatus 属性，在 Attributes 工具栏中点击 Add to Views（add attribute to screens）按钮：

attribute 3

出现的对话框中会显示所有用于展示 User 实体的视图。我们选择 User.detail 和 User.list 视图：

attribute 4

点击 OK。

Studio 会在 User.list 视图的 dataGrid` 组件和 User.detail 视图的 formLayout 组件中添加 onboardingStatus 属性。

运行应用程序

点击主工具栏中的 Debug（start debugger）按钮启动应用程序。

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

run app 1

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

点击 Save and run。

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

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

点击主菜单的 Application → Users，打开 User.list 视图，可以看到 Onboarding status 列。

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

run app 4

设置属性的初始值

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

打开 UserDetailView.java 类，并找到 onInitEntity() 方法：

init attr 1

该方法是一个由 Jmix 框架调用的事件处理器，当打开详情视图创建新实体时会调用该方法。传入的 event 对象包含新实体。

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

@Subscribe
public void onInitEntity(InitEntityEvent<User> event) {
    // ...

    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 started、In progress、Completed。

学习内容：

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

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

  • 新添加的实体属性可以通过实体设计器中 Attributes 工具栏的 Add to Views（add attribute to screens）按钮很容易地添加到已有的视图中。

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