在网站内容运营中，我们常常会遇到这样的情况：文章列表页需要显示内容的摘要，产品详情页需要展示简短的介绍，或者在某些特殊模块中，我们需要从冗长的文本或包含HTML标签的内容中截取一部分，并在末尾加上“…”来提示用户内容未完。这样做不仅能有效节省页面空间，保持版面整洁，更能提升用户阅读体验，吸引他们点击查看完整内容。

要实现这样的功能，如果每次都手动截取，无疑会耗费大量时间和精力。幸运的是，AnQiCMS 深知这些需求，在模板系统中内置了一系列强大且灵活的过滤器，能够帮助我们轻松完成长字符串和HTML内容的截取与省略号显示，而且无需编写复杂的代码。

AnQiCMS 模板引擎提供的核心过滤器包括：

  • truncatechars: 适用于纯文本内容，根据指定的字符数量进行截取。
  • truncatewords: 适用于纯文本内容，根据指定的单词数量进行截取。
  • truncatechars_html: 专门用于包含HTML标签的内容，按字符数量截取，同时智能地保持HTML结构的完整性。
  • truncatewords_html: 同样用于包含HTML标签的内容，按单词数量截取，并确保HTML标签的正确闭合。

所有这些过滤器在截取内容后，都会在末尾自动添加省略号（“…”），使内容展示更加专业和友好。

针对纯文本内容的截取：truncatechars 和 truncatewords

当我们需要处理的文章标题、简短描述等不包含任何HTML标签的纯文本时，truncatechars 和 truncatewords 是理想的选择。

按字符数截取：truncatechars

这个过滤器会从字符串开头开始计算字符，达到指定数量后进行截取，并在末尾添加省略号。值得注意的是，它在计数时会将省略号本身的三个字符计算在内。

