在 AnQiCMS 模板中，如何优雅地截取文章内容并显示“…”？

在网站内容运营中，我们经常需要在列表页、聚合页或搜索结果中展示文章、产品或单页内容的摘要。这些摘要不仅能让页面看起来更整洁，还能帮助访客快速了解内容梗概，从而决定是否点击阅读全文。然而，直接显示完整内容显然是不切实际的，这就引出了一个常见需求：如何对文章内容进行字数截取，并在末尾加上“…”来提示读者内容尚未结束？

AnQiCMS 凭借其基于 Go 语言的高性能架构和灵活的模板引擎，为内容展示提供了丰富的可能性。我们的模板系统支持类似 Django 语法的标签和过滤器，使得内容处理变得直观而高效。要实现文章内容的字数截取并显示“…”，我们主要会用到模板中的“过滤器”功能。

核心工具：内容截取过滤器

AnQiCMS 模板内置了多种强大的过滤器，其中专门用于内容截取的主要有以下几种：

  1. truncatechars (按字符截取)： 这个过滤器会按照您指定的字符数量来截取字符串。它非常适合需要精确控制长度的场景。但需要注意的是，truncatechars 是“无情”的，它可能会在一个词的中间截断，甚至可能破坏 HTML 标签结构，导致显示异常。

  2. truncatewords (按单词截取)： 如果您更关注内容的完整性，不希望在单词中间截断，那么 truncatewords 是更好的选择。它会按单词进行截取，确保每个词都是完整的，但最终的字符长度可能会略有浮动。

当您处理的内容是纯文本（例如文章标题、简介等）时，直接使用 truncatechars 或 truncatewords 即可。这些过滤器会自动在截取后的文本末尾添加“…”以示省略。

截取纯文本内容的示例：

假设您想在列表页显示文章的标题和简介，并希望标题最多显示 30 个字符，简介最多显示 50 个词。您可以这样编写模板代码：

<div class="article-item">
    <h3><a href="{{ article.Link }}">{{ article.Title|truncatechars:30 }}</a></h3>
    <p>{{ article.Description|truncatewords:50 }}</p>
    <a href="{{ article.Link }}" class="read-more">阅读更多</a>
</div>

在这个例子中：

  • {{ article.Title|truncatechars:30 }} 会将文章标题截取到最多 30 个字符，并在后面加上“…”。
  • {{ article.Description|truncatewords:50 }} 会将文章简介截取到最多 50 个单词，并在后面加上“…”。

处理富文本（HTML）内容时的截取

在实际操作中，文章内容往往是富文本形式，包含图片、链接、加粗等 HTML 标签。如果直接对 archive.Content 这样的字段使用 truncatechars 或 truncatewords，很可能会导致 HTML 标签被不完整地截断，从而破坏页面的布局和样式，甚至引发浏览器解析错误。

为了解决这个问题，AnQiCMS 提供了专门的 HTML 安全截取过滤器：

  1. truncatechars_html (按字符安全截取 HTML)： 它与 truncatechars 类似，但具有 HTML 智能识别能力，能够确保 HTML 标签在截取后依然保持完整和闭合。这意味着它会正确处理开放的标签，避免出现 <div><b>文章内... 这样的情况。

  2. truncatewords_html (按单词安全截取 HTML)： 同理，它与 truncatewords 类似，但同样具备 HTML 安全处理能力，确保按单词截取时，HTML 结构不会被破坏。

特别提示： 当使用 truncatechars_html 或 truncatewords_html 处理 HTML 内容时，务必在截取过滤器之后加上 |safe 过滤器。|safe 的作用是告诉模板引擎，这段内容是安全的 HTML，不需要进行二次转义，这样浏览器才能正确解析和渲染。

截取 HTML 内容的示例：

假设您想在文章列表中显示文章内容的简要预览，并希望保留 HTML 格式：

