在网站内容管理和展示中，我们经常需要在文章列表、首页摘要或相关推荐区域显示文章的部分内容，以吸引读者点击。然而，直接对包含 HTML 标签的文章内容进行字符或字数截取，很容易破坏其原有的 HTML 结构，导致页面显示错乱，甚至影响整体布局和用户体验。
安企CMS（AnQiCMS）深知这一痛点，其强大的模板引擎和内置过滤器提供了优雅且安全的解决方案，让您无需担心因内容截取而带来的显示问题。接下来，我们将探讨如何在安企CMS中安全地截取包含 HTML 标签的文章内容。
为什么常规截取方式会破坏 HTML 结构？
想象一下，一篇文章的内容可能是这样的：
<p>这是一段包含<strong>重要信息</strong>的文字。</p>
<div class="image-box">
<img src="/path/to/image.jpg" alt="图片描述">
</div>
<p>更多精彩内容。</p>
如果您仅仅通过字符串截取功能，例如限制显示前 50 个字符，而这 50 个字符恰好在 <strong> 标签内部被截断，或者在 <div class="image-box"> 标签之后但在其闭合标签 </div> 之前，那么最终页面上呈现的代码可能就会是 <p>这是一段包含<strong>重要信 或者 <div class="image-box">。这样的不完整 HTML 代码会导致浏览器无法正确渲染，轻则样式丢失，重则页面布局混乱，甚至影响其他元素的正常显示。
安企CMS 的解决方案：HTML 安全截取过滤器
安企CMS 采用类似 Django 的模板引擎语法，提供了丰富的过滤器（Filters）来处理内容。针对 HTML 内容的安全截取，系统内置了 truncatechars_html 和 truncatewords_html 这两个非常实用的过滤器。它们的核心优势在于，在截取内容时能够智能地识别并闭合未完成的 HTML 标签，从而保证输出内容的结构完整性。
1. 按字符数安全截取：truncatechars_html
如果您需要更精确地控制截取长度，例如要求摘要必须在 100 个字符以内，即使这会截断某个单词，truncatechars_html 就是您的理想选择。它会按照您指定的字符数进行截取，同时确保所有在截取点被“打开”的 HTML 标签都能被正确地闭合。
使用示例：
假设您的文章内容存储在 item.Content 变量中，您想截取前 120 个字符作为摘要。
{{ item.Content|truncatechars_html:120|safe }}
这里的 120 就是您希望截取的字符数。|safe 过滤器在这里至关重要，它告诉模板引擎，输出的内容是安全的 HTML，不应进行自动转义，从而让浏览器能够正常解析截取后的 HTML 结构。
2. 按单词数安全截取：truncatewords_html
相比之下，如果您的内容更注重语义完整性，希望避免截断单词，即使这样会导致实际字符数略有浮动，那么 truncatewords_html 会是更好的选择。它会按照您指定的单词数进行截取，同样会智能地处理 HTML 标签的闭合问题。
使用示例： 如果您希望文章摘要显示大约 30 个单词。
{{ item.Content|truncatewords_html:30|safe }}
这里的 30 就是您希望截取的单词数。同样地，|safe 过滤器是不可或缺的。
实际操作示例
在安企CMS的模板中，您通常会在循环展示文章列表（例如使用 archiveList 标签）时用到这些截取功能。一个典型的场景是，如果文章有独立的“简介/摘要”字段（例如 item.Description），我们优先使用它；如果文章没有填写简介，就从文章正文 item.Content 中安全截取一部分。
{# 假设我们正在循环输出一个文章列表 #}
{% archiveList archives with type="list" limit="10" %}
{% for item in archives %}
<article class="article-item">
<h2><a href="{{item.Link}}">{{item.Title}}</a></h2>
<div class="article-meta">
<span>发布日期: {{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
<span>分类: <a href="{% categoryDetail with name='Link' id=item.CategoryId %}">{% categoryDetail with name='Title' id=item.CategoryId %}</a></span>
</div>
<div class="article-summary">
{# 优先使用文章的简介字段，如果为空，则从内容中安全截取前180个字符 #}
<p>{{ item.Description|default:item.Content|truncatechars_html:180|safe }}</p>
</div>
<a href="{{item.Link}}" class class="read-more">阅读全文 >></a>
</article>
{% endfor %}
{% endarchiveList %}
在这个例子中，item.Description|default:item.Content 的意思是：如果 item.Description 有值，则使用它；否则，使用 item.Content。然后，无论是简介还是正文，都通过 truncatechars_html:180|safe 过滤器进行安全截取和输出。这样既保证了内容的灵活配置，又兼顾了页面结构的稳定性。
注意事项
|safe过滤器不可省略： 这是最为关键的一点。truncatechars_html和truncatewords_html过滤器处理后的内容仍然是带有 HTML 标签的字符串。为了让浏览器正确解析这些标签而不是将其作为纯文本显示，必须在输出时添加|safe过滤器。否则，您可能会看到原始的 HTML 标签，如<p>。- 优先使用独立摘要字段： 在内容运营实践中，最好的做法是在发布文章时就填写独立的摘要或简介字段 (
item.Description)。这样既能保证摘要的精准性和吸引力，又能减轻模板引擎在每次页面加载时进行 HTML 解析截取的负担。当没有独立摘要时，再使用truncate_html系列过滤器作为备用方案。 - 截取长度的考量： 根据您网站的设计和页面布局，合理设置字符或单词截取长度。过短可能无法传达足够信息，过长则失去摘要的意义。
借助安企CMS提供的强大模板过滤器，您可以轻松实现包含 HTML 标签的文章内容的安全截取，既能优化页面显示，提升用户体验，又能有效管理您的网站内容，让网站运营更加高效。
常见问题 (FAQ)
Q1: truncatechars_html 和 truncatechars 有什么本质区别？
A1: truncatechars_html 和 truncatechars 都用于按字符数截取字符串，但它们处理 HTML 内容的方式完全不同。truncatechars 是纯粹的字符串截取，不关心内容中是否包含 HTML 标签，如果截取点恰好在一个标签内部，就会破坏 HTML 结构。而 truncatechars_html 则是 HTML 感知的，它会在截取后智能地闭合所有未完成的 HTML 标签，从而保证截取后内容的 HTML 结构是完整的和有效的。因此，处理包含 HTML 的文章内容时，务必使用 truncatechars_html。
Q2: 为什么在使用了 truncatechars_html 之后，内容还是没有正确显示，反而把 HTML 标签也显示出来了？
A2: 这通常是因为您忘记在输出截取后的内容时添加 |safe 过滤器。安企CMS（以及大多数现代模板引擎）为了安全起见，默认会对所有输出内容进行 HTML 转义，以防止 XSS 攻击。当 truncatechars_html 处理完内容后，输出的仍然是包含 HTML 标签的字符串。如果您不加 |safe，这些标签（如 <p>）会被转义成 <p>，从而以纯文本形式显示在页面上。加上 |safe 后，会告诉模板引擎这些内容是安全的 HTML，可以直接输出而不进行转义。
Q3: 我可以直接在安企CMS后台设置全局的文章摘要截取长度吗？
A3: 安企CMS 提供内容模型的自定义字段功能，鼓励您为文章单独设置一个“简介”或“摘要”字段，并在发布时手动填写。这样可以最大限度地控制摘要质量。如果您未设置单独摘要字段，且需要从文章正文自动截取，安企CMS 更多是倡导通过模板层面使用 truncatechars_html 或 truncatewords_html 过滤器来灵活控制截取长度。这意味着您需要在模板文件中根据不同区域（如首页、分类页、搜索结果页）的需求，自行设定并应用截取逻辑，而不是通过后台全局统一设置。这种方式提供了更大的灵活性和定制空间。