`truncatechars_html`和`truncatewords_html`过滤器如何安全地截取带有HTML标签的文本，防止结构破坏？

在网站内容运营中，我们经常需要在不同的场景下展示内容的摘要或部分片段，例如在列表页、搜索结果或者相关推荐中。这时，就需要对内容进行截取。如果内容是纯文本，简单的字符或单词截取器就能很好地完成任务。然而，当内容富含HTML标签时，问题就变得复杂起来：直接截取可能导致HTML标签被截断，从而破坏页面结构，引发显示异常，甚至影响用户体验。

AnQiCMS作为一款高效的内容管理系统，充分考虑到了内容展现的灵活性和安全性。它为我们提供了两个专为处理带有HTML标签文本设计的模板过滤器：truncatechars_html和truncatewords_html，巧妙地解决了HTML内容安全截取的问题。

HTML截取面临的挑战

想象一下，你有一段内容是这样的：<p>这是一段很长的文本，其中包含<b>重要的关键词</b>，还有一些<i>斜体字</i>和<img src="/image.jpg" alt="图片描述">。</p> 如果我们简单地将这段文本截取前20个字符，结果可能变成：<p>这是一段很长的文本，其中包含<b>重。很明显，<b>标签没有闭合，<i>标签和<img>标签也可能被截断，这将导致：

• 页面布局混乱：未闭合的标签可能影响后续元素的样式。
• 语义破坏：重要的关键词可能失去其加粗效果。
• 用户体验下降：图片无法正常显示，甚至可能出现浏览器解析错误。

传统的文本截取器无法理解HTML的结构，它们只会按照字符或单词数量进行暴力截断。

AnQiCMS的解决方案：智能HTML截取器

AnQiCMS提供的truncatechars_html和truncatewords_html过滤器正是为了解决上述问题而生。它们的核心优势在于能够智能地解析HTML结构，在截取文本内容的同时，确保所有被截断的HTML标签都能得到正确的闭合，从而避免结构破坏。

1. truncatechars_html：按字符数安全截取HTML文本

truncatechars_html过滤器允许你指定一个字符数限制，它会在截取文本到指定字符数时，确保所有打开的HTML标签都被正确关闭。这使得即使内容被截短，页面的HTML结构依然保持完整。

使用方法： {{ obj|truncatechars_html:number }}

其中，obj是你需要截取的HTML文本内容，number是你希望截取到的字符总数（包括最终添加的省略号）。

示例： 假设我们有以下HTML文本： long_html_text = "<div class=\"foo\"><ul class=\"foo\"><li class=\"foo\"><p class=\"foo\">这是一段很长的文本，其中包含<b>重要的关键词</b>。</p></li></ul></div>"

如果我们希望截取大约25个字符（实际可见字符数会略少于25，因为HTML标签不算入可见字符，但省略号算入）： {{ long_html_text|truncatechars_html:25 }}

输出可能类似： <div class="foo"><ul class="foo"><li class="foo"><p class="foo">这是一段很长的文本，其中包含<b>重要的...</b></p></li></ul></div>

从输出中可以看到，即使文本被截断，<b>、<p>、<li>、<ul>、<div>等所有标签都得到了正确的闭合，避免了结构性错误。如果最终截取的内容没有达到指定字符数，它将自动添加“…”以表示截断。

应用场景： 当你需要严格控制摘要的字符长度，例如在SEO友好的描述或字数受限的广告位中，这个过滤器就显得尤为实用。

2. truncatewords_html：按单词数安全截取HTML文本

与truncatechars_html类似，truncatewords_html则是根据单词数量进行截取。它同样会智能地识别并闭合所有相关的HTML标签，确保截取后的HTML代码有效。

使用方法： {{ obj|truncatewords_html:number }}

其中，obj是你需要截取的HTML文本内容，number是你希望截取到的单词总数。

示例： 假设有HTML文本： html_content = "<p>This is a long test which will be cutted after some words. <b>Important words here.</b></p>"

如果我们希望截取5个单词： {{ html_content|truncatewords_html:5 }}

输出可能类似： <p>This is a long test ...</p>

这里可以看到，在截取了5个单词后，<b>标签虽然未包含在最终内容中，但<p>标签得到了正确闭合。

应用场景： 适用于博客文章列表、新闻摘要等场景，这些场景通常更关注内容的阅读连贯性，按单词截取能提供更好的可读性。

为什么选择HTML截取器而非普通截取器？

AnQiCMS也提供了truncatechars和truncatewords这两个针对纯文本的截取器。它们不会解析HTML标签，而是直接按照字符或单词数量进行截断。

• truncatechars：{{ "<b>Hello World</b>"|truncatechars:10 }} 可能输出 <b>Hello Wo...，HTML结构损坏。
• truncatewords：{{ "<b>Hello World</b>"|truncatewords:1 }} 可能输出 <b>Hello...，HTML结构损坏。

因此，只要你的文本内容可能包含任何HTML标签，就应该优先选择truncatechars_html或truncatewords_html，以确保页面的稳定性和美观性。只有当你确定文本是纯文本时，才考虑使用非HTML的截取器。

使用技巧与注意事项

1. 始终配合 |safe 过滤器使用： AnQiCMS模板引擎默认会对输出的变量进行HTML实体转义，以防止XSS攻击。当truncatechars_html或truncatewords_html返回的是一段经过处理的HTML代码时，我们需要使用|safe过滤器明确告诉模板引擎，这段HTML是安全的，无需再次转义，否则最终展示在页面上的将是带有<和>等实体编码的原始HTML字符串。 例如：{{ archive.Content|truncatechars_html:100|safe }}
2. 源HTML质量： 这些过滤器能安全地闭合它们自己截断的标签，但它们无法修复原始文本中已经损坏的HTML结构。如果你的源内容本身就存在大量未闭合或错误的标签，这些过滤器也无法将其修复为完美状态。因此，从内容输入的源头保证HTML的规范性仍然非常重要。
3. 截取长度的考量： 截取字符数或单词数时，需要根据实际页面布局和设计需求进行测试和调整，以确保摘要既能传达足够的信息，又不会破坏页面美感。
4. **省略号行为：