|
此版本仍在开发中，尚未被视为稳定版。如需最新稳定版本，请使用 Spring Framework 7.0.6！ |
视图技术
Spring WebFlux 中的视图渲染是可插拔的。无论您选择使用 Thymeleaf、FreeMarker 还是其他视图技术，主要都只需进行配置上的更改。本章将介绍与 Spring WebFlux 集成的视图技术。
有关视图渲染的更多上下文信息，请参阅视图解析。
| Spring WebFlux 应用程序的视图位于应用程序的内部信任边界之内。视图可以访问应用上下文中的 Bean，因此，我们不建议在模板可由外部来源编辑的应用程序中使用 Spring WebFlux 的模板支持，因为这可能会带来安全风险。 |
Thymeleaf
Thymeleaf 是一种现代的服务器端 Java 模板引擎，强调使用自然的 HTML 模板，这些模板只需双击即可在浏览器中预览，这对于独立开发 UI 模板（例如由设计师完成）非常有帮助，无需启动服务器。Thymeleaf 提供了丰富的功能集，并且正处于积极的开发和维护中。如需更全面的介绍，请参阅 Thymeleaf 项目主页。
Thymeleaf 与 Spring WebFlux 的集成由 Thymeleaf 项目负责管理。该配置涉及几个 Bean 的声明，例如
SpringResourceTemplateResolver、SpringWebFluxTemplateEngine 和
ThymeleafReactiveViewResolver。更多详细信息，请参阅
Thymeleaf+Spring 以及 WebFlux 集成的
公告。
FreeMarker
Apache FreeMarker 是一个模板引擎，可用于生成各种类型的文本输出，从 HTML 到电子邮件等。Spring Framework 内置了对在 Spring WebFlux 中使用 FreeMarker 模板的支持。
视图配置
以下示例展示了如何将 FreeMarker 配置为视图技术：
-
Java
-
Kotlin
@Configuration
public class WebConfiguration implements WebFluxConfigurer {
@Override
public void configureViewResolvers(ViewResolverRegistry registry) {
registry.freeMarker();
}
// Configure FreeMarker...
@Bean
public FreeMarkerConfigurer freeMarkerConfigurer() {
FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
configurer.setTemplateLoaderPath("classpath:/templates/freemarker");
return configurer;
}
}@Configuration
class WebConfiguration : WebFluxConfigurer {
override fun configureViewResolvers(registry: ViewResolverRegistry) {
registry.freeMarker()
}
// Configure FreeMarker...
@Bean
fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {
setTemplateLoaderPath("classpath:/templates/freemarker")
}
}您的模板需要存储在前面示例中 FreeMarkerConfigurer 所指定的目录中。根据上述配置，如果您的控制器返回视图名称 welcome，解析器将查找 classpath:/templates/freemarker/welcome.ftl 模板。
FreeMarker 配置
你可以通过在 Configuration bean 上设置相应的 bean 属性，将 FreeMarker 的 'Settings' 和 'SharedVariables' 直接传递给 FreeMarker 的 FreeMarkerConfigurer 对象（该对象由 Spring 管理）。其中，freemarkerSettings 属性需要一个 java.util.Properties 对象，而 freemarkerVariables 属性则需要一个 java.util.Map。以下示例展示了如何使用 FreeMarkerConfigurer：
-
Java
-
Kotlin
@Configuration
public class WebConfiguration implements WebFluxConfigurer {
// ...
@Bean
public FreeMarkerConfigurer freeMarkerConfigurer() {
Map<String, Object> variables = new HashMap<>();
variables.put("xml_escape", new XmlEscape());
FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
configurer.setTemplateLoaderPath("classpath:/templates");
configurer.setFreemarkerVariables(variables);
return configurer;
}
}@Configuration
class WebConfiguration : WebFluxConfigurer {
// ...
@Bean
fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {
setTemplateLoaderPath("classpath:/templates")
setFreemarkerVariables(mapOf("xml_escape" to XmlEscape()))
}
}有关设置和变量的详细信息，请参阅 FreeMarker 文档，这些内容适用于 Configuration 对象。
表单处理
Spring 提供了一个用于 JSP 的标签库，其中包含（但不限于）一个 <spring:bind/> 元素。该元素主要用于在表单中显示表单支持对象（form-backing objects）的值，并展示 Web 层或业务层中 Validator 验证失败的结果。Spring 还为 FreeMarker 提供了相同功能的支持，并额外提供了便捷的宏（macros），用于直接生成表单输入元素。
绑定宏
FreeMarker 的一组标准宏定义维护在 spring-webflux.jar 文件中，因此对于经过适当配置的应用程序而言，这些宏始终可用。
Spring 模板库中定义的一些宏被视为内部（私有）宏，但在宏定义中并不存在此类作用域限制，因此所有宏对调用代码和用户模板都是可见的。以下各节仅聚焦于您需要在模板中直接调用的宏。如果您希望直接查看宏的源代码，该文件名为 spring.ftl，位于 org.springframework.web.reactive.result.view.freemarker 包中。
有关绑定支持的更多详细信息，请参阅 Spring MVC 的简单绑定。
脚本视图
Spring Framework 内置了与 Spring WebFlux 集成的功能，可配合任何基于 JSR-223 Java 脚本引擎运行的模板库使用。 下表列出了我们在不同脚本引擎上已测试过的模板库：
| 脚本库 | 脚本引擎 |
|---|---|
集成任何其他脚本引擎的基本规则是，它必须实现
ScriptEngine 和 Invocable 接口。 |
脚本模板
你可以声明一个 ScriptTemplateConfigurer Bean 来指定要使用的脚本引擎、
要加载的脚本文件、用于渲染模板的函数等等。
以下示例使用了 Jython Python 引擎：
-
Java
-
Kotlin
@Configuration
public class WebConfiguration implements WebFluxConfigurer {
@Override
public void configureViewResolvers(ViewResolverRegistry registry) {
registry.scriptTemplate();
}
@Bean
public ScriptTemplateConfigurer configurer() {
ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();
configurer.setEngineName("jython");
configurer.setScripts("render.py");
configurer.setRenderFunction("render");
return configurer;
}
}@Configuration
class WebConfiguration : WebFluxConfigurer {
override fun configureViewResolvers(registry: ViewResolverRegistry) {
registry.scriptTemplate()
}
@Bean
fun configurer() = ScriptTemplateConfigurer().apply {
engineName = "jython"
setScripts("render.py")
renderFunction = "render"
}
}render 函数被调用时带有以下参数：
-
String template：模板内容 -
Map model：视图模型 -
RenderingContext renderingContext:RenderingContext，它提供对应用程序上下文、区域设置、模板加载器和 URL 的访问权限。
HTML 片段
HTMX 和 Hotwire Turbo 强调一种“通过线路传输 HTML”的方法，即客户端接收服务器以 HTML 格式而非 JSON 格式发送的更新。 这种方法可以在无需编写大量甚至完全不编写 JavaScript 的情况下，获得单页应用（SPA）的优势。如需全面了解并深入学习，请访问它们各自的官方网站。
在 Spring WebFlux 中，视图渲染通常涉及指定一个视图和一个模型。
然而，在 HTML-over-the-wire（通过网络传输 HTML）中，一种常见的功能是发送多个 HTML 片段，
供浏览器用于更新页面的不同部分。为此，控制器方法可以返回 Collection<Fragment>。例如：
-
Java
-
Kotlin
@GetMapping
List<Fragment> handle() {
return List.of(Fragment.create("posts"), Fragment.create("comments"));
}@GetMapping
fun handle(): List<Fragment> {
return listOf(Fragment.create("posts"), Fragment.create("comments"))
}也可以通过返回专用类型 FragmentsRendering 来实现相同的效果：
-
Java
-
Kotlin
@GetMapping
FragmentsRendering handle() {
return FragmentsRendering.fragment("posts").fragment("comments").build();
}@GetMapping
fun handle(): FragmentsRendering {
return FragmentsRendering.fragment("posts").fragment("comments").build()
}每个片段都可以拥有一个独立的模型，并且该模型会从请求的共享模型中继承属性。
HTMX 和 Hotwire Turbo 支持通过 SSE（服务器发送事件）进行流式更新。
控制器可以使用 FragmentsRendering 创建 Flux<Fragment>，
或者通过 Publisher 将任何其他可适配为 Reactive Streams ReactiveAdapterRegistry 的响应式生产者用于创建 Flux<Fragment>。
也可以直接返回 FragmentsRendering，而无需使用 6 包装器。
JSON 和 XML
为了内容协商的目的，能够根据客户端请求的内容类型，在通过 HTML 模板渲染模型与其他格式（如 JSON 或 XML）之间进行切换是非常有用的。为了支持这一功能，Spring WebFlux 提供了HttpMessageWriterView，您可以使用它来插入来自spring-web的任何可用编解码器（Codecs），例如JacksonJsonEncoder、JacksonSmileEncoder或Jaxb2XmlEncoder。
与其他视图技术不同，HttpMessageWriterView 不需要 ViewResolver，而是作为默认视图进行配置。
您可以配置一个或多个此类默认视图，每个视图包装不同的 HttpMessageWriter 实例或 Encoder 实例。在运行时，将使用与请求的内容类型匹配的那个视图。
在大多数情况下，模型包含多个属性。要确定序列化哪一个属性，您可以使用要用于渲染的模型属性名称来配置 HttpMessageWriterView。如果模型仅包含一个属性，则使用该属性。