在AnQiCMS的模板开发中，我们常常需要对文章标题或描述进行长度控制，以便在列表页、卡片布局或其他紧凑的展示区域保持页面整洁和统一的视觉效果。同时，当内容被截断时，习惯性地加上省略号，能够友好地提示读者此处还有更多内容。AnQiCMS强大的模板引擎内置了丰富的过滤器（Filters），让这项任务变得异常简单和高效。

理解内容截取的需求

无论是文章列表、推荐位还是SEO元描述，内容的长度限制都是前端展示中的常见挑战。过长的标题或描述会破坏页面布局，影响美观；而简短统一的展示则能提升用户体验，让页面看起来更专业。因此，灵活地截取文章标题（Title）或描述（Description）并自动添加省略号，是模板开发中不可或缺的技巧。

核心工具：truncatechars 过滤器

AnQiCMS的模板引擎提供了truncatechars过滤器，这是实现标题和描述截取并添加省略号最直接、最常用的方法。它的作用是根据您指定的字符长度来截断字符串，如果原始字符串的长度超过这个限制，它会在末尾自动添加省略号（...）。

使用方法非常直观，您只需要在需要处理的变量后面，通过管道符 | 调用 truncatechars，并传入您希望保留的字符长度即可。

例如，如果您想将文章标题截取到25个字符： {{ item.Title | truncatechars:25 }}

假设item.Title的原文是“AnQiCMS模板内容截取指南：告别冗长，精准呈现文章标题与描述”，那么经过truncatechars:25处理后，输出可能会是：“AnQiCMS模板内容截取指南：告别冗长，精…”

需要特别注意的是，truncatechars过滤器在计算长度时，是按照UTF-8字符进行计数的。这意味着，即使是中文字符，一个汉字也算作一个字符进行计算，这对于中文网站的排版控制非常友好和精准。

处理包含 HTML 的内容：truncatechars_html

在某些情况下，文章描述（Description）可能包含少量的HTML标签，例如粗体、链接等。如果直接使用truncatechars截取，可能会导致HTML标签被截断，从而破坏页面的结构或样式。

针对这种情况，AnQiCMS提供了truncatechars_html过滤器。它与truncatechars的功能类似，但会智能地识别并保留HTML标签的完整性，避免因截断而产生的HTML结构错误，并在适当的位置添加省略号。

在使用truncatechars_html时，通常建议搭配|safe过滤器，以确保被截断并处理过的HTML内容能够被浏览器正确解析，而不是作为纯文本输出。

例如，如果您需要截取包含HTML的文章描述到80个字符，并确保HTML结构不会被破坏： {{ item.Description | truncatechars_html:80 | safe }}

另一种选择：按词截取 truncatewords 与 truncatewords_html

除了按字符截取，AnQiCMS还提供了按单词截取的过滤器：truncatewords和truncatewords_html。这些过滤器特别适合英文内容，因为它们会尝试在单词边界处进行截断，以保持文本的语义完整性，避免截断一个单词的中间部分。

使用方式与truncatechars系列类似，只是传入的是您希望保留的单词数量：

  • 按单词截取纯文本：{{ item.Title | truncatewords:10 }}
  • 按单词截取HTML内容：{{ item.Description | truncatewords_html:20 | safe }}

实际应用场景与代码示例

在文章列表页中，您通常会循环展示多篇文章，这时就可以在循环体内灵活运用这些过滤器：

{# 假设这是文章列表的循环体 #}
{% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <div class="article-card">
        <a href="{{item.Link}}">
            {# 截取标题到25个字符，并添加省略号 #}
            <h3 class="article-title">{{ item.Title | truncatechars:25 }}</h3>

            {# 截取描述到60个字符，如果包含HTML则智能处理，并添加省略号 #}
            <p class="article-description">{{ item.Description | truncatechars_html:60 | safe }}</p>

            <span class="read-more">阅读更多</span>
        </a>
    </div>
    {% empty %}
    <p>暂时没有文章内容。</p>
    {% endfor %}
{% endarchiveList %}

这段代码中，h3标签内的文章标题会被截取到25个字符，如果超出则显示省略号。p标签内的文章描述则会被截取到60个字符，并且即便描述内容中包含HTML标签，truncatechars_html也会尽量保证这些标签的完整性，避免页面显示异常。最后的|safe过滤器，则是确保浏览器能正确渲染这些可能包含HTML的文本。

总结

AnQiCMS的模板过滤器为网站内容运营者提供了极大的便利。通过简单地应用truncatechars和truncatechars_html等过滤器，您就能轻松实现文章标题和描述的长度控制，不仅优化了前端展示的视觉效果，也提升了用户阅读体验。灵活运用这些工具，将使您的网站内容管理更加高效和美观。

常见问题 (FAQ)

1. 为什么在截取包含HTML的内容时，通常要同时使用truncatechars_html和|safe过滤器？

truncatechars_html过滤器能够智能地截取包含HTML标签的字符串，避免标签被破坏。然而，AnQiCMS的模板引擎默认会对所有输出内容进行HTML转义，以防止XSS攻击。如果您截取的内容本身就带有HTML标签（例如<p>、<strong>），并且希望这些标签能够被浏览器正常解析而不是显示为纯文本，那么在truncatechars_html之后，还需要加上|safe过滤器来明确告诉模板引擎这些内容是安全的，不需要进行转义。

2. 如果我设定的截取长度比实际的标题或描述还要长，会发生什么？

如果设定的截取长度（例如truncatechars:50）大于或等于原始字符串的实际长度，那么truncatechars（或truncatechars_html）过滤器将不会对内容进行截断，也不会添加省略号。它会直接输出原始的完整内容。

3. truncatechars和truncatewords过滤器有什么区别？在什么情况下应该使用它们？

truncatechars是按字符来截取内容，不论是英文字母、数字还是中文字符，都算作一个字符。它在达到指定长度时直接截断，可能会截断单词的中间。而truncatewords则是按单词来截取内容，它会尝试在单词的边界处进行截断，以保持每个单词的完整性。

通常情况下：

  • 如果您的内容以中文为主，或者对字符数量有严格的像素级布局要求，truncatechars是更精确的选择。
  • 如果您的内容以英文为主，并且希望在截断时保持单词的完整性，truncatewords会提供更好的阅读体验。相应的HTML版本truncatechars_html和truncatewords_html则用于处理含有HTML标签的内容。