3.1 版本说明

视图创建向导 新增了一个列表和主从视图的步骤，可以在其中选择用户如何过滤数据：genericFilter（默认）、为选择的属性生成的一组 propertyFilter 组件、如果项目中包含 Search 扩展组件则使用 fullTextFilter，或者不使用过滤器。

实体设计器 支持为实体或实体引用属性定义 @LookupField 注解。视图创建向导在为引用属性生成选择组件时会使用此注解。

实体设计器中新加的 Views with Attribute 操作会显示绑定到实体属性的视图组件，并在所选组件处打开视图 XML。还支持将属性添加到实体的视图中。该操作可在属性表格工具栏和每个属性行中使用。

新的 Copy View 操作会复制一个视图，包括其控制器、XML 和消息。

New → Advanced → Custom Component 操作会创建 自定义 UI 组件 的文件：组件类、XML 加载器以及注册加载器的 Spring 配置。还可以为组件的 XML 元素创建 XSD schema、创建 Studio 元数据，以及创建一个包含 Lit Web 组件的 JavaScript 文件。

包含未应用的 Liquibase 变更日志的对话框现在会显示所选变更日志的内容。可以用来查看新加扩展组件中包含的变更日志。

可以从 LoadContext.Query 和 setQueryString() 方法中查询语句的侧边栏图标打开 JPQL 设计器。

Studio 检查会检查 Java 代码中定义的有 流式带区 的报表结构。会报告报表引擎不支持的结构，例如，包含多个个流式带区、流式带区的子带区，或者不是 SQL 或 JPQL 的数据集。

aiChat 是一个完整的聊天组件，支持流式回答、Markdown 消息、文件附件和对消息的操作。可以与自定义的聊天消息实体集合绑定，从而实现保存对话。

aiMessageList 和 aiMessageInput 可以单独使用，构建 aiChat 自定义的聊天界面。

aiCodeBlock 支持在聊天消息和其他任何视图中显示源代码。

UI 处理器 为视图添加行为：在按钮点击、值更改和视图事件发生时运行定义的表达式，并且可以调用带 @DynamicModelOperation 注解的应用程序方法。

全文搜索：可搜索的动态属性会被索引。

集群支持：在一个节点上发布的模型会自动发布到所有其他节点。

Dynamic model: modify settings without data loss 角色支持用户仅发布不会丢失数据的更改。

模型历史 显示模型的所有已发布版本。

可以更改 属性顺序。

可以为引用属性设置 查找字段类型和操作。

动态视图的菜单项可以有 图标。

Generate XML 按钮会 将视图模板渲染为 XML，然后可以进行编辑。

模型中授予某个角色的访问权限也适用于该角色的子角色。参考 继承角色。

动态实体和属性会显示在 数据工具 的视图中。

新的 @ExcludeFromAi 注解在代码级别对数据加载工具隐藏实体或属性。与 jmix.aitools.dataload.* 包含和排除属性不同，该注解无法在部署时被覆盖，因此只能通过更改代码并重新构建应用程序来开放隐藏数据。

聊天 UI 会 自动设置会话标题。默认情况下，使用第一条用户消息作为标题。新的 jmix.aitools.ui.conversation-title-mode 属性定义标题的规则。

可以编辑流程的 History level 以及其他 流程属性。所选级别会覆盖流程引擎的 历史级别。

可以为任务、嵌入式子流程、调用活动、网关和大多数事件设置 flowable:exclusive、flowable:asyncLeave 和 flowable:asyncLeaveExclusive 属性。对于用户任务、网关和事件，现在还可以使用 flowable:async。请参阅 异步执行属性。

可以为流程添加 升级事件、设置其属性，并在 流程属性 中管理 Escalation definitions。

报表带区现在可以是 流式 的：通过数据库游标按行读取并写入 XLSX 文档，而不是加载到内存中。如需配置流式带区，请在报表详情视图中勾选 Streaming，或在 @BandDef 注解中设置 streaming = true。

新的 AI 生成的 JPQL 数据集类型支持用自然语言描述带区数据。在报表详情视图中，LLM 根据提示生成 JPQL 查询语句，视图将其存储在报表定义中。报表运行通过 DataManager 执行存储的语句，并应用当前用户的数据访问权限。

新的 电子邮件连接 视图替代了 OAuth2 token 视图。使用授权码流程连接邮箱账户，对于 Microsoft 则使用设备码流程，并存储刷新令牌。该视图还显示连接参数，可以测试与邮件服务器的连接。

新的 jmix.email.oauth2.redirect-uri 属性可以设置授权码流程的重定向 URI，例如当应用程序在反向代理后运行时。

扩展组件会自动设置 XOAUTH2 认证机制，因此无需添加 spring.mail.properties.* 配置。

可以在 Studio 中使用 视图创建向导 的 Entity read view 和 DTO entity read view 模板创建只读视图。

可以使用 ViewNavigators 和 DialogWindows bean，以及标签页模式扩展组件的 ViewBuilders bean 打开只读视图。

