在内容管理中，为了保持网站页面的整洁和加载效率，我们经常需要对文章、产品描述或其他长文本内容进行截断，只显示部分摘要。然而，如果内容本身包含 HTML 标签，简单的字符截断往往会破坏这些标签的结构，导致页面显示混乱，甚至影响网站的布局和功能。例如，一个 <p>这是一个<b>重要</b>的段落</p> 的内容，如果被简单截断为 <p>这是一个<b>重要</b，就会留下未闭合的标签，从而打乱其后的所有 HTML 结构。
AnQiCMS 深知这一痛点，在内容处理上提供了专门的解决方案，确保在截断 HTML 文本时能够智能地识别并闭合标签，从而优雅地呈现内容摘要，同时维护页面结构的完整性。
了解 HTML 截断的挑战
传统的文本截断方式，通常是按字符或按词语进行。当遇到 <p>Lorem <b>ipsum</b> dolor</p> 这样的 HTML 片段，如果截断点恰好落在 <p>Lo 后面或 <b>ips 后面，就会导致 <b> 或 <p> 标签未闭合。这不仅让页面看起来不专业，还可能引发各种前端渲染问题，比如样式错乱、丢失部分内容，甚至影响 SEO 优化。因此，对于富文本编辑器生成的内容，我们不能简单地进行字符串切割。
AnQiCMS 的智慧解决方案：HTML 截断过滤器
AnQiCMS 模板引擎内置了强大的过滤器，其中 truncatechars_html 和 truncatewords_html 就是专为处理含 HTML 内容而设计的。它们不仅仅是简单地截取字符串，更会智能地解析 HTML 结构，确保在截断文本的同时，所有被打开的 HTML 标签都能被正确地闭合，从而避免结构破坏。
truncatechars_html: 这个过滤器允许你指定一个字符数，AnQiCMS 会尝试在不超过这个字符数的前提下截断内容，并确保截断后的 HTML 标签是闭合的。truncatewords_html: 类似地，这个过滤器让你指定一个词语数。AnQiCMS 会在不超过这个词语数的前提下截断内容，并同样保证 HTML 结构的完整性。
这些过滤器是处理富文本内容摘要的理想选择，它们让内容运营者无需担心手动调整 HTML 标签，只需关注内容的长度控制。
如何在模板中优雅地应用这些过滤器
在使用 truncatechars_html 或 truncatewords_html 过滤器时，需要注意将其应用于包含 HTML 内容的变量，并且由于这些过滤器输出的是处理后的 HTML 片段，因此通常还需要配合 |safe 过滤器使用，以防止模板引擎再次对 HTML 内容进行转义，导致标签以纯文本形式显示。
假设你正在文章列表页中显示文章摘要，而摘要内容（例如 archive.Description 或 archive.Content）可能包含 HTML 标签。
示例一：按字符数截断 HTML 内容
如果你想将文章内容截断为最多 150 个字符（包括 HTML 标签，但实际可见字符会少一些），并确保 HTML 结构完整：
{# 假设 articleContent 变量中包含了文章的富文本内容 #}
{% archiveDetail articleContent with name="Content" %}
<div class="article-summary">
{{ articleContent|truncatechars_html:150|safe }}
<a href="{{ archive.Link }}">阅读更多</a>
</div>
在这个例子中，articleContent 会被截断，并且如果截断点在 <div> 或 <strong> 标签内部，AnQiCMS 会自动为其添加闭合标签，保证 div.article-summary 内部的 HTML 是有效的。
示例二：按词语数截断 HTML 内容
如果你的内容更适合按词语来截断，比如你想显示前 30 个词语：
{# 假设 productDescription 变量中包含了产品的详细描述，可能带有 HTML #}
{% pageDetail productDescription with name="Description" %}
<div class="product-teaser">
{{ productDescription|truncatewords_html:30|safe }}
<a href="{{ page.Link }}">查看详情</a>
</div>
productDescription 在被截断后，同样会保证 HTML 标签的正确闭合。
重点提醒：|safe 过滤器的使用
|safe 过滤器是至关重要的。AnQiCMS 模板引擎默认为了防止跨站脚本攻击（XSS），会对所有输出到页面的变量内容进行 HTML 转义。这意味着如果你的内容是 <p>Hello</p>，不加 |safe 可能会显示为 <p>Hello</p>。当使用 truncatechars_html 等过滤器处理后，我们希望得到的是可解析的 HTML，因此 |safe 明确告诉系统：“这个内容是安全的 HTML，请直接输出，不要转义。”
总结
AnQiCMS 提供的 truncatechars_html 和 truncatewords_html 过滤器，是内容运营者在处理富文本内容摘要时的得力助手。它们通过智能识别和闭合 HTML 标签，彻底解决了截断 HTML 文本时可能出现的结构损坏问题，极大地提升了内容显示的稳定性和用户体验。只要正确地运用这些过滤器，并配合 |safe 使用，就能轻松实现既美观又健壮的内容摘要展示。
常见问题 (FAQ)
1. 如果对包含 HTML 标签的内容使用 truncatechars 或 truncatewords 过滤器，而不是 _html 结尾的过滤器，会发生什么？
如果对含有 HTML 标签的内容错误地使用了 truncatechars 或 truncatewords 这样的纯文本截断过滤器，系统会将其视为普通字符串进行截断，而不会去解析或处理 HTML 标签。这很可能导致标签被从中间截断，留下未闭合的标签。例如，<b>重要</b> 可能会被截断为 <b>重。这样一来，页面结构就会被破坏，导致后续的 HTML 元素显示异常，样式错乱，甚至可能影响页面功能。因此，务必对包含 HTML 的内容使用 _html 结尾的过滤器。
2. 为什么在使用 truncatechars_html 或 truncatewords_html 过滤器后，还需要加上 |safe 过滤器？
AnQiCMS 模板引擎出于安全考虑，默认会自动对所有从变量输出到页面的内容进行 HTML 转义，将 < 转换为 < 等。虽然 truncatechars_html 和 truncatewords_html 过滤器能够生成结构完整的 HTML 片段，但如果不加 |safe 过滤器，这些生成的 HTML 标签（如 <p>、<div>）本身仍会被转义，导致在页面上看到的是 <p> 而不是一个真正的段落。|safe 过滤器明确告诉模板引擎：这段内容是经过处理且安全的 HTML，请按原样输出，不要进行转义，从而确保截断后的 HTML 能够正确地渲染在页面上。
3. 可以自定义截断后显示的省略号（…）吗？
目前，AnQiCMS 内置的 truncatechars_html 和 truncatewords_html 过滤器默认使用标准的省略号“…”来表示内容被截断。在过滤器本身的参数中，并没有直接提供修改或自定义这个省略号字符的选项。这是为了保持显示的一致性和简洁性，通常在网页设计中，省略号已经是一个被广泛接受的表示内容截断的符号。