在网站内容运营中，我们经常需要在列表页、摘要区域或特定版块显示文章、产品或单页面的部分内容。这些内容往往是包含 HTML 标签的富文本，如果简单地按字符数进行截取，很可能会导致 HTML 标签被截断，从而破坏页面的布局和显示效果。例如，一个 <p>这是一个段落<strong id="test">中的加粗</str...</p> 这样的内容如果被粗暴截断，可能会导致页面出现未闭合的 <strong> 标签，影响后续内容的渲染。

为了解决这一难题，安企CMS（AnQiCMS）的模板引擎提供了一个名为 truncatechars_html 的强大过滤器，它能够安全地截取包含 HTML 标签的富文本内容，并智能地闭合所有未完成的标签，确保页面结构的完整性。

安企CMS 中的 HTML 内容来源

在安企CMS中，富文本内容主要来源于以下几个核心字段：

  • 文档内容 (Archive.Content)：通过 archiveDetail 标签获取，这是文章或产品详情页的主体内容。
  • 分类内容 (Category.Content)：通过 categoryDetail 标签获取，用于展示分类的详细介绍。
  • 单页面内容 (Page.Content)：通过 pageDetail 标签获取，例如“关于我们”、“联系方式”等独立页面。

这些字段通常由后台的富文本编辑器生成，包含了各种 HTML 标签（如 <p>, <strong>, <a>, <img> 等），因此在截取时需要特别小心。

认识 truncatechars_html 过滤器

truncatechars_html 过滤器专门设计用于处理含有 HTML 标签的字符串。它的核心优势在于，当你在指定长度内截取文本时，它会自动检测并闭合所有被截断的 HTML 标签。这意味着你无需担心截取操作会导致页面元素错乱，或者因为标签未闭合而引发浏览器解析错误。

与简单的字符串截取过滤器（如 truncatechars）不同，truncatechars_html 过滤器能够“理解”HTML 结构。例如，一个包含 <b>Bold text</b> 的字符串如果被截取在 <b> 标签内部，它会确保最终输出的 HTML 仍然是有效的，例如 <b>Bold...</b>，而不是留下一个开放的 <b> 标签。被截取的内容末尾通常会添加一个省略号（…）以提示用户内容已被省略。

如何安全地使用 truncatechars_html

使用 truncatechars_html 过滤器非常直观，但需要注意一个重要的配合操作：

{{ 你的HTML内容变量|truncatechars_html:截取长度|safe }}

让我们以一个实际场景为例，假设你需要在文章列表页显示每篇文章的简短摘要，这个摘要是从文章的完整内容 (archive.Content) 中截取出来的：

{% archiveList articles with type="page" limit="10" %}
    {% for article in articles %}
    <div class="article-item">
        <h3><a href="{{ article.Link }}">{{ article.Title }}</a></h3>
        <div class="article-summary">
            {# 假设 article.Content 包含 HTML 标签 #}
            {%- archiveDetail articleContent with name="Content" id=article.Id %}
            {{ articleContent|truncatechars_html:120|safe }}
            {%- endarchiveDetail %}
            <a href="{{ article.Link }}" class="read-more">阅读更多 &gt;</a>
        </div>
    </div>
    {% endfor %}
{% endarchiveList %}

在上面的代码中：

  1. articleContent 变量存储了文章的完整 HTML 富文本内容。
  2. truncatechars_html:120 会将 articleContent 截取到大约 120 个字符（包括 HTML 标签和省略号），并自动闭合任何被截断的标签。
  3. |safe 过滤器是至关重要的一步。安企CMS的模板引擎出于安全考虑，默认会对所有输出内容进行 HTML 实体转义。这意味着，如果你不加 |safe，即使 truncatechars_html 生成了正确的 HTML，这些 HTML 标签也会被转义成 &lt;p&gt;、&lt;strong&gt; 等，直接显示在页面上，而不是被浏览器渲染成相应的样式。因此，在 truncatechars_html 之后添加 |safe 是必不可少的，它告诉模板引擎这部分内容是安全的 HTML，可以直接输出。

实用场景与进阶考量

  • 列表页摘要： 这是最常见的应用，例如在博客文章列表、产品目录页等显示内容的概览。通过控制 截取长度，可以很好地适应不同的页面布局和设计需求。
  • 字数统计优化： 截取长度应根据实际需求和设计稿确定。过长会失去摘要的意义，过短可能会让内容显得过于零碎。
  • truncatewords_html 过滤器： 如果你更希望按单词数量而不是字符数量进行截取，并同样保持 HTML 结构的完整性，可以使用 truncatewords_html 过滤器。例如 {{ articleContent|truncatewords_html:30|safe }} 将会截取大约 30 个单词。选择哪一个取决于你的具体内容和语言习惯。
  • 调试与检查： 如果截取后的内容显示不如预期，可以尝试使用 dump 过滤器来查看 truncatechars_html 过滤前和过滤后的变量内容和类型，这有助于你定位问题。例如 {{ articleContent|dump }} 可以打印出原始内容，帮助检查是否存在格式问题。
  • 默认省略号： 默认情况下，截取后会添加 ... 作为省略符。如果希望定制，安企CMS的文档中虽然未明确说明可以直接修改此省略符，但通常这在多数Django-like模板引擎中是固定行为。

通过巧妙运用 truncatechars_html 过滤器，你可以在安企CMS模板中轻松实现富文本内容的安全截取，既能保证页面的美观，又能维护 HTML 结构的完整性，从而为用户提供更优质的浏览体验。

常见问题 (FAQ)

1. 为什么我使用了 truncatechars_html 过滤器后，页面上显示的是 <p>内容...</p> 这样的 HTML 标签文本，而不是格式化的内容？

这是因为你可能忘记在 truncatechars_html 过滤器之后添加 |safe 过滤器。安企CMS的模板引擎为了防止潜在的安全风险（如XSS攻击），默认会对所有输出内容中的 HTML 标签进行转义。|safe 过滤器明确告诉模板引擎，这部分内容是经过安全处理的 HTML，可以直接作为 HTML 渲染，而无需转义。

2. truncatechars_html 和 truncatewords_html 过滤器有什么区别？我应该选择哪一个？

它们的主要区别在于截取的单位：

  • truncatechars_html: 按字符数量截取。它会从文本开头计算指定数量的字符，并在达到限制时截断。
  • truncatewords_html: 按单词数量截取。它会识别文本中的单词，并截取指定数量的单词。

选择哪个取决于你的内容类型和显示需求。如果你的内容是中文，通常按字符截取（truncatechars_html）更常用；如果是英文内容，按单词截取（truncatewords_html）可能更容易保持语意的完整性，因为英文单词之间有自然空格。

3. 截取后的内容总是以“…”结尾，我能改变这个省略符吗？

根据安企CMS当前的文档，truncatechars_html 和 truncatewords_html 过滤器默认使用的省略符是固定的“…”，且未提供直接修改该符号的参数。如果你需要不同的省略符，可能需要在截取后通过其他字符串替换的方式进行处理，但这会增加操作的复杂性，并可能影响 HTML 标签闭合的安全性，通常不建议这样做。在大多数情况下，默认的省略符已经能够很好地传达内容被截取的信息。