在网站内容的呈现中，我们经常需要将冗长的文本信息进行精简，以适应不同的布局需求，例如在列表页展示文章摘要、产品卡片上的简短描述等。这不仅能让页面看起来更整洁，也有助于访问者快速抓住核心信息。安企CMS（AnQiCMS）为这类需求提供了灵活的模板过滤器，其中，truncatewords 过滤器就是您按单词数量截断文本的得力助手。

巧妙精简，让内容一目了然：truncatewords 过滤器解析

truncatewords 过滤器如同其名称所指，它的核心功能是依据文本中的单词数量进行截断。当原始文本的单词数量超过您设定的阈值时，它会智能地在最后一个完整单词的末尾切断，并在文本末尾自动添加省略号（...）。这种处理方式的巧妙之处在于，它尊重了单词的完整性，避免了因字符截断而可能出现的半个单词或语义不清的情况，从而显著提升了内容的易读性。

如何使用 truncatewords？

在安企CMS的模板中，使用 truncatewords 过滤器非常直观。您只需要将需要处理的文本变量通过管道符号 | 传递给过滤器，并指定您希望保留的单词数量即可。

基本语法结构如下：

{{ text_variable|truncatewords:number }}

这里的 text_variable 是您要截断的文本内容（比如文章描述 item.Description），而 number 则是您希望保留的单词数量。

让我们通过一些具体的例子来理解它的工作方式：

示例 1：英文文本的单词截断

假设您的文本内容是 "This is a long test which will be cutted after some words."，如果您希望保留前9个单词：

{{ "This is a long test which will be cutted after some words."|truncatewords:9 }}

输出结果将会是：This is a long test which will be cutted after some ...

示例 2：中文文本的单词截断

对于中文、日文、韩文等非空格分隔的语言，truncatewords 过滤器的行为会有些特殊。如果文本中不包含空格，过滤器会倾向于将整段文本视为一个“单词”。这意味着，除非您指定的单词数量为0，否则它可能不会在文本中间进行截断。

假设您的文本内容是 "你好世界"：

{{ "你好世界"|truncatewords:1 }}

输出结果仍是：你好世界

这是因为 你好世界 被视为一个整体的“单词”。但如果文本包含空格，例如 "你好 世界"：

{{ "你好 世界"|truncatewords:1 }}

输出结果可能就是：你好 ...

因此，在处理中文等语言时，如果需要更细粒度的截断控制，可能需要结合实际文本结构或考虑使用其他过滤器。

实际应用场景

truncatewords 过滤器在网站内容运营中有着广泛的应用：

  • 博客或新闻列表页： 在首页或分类页展示文章列表时，每篇文章的详细内容可能很长，直接展示会显得页面冗余。使用 truncatewords 可以轻松地将文章描述截断为30个、50个单词的摘要，既能吸引点击，又能保持页面整洁。
  • 产品展示页： 在电商网站的产品列表或搜索结果页，产品特性或简短介绍如果太长，会影响用户浏览效率。通过此过滤器，您可以将产品描述统一截断，确保所有卡片或列表项的高度一致，提升视觉体验。
  • 内容推荐模块： 在侧边栏或底部的内容推荐区，空间通常有限。truncatewords 能够帮助您快速生成精炼的推荐标题或简介，提高推荐内容的点击率。

与 truncatechars 的异同与选择

安企CMS还提供了 truncatechars 过滤器，它通过指定字符数量来截断文本。那么，何时选择 truncatewords，何时选择 truncatechars 呢？

  • truncatewords： 优先考虑保持文本的语义完整性和单词的独立性。它更适合需要展示完整词语、避免断词造成阅读障碍的场景。缺点是无法精确控制最终的字符长度。
  • truncatechars： 优先考虑精确控制最终的字符长度。它更适合对显示空间有严格限制的场景，即使截断可能发生在单词中间。

总的来说，如果您更注重内容的可读性和优雅度，truncatewords 是一个很好的选择。如果对字符长度有硬性要求，truncatechars 则更合适。

处理包含 HTML 标签的内容

值得注意的是，如果您的文本内容包含 HTML 标签（例如富文本编辑器生成的带有加粗、链接的文本），直接使用 truncatewords 过滤器可能会破坏 HTML 标签的结构，导致页面显示异常。

在这种情况下，安企CMS提供了一个专门的解决方案：truncatewords_html 过滤器。truncatewords_html 能够智能地解析并截断 HTML 内容，同时确保所有标签都被正确关闭，从而维护页面的正常渲染。当您的截断内容可能带有格式时，请务必使用 truncatewords_html 以确保兼容性。

总结

truncatewords 过滤器是安企CMS模板中一个强大而实用的工具，它能够帮助您以优雅且易读的方式呈现文本内容摘要，极大地提升网站的用户体验和页面美观度。通过理解其工作原理，并结合 truncatechars 和 truncatewords_html 的特性，您可以根据不同场景灵活运用，打造出更具吸引力的网站。

常见问题 (FAQ)

1. truncatewords 和 truncatechars 过滤器有什么区别？ truncatewords 过滤器根据文本中的“单词”数量来截断，它会尝试保留单词的完整性，并在最后一个完整单词后添加省略号。而 truncatechars 过滤器是根据“字符”数量来截断，无论是否是单词的中间部分，它都会直接截断，通常用于对文本长度有严格像素或布局限制的场景。

2. 如果我需要截断的内容包含 HTML 标签，应该使用哪个过滤器？ 对于包含 HTML 标签的内容，建议使用 truncatewords_html 过滤器。它能智能地解析 HTML 结构，在截断文本的同时确保标签的正确闭合，避免因截断导致页面布局混乱或显示错误。直接使用 truncatewords 可能会破坏 HTML 结构。

3. truncatewords 过滤器对中文等非空格分隔的语言是如何处理的？ 对于中文、日文、韩文等没有明确空格分隔单词的语言，truncatewords 过滤器通常会将一段连续的文本视为一个“单词”。这意味着，如果您设定的单词数量不为零，它可能不会在文本中间进行截断，而是显示整段文本，除非文本中包含空格。在这种情况下，如果您需要精确控制截断长度，可能需要更仔细地考虑使用 truncatechars 或结合其他自定义逻辑。