全局变量

Halo 目前为模板引擎在全局提供了一些变量，本文档将列出已提供的变量以及介绍这些变量的使用方法。

site

描述

提供了部分可公开的系统相关的设置项，其中所有参数均来自于 Console 的系统设置。

类型

SiteSettingVo

{
  "title": "string", // 站点标题
  "subtitle": "string", // 站点副标题
  "url": "string", // 站点的外部访问链接
  "version": "string", // 当前 Halo 版本
  "logo": "string", // Logo 地址
  "favicon": "string", // Favicon 地址
  "language": "string", // 站点语言
  "allowRegistration": false, // 是否允许注册
  "post": {
    // 文章相关设置
    "postPageSize": 10, // 首页默认分页大小
    "archivePageSize": 10, // 归档页默认分页大小
    "categoryPageSize": 10, // 分类归档页默认分页大小
    "tagPageSize": 10, // 标签归档页默认分页大小
    "authorPageSize": 10, // 作者归档页默认分页大小
  },
  "seo": {
    // SEO 相关设置
    "blockSpiders": false, // 禁止搜索引擎抓取
    "keywords": "string", // 站点全局关键词，一般不需要主动使用，Halo 会自动插入到 head 标签中
    "description": "string", // 站点全局描述，一般不需要主动使用，Halo 会自动插入到 head 标签中
  },
  "comment": {
    // 评论相关设置
    "enable": true, // 是否开启评论
    "systemUserOnly": false, // 是否只允许登录用户评论
    "requireReviewForNew": false, // 是否需要审核新评论
  },
  "routes": {
    "categoriesUri": "/categories", // 分类页路由前缀
    "tagsUri": "/tags", // 标签页路由前缀
    "archivesUri": "/archives", // 归档页路由前缀
  },
}

示例

显示站点标题：

<h1 th:text="${site.title}"></h1>

显示站点 Logo：

<img th:src="${site.logo}" alt="Logo" />

显示当前 Halo 版本：

<span th:text="${site.version}"></span>

#halo.matchVersion(constraint)

描述

用于判断当前运行的 Halo 版本是否满足指定的语义化版本范围，适合在主题模板中为依赖新版 Halo 能力的片段添加兼容判断。

引入版本: 2.25.0

版本范围格式遵循 Semantic Range Expressions，例如 >=2.25.0、>2.0.0 & <3.0.0 等。

开发版本行为

开发版本 0.0.0 会始终返回 true，以便在本地开发环境中调试主题模板。

示例

仅在 Halo 版本满足要求时渲染模板片段：

<div th:if="${#halo.matchVersion('>=2.25.0')}">
  <!-- 这里可以使用仅在 Halo 2.25.0 及以上版本可用的能力 -->
</div>

判断一个版本范围：

<div th:if="${#halo.matchVersion('>=2.25.0 & <3.0.0')}">
  <!-- 仅在 Halo 2.x 的指定版本范围内渲染 -->
</div>

theme

描述

关于当前激活主题的信息。

类型

ThemeVo

{
  "metadata": {
    "name": "string", // 唯一标识
    "labels": {
      "additionalProp1": "string",
    },
    "annotations": {
      "additionalProp1": "string",
    },
    "creationTimestamp": "2022-11-20T14:44:58.984Z", // 创建时间
  },
  "spec": {
    "displayName": "string", // 显示名称
    "author": {
      // 作者相关信息
      "name": "string", // 作者名称
      "website": "string", // 作者网站
    },
    "description": "string", // 主题描述
    "logo": "string", // 主题 Logo
    "homepage": "string", // 主题主页地址
    "repo": "string", // 主题仓库地址
    "issues": "string", // 主题问题反馈地址
    "version": "string", // 主题版本
    "requires": "string", // 主题依赖 Halo 版本的设置
    "license": [
      // 主题许可信息
      {
        "name": "string", // 许可名称
        "url": "string", // 许可地址
      },
    ],
    "settingName": "string", // 主题设置表单名称
    "configMapName": "string", // 主题配置名称
    "customTemplates": {}, // 主题自定义模板设置
  },
  "config": {}, // 主题配置
}

其中：

customTemplates：一般不会在模板引擎中使用，使用文档请参考：模板编写
config：主题配置，使用文档请参考：设置选项

版本说明：spec.homepage 和 spec.license 自 Halo 2.7.0 起可用，spec.issues 自 Halo 2.15.0 起可用。

示例

显示主题名称：

<h1 th:text="${theme.spec.displayName}"></h1>

在静态资源加入版本号参数，以防止升级之后的缓存问题：

<link
  rel="stylesheet"
  th:href="@{/assets/dist/style.css?v={version}(version=${theme.spec.version})}"
/>
<script
  th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"
></script>

按登录状态条件渲染

描述

Halo 的模板引擎集成了 Spring Security 方言，可以在任意模板中使用 sec:authorize 属性，根据当前访问者的认证状态和角色决定元素是否渲染。属性值使用 Spring Security 表达式。

常用表达式：

isAuthenticated()：访问者已登录
isAnonymous()：访问者未登录
hasRole('xxx')：访问者具有指定角色，例如内置的超级管理员角色为 super-role

未登录的访问者会被视为匿名用户（角色为 anonymous）。

示例

根据登录状态显示登录或退出入口：

<a sec:authorize="isAnonymous()" th:href="@{/login}">登录</a>
<a sec:authorize="isAuthenticated()" th:href="@{/logout}">退出</a>

仅对超级管理员显示入口：

<a sec:authorize="hasRole('super-role')" th:href="@{/console}">管理后台</a>

访问量统计脚本

描述

文章详情页（post.html）和自定义页面详情页（page.html）的模型中包含了统计所需的信息，Halo 会向这些页面的 <head> 自动注入异步统计脚本（/halo-tracker.js），用于累计对应内容的访问量，即 PostVo 等模型中 stats.visit 数据的来源。

主题无需为此手动引入任何脚本，也不要重复注入。Console 中的内容预览请求不会被统计。

示例

在模板中展示访问量：

<span th:text="${post.stats.visit}"></span>

全局变量#

#site

#描述

#类型

#示例

##halo.matchVersion(constraint)

#描述

#示例

#theme

#描述

#类型

#示例

#按登录状态条件渲染

#描述

#示例

#访问量统计脚本

#描述

#示例