Skip to content

模板语法

ace-template 采用 Mustache 风格的逻辑轻量语法:模板不含表达式运算/条件逻辑,取值与控制流由标签驱动。默认分隔符 {{ }}

插值与转义

html
{{ name }}      <!-- 默认 HTML 转义(防 XSS),含 & < > " ' 与反引号 -->
{{& html }}     <!-- 原样输出,不转义 -->
{{{ html }}}    <!-- 原样输出,等价 {{& }} -->

缺失变量渲染为空串(逻辑轻量:缺失不报错)。标量类型(字符串/整数/浮点/布尔)按其文本渲染。

Section

section 的行为由所取值决定:

html
{{#user}}Hi {{ name }}{{/user}}        <!-- 对象:压入作上下文 -->
{{#items}}<li>{{ . }}</li>{{/items}}   <!-- 列表:逐项迭代,{{.}} 为当前项 -->
{{#isVip}}尊贵会员{{/isVip}}            <!-- 布尔/真值:渲染一次;假值跳过 -->

真值判定:空值 / false / 空串 / 0 / 空列表 为假,其余为真;对象恒真。section 内仍可解析外层作用域的名字(就近沿栈上溯)。

反转 Section

值为时渲染一次,常用于空态:

html
{{#items}}<li>{{ . }}</li>{{/items}}
{{^items}}<p>暂无数据</p>{{/items}}

注释与局部模板

html
{{! 这是注释,不会输出 }}
{{> user_row }}   <!-- 引入局部模板 user_row(经文件加载器或 register 解析) -->

局部模板缺失时渲染为空(不报错)。自包含的局部模板(直接或间接引用自身)会抛 TemplateException(递归环防护)。

点分路径与当前值

html
{{ user.address.city }}   <!-- 逐层下钻;任一段缺失即空 -->
{{ . }}                   <!-- 当前 section 上下文值本身 -->

循环元数据

列表 section 迭代内可用循环元变量:

变量含义
{{@index}}下标(0 基)
{{@number}}序号(1 基)
{{@first}}是否首项(Bool)
{{@last}}是否末项(Bool)
{{@length}}列表长度
{{@odd}} / {{@even}}下标奇/偶(Bool)
html
<ol>
{{#users}}
  <li class="{{#@odd}}odd{{/@odd}}{{#@even}}even{{/@even}}{{#@last}} last{{/@last}}">
    {{@number}}. {{ name }}{{#@last}} ← 末位{{/@last}}
  </li>
{{/users}}
</ol>

嵌套循环时 @index 等取最内层循环;无活动循环时 @... 为空。

过滤器链

变量可接过滤器链,| 分隔,namename:arg

html
{{ name | upper }}
{{ bio | default:"暂无" }}
{{ title | lower | capitalize }}
{{ q | url }}                 <!-- 生成 URL 查询参数 -->

内置过滤器、终结转义(raw/html/js/url/attr)与自定义助手见 过滤器与助手

模板继承(布局)

父模板{{$ 块名}}默认体{{/ 块名}} 定义可覆盖块:

html
<!-- templates/layout.mustache -->
<!doctype html>
<html><head><title>{{$ title}}默认标题{{/ title}}</title></head>
<body>{{$ content}}{{/ content}}<footer>{{ year }}</footer></body>
</html>

子模板首行 {{< 父模板名}} 声明继承,再用同名 {{$ 块}} 覆盖:

html
<!-- templates/index.mustache -->
{{< layout}}
{{$ title}}用户列表{{/ title}}
{{$ content}}
  <h1>用户列表</h1>
  {{#users}}<p>{{ name }}</p>{{/users}}
{{/ content}}

渲染 index 实际渲染 layout,其 {{$ title}}/{{$ content}} 被子模板覆盖,未覆盖的块用默认体。子模板中块之外的内容被忽略。支持多级继承(子覆盖父覆盖祖,就近者胜);继承环会抛 TemplateException

自定义分隔符

{{=<新开始> <新结束>=}} 切换后续分隔符,适合模板里大量出现 {{/}} 字面量的场景:

html
{{=<% %>=}}
现在用 <% name %> 取值,而 {{ 是普通文本。

standalone 空白处理

独占一行的块级标签(section 开/闭、反转、注释、局部模板、继承块、set-delimiter)会被识别为 standalone:该行的前导/尾随空白与行尾换行被删除,不产生空行

html
{{#items}}
  <li>{{ . }}</li>
{{/items}}

上面 {{#items}}{{/items}} 各自独占一行,渲染结果不会出现多余空行。此外,standalone 的局部模板会把其前导缩进应用到 partial 输出的每一行(保持缩进对齐)。变量/插值标签不参与 standalone 处理。

基于 Apache-2.0 许可证发布