在网站内容管理中，我们常常会遇到这样的情况：为了保持页面布局的整洁和统一，我们需要截取过长的文本内容，同时又不希望破坏其语义或排版。无论是文章摘要、产品简介，还是用户评论，适当地控制文本长度并添加省略号，都能大大提升用户体验。安企CMS（AnQiCMS）的模板引擎为我们提供了两种非常实用的过滤器：truncatechars 和 truncatewords，以及它们处理HTML内容的变体，帮助我们轻松实现这一目标。

优雅地截取纯文本内容：truncatechars 与 truncatewords

当你的内容是纯文本时，你可以根据字符数量或单词数量进行截取。

  1. 按字符截取：truncatechars 顾名思义，truncatechars 过滤器是根据你指定的字符数量来截取文本的。它会从文本的开头开始计数，一旦达到指定长度，就会截断并自动在末尾添加省略号（...）。需要注意的是，这个省略号的三个字符也会计入总长度。

    使用示例： 假设我们有一段文本 {{ item.Description }}。

    {{ item.Description|truncatechars:30 }}

    如果 item.Description 的内容是“安企CMS是一款基于Go语言开发的企业级内容管理系统，功能强大，部署简单。” 那么上述代码可能会输出：“安企CMS是一款基于Go语言开发的企业级内容…” (实际字符数可能因编码有所差异，但逻辑是按字符计数)。

  2. 按单词截取：truncatewords 而 truncatewords 过滤器则更注重词语的完整性。它会按单词（以空格分隔）进行截取，当你指定截取多少个单词时，它会保留前几个完整的单词，然后添加省略号。这对于英文内容尤其有用，能避免单词被截断一半而变得难以阅读。

    使用示例：

    {{ item.Title|truncatewords:10 }}

    如果 item.Title 的内容是“AnQiCMS is a Go-based enterprise content management system with powerful features and easy deployment.” 那么上述代码可能会输出：“AnQiCMS is a Go-based enterprise content management system…”

处理包含 HTML 的内容：truncatechars_html 与 truncatewords_html

如果你的内容包含了 HTML 标签（比如文章详情中的富文本内容），直接使用 truncatechars 或 truncatewords 可能会导致页面结构混乱，因为它们会无差别地截断字符，可能把 HTML 标签截断一半。为了解决这个问题，安企CMS 贴心地提供了 truncatechars_html 和 truncatewords_html 过滤器。

这两个过滤器会在截取文本的同时，智能地闭合 HTML 标签，确保页面结构不会被破坏。同样，它们也分为按字符截取和按单词截取。

重要提示： 在使用这些过滤器处理 HTML 内容时，请务必在输出时加上 |safe 过滤器。这是因为模板引擎为了安全考虑，默认会对所有输出进行 HTML 转义（将 < 转换为 &lt; 等），如果不加 |safe，你的 HTML 标签会被原样输出而不是被浏览器解析。

  1. 按字符截取 HTML：truncatechars_html 使用示例：

    {{ item.Content|truncatechars_html:100|safe }}

    如果 item.Content 的内容是 <strong>这是一段加粗的文字，后面还有很多内容，可能会被截断。</strong><p>这是一个段落。</p> 那么上述代码可能会输出类似：“这是一段加粗的文字，后面还有很多内容，可能会被截断。…” 这样的结果，且 HTML 标签会正确闭合和渲染。

  2. 按单词截取 HTML：truncatewords_html 使用示例：

    {{ item.SummaryHtml|truncatewords_html:20|safe }}

    这个过滤器与 truncatechars_html 类似，只是截取的单位变成了单词，同时保持 HTML 结构的完整性。

实际应用场景

掌握了这些过滤器，你就可以在AnQiCMS模板中灵活运用，优化你的网站内容展示：

  • 文章列表页的摘要展示： 在首页、分类页或搜索结果页展示文章标题和一小段描述，使用 truncatechars 或 truncatechars_html 保持排版整齐。
  • 产品详情页面的简要介绍： 对于过长的产品特性或介绍，使用截取过滤器提供快速预览。
  • SEO的Meta Description控制： 即使内容编辑者写入了很长的描述，你也可以在模板层级通过这些过滤器确保 Meta Description 的长度符合搜索引擎的**实践。
  • 用户评论或留言的统一显示： 对用户提交的较长评论进行截取，点击后才显示完整内容，提升页面加载速度和美观度。

使用小贴士

  • 善用 |safe 过滤器： 当你确定输出的内容是经过AnQiCMS处理过，且不包含恶意代码时，对于包含HTML的文本，务必使用 |safe 以正确渲染。
  • 中英文截取效果差异： 对于中文内容，truncatewords 会将整个句子视为一个“单词”（除非有空格），因此通常 truncatechars 会更适合中文内容的按字数截取需求。英文内容则可根据实际情况选择。
  • 灵活调整截取长度： 通过反复测试不同长度的效果，找到最适合你网站设计和用户阅读习惯的截取长度。
  • 结合 if 语句使用： 你可以更智能地运用这些过滤器，例如，只有当内容实际超过预设长度时才进行截取并显示省略号，否则原样显示，这样可以避免不必要的省略号。 
    
{% set max_length = 100 %}
{% if item.Content|length > max_length %}
    {{ item.Content|truncatechars_html:max_length|safe }}
{% else %}
    {{ item.Content|safe }}
{% endif %}

掌握了 truncatechars、truncatewords 及其 HTML 变体，你就可以让你的AnQiCMS网站内容呈现更加专业和友好，无论是纯文本还是富媒体内容，都能以**姿态呈现在用户面前。

常见问题 (FAQ)

Q1: 为什么在截取包含 HTML 的内容时，我必须加上 |safe 过滤器？ A1: 这是因为 AnQiCMS 的模板引擎为了防止跨站脚本攻击（XSS）等安全问题，默认会对所有输出的变量内容进行 HTML 转义。这意味着它会将 < 转换成 &lt;，> 转换成 &gt; 等。如果你不加 |safe，HTML 标签本身也会被转义，导致它们无法被浏览器识别和渲染，而是作为普通文本显示在页面上。加上 |safe 过滤器是告诉模板引擎，这部分内容是安全的，不需要进行转义，可以直接按 HTML 格式输出。

Q2: truncatechars 和 truncatewords 在计算截取长度时，会把自动添加的省略号（...）计算在内吗？ A2: 是的，它们会把自动添加的省略号（...）的三个字符或一个“单词”单位计算在总的截取长度之内。例如，如果你使用 truncatechars:10，那么最终输出的文本（包括省略号）的总长度将是 10 个字符。

Q3: 如果我设置的截取长度比实际文本内容还长，过滤器会怎么处理？ A3: 如果你设置的截取长度大于或等于实际文本内容的长度，过滤器会直接输出完整的文本内容，而不会添加省略号。只有当文本内容实际超出你设定的长度时，过滤器才会进行截取并添加省略号。