如何在AnQiCMS模板中安全地截取字符串或HTML内容并添加省略号？

在运营网站时，我们常常需要展示文章简介、产品描述或用户评论等内容。这些文本如果未经处理，直接完整显示，过长的文本可能会打乱页面布局，影响整体美观和信息传递效率。这时，对内容进行适当的截取并添加省略号，就显得尤为重要。

AnQiCMS 作为一个高效、可定制的内容管理系统，其基于 Go 语言开发的强大模板引擎，为我们提供了简单而智能的解决方案。通过内置的过滤器（filters），我们可以轻松地实现字符串或 HTML 内容的灵活截取，并自动添加省略号，确保内容既简洁又完整，同时保持良好的页面结构。

截取普通文本内容：兼顾简洁与可读

对于不含任何 HTML 标签的纯文本内容，AnQiCMS 提供了两个方便的过滤器来满足不同的截取需求：truncatechars 和 truncatewords。

1. truncatechars：按字符数截取

这个过滤器非常适合当你需要严格控制文本显示长度时使用。它会按照你指定的字符数量来截取字符串，并在这个长度内添加省略号（...）。这意味着，如果你设定截取 10 个字符，最终显示的内容（包括省略号）最多就是 10 个字符长。需要注意的是，truncatechars 在截取时可能会“切断”一个单词，因为它只计算字符数量。

使用示例： 假设你的文章描述 item.Description 是一段纯文本，你希望它最多显示 30 个字符：

<p>{{ item.Description|truncatechars:30 }}</p>

如果 item.Description 的内容是“AnQiCMS是一款基于Go语言开发的企业级内容管理系统，功能强大，部署简便。”，那么它可能会显示为“AnQiCMS是一款基于Go语言开发的企业级内容管理系统，功能…”

2. truncatewords：按单词数截取

当你更关注内容的语义完整性，希望截取后的文本不出现“半个词”的情况时，truncatewords 过滤器就派上用场了。它会按照你指定的单词数量进行截取，并确保每个单词都是完整的。当然，在英文环境下，这个过滤器效果会非常自然。对于中文内容，由于中文没有明显的“单词”分隔符，因此其效果可能不如truncatechars直接按字数截取来得精确和符合预期。

使用示例： 如果你希望英文文章的简介 item.Description 显示前 15 个单词：

<p>{{ item.Description|truncatewords:15 }}</p>

如果 item.Description 是“AnQiCMS is an enterprise-level content management system developed based on Go language, powerful and easy to deploy.”，它可能会显示为“AnQiCMS is an enterprise-level content management system developed based on Go language, powerful and easy…”

截取包含 HTML 的内容：安全与结构并重

直接对含有 HTML 标签的内容进行字符或单词截取是一个棘手的问题。简单粗暴地截取很可能会破坏 HTML 标签的完整性，导致页面显示错乱，甚至可能引入安全隐患。AnQiCMS 提供了专为 HTML 内容设计的过滤器，它们能够智能地处理标签，确保截取后的 HTML 结构依然有效。

1. truncatechars_html：安全地按字符截取 HTML

这个过滤器与 truncatechars 类似，但它在截取时会智能地识别并维护 HTML 标签的结构。无论你截取多少字符，它都会确保所有打开的标签都能正确关闭，避免因标签不匹配而导致的页面渲染问题。这对于文章正文、富文本编辑器生成的简介等场景非常实用。

重要提示： 在使用 truncatechars_html 或 truncatewords_html 截取 HTML 内容后，请务必在变量输出时添加 |safe 过滤器。这是因为 AnQiCMS 的模板引擎为了安全，默认会对所有输出内容进行 HTML 转义（例如 < 会被转义成 <）。如果不对经过 _html 过滤器处理的内容进行 |safe 标记，浏览器会把你的 HTML 标签当作普通文本显示出来，而不是渲染它们。|safe 明确告诉模板引擎，这些内容是安全的，不需要转义，可以直接作为 HTML 输出。

使用示例： 假设你的文章内容 archive.Content 包含丰富的 HTML 格式，你希望截取前 100 个字符显示：

<div class="summary">{{ archive.Content|truncatechars_html:100|safe }} <a href="{{ archive.Link }}">阅读更多</a></div>

2. truncatewords_html：安全地按单词截取 HTML

与 truncatewords 类似，truncatewords_html 会按照单词数量来截取包含 HTML 的内容，同时也能智能地维护 HTML 标签的完整性。同样，它也适用于英文等有明确单词分隔符的语言环境，并且也需要配合 |safe 过滤器使用。

使用示例： 如果你希望产品详情 product.Description 显示前 20 个单词，同时保留其 HTML 格式：

<div class="product-brief">{{ product.Description|truncatewords_html:20|safe }} <a href="{{ product.Link }}">查看详情</a></div>

**实践与实用建议

• 选择合适的截取方式： 对于纯文本描述，选择 truncatechars 或 truncatewords。对于含有 HTML 格式的富文本内容，始终使用 truncatechars_html 或 truncatewords_html，以避免破坏页面结构。
• 牢记 |safe 过滤器： 任何时候，只要你使用了 truncatechars_html 或 truncatewords_html 过滤器来处理 HTML 内容，就必须紧接着使用 |safe 过滤器，否则浏览器会显示原始的 HTML 标签而非渲染后的效果。
• 统一截取长度： 在网站的不同区域，尽量保持相同类型内容的截取长度一致性。例如，所有文章列表页的简介都截取为 80 个字符，这样能让页面看起来更整洁和专业。
• 添加“阅读更多”链接： 截取内容后，通常需要在末尾添加一个“阅读更多”或“查看详情”的链接，引导用户访问完整内容，提升用户体验。

通过灵活运用 AnQiCMS 提供的这些内容截取过滤器，您将能够更好地管理和呈现网站内容，为访客提供一个既美观又高效的浏览体验。

常见问题 (FAQ)

1. truncatechars 和 truncatewords_html 有什么核心区别？ truncatechars 是用于截取纯文本的过滤器，它简单地按字符计数，可能会截断单词。而 truncatewords_html 则是用于截取含有 HTML 标签的文本，它会智能地识别并维护 HTML 结构，按单词计数来截取。最重要的是，truncatewords_html 处理后的内容必须配合 |safe 过滤器才能正确渲染 HTML。

2. 为什么在截取 HTML 内容时，我使用了 truncatechars_html，但页面上还是显示了 <p>、<a> 等标签？ 这通常是因为您忘记在输出内容后添加 |safe 过滤器。AnQiCMS 模板引擎默认会对所有变量输出进行 HTML 转义，以防止 XSS 攻击。当您使用 truncatechars_html 处理完 HTML 内容后，如果缺乏 |safe 过滤器，转义机制会把 HTML 标签转换为对应的实体字符（如 <p> 变成 <p>），导致浏览器将其显示为普通文本。加上 |safe 会告诉模板引擎这段内容是安全的，直接按 HTML 渲染。

3. 我可以自定义省略号的样式或内容吗？ 目前 AnQiCMS 内置的截取过滤器默认使用 ... 作为省略号。这些过滤器主要是处理截取逻辑和 HTML 结构，并不提供直接的参数来修改省略号的具体内容或其 CSS 样式。如果您有特定的样式需求，可能需要在截取后，通过前端 JavaScript 或者 CSS 规则对截取后的文本容器进行额外的处理。