name: template-dev description: AnQiCMS 模板开发技能：基于 pongo2（Django 语法）的自定义模板引擎，标签闭合规则完整速查 category: Development version: 1.2 tags: [anqicms, template, pongo2, django, tag]

AnQiCMS 模板开发技能

AnQiCMS 使用基于 github.com/flosch/pongo2（Django-like syntax）的模板引擎，并在此基础上做了自定义扩充。

核心语法

• 变量：{{ item.Title }} — 严格区分大小写，字段首字母大写
• 过滤器：{{ var|filter }}
• 注释：{# 单行 #} 或 {% comment %}...{% endcomment %}
• 时间格式：使用 Golang 参考时间 2006-01-02 15:04:05
• 函数：{{ stampToDate(timestamp, "2006-01-02") }}
• 过滤器：{{ timestamp|dateFormat:"2006-01-02" }}
• 空值判断：{% if array %} 或 {% for %}...{% empty %}...{% endfor %}
• 条件：{% if cond %}...{% elif %}...{% else %}...{% endif %}（用 elif 不是 elseif）
• 变量声明：用标签获取数据时需声明变量名才能后续引用

标签闭合规则

并非所有标签都需要闭合。 以下按类型区分。

需闭合标签（BLOCK_TAGS）

这些标签必须成对使用：{% tag %}...{% endtag %}`

自闭合标签（SINGLE_TAGS）

这些标签不需要闭合，单行使用即可：

archiveDetail · categoryDetail · tagDetail · pageDetail · moduleDetail · placeDetail · userDetail · userGroupDetail · tdk · system · contact · diy · tr · lorem · now · set · include · extends · import · ssi · templatetag · widthratio · attachment · cycle · firstof · jump

{% tdk t %}
{% system siteInfo %}
{% contact contactInfo %}
{% archiveDetail article with id=123 %}
{% include "partial/header.html" %}
{% extends "base.html" %}
{% set varName = value %}

控制标签（CONTROL_TAGS）

这些标签必须出现在特定的块标签内部：

常用标签速查

内容获取

{% archiveList articles with moduleId=1 categoryId=2 limit="10" order="id desc" %}
  {% for article in articles %}
    <h3><a href="{{ article.Link }}">{{ article.Title }}</a></h3>
    <span>{{ article.CreatedTime|dateFormat:"2006-01-02" }}</span>
  {% empty %}
    <p>暂无内容</p>
  {% endfor %}
{% endarchiveList %}

页面组件

{% pagination pages with show="5" %}
  {% if pages.PrevPage %}<a href="{{ pages.PrevPage.Link }}">上一页</a>{% endif %}
  {% for page in pages.Pages %}
    <a href="{{ page.Link }}" class="{% if page.IsCurrent %}active{% endif %}">{{ page.Name }}</a>
  {% endfor %}
  {% if pages.NextPage %}<a href="{{ pages.NextPage.Link }}">下一页</a>{% endif %}
{% endpagination %}
 
{% navList navs with type="top" %}
  {% for nav in navs %}
    <a href="{{ nav.Link }}" {% if nav.IsCurrent %}class="active"{% endif %}>{{ nav.Title }}</a>
  {% endfor %}
{% endnavList %}
 
{% breadcrumb crumbs %}
  {% for crumb in crumbs %}
    <a href="{{ crumb.Link }}">{{ crumb.Name }}</a>
  {% endfor %}
{% endbreadcrumb %}

逻辑控制

{% if user %}
  {{ user.UserName }}
{% elif guest %}
  访客
{% else %}
  未知
{% endif %}
 
{% for item in items %}
  {{ item.Name }}
{% empty %}
  列表为空
{% endfor %}

过滤器与函数

全局函数（AddFunc 注册，用 {{ fn(args) }} 调用）：stampToDate · priceFormat · range · CustomFunc

• 时间：{{ stampToDate(timestamp, "2006-01-02") }}
• 价格：{{ priceFormat(price) }}

AnQiCMS 自定义过滤器（tags/filter.go，用 {{ var|filter }}）： thumb（缩略图）· render（渲染模板片段）· json（转 JSON）· lazy（懒加载占位）· dump · contain · fields · index · repeat · list · count · trim · trimLeft · trimRight · replace · dateFormat · priceFormat；另替换了内置的 split、wordwrap。

• 时间过滤器：{{ timestamp|dateFormat:"2006-01-02" }}
• 价格过滤器：{{ price|priceFormat }}

pongo2 内置过滤器：default · length · upper · lower · title · urlencode · addslashes · slugify · first · last · cut · center · wordcount · random 等。

注意：stampToDate 是全局函数不是过滤器，写成 {{ stampToDate(x, "2006-01-02") }}；对应的时间过滤器是 dateFormat。

验证清单

• [ ] 字段首字母大写（Title 不是 title，Link 不是 link）
• [ ] 需闭合的标签正确成对（见上方 BLOCK_TAGS 表）
• [ ] 自闭合标签没有错误添加 end 前缀
• [ ] elif 不是 elseif
• [ ] 时间用 stampToDate 函数或 dateFormat 过滤器
• [ ] 模板目录结构遵循标准布局（base.html + 模型目录）
• [ ] 修改后调用 system_config（action=template_reload）生效