从经典 UI 迁移

由于 Classic UI 和 Flow UI 的不兼容,因此,无法自动从 Jmix 1.5 Classic UI 项目自动升级为 Jmix 2.3。本章节提供如何手动从 Jmix 1.5 Classic UI 升级的说明。

将项目转换为 Flow UI

首先,需要从项目中删除 Classic UI,并将项目结构和构建脚本迁移至 Flow UI。

  1. 在 IDE 打开 Classic UI 项目。

    本向导的后面部分,我们将该项目称为 “待迁移” 项目。

  2. 使用 Full-Stack Application with Incubating FlowUI 模板在不同的文件夹创建一个 Jmix 1.5 最新版本的新项目。创建时,请使用与待迁移项目相同的项目名和包名。

    本向导的后面部分,我们将该项目称为 “新建” 项目。

  3. 将新建项目的下列文件拷贝至待迁移项目的根目录:

    .gitignore
    build.gradle
    package.json
    tsconfig.json
    types.d.ts
    vite.config.ts

    从这里往下,请使用 Project 工具窗口的 Copy 命令复制源项目的文件,然后在目标项目的对应节点使用 Paste 命令。

  4. 在待迁移项目中,删除下列文件夹(可以关闭 Safe delete 避免无效警告):

    1. src/main/java/<base_package>/screen

    2. src/main/resources/<base_package>/screen

    3. src/main/themes

    4. src/main/resources/<base_package>/theme

  5. 将新建项目的下列文件夹复制到待迁移项目:

    1. frontend

    2. src/main/java/<base_package>/view

    3. src/main/resources/<base_package>/view

    4. src/main/resources/META-INF

  6. 在待迁移项目的 application.properties 中:

    1. 删除 jmix.ui.* 相关的配置。

    2. 从新建项目复制 jmix.flowui.*ui.*vaadin.* 配置至待迁移项目。

  7. 从新建项目复制 src/main/resources/<base_package>/menu.xml 文件至待迁移项目,并覆盖已有文件。

  8. 打开待迁移项目的 src/main/resources/<base_package>/messages_en.properties 文件并删除 <base_package>.screen.*<base_package>/menu.application 相关的键值。从新建项目的相同文件中复制 <base_package>.view.*<base_package>/menu.application.title 键值至待迁移项目。

  9. 复制新建项目 <base_package>.security 包中的 FullAccessRoleUiMinimalRole 类至待迁移项目。

  10. 在待迁移项目的其他角色中,删除 io.jmix.securityui.role.annotation.MenuPolicyio.jmix.securityui.role.annotation.ScreenPolicy 注解。

  11. 在应用程序主类中添加下列代码:

    @Push
    @Theme(value = "<project_name>")
    @PWA(name = "<project_name>", shortName = "<project_name>")
    class ... implements AppShellConfigurator

    示例:

    // ...
    import com.vaadin.flow.component.page.AppShellConfigurator;
    import com.vaadin.flow.component.page.Push;
    import com.vaadin.flow.server.PWA;
    import com.vaadin.flow.theme.Theme;
    // ...
    
    @Push
    @Theme(value = "onboarding")
    @PWA(name = "Onboarding", shortName = "Onboarding")
    @SpringBootApplication
    public class OnboardingApplication implements AppShellConfigurator {
    }
  12. 运行 Gradle 工具窗口的 Reload All Gradle Projects 命令重新加载项目。

  13. 使用 Studio 的 Upgrade 升级程序 将项目升级至最新的 Jmix 2.3。

  14. 按照扩展组件文档的说明通过市场或者手动添加 starter 的方式为项目添加所需的扩展组件。

  15. 执行 BuildBuild Project 并修复可能出现的编译错误。

  16. 运行应用程序。

    1. Studio 将展示 Liquibase Root Changelog Check 窗口并建议删除 Jmix 2.3 Flow UI 不可用模块的 include 语句(比如,/io/jmix/uidata/liquibase/changelog.xml)。这里接受建议并继续。

    2. Studio 将创建一些新的 changeset 用于删除 UI_FILTER_CONFIGURATIONUI_SETTINGUI_TABLE_PRESENTATION 表。这里需要保存并应用这些改动,因为 Flow UI 不需要这些表。

    3. 如果你的数据库包含 Jmix 2.3 没有的扩展组件的表,请注意不要删除这些表。可以在 Liquibase 弹窗中选择 Remove from ChangelogRemove and Ignore 忽略特定的 dropTable changeset,或暂时取消当前的流程,然后在应用程序属性中添加 main.datasource.studio.liquibase.exclude-prefixes,再运行应用程序。示例:

      main.datasource.studio.liquibase.exclude-prefixes = FOO_

应用程序启动后,你应该可以登录并打开标准的用户管理视图。

开发新视图

此时,待迁移项目应该是一个基于 Jmix 2.3 Flow UI 能正常运行的应用程序了。但是用户界面仅包含新项目模板自带的一些视图:LoginViewMainViewUserListViewUserDetailView

然后,可以使用 视图创建向导 为数据模型实体创建 CRUD 视图。

最后,你的应用程序包含原有的数据模型和后台业务逻辑,以及一些新 UI 的标准列表页和详情页。之后,你可以使用 Flow UI API 和组件进行进一步开发。