针对包含HTML标签的文章内容，如何使用`truncatechars_html`安全地截取指定长度的文本？
在使用安企CMS（AnQiCMS）管理网站内容时，我们经常会遇到这样的场景：文章内容为了排版美观，使用了各种HTML标签来丰富视觉效果，比如段落（<p>）、图片（<img>）、链接（<a>）、加粗（<strong>）等等。然而，在文章列表页或者相关推荐模块，我们往往需要展示这些文章的摘要或部分内容，但又不能直接把长篇大论全部显示出来。
这时候，一个常见的做法是截取文章开头的固定长度文本。如果直接简单地对包含HTML标签的文本进行字符串截取，比如截取前100个字符，结果往往不尽如人意。因为这种粗暴的截取方式可能会将HTML标签截断，导致页面渲染错误，出现未闭合的标签、混乱的样式，甚至破坏整个页面的布局。这不仅影响用户体验，也可能造成浏览器的兼容性问题。
为了优雅而安全地处理这种带有HTML标签的文章内容截取需求，安企CMS提供了一个非常实用的模板过滤器——truncatechars_html。
为什么选择 truncatechars_html？
truncatechars_html过滤器的核心价值在于它能够智能地处理HTML结构。它不像普通的字符串截取那样简单地按字符计数，而是会解析HTML标签。在截取指定长度的可见文本（不包括HTML标签本身的字符）后，它会自动闭合所有未闭合的HTML标签，从而确保输出的HTML代码依然是完整且有效的。这意味着，你无需担心截断的HTML内容会破坏页面的布局或样式，它会尽力保持内容的语义和视觉完整性。
如何在安企CMS模板中使用 truncatechars_html？
在安企CMS的模板系统中，使用truncatechars_html非常直观。你只需要将它作为一个过滤器应用到你想要截取的内容变量上，并指定希望保留的字符长度即可。
其基本语法是：{{ 变量名|truncatechars_html:长度|safe }}。
例如，在文章列表页，你可能需要展示每篇文章的摘要。假设你的文章内容存储在 archive.Content 变量中，并且你想截取前120个可见字符作为摘要：
{# 假设我们正在遍历一个文章列表 archives #}
{% archiveList archives with type="page" limit="10" %}
{% for item in archives %}
<div class="article-item">
<h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
<div class="article-summary">
{# 安全地截取文章内容的前120个可见字符，并保持HTML结构完整 #}
{{ item.Content|truncatechars_html:120|safe }}
</div>
<a href="{{ item.Link }}" class="read-more">阅读更多</a>
</div>
{% endfor %}
{% endarchiveList %}
在这里，item.Content 是文章的详细内容，可能包含如 <p>这是文章的<strong>第一段</strong>内容。</p><img src="/image.jpg" alt="图片描述"> 这样的HTML。
truncatechars_html:120会告诉系统截取前120个可见字符（HTML标签本身不计入长度），同时智能地闭合任何在截取点被打开的标签。|safe过滤器是必不可少的。因为truncatechars_html的输出本身就是经过处理的HTML代码。安企CMS模板引擎为了安全起见，默认会对所有输出内容进行HTML实体转义（比如把<转成<）。如果不加|safe，截取后的HTML标签会被当作普通文本显示，而不是被浏览器解析，从而失去原有样式。
truncatechars_html 的工作原理示例
假设有以下一段HTML内容：
<p>这是一段很长的文本，其中包含<strong>加粗</strong>和<a href="#">链接</a>，我们希望截取它的部分内容，同时保持格式。</p>
<p>第二段内容，可能也会被截取到。</p>
如果你使用{{ original_html_content|truncatechars_html:50|safe }}进行截取，truncatechars_html会计算可见字符，然后可能会输出类似这样：
<p>这是一段很长的文本，其中包含<strong>加粗</strong>和<a href="#">链接</a>，我们希望截取它的部分内容，同时保持格式...</p>
可以看到，尽管在链接后面被截断，但<a>和<strong>、<p>标签都得到了正确的闭合，并且在末尾添加了省略号（...），保证了HTML的有效性和页面的整洁。
实际应用场景
- 文章列表/新闻摘要： 在博客、新闻网站的文章列表中，展示每篇文章的简短摘要，引导用户点击查看全文。
- 产品列表/简介： 在电商网站的产品列表页，展示产品详细描述的开头部分，保持样式和链接的可用性。
- 搜索结果页： 搜索引擎内部的搜索结果，提供相关内容的片段预览。
- 相关推荐模块： 在文章底部或侧边栏，推荐其他相关文章，并显示其摘要。
通过灵活运用truncatechars_html过滤器，可以大大提升安企CMS网站内容的展示效果和用户体验，确保即使是摘要内容也能以专业、美观的方式呈现。
常见问题 (FAQ)
1. truncatechars_html 和 truncatechars 有什么区别？
truncatechars是用于纯文本内容的截取，它只是简单地按字符数量进行截断，不会考虑HTML标签。如果对含有HTML的内容使用，很容易截断标签，导致页面显示错误。而truncatechars_html则会智能识别HTML标签，在截取可见字符的同时，确保所有被打开的标签都能正确闭合，从而输出合法的HTML片段。
2. 为什么在使用 truncatechars_html 后还需要加上 |safe 过滤器？
安企CMS的模板引擎出于安全考虑，默认会对所有输出内容进行HTML实体转义，以防止跨站脚本攻击（XSS）。truncatechars_html虽然会输出合法的HTML片段，但如果不加|safe过滤器，模板引擎会再次对其进行转义，例如将<p>显示为<p>。加上|safe是明确告诉模板引擎：这段内容是安全的，请直接按HTML解析显示。
3. 如果我的内容是纯文本，可以使用 truncatechars_html 吗？
可以。truncatechars_html对纯文本内容同样有效，它会将其视为不含标签的HTML，并按指定长度截取。但对于纯文本，更推荐使用truncatechars过滤器，因为它更轻量级，无需进行HTML解析，效率更高。通常，只有当内容可能包含HTML标签时，才需要使用truncatechars_html。