如果实体有只读视图，则 list_read 操作会以只读模式打开，而不是打开详情视图。新的 entity_read 操作可以显示在实体选择器中选中的实体。

@ReadViewTemplate 注解在运行时为实体生成只读视图。动态模型扩展组件为声明了 只读类型视图 的动态实体生成只读视图。

integerSlider 和 decimalSlider 支持选择 Integer 或 Double 值。与其他字段一样，可以与实体属性绑定并支持验证器。

integerRangeSlider 和 decimalRangeSlider 支持选择值的范围，例如过滤数据。

image 组件不能再包含其他组件。JmixImage 不再提供 setText()/getText()、setWhiteSpace()、setEnabled()/isEnabled()、add() 和 remove() 方法。在 XML 中，image 的 enabled、text 和 whiteSpace 属性以及内部组件将被忽略。

JmixMenuBarRootItem.updateClassName() 方法已移除。

InMemoryUploadHandler 和 FileTemporaryStorageUploadHandler 现在继承 Vaadin 的 AbstractUploadHandler，而不是 TransferProgressAwareHandler。FileTemporaryStorageUploadHandler 在上传失败或被拒绝时删除临时文件，其 getFileInfo() 方法在当前上传组件创建文件之前返回 null。

在 标签页模式 扩展组件中，app shell 的 @Push 配置在调用 UIInitListener 监听器之前应用，因此监听器可以覆盖该配置。

Anchor.setHref() 和 IFrame.setSrc()，以及 anchor 和 iframe 的 href 和 src XML 属性，对于 Vaadin 认为不安全的 URL scheme（例如 javascript:）会抛出 IllegalArgumentException。将该 scheme 添加到 Vaadin 的 safeUrlSchemes 配置参数，或在代码中使用 setUnsafeHref() 和 setUnsafeSrc()。

addThemeName("") 抛出 IllegalArgumentException。

TreeGrid 方法 expand()、collapse()、expandRecursively() 和 collapseRecursively() 现在接收 Collection<? extends T> 和 Stream<? extends T> 参数。如果在 TreeDataGrid 子类中重写了这些方法，请更新方法签名。

许多 VaadinIcon 常量和对应的 JmixFontIcon 常量已弃用。JmixSideDialog 的 setRole() 已弃用，改用 setAriaRole()；Dialogs.SideDialogBuilder 的 withOverlayRole() 已弃用，改用 withAriaRole()。

JpqlExecutionResult.getRows() 和 EntityDataLoadResult.getRows() 的返回的行现在对于没有值的列包含 null（见 #5598）。以前这种情况是包含空字符串。工具返回给模型的行也包含 null 而不是空字符串。方法签名相同，因此编译器不会显示需要修复的位置。读取行时请检查值是否为 null：

EntityDataLoadResult result = aiDataLoadService.loadData("customers with their email");
for (Map<String, Object> row : result.getRows()) {
    Object email = row.get("email");
    String text = email != null ? email.toString() : ""; // email can be null
}

EntityDataLoadResult.getQuery() 现在返回实际执行或验证失败的查询语句（见 #5749）。如果生成的查询语句被修复，该方法返回修复后的查询，其解释、警告、maxResults 和 firstResult 都来自修复后的结果。LLM 生成的原始查询无法从结果中获取。

AiChatMessageService 接口新增了 loadLatestMessages() 方法（见 #5649）。如果有自己实现，请实现该方法。聊天中心现在按最后一条消息的时间而不是创建时间对对话进行排序和分组。

新对话现在会将第一条用户消息作为标题（见 #5648）。以前会保留 New AI Conversation 标题。如果代码在第一条消息之前为对话设置了自定义标题，第一条消息会替换该标题。如需保留自定义的标题，请在显示该对话的 AiChatFragment 上调用 setTitleMode(AiConversationTitleMode.NONE)。如需在整个应用程序中保留以前的行为，请将 jmix.aitools.ui.conversation-title-mode 属性设置为 NONE。

默认主题具有新的调色板和间距。图例位于底部居中，标题位于顶部居中。如需让外观更接近之前的版本，请在 charts:chart 上设置 colorPalette="#5470c6, #91cc75, #fac858, #ee6666, #73c0de, #3ba272, #fc8452, #9a60b4, #ea7ccc"，在 charts:legend 上设置 top="0"，并在 charts:title 上设置 left="0" top="0"。检查顶部或底部有组件的图表，例如滑块 dataZoom：可能与标题或图例重叠。

轴标签和名称保留在图表内部，轴名称会移动以避免与轴标签重叠。如需恢复以前的行为，请在 charts:gridItem 上设置 outerBoundsMode="NONE"，或在轴上设置 nameMoveOverlap="false"。

富文本样式继承普通标签的字体和文本阴影设置。如需恢复以前的行为，请将 "richInheritPlainLabel": false 添加到 nativeJson。

条形图、象形条形图、K线图和箱线图的形状不再超出网格。如需恢复以前的行为，请在轴上设置 containShape="false"。

