在安企CMS的模板开发中，为了更好地展示内容摘要或控制页面布局，我们经常需要截断文本。此时，truncatechars和truncatewords这两个过滤器便派上了用场。它们都能帮助我们将过长的文本缩短，并在末尾添加省略号，但两者的截断逻辑有着本质的区别，理解这些差异对于正确选择和运用它们至关重要。

truncatechars：精确到字符的截断

truncatechars过滤器，顾名思义，是按照字符数量进行截断的。当你为它设定一个数字参数时，它会从文本的开头开始计数，直到达到指定的字符数，然后在这个位置将文本截断，并在末尾加上省略号（...）。需要注意的是，这个数字参数是包含省略号的字符数的。

核心特点：

  1. 字符计数精确： 它不关心单词的完整性，每一个字母、数字、符号甚至是一个空格都被视为一个字符。对于中文字符，它也会按一个字符单位进行计数。
  2. 可能截断单词： 由于严格按照字符数来截断，truncatechars可能会在某个单词的中间位置进行截断，导致显示效果略显生硬，不符合自然阅读习惯。
  3. HTML处理： 当处理包含HTML标签的富文本内容时，直接使用truncatechars会破坏HTML结构，导致页面显示异常。此时，应使用其HTML友好版本truncatechars_html。truncatechars_html会在截断时智能地关闭未闭合的HTML标签，确保页面的结构完整。

示例：

假设有字符串 "AnQiCMS是一个功能强大的CMS系统。" {{ "AnQiCMS是一个功能强大的CMS系统。"|truncatechars:10 }} 可能会输出 AnQiCMS是...。

而{{ "AnQiCMS是一个功能强大的CMS系统。"|truncatechars:15 }} 可能输出 AnQiCMS是一个功...。

如果内容是HTML代码，例如 <p><strong>AnQiCMS</strong> 是一个内容管理系统。</p>，使用{{ value|truncatechars_html:20 }}，它会智能地截断并正确闭合标签，如 <p><strong>AnQiCMS</strong> 是一个内容...</p>。

truncatewords：以单词为单位的截断

与truncatechars不同，truncatewords过滤器是基于单词进行截断的。它会将文本内容分解为一个个独立的单词（通常以空格作为分隔符），然后按照你指定的单词数量进行截断，并在末尾添加省略号。

核心特点：

  1. 保持单词完整： truncatewords会确保每个单词都完整无缺。它不会在单词中间进行截断，从而保证了文本的可读性和自然性。
  2. 不适合无空格语言： 这是truncatewords在安企CMS（或其他基于西方语言逻辑的模板引擎）中处理中文、日文、韩文（CJK）等语言时最显著的局限。由于CJK语言的单词之间没有天然的空格分隔，truncatewords往往会把一整段连续的中文文本视为一个“超级长”的单词。这意味着，如果你指定截断10个单词，而你的中文段落没有空格，它很可能返回整个段落，因为“10个单词”对它来说就是那一个“超级长词”。
  3. HTML处理： 同样地，当处理包含HTML标签的富文本内容时，应使用truncatewords_html版本。它能在保持单词完整性和HTML结构完整性之间取得平衡。

示例：

假设有字符串 "AnQiCMS is a powerful Content Management System." {{ "AnQiCMS is a powerful Content Management System."|truncatewords:5 }} 会输出 AnQiCMS is a powerful Content...。

但如果字符串是中文 "安企CMS是一个功能强大的内容管理系统。"， {{ "安企CMS是一个功能强大的内容管理系统。"|truncatewords:5 }} 很可能输出 安企CMS是一个功能强大的内容管理系统。 （即不截断），因为它将整句话视为一个单词。

如果内容是HTML代码，例如 <p><strong>AnQiCMS</strong> is a Content Management System.</p>，使用{{ value|truncatewords_html:5 }}，它会智能地截断并正确闭合标签，如 <p><strong>AnQiCMS</strong> is a Content Management...</p>。

本质区别与选择建议

特点/过滤器 truncatechars / truncatechars_html truncatewords / truncatewords_html
截断单位 字符（包含空格、标点、中文字符） 单词（以空格分隔）
单词完整性 不保证，可能在单词中间截断 保证，总是保持单词完整
长度精确性 高，精确控制字符总数（含省略号） 低，取决于单词长度，实际字符数不精确
中文支持 良好，按字符计数，截断可预期 差，可能将整段中文视为一个单词，导致不截断
HTML支持 truncatechars_html 保证结构 truncatewords_html 保证结构

如何选择？

  • 当你需要严格控制显示字符总长度时（例如，在表格单元格中，或为了SEO元描述精确到字符数，且不介意单词被截断），并且你的内容可能包含中文、日文、韩文等无空格分隔的语言时，请优先选择 truncatechars。 对于中文字符串，truncatechars能提供更直观和可预测的截断效果。
  • 当你更关注文本的可读性和语义完整性，不希望单词被截断，且你的内容主要是英文或其他以空格分隔单词的语言时，请优先选择 truncatewords。 它能为用户提供更流畅的阅读体验，例如在文章列表的摘要中。
  • 无论选择哪种截断方式，如果你的内容是富文本（包含HTML标签），请务必使用其对应的 _html 版本（即 truncatechars_html 或 truncatewords_html）。 这将避免因截断导致页面HTML结构损坏。

总而言之，理解这两种过滤器的底层逻辑和各自的优势劣势，特别是它们在处理不同语言时的表现，能帮助你在安企CMS的内容运营中做出明智的选择，从而提升网站内容的展示质量和用户体验。

常见问题解答 (FAQ)

  1. 过滤器中的数字参数是否包含省略号（…）的长度？ 是的，truncatechars和truncatewords过滤器设定的数字参数都包含了末尾可能出现的省略号（...）的字符长度。例如，如果你设置truncatechars:10，那么最终输出的文本（包括省略号）最多会是10个字符长。

  2. 如果我的内容是HTML格式，直接使用truncatechars或truncatewords会有什么问题？ 直接使用truncatechars或truncatewords来处理HTML格式的内容，可能会破坏HTML标签的结构。例如，一个<strong>标签可能被截断，但它的闭合标签</strong>却被遗漏，导致页面显示混乱。因此，处理HTML内容时，请务必使用其对应的HTML友好版本：truncatechars_html和truncatewords_html，它们会智能地闭合未完成的HTML标签。

  3. 我的网站内容主要是中文，应该优先选择哪种过滤器来截断文章摘要？ 对于主要包含中文内容的网站，通常更推荐使用truncatechars或truncatechars_html。这是因为中文单词之间没有空格分隔，truncatewords过滤器会把一整段连续的中文文本视为一个“大单词”，导致即使你设定了较小的单词数量，它也可能不会进行截断，或者截断行为不可预测。而truncatechars则会按照实际的字符数量（每个汉字算一个字符）进行截断，结果更符合预期。