Thymeleaf中文网

深色模式

12.4 CSS内联 ​

Thymeleaf 为 <style> 标签提供了专属的 CSS 内联机制，允许你在 CSS 代码中嵌入 Thymeleaf 表达式，动态生成类名、样式值等。和 JS 内联类似，它需要显式激活，且会智能适配 CSS 语法规则，保证生成的 CSS 合法可用。

就像这样：

html
<style th:inline="css">
    ...
</style>

假设后端定义了两个变量：

  • classname = 'main elems'
  • align = 'center'

模板中的 CSS 内联代码：

html
<style th:inline="css">
    .[[${classname}]] {
      text-align: [[${align}]];
    }
</style>

最终渲染结果：

html
<style>
    .main\ elems { /* 空格被转义，CSS 能正确识别该类名 */
      text-align: center;
    }
</style>

请注意，CSS 内联也具备一定的智能性，与 JavaScript 内联类似。具体来说，通过转义表达式（如 [[${classname}]]）输出的内容将被转义为 CSS 标识符。这就是为什么在上面的代码片段中，我们的 classname = 'main elems' 会变成 main\ elems。

  • 如果不使用 CSS 内联，直接写 .main elems 会被 CSS 解析为「main 类下的 elems 元素」，而非「名为 main elems 的类」，导致样式失效。

核心规则与细节 ​

  1. 显式激活：必须添加 th:inline="css"，否则 [[...]] 会被当作普通文本，导致 CSS 语法错误；
  2. 转义规则：
    • 针对 CSS 标识符（类名、ID、属性名）：自动转义空格、特殊符号（如 #/&）为 CSS 合法格式；
    • 针对样式值（如 text-align、font-size）：直接输出值，不额外转义（保证与 CSS 语法兼容）；
  3. 原生模板友好性： 可结合注释+静态占位符，实现静态预览合法：
    html
    <style th:inline="css">
    /* 注释包裹表达式 + 静态类名/值 */
    ./*[[${classname}]]*/main-elems {
      text-align: /*[[${align}]]*/left;
    }
</style>
    • 静态预览时：生效的是 .main-elems { text-align: left; }；
    • 动态渲染时：替换为 .main\ elems { text-align: center; }；
  4. 不转义内联（[(...)]）： 慎用！仅当需要拼接完整 CSS 代码片段时使用，且需确保表达式结果是合法的 CSS 语法，否则会导致样式失效：
    html
    <style th:inline="css">
    /* 不推荐：无自动转义，易出错 */
    .[(${classname})] { text-align: center; }
</style>
    结果会是 .main elems { ... }（CSS 解析错误），因此 CSS 内联几乎只使用 [[...]]。

典型使用场景 ​

  • 动态类名/ID：根据后端配置生成自定义类名（如主题相关的类名、权限相关的样式类）；
  • 动态样式值：传递后端配置的样式参数（如字体大小、颜色、对齐方式）；
  • 主题切换：通过后端变量控制 CSS 样式，实现前端无感知的主题切换：
    html
    <style th:inline="css">
    :root {
      --primary-color: [[${theme.primaryColor}]]; /* 动态主题色 */
      --font-size: [[${theme.fontSize}]]px;
    }
    body {
      color: var(--primary-color);
      font-size: var(--font-size);
    }
</style>

总结 ​

  1. CSS 内联需通过 th:inline="css" 显式激活，核心价值是智能适配 CSS 标识符规则（自动转义特殊字符）；
  2. [[${表达式}]] 是唯一推荐的用法，会自动转义类名/ID 中的特殊字符，保证 CSS 语法合法；
  3. 结合注释+静态占位符，可实现「静态预览合法、动态渲染正确」的原生模板效果；
  4. 适合动态类名、动态样式值、主题切换等场景，避免手动拼接 CSS 导致的语法错误。