tooltip valueFormatter 函数的第二个参数现在是原始系列数据中的索引，而不是 dataZoom 过滤后的索引。请更新用到这个参数的 JavaScript 函数。

Grid.containLabel 已弃用。请改用 outerBoundsMode="SAME" 和 outerBoundsContain="AXIS_LABEL"。启用 containLabel 时，outerBounds* 选项将被忽略。

OAuth2 token 视图替换为新的连接视图，视图 id 从 email_tokenView 更改为 email_connectionView（见 #5546）。旧的 email/token 路由仍然有效。请在以下位置替换旧视图 id：

扩展组件不再定义 mailSendTaskExecutor bean（见 #5703）。以前，Vaadin 可能将此 bean 用于异步工作，并且如果应用程序有另一个 TaskExecutor bean，则启动失败。现在：

启用 OAuth2 认证时，扩展组件会更严格地检查配置（见 #5539）：

有 featureModifyEnabled="true" 的源默认不再显示 Delete 操作。在源上设置 featureDeleteEnabled="true"，或将 jmix.maps.ui.feature-modify-includes-delete 应用程序属性设置为 true，可以为所有未设置 featureDeleteEnabled 的源保留以前的行为。

SourceFeatureDeleteEvent 和 addSourceFeatureDeleteListener() 已从 HasFeatureModify 移到 HasFeatureDelete。请在代码中将 HasFeatureModify.SourceFeatureDeleteEvent 替换为 HasFeatureDelete.SourceFeatureDeleteEvent。

OidcAutoConfiguration.DefaulOidcVaadinWebSecurity → DefaultOidcVaadinWebSecurity

SamlAutoConfiguration.DefaulSamlVaadinWebSecurity → DefaultSamlVaadinWebSecurity

SamlAutoConfiguration 中的 claimsRoleMapper bean → samlAssertionRolesMapper

io.jmix.reports.yarg.loaders.impl.GroovyDataLoader 类。扩展组件对 groovy 加载器类型使用 JmixGroovyDataLoader。与被移除的类不同，新的类会检查 jmix.core.unsafe-runtime-features-enabled 和 jmix.reports.groovy-enabled 属性。

io.jmix.reports.yarg.exception 包中的 InitializationException 和 ReportingXmlException 类。

io.jmix.reports.yarg.util.db.QueryRunner 的 update() 和 batch() 方法。请改用 Spring JdbcTemplate 或 JDBC。

io.jmix.reports.yarg.util.db.DbUtils 的 commitAndClose()、commitAndCloseQuietly()、rollback()、rollbackAndClose()、rollbackAndCloseQuietly()、loadDriver()、printStackTrace() 和 printWarnings() 方法。

UnoConverter.createAny(Object) 方法。请改用 new Any(new Type(XCell.class), value)。

AbstractFormatter.SIMPLE_ALIAS_REGEXP 和 DataExtractorImpl.EMPTY_MAP 字段。

依赖 Xalan 特有 XSLT 功能的代码可能会失败。

处理超出 JDK 限制的 XML 可能会失败。

在 Java 21 上，由于 JDK-8349516 缺陷，校验带有空 CDATA 的 StAXSource 会失败。例如，BPM 无法部署此类 DMN 文件（见 #5778）。

isLoaded() 对除 id 和创建后设置的属性之外的所有属性返回 false。

isLoadedSafe() 返回 YES 或 NO，并且不调用 getter。

isLoadedWithFetchPlan() 对于包含其他属性的 fetch plan 返回 false。

getCurrentFetchPlan() 返回包含 id 和创建后设置的属性的 fetch plan。

引用在序列化时（在 REST、BPM 流程变量等中）仅包含 id 和设置了值的属性。

引用不包含在 @PostConstruct 方法或字段初始化器中创建时分配的默认值。

将引用 DataContext.merge() 到有已加载实例的上下文中时，不会用 null 替换已加载的值。

每个测试后会调用 ServiceDestroyListener 监听器。如果此类监听器（例如在 VaadinServiceInitListener 中添加的监听器）关闭了执行器或 bean 等共享资源，那么现在会在第一个测试后执行关闭，而后续使用同一 Spring 上下文的测试将使用已关闭的资源。

每个测试后，UI.getCurrent()、VaadinSession.getCurrent()、VaadinService.getCurrent() 和 RequestContextHolder.getRequestAttributes() 会返回 null。这会影响 @AfterAll 方法、在 @UiTest 之前注册的 JUnit 扩展，以及 Spring 测试执行监听器的 afterTestMethod() 方法。测试类的 @AfterEach 方法仍能获取这些对象。

JmixUiTestExtension 现在带有 @NullMarked 注解。在 Kotlin 中，未做 null 检查就调用 getViewBasePackages() 的代码可能无法编译。对于将该扩展的 ui、vaadinSession、uiTestAuthenticator、initialView 或 viewBasePackages 字段作为非空使用，或用可空返回类型重写其方法的子类，也是如此。