{# 假设有一个纯文本变量 `article.Title`，内容为 "AnQiCMS是一款高效、可定制、易扩展的内容管理系统。" #}

{# 截取前10个字符，包括省略号 #}
{{ article.Title|truncatechars:10 }}
{# 预期输出: AnQiCMS是... #}

{# 截取前20个字符 #}
{{ article.Title|truncatechars:20 }}
{# 预期输出: AnQiCMS是一款高效、可定制、易扩展的... #}

在处理中文内容时，truncatechars 会按实际中文字符数量进行计数，一个中文字符算一个字符，非常符合直觉。

按单词数截取：truncatewords

如果你更倾向于按单词（以空格为分隔符）来截取内容，truncatewords 会是更好的选择。它会计算指定数量的单词后截取，并在末尾添加省略号。

{# 假设有一个纯文本变量 `article.Description`，内容为 "AnQiCMS is an enterprise-grade content management system developed using Go language." #}

{# 截取前5个单词 #}
{{ article.Description|truncatewords:5 }}
{# 预期输出: AnQiCMS is an enterprise-grade content... #}

对于中文内容，由于中文不像英文那样有明确的空格分隔单词，truncatewords 会将连续的中文文字视为一个“单词”。例如，"你好世界"|truncatewords:1 的结果会是 "你好世界"，因为它被视为一个完整的单词。因此，在处理中文时，通常建议使用 truncatechars 来实现更精确的截取效果。

针对HTML内容的截取：truncatechars_html 和 truncatewords_html

在很多情况下，我们的文章内容、产品详情描述等会包含丰富的HTML标签，如段落、加粗、图片等。直接使用 truncatechars 或 truncatewords 可能会导致HTML标签被截断，从而破坏页面布局，甚至引起显示错误。AnQiCMS 提供了带有 _html 后缀的过滤器来解决这个问题，它们在截取内容的同时，会智能地闭合所有未闭合的HTML标签，确保页面结构的完整性。

按字符数截取HTML内容：truncatechars_html

这个过滤器会按字符数量进行截取，并在截取点之前闭合所有打开的HTML标签。为了让浏览器正确解析截取后的HTML内容，通常需要搭配 |safe 过滤器使用，告诉模板引擎这段内容是安全的，不需要进行额外的HTML实体转义。

{# 假设 `article.Content` 包含 HTML 内容，例如：
   `<p><b>AnQiCMS</b>是一个基于<i>Go语言</i>开发的企业级内容管理系统，致力于提供高效、可定制、易扩展的内容管理解决方案。</p><p>项目定位于服务中小企业、自媒体运营者和多站点管理需求的用户。</p>` #}

{# 截取前40个字符的HTML内容，并保持HTML结构 #}
{{ article.Content|truncatechars_html:40|safe }}
{# 预期输出可能类似 (具体截取点及省略号前内容会根据实际HTML结构调整，并确保闭合):
   <p><b>AnQiCMS</b>是一个基于<i>Go语言</i>开发的企业级内容管理系统，致力于提供高效、可定制、易扩展... </p>
#}

按单词数截取HTML内容：truncatewords_html

与 truncatechars_html 类似，truncatewords_html 则是按单词数量截取HTML内容，并同样会智能闭合HTML标签。同样，为了确保HTML内容正确显示，需要配合 |safe 过滤器使用。

{# 假设 `article.Content` 内容同上 #}

{# 截取前15个单词的HTML内容，并保持HTML结构 #}
{{ article.Content|truncatewords_html:15|safe }}
{# 预期输出可能类似:
   <p><b>AnQiCMS</b>是一个基于<i>Go语言</i>开发的企业级内容管理系统，致力于提供高效、可定制、易扩展的内容管理... </p>
#}

重要提示： 在使用 truncatechars_html 和 truncatewords_html 过滤器时，务必在管道操作的末尾加上 |safe。这是因为 AnQiCMS 的模板引擎默认会对所有输出进行HTML实体转义，以防止XSS攻击。而这些 _html 过滤器产生的正是需要浏览器直接解析的HTML代码，如果缺少 |safe，截取后的HTML标签会被当作普通文本显示，而不是被浏览器渲染。

实际应用场景

这些过滤器在 AnQiCMS 的模板设计中非常实用：

  • 文章列表页：在 archiveList 标签循环输出文章时，可以使用 item.Description|truncatechars:100 或 item.Content|truncatewords_html:50|safe 来显示文章摘要，保持列表页的整洁。
  • 产品展示页：在产品概览部分，可以用 product.Detail|truncatechars_html:150|safe 来预览产品的详细描述。
  • 侧边栏或推荐模块：需要展示标题较长的热门文章或推荐内容时，article.Title|truncatechars:25 可以确保标题不会溢出。

通过灵活运用这些内置过滤器，AnQiCMS 用户能够更加精细地控制内容的呈现方式，显著提升网站的用户体验和视觉效果。

常见问题解答 (FAQ)

1. truncatechars 和 truncatewords 这两个过滤器有什么区别，我应该如何选择？

truncatechars 按字符数量截取，即使截取点在单词中间也会直接截断，包括省略号在内的字符总数不会超过你设定的值。而 truncatewords 则按单词数量截取，它会尽量保持单词的完整性，在最后一个完整单词后截取。

  • 如果你的内容是纯文本，并且需要精确控制最终显示文本的长度（例如，固定高度的卡片），选择 truncatechars 更合适。
  • 如果你的内容是纯文本，且你希望截取后的文本语义更完整（不希望单词被切开），则 truncatewords 是更好的选择。
  • 在处理中文内容时，由于中文没有天然的空格分隔，truncatewords 会将连续的中文视为一个“单词”，这可能导致截取不准确，此时更推荐使用 truncatechars。

2. 为什么在截取HTML内容时，我必须使用 truncatechars_html 或 truncatewords_html，而不是普通的 truncatechars 呢？

这是因为普通的 truncatechars 或 truncatewords 过滤器会把HTML标签也当做普通文本来计算长度或单词，并直接截断。这会导致HTML标签闭合不完整，从而破坏页面的结构和样式，造成排版混乱，甚至显示错误。 带有 _html 后缀的过滤器（如 truncatechars_html）则会智能地识别HTML标签，在截取文本内容的同时，确保所有打开的HTML标签（如 <b>、<p>、<i> 等）在截取点前被正确闭合，从而避免页面结构被破坏，保证内容的正确渲染。

3. 截取后显示的省略号可以自定义为其他符号或文字吗？

目前 AnQiCMS 内置的 truncatechars、truncatewords、truncatechars_html 和 truncatewords_html 过滤器，默认生成的省略号是三个点（“…”），并且不支持直接通过参数自定义省略号的符号或文字。如果需要自定义，你可能需要考虑在内容截取后，手动移除默认的省略号，并添加你想要的自定义文本。但这会增加模板的复杂性，且可能需要结合字符串替换等操作。在大多数情况下，使用默认的省略号已经足够满足内容展示的需求。