Thymeleaf中文网

深色模式

消息工具（Messages） ​

#messages：是用于在变量表达式中获取外部化消息的工具方法，其功能与 #{...} 语法获取消息的方式完全一致。

java
/*
 * ======================================================================
 * 请查阅 org.thymeleaf.expression.Messages 类的 Javadoc API 文档
 * ======================================================================
 */

/*
 * 获取国际化外部化消息（外部化消息）。该方法可接收以下参数形式：
 * - 单个消息键；
 * - 一个消息键 + 若干参数；
 * - 消息键的数组/列表/集合（此种情况下，方法会返回对应数量的国际化消息数组/列表/集合）。
 * 若未找到指定键对应的消息，将返回默认提示文本（例如 '??msgKey??' 形式）。
 */
${#messages.msg('msgKey')}
${#messages.msg('msgKey', param1)}
${#messages.msg('msgKey', param1, param2)}
${#messages.msg('msgKey', param1, param2, param3)}
${#messages.msgWithParams('msgKey', new Object[] {param1, param2, param3, param4})}
${#messages.arrayMsg(messageKeyArray)}
${#messages.listMsg(messageKeyList)}
${#messages.setMsg(messageKeySet)}

/*
 * 获取国际化外部化消息，若未找到则返回 null。
 * 与普通 msg 方法不同，当指定键的消息不存在时，此系列方法不会返回默认提示文本，而是返回 null。
 */
${#messages.msgOrNull('msgKey')}
${#messages.msgOrNull('msgKey', param1)}
${#messages.msgOrNull('msgKey', param1, param2)}
${#messages.msgOrNull('msgKey', param1, param2, param3)}
${#messages.msgOrNullWithParams('msgKey', new Object[] {param1, param2, param3, param4})}
${#messages.arrayMsgOrNull(messageKeyArray)}
${#messages.listMsgOrNull(messageKeyList)}
${#messages.setMsgOrNull(messageKeySet)}

补充说明（贴合 Thymeleaf 国际化技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
externalized messages国际化外部化消息（Thymeleaf 核心特性，将文案抽离到外部配置文件，适配多语言）
message key消息键（配置文件中消息的唯一标识，如 welcome=欢迎您 中的 welcome）
default message默认提示文本（消息键未找到时的兜底值，Thymeleaf 默认格式为 ??键名??）
Messages消息工具类（Thymeleaf 表达式工具，#messages 是其在模板中的简写，专用于读取国际化文案）

2. 关键逻辑解读 ​

  • 基础用法：#messages.msg('msgKey') 是最核心的用法，对应读取国际化配置文件中 msgKey 对应的文案；
  • 带参数用法：若配置文件中消息为 greeting=你好，{0}！，则 #messages.msg('greeting', '张三') 会输出 你好，张三！；
  • 批量用法：arrayMsg/listMsg/setMsg 支持传入多个消息键，批量返回对应文案（返回类型与入参类型一致）；
  • null 兜底用法：msgOrNull 系列方法与 msg 系列的核心区别是“未找到消息时返回 null，而非 ??msgKey??”，适合需要自定义兜底逻辑的场景。

3. 句式优化说明 ​

  • 将原文冗长的参数说明拆分为“列表+短句”形式（如“可接收以下参数形式：- 单个消息键；- 一个消息键 + 若干参数；”），更符合中文技术文档的阅读习惯；
  • 补充“国际化外部化消息”的核心定位，明确该工具类的用途（区别于普通文本）；
  • 用“与普通 msg 方法不同”强化 msgOrNull 系列的特性，突出“返回 null 而非默认文本”的核心差异；
  • 保留 ${#messages.xxx} 表达式原样（技术规范），注释部分则转为流畅的中文技术描述，兼顾精准与易懂。

总结 ​

  1. #messages 核心作用：在 Thymeleaf 模板中读取国际化配置文件的文案，实现多语言适配；
  2. 核心用法分类：
    • 基础读取：msg('键名')（未找到返回 ??键名??）；
    • 带参数读取：msg('键名', 参数1, 参数2)（支持动态填充文案占位符）；
    • 批量读取：arrayMsg/ listMsg/setMsg（按集合类型批量返回文案）；
    • 无兜底读取：msgOrNull 系列（未找到返回 null，自定义兜底场景）；
  3. 适用场景：模板中所有需要多语言适配的文本（如按钮文案、提示信息、页面标题）。