<div class="article-preview">
    <h4><a href="{{ archive.Link }}">{{ archive.Title }}</a></h4>
    <div class="content-summary">
        {# 截取文章内容前150个字符，并确保HTML结构完整 #}
        {{ archive.Content|truncatechars_html:150|safe }}
    </div>
    <a href="{{ archive.Link }}" class="view-detail">查看详情</a>
</div>

在这个例子中：

  • {{ archive.Content|truncatechars_html:150|safe }} 会将 archive.Content （假设为文章详情的富文本内容）截取到最多 150 个字符。
  • truncatechars_html 会智能处理其中的 HTML 标签，例如，如果截取到一半，它会自动闭合所有未闭合的标签，避免页面混乱。
  • 最后的 |safe 确保浏览器能够将截取后的 HTML 代码正确渲染出来，而不是将其作为纯文本显示。

如果您更喜欢按单词截取 HTML 内容：

<div class="product-teaser">
    <h5><a href="{{ product.Link }}">{{ product.Title }}</a></h5>
    <div class="description-teaser">
        {# 截取产品描述前30个单词，并确保HTML结构完整 #}
        {{ product.Description|truncatewords_html:30|safe }}
    </div>
    <a href="{{ product.Link }}" class="learn-more">了解更多</a>
</div>

一些实用建议

  1. 选择合适的截取方式：对于标题、简短描述等纯文本，truncatechars 或 truncatewords 足够。对于 archive.Content 或 page.Content 这类富文本字段，务必使用 _html 结尾的过滤器，并结合 |safe。
  2. 设定合理的长度：截取长度应根据您网站的布局和设计风格来决定。在响应式设计中，过长的摘要可能会在小屏幕上显得冗余，而过短又可能无法提供足够的信息。建议在不同设备上预览效果。
  3. 结合条件判断：有时文章可能没有简介，或者内容很短，截取反而显得多余。您可以结合 {% if ... %} 判断来优化显示： 
    
{% if archive.Description|length > 0 %}
    <p>{{ archive.Description|truncatewords:50 }}</p>
{% elif archive.Content|length > 0 %}
    <p>{{ archive.Content|striptags|truncatewords:50 }}</p> {# 先剥离HTML标签，再截取纯文本 #}
{% else %}
    <p>暂无内容摘要。</p>
{% endif %}
    这里 |striptags 过滤器可以先将 HTML 内容中的所有标签剥离，只剩下纯文本，这样就可以用 truncatewords 进行纯文本截取了。

通过灵活运用 AnQiCMS 提供的这些内容截取过滤器，您可以轻松打造出既美观又实用的内容展示效果，极大地提升网站的用户体验和内容的可读性。

常见问题 (FAQ)

1. 截取后的“…”符号可以自定义成其他文字吗？例如“【查看更多】”？

AnQiCMS 内置的 truncatechars、truncatewords 及其 HTML 安全版本过滤器，默认会在截取内容后统一添加“…”。目前，这些过滤器本身不提供直接自定义这个省略符号的参数。如果您有特殊的需求，例如显示“【查看更多】”，可能需要通过更复杂的模板逻辑（如先判断内容是否超出长度，然后手动拼接字符串）来实现，但这会增加模板的复杂度。通常情况下，我们建议直接使用默认的“…”符号，以保持简洁和一致性。

2. 为什么我对 HTML 内容使用了 truncatechars_html 截取后，前端页面显示还是出现乱码或者布局错乱？

这很可能是因为您忘记在 truncatechars_html 过滤器之后，紧接着使用 |safe 过滤器。truncatechars_html 虽然会智能闭合 HTML 标签，但它输出的仍然是一个字符串。如果没有 |safe 过滤器告诉 AnQiCMS 模板引擎这是一个安全的 HTML 片段，引擎会将其作为普通文本进行转义，导致所有 HTML 标签被显示为 &lt;p&gt;、&lt;img&gt; 等实体字符，从而出现乱码或布局问题。请确保您的代码类似于