AnQiCMS 模板中，如何截取文章摘要并添加省略号显示？

在网站运营中，如何让文章列表页既美观又信息量充足，是大家普遍关心的问题。通常，我们不会在列表页展示文章的完整内容，而是通过一小段“摘要”来吸引读者点击。为了保持页面的整洁和专业，这些摘要往往还需要在超出一定长度时自动截断，并添加一个优雅的省略号。

AnQiCMS 作为一款功能强大的内容管理系统，在模板中提供了灵活的工具来帮助我们实现这一需求。下面，我们就来详细探讨如何在 AnQiCMS 模板中截取文章摘要并显示省略号。

摘要内容的来源：Description 字段优先，Content 字段次之

在 AnQiCMS 中，每篇文章都有两个重要的内容字段可以作为摘要的来源：

  1. Description (文档简介)：这是最理想的摘要来源。在后台发布文章时，通常会有一个“文档简介”的输入框，您可以手动填写一段精炼的文字作为文章的概括。AnQiCMS 官方文档也建议将文档简介控制在 150 字以内。如果您没有手动填写，系统会自动从 Content 字段中提取前 150 字作为默认简介。这个字段通常是纯文本，或只包含少量简单 HTML 标签。

  2. Content (文档内容)：这是文章的完整内容，可能包含丰富的图文、视频和各种 HTML 结构。当 Description 字段为空时，我们可以从 Content 字段中截取一部分作为摘要。但由于 Content 字段是富文本，直接截取可能会破坏 HTML 结构，导致页面显示异常，因此需要特别处理。

了解了这两个来源后，我们的策略就是优先使用 Description 字段，当其为空时，再从 Content 字段中智能截取。

截取纯文本摘要：truncatechars 过滤器

当您确定 Description 字段是纯文本时，可以使用 truncatechars 过滤器来按字符数量截取内容并自动添加省略号。

使用方法： 在文章循环（通常是 archiveList 标签内的 for 循环）中，您可以这样调用：

{{ item.Description|truncatechars:长度 }}

其中，长度 是您希望摘要显示的字符总数，这个长度会包含最后的省略号（“…”）所占的字符。

示例： 如果您希望摘要显示最多 100 个字符：

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

如果 item.Description 的内容是“这是一篇关于 AnQiCMS 模板制作的文章，内容非常详尽，希望能帮助到大家。这只是一个测试摘要，看看截取效果如何。”，并且实际长度超过 100 字符，它就会被截断成类似“这是一篇关于 AnQiCMS 模板制作的文章，内容非常详尽，希望能帮助到大家。这只是一个测试摘要，看看截取效果…”这样的形式。

处理包含 HTML 的摘要：truncatechars_html 过滤器

当您的摘要内容来自 Content 字段（它是富文本），或者 Description 字段可能包含 HTML 标签时，直接使用 truncatechars 可能会截断未闭合的 HTML 标签，导致页面布局混乱。这时，truncatechars_html 过滤器就派上用场了。它能智能地截取 HTML 内容，同时确保所有标签都被正确关闭，从而维护页面的结构完整性。

使用方法：

{{ item.Content|truncatechars_html:长度|safe }}

这里有两点需要注意：

  1. truncatechars_html:长度：这个过滤器会按照指定的字符长度截取 HTML 内容，并智能地闭合所有打开的 HTML 标签。
  2. |safe：这是至关重要的一步！AnQiCMS 的模板引擎默认会对所有输出内容进行 HTML 转义，以防止 XSS 攻击。这意味着，如果您不加 |safe，截取后的 HTML 标签（如 <p>, <strong>）将作为纯文本显示，而不是被浏览器解析。加上 |safe 后，模板引擎会认为这些内容是安全的，从而按 HTML 格式正常渲染。

示例： 如果您希望从 Content 中截取最多 150 个字符作为摘要：

<div>{{ item.Content|truncatechars_html:150|safe }}</div>

即使 item.Content 是一个复杂的 HTML 片段，truncatechars_html 也会在截取时小心翼翼，确保如 <p>...</p>、<strong>...</strong> 等标签的完整性，并正确添加省略号。

按单词截取：truncatewords 和 truncatewords_html 过滤器（可选）

除了按字符截取，AnQiCMS 也提供了按单词截取摘要的过滤器，这对于英文或其他以空格分隔单词的语言特别有用，可以避免截断一个单词的中间部分，让摘要阅读起来更自然。

  • truncatewords：用于纯文本内容，按单词数量截取。 {{ item.Description|truncatewords:20 }} (截取 20 个单词)
  • truncatewords_html：用于包含 HTML 的内容，按单词数量截取并保持 HTML 结构。 {{ item.Content|truncatewords_html:25|safe }} (截取 25 个单词，并安全渲染 HTML)

实战应用：构建一个智能摘要显示逻辑

为了达到**效果，我们通常会结合使用上述方法，构建一个智能的摘要显示逻辑：优先显示 Description 字段，如果 Description 为空，则从 Content 字段截取并安全渲染，最后再加入一个默认文本作为最终的备选。

以下是一个完整的模板代码片段，展示了如何在 archiveList 循环中实现这一逻辑：

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <article class="article-item">
        <a href="{{ item.Link }}" class="article-thumb">
            {# 优先显示文章缩略图，如果没有则显示默认图 #}
            {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}">
            {% else %}
                <img src="/public/static/images/default-thumb.png" alt="默认图片">
            {% endif %}
        </a>
        <div class="article-info">
            <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
            <div class="article-meta">
                <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                <span>阅读量：{{ item.Views }}</span>
            </div>
            <p class="article-summary">
                {% if item.Description %}
                    {# 优先使用 Description 字段，并截取为 120 字符 #}
                    {{ item.Description|truncatechars:120 }}
                {% else %}
                    {# 如果 Description 为空，则从 Content 截取 150 字符并确保 HTML 安全 #}
                    {{ item.Content|truncatechars_html:150|safe|default:"暂无内容" }}
                {% endif %}
            </p>
            <a href="{{ item.Link }}" class="read-more">阅读更多 &raquo;</a>
        </div>
    </article>
    {% empty %}
    <p>抱歉，目前没有可供展示的文章。</p>
    {% endfor %}
{% endarchiveList %}

在这段代码中：

  • 我们首先检查 item.Description 是否有内容。如果有，就使用 truncatechars 截取它。
  • 如果 item.Description 为空，我们就转而使用 item.Content，通过 truncatechars_html 进行 HTML 安全截取，并加上 |safe 过滤器确保内容被正确解析。
  • 最后，|default:"暂无内容" 作为一个兜底，确保即使 Content 截取后仍然为空（比如文章内容太短或根本没有内容），也能显示一个友好的提示。

通过上述方法，您可以灵活地在 AnQiCMS 模板中截取文章摘要，并以美观、安全的方式在列表页展示出来，大大提升用户浏览体验。

常见问题 (FAQ)

Q1：截取长度是否包含省略号的字符数？ A1：是的，当您使用 truncatechars 或 truncatechars_html 过滤器时，您设定的长度会包含最后自动添加的省略号（“…”）所占的字符。例如，如果您设置截取长度为 100，最终显示的摘要（包含省略号）的字符总数就是 100。

Q2：为什么截取 HTML 内容时需要 |safe 过滤器？ A2