AnQiCMS模板中，`{{ obj|filter__name:param }}` 过滤器的正确使用语法是什么？

安企CMS（AnQiCMS）以其高效、灵活的特性，为内容运营提供了强大的支持。在日常内容展示中，我们常常需要对数据进行精细化的处理和格式化，以确保信息以**状态呈现给访问者。此时，模板中的“过滤器”就成为了我们不可或缺的利器。

今天，我们就来深入探讨安企CMS模板中过滤器的正确使用语法：{{ obj|filter_name:param }}。理解并掌握它，能让你的网站内容展现出前所未有的专业度和动态感。

过滤器：数据呈现的“精修师”

在安企CMS的模板世界里，当你从后台获取到变量（obj）时，它可能只是原始的数据。例如，一个时间戳可能需要被格式化为“2023年10月26日”，一段长文本可能需要被截断并加上省略号，或者某些HTML内容需要确保安全地渲染。过滤器，正是为这些需求而生，它像一个“精修师”，对原始数据进行处理、转换或验证，然后输出加工后的结果。

它的基本语法非常直观：

{{ obj|filter_name:param }}

让我们拆解一下这个结构：

• {{ ... }}：这是安企CMS模板中用于输出变量内容的标准双花括号语法。所有需要展示给用户的数据，最终都会通过它输出。
• obj：这代表你要处理的原始变量或数据对象。它可以是字符串、数字、数组，甚至是更复杂的结构体。
• | (管道符)：这个符号是过滤器的核心，它表示将左侧的 obj 作为输入，“管道”给右侧的 filter_name 进行处理。
• filter_name：这是你希望应用的特定过滤器的名称，比如 truncatechars（截断字符）、date（日期格式化）或 safe（安全输出HTML）。
• : (冒号)：如果过滤器需要额外的参数来工作，这个冒号就用来分隔过滤器名称和它的参数。
• param (参数)：这是传递给过滤器的可选参数。不同的过滤器可能需要不同类型和数量的参数。有些过滤器可能不需要任何参数。

理解了语法，我们来看看一些常见的实际应用场景。

常见的过滤器及其用法示例

安企CMS内置了丰富的过滤器，能满足我们日常内容运营的各种需求。

1. 默认值处理：default 与 default_if_none

当某个变量可能为空或不存在时，我们不希望页面显示空白或错误，这时就可以使用 default 或 default_if_none 过滤器来设置一个备用值。

• default：如果变量为空字符串、零值、nil 或布尔false，则显示默认值。

  
  <!-- 如果 userName 为空，显示 "大侠匿名" -->
  {{ userName|default:"大侠匿名" }}
  

• default_if_none：更严格一些，只在变量为 nil（即Go语言中的nil，通常指指针类型为空）时显示默认值，而不会把空字符串或0当作空。

  
  <!-- 如果 userSignature 是 nil，显示 "这个人很懒，什么都没留下" -->
  {{ userSignature|default_if_none:"这个人很懒，什么都没留下" }}
  

2. 日期和时间格式化：date

虽然安企CMS提供了 stampToDate 标签来格式化时间戳，但如果你的变量已经是 time.Time 类型（通常由后端直接传递），date 过滤器是更简洁的选择。

<!-- 将 createTime（假设为 time.Time 类型）格式化为 "2006-01-02" 格式 -->
{{ article.createTime|date:"2006-01-02" }}

请注意，date 过滤器遵循 Go 语言的特殊日期格式化规则（例如“2006-01-02 15:04:05”是参考模板，而非实际输出）。

3. 文本截断：truncatechars 和 truncatewords

对于文章简介或摘要，我们经常需要限制其显示长度，同时保持阅读的连贯性。

• truncatechars：按字符数截断文本，包括省略号。

  
  <!-- 截断 article.Description，最多显示 100 个字符，超出部分用 "..." 代替 -->
  {{ article.Description|truncatechars:100 }}
  

• truncatechars_html：与 truncatechars 类似，但更智能，它会尝试保留 HTML 结构。

  
  <!-- 截断 HTML 文本，并保持标签闭合 -->
  {{ article.Content|truncatechars_html:200|safe }}
  

• truncatewords：按单词数截断文本，通常用于英文内容。

  
  <!-- 截断英文文本，最多显示 20 个单词 -->
  {{ article.Abstract|truncatewords:20 }}
  

4. 内容安全与渲染：safe 和 escape

处理用户输入或富文本内容时，防止跨站脚本（XSS）攻击至关重要。

• safe：告诉模板引擎，该变量的内容是安全的HTML，不需要转义，可以直接渲染。常用于后台富文本编辑器生成的内容。

  
  <!-- 安全地输出 article.Content，使其作为 HTML 内容被浏览器解析 -->
  {{ article.Content|safe }}
  

  重要提示： 使用 safe 必须谨慎，确保内容来源可信，否则可能引入安全漏洞。
• escape：强制对内容进行HTML转义，即使默认已开启自动转义，它也会再次转义。这有助于显示原始HTML代码而不是渲染它。

  
  <!-- 将可能包含 HTML 标签的 userInput 转义，显示其原始代码 -->
  {{ userInput|escape }}
  

  安企CMS默认会进行HTML转义，除非你使用了safe或autoescape off。

5. 长度计算：length

获取字符串、数组或映射的长度（元素数量）。

<!-- 显示文章标题的字符数 -->
{{ article.Title|length }}

<!-- 显示评论列表中的评论总数 -->
{{ comments|length }}

6. 字符串处理：add、replace、split、join

• add：将两个数字或字符串相加/拼接。

  
  <!-- 数字相加 -->
  {{ price|add:discount }}
  <!-- 字符串拼接 -->
  {{ "欢迎使用"|add:"安企CMS" }}
  

• replace：替换字符串中的特定子串。

  
  <!-- 将 article.Title 中的 "CMS" 替换为 "内容管理系统" -->
  {{ article.Title|replace:"CMS,内容管理系统" }}
  

• split：根据指定分隔符将字符串分割成数组。

  
  <!-- 将逗号分隔的关键词字符串分割成数组 -->
  {% set tags_array = article.Keywords|split:"," %}
  {% for tag in tags_array %}
      <span>{{ tag }}</span>
  {% endfor %}
  

• join：将数组元素用指定分隔符连接成字符串。

  
  <!-- 将 tags_array 中的元素用 " | " 连接起来 -->
  {{ tags_array|join:" | " }}
  

7. 清理字符串：trim、trimLeft、trimRight

用于移除字符串首尾的空格或特定字符。

• trim：移除字符串两端的空格或指定字符。 “`twig {{” 安企CMS “|trim}} <!– 移除字符串两