在网站内容运营中，文章摘要或内容简介的展示长度往往需要精心控制。过长的内容会影响页面布局和用户体验，而精炼的摘要辅以省略号，则能有效引导用户点击阅读详情。AnQiCMS 提供了灵活的模板标签和过滤器，让我们可以轻松实现这一功能。

在 AnQiCMS 的模板中，我们经常会用到 archiveList 标签来循环展示文章列表，或者通过 archiveDetail 标签获取单篇文章的详细信息。无论是哪种情况，文章的摘要通常都存储在 Description 字段中。例如，在文章列表中，我们通过 {{item.Description}} 来获取每篇文章的摘要；在文章详情页，则是 {{archive.Description}}。现在，我们的目标就是对这些长字符串进行截取，并在末尾加上省略号。

AnQiCMS 的模板系统提供了非常便捷的过滤器来实现这一需求。其中，最核心的工具就是 truncatechars 过滤器。

使用 truncatechars 过滤器截取纯文本字符串

truncatechars 过滤器能够将一个字符串截取到您指定的长度，并在末尾自动添加省略号“…”。这个长度是包含省略号在内的总字符数。

它的使用方法非常直观：

{{ 变量 | truncatechars:长度 }}

例如，如果您想将文章摘要截取为 50 个字符：

<p>{{ item.Description | truncatechars:50 }}</p>

这样，如果 item.Description 的内容超过 50 个字符，它就会被截断，并在第 47 个字符后添加“…”，总长度为 50。如果内容本身就少于 50 个字符，truncatechars 则不会进行任何操作，原样输出。

处理包含 HTML 的长字符串：truncatechars_html

很多时候，文章的摘要可能不是纯文本，而是包含了 <strong>、<em>、<a> 等 HTML 标签的富文本内容。如果直接对包含 HTML 的字符串使用 truncatechars，可能会导致 HTML 标签被截断，从而破坏页面的结构或样式。

为了优雅地处理这种情况，AnQiCMS 提供了 truncatechars_html 过滤器。这个过滤器会智能地识别并保留 HTML 标签的完整性，在截取字符串的同时，确保最终输出的 HTML 仍然是有效的。

其使用方法与 truncatechars 类似：

{{ 变量 | truncatechars_html:长度 }}

例如：

<p>{{ item.Description | truncatechars_html:100 | safe }}</p>

在这里，| safe 过滤器也至关重要。truncatechars_html 会产生包含 HTML 标签的字符串，而 | safe 告诉 AnQiCMS 模板引擎这是一个安全的 HTML 片段，可以直接渲染，而无需进行 HTML 实体转义。这样，您才能确保截取后的 HTML 内容能够正确显示。

实战应用与**实践

将上述过滤器应用到您的模板中，能够灵活地控制内容展示。

1. 列表页文章摘要的截取

在网站的首页或分类列表页，经常需要显示多篇文章的简短摘要。

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <div class="article-card">
        <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
        {# 假设 item.Description 包含 HTML，并截取为 120 个字符 #}
        <p class="article-summary">{{ item.Description | truncatechars_html:120 | safe }}</p>
        <a href="{{ item.Link }}" class="read-more">阅读更多</a>
    </div>
    {% endfor %}
{% endarchiveList %}

2. 详情页顶部简述的截取

在某些文章详情页，您可能希望在文章主体内容之前，先展示一个简短的摘要。

{% archiveDetail archive with name="Description" %}
<div class="post-intro">
    {# 假设 archive.Description 可能包含简单HTML，并截取为 150 个字符 #}
    <p>{{ archive | truncatechars_html:150 | safe }}</p>
</div>
{% endarchiveDetail %}

{# 文章主体内容 #}
<div class="post-content">
    {% archiveDetail articleContent with name="Content" %}
    {{ articleContent | safe }}
    {% endarchiveDetail %}
</div>

3. 智能判断，避免不必要的省略号

有时候，文章摘要本身就很短，无需截取。为了避免即使内容很短也加上省略号，我们可以结合 length 过滤器和 if 标签进行条件判断。

{% set raw_summary = item.Description %}
{% if raw_summary|length > 80 %} {# 判断原始字符串长度是否超过 80 #}
    <p>{{ raw_summary | truncatechars_html:80 | safe }}</p>
{% else %}
    <p>{{ raw_summary | safe }}</p> {# 如果不长，则原样输出 #}
{% endif %}

这样的处理方式更加人性化，能够提升用户的阅读体验。

总结

通过 truncatechars 和 truncatechars_html 这两个强大的过滤器，AnQiCMS 模板在处理长字符串截取和省略号显示方面表现得非常灵活和高效。根据您内容的性质（纯文本或富文本），选择合适的过滤器，并结合 | safe 和条件判断，就能轻松实现多样化的内容展示需求，让您的网站界面更加整洁和专业。

常见问题 (FAQ)

  1. 问：truncatechars 和 truncatechars_html 过滤器有什么本质区别？ 答： truncatechars 过滤器主要用于截取纯文本字符串，它会简单地按字符数量进行截断，不考虑字符串中可能存在的 HTML 标签。如果您的内容包含 HTML，使用 truncatechars 可能会导致标签断裂，破坏页面结构。而 truncatechars_html 则专门设计用于处理含有 HTML 标签的字符串，它在截取时会智能地识别并尽量保持 HTML 标签的完整性，确保输出的 HTML 仍然是有效的，从而避免页面显示异常。

  2. 问：截取长度时，省略号“…”是否计算在内？ 答： 是的，您在 truncatechars 或 truncatechars_html 过滤器中设置的长度（例如 truncatechars:50 中的 50）是包含自动添加的省略号“…”在内的总字符数。这意味着，如果您设置长度为 50，实际显示的内容字符数将是 47 个，再加上 3 个省略号。

  3. 问：我正在运营一个多语言网站，英文内容使用 truncatechars 截取时，单词经常被切断，有什么更好的方法吗？ 答： 对于英文等以单词为基本单位的语言内容，AnQiCMS 提供了 truncatewords 和 truncatewords_html 过滤器。它们的工作方式与 truncatechars 和 truncatechars_html 类似，但不是按字符数截断，而是按单词数量截断，这样可以避免将一个单词从中间切断，使阅读体验更自然。中文内容由于没有明显的单词分隔，通常使用 truncatechars 系列过滤器更合适。