如何利用`truncatechars`或`truncatewords_html`过滤器截断文本或HTML内容并添加省略号进行显示？

在运营网站时，我们经常遇到需要展示长篇内容，但页面空间有限的情况。比如，在文章列表页，我们通常只希望显示文章的摘要；在产品详情卡片上，可能只想展示一段简短的描述。如果不对这些内容进行处理，它们可能会溢出容器，破坏页面布局，影响用户体验。

安企CMS深知内容展示的重要性，为我们提供了强大的模板功能。其中，truncatechars、truncatewords_html等过滤器就是解决内容截断问题的利器。它们能帮助我们优雅地控制文本或HTML内容的显示长度，并在内容被截断时，自动添加美观的省略号，让网站界面保持整洁和专业。

接下来，我们将详细了解这些实用的内容截断过滤器及其应用。

纯文本内容的截断处理：truncatechars 和 truncatewords

当我们需要截断的是纯粹的文本内容，不含任何HTML标签时，truncatechars 和 truncatewords 是我们的首选。

按字符截断：truncatechars

truncatechars 过滤器允许我们指定一个字符数，内容将根据这个字符数进行截断。需要注意的是，它会在截断位置添加省略号（...），并且这三个省略号也会计入你设定的总字符数中。

使用示例： 假设我们有一段文章简介：“Joel is a slug that likes to write about AnQiCMS.”，我们希望它显示不超过9个字符。

{{ "Joel is a slug"|truncatechars:9 }}

显示结果： Joel i...

可以看到，Joel is a 加上省略号，刚好是9个字符。truncatechars非常适合对那些简短的纯文本（如标题、标签）进行精确的字符长度控制。

按单词截断：truncatewords

如果你的内容是英文或以空格分隔的词语，并且你更希望按词完整截断，避免截断一半的单词，那么 truncatewords 会是更好的选择。它会寻找最近的单词边界进行截断，同样会在末尾添加省略号，这些省略号也计入单词数。

使用示例： 我们有一段较长的英文描述：“This is a long test which will be cutted after some words.”，我们希望它显示不超过5个单词。

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

显示结果： This is a long test ...

这样就确保了每个单词的完整性，更符合自然语言的阅读习惯。

HTML内容的截断处理：truncatechars_html 和 truncatewords_html

直接使用 truncatechars 或 truncatewords 来处理包含 HTML 标签的内容时，可能会出现问题。例如，如果内容在 <div> 标签内部被截断，但 </div> 标签没有被包含进来，就会导致页面HTML结构混乱，样式错乱，甚至功能异常。

为了解决这个问题，安企CMS提供了两个专门用于处理 HTML 内容的过滤器：truncatechars_html 和 truncatewords_html。它们在截断内容的同时，会智能地闭合所有未闭合的HTML标签，确保页面的结构完整性。

按字符截断 HTML：truncatechars_html

truncatechars_html 允许我们按字符数截断 HTML 内容，并确保所有HTML标签被正确闭合。它同样会添加省略号并计入字符数。

使用示例： 我们有一段带有HTML标签的段落：“<p class='test' id='foo'>This is a long test which will be cutted after some chars.</p>”，我们希望它显示不超过25个字符。

{{ "<p class='test' id='foo'>This is a long test which will be cutted after some chars.</p>"|truncatechars_html:25 }}

显示结果： <p class='test' id='foo'>This is a long test wh...</p>

可以看到，即使截断位置在 which 中间，过滤器也自动为我们闭合了 <p> 标签，保证了页面的HTML结构不会被破坏。

按单词截断 HTML：truncatewords_html

类似地，truncatewords_html 则确保在按单词截断 HTML 内容的同时，也能保持标签的完整性。它会在最近的单词边界截断，并正确闭合标签。

使用示例： 我们有一段HTML内容：“<p>This is a long test which will be cutted after some words.</p>”，我们希望它显示不超过2个单词。

{{ "<p>This is a long test which will be cutted after some words.</p>"|truncatewords_html:2 }}

显示结果： <p>This is ...</p>

通过这个过滤器，我们可以在截断HTML内容时，既保持了语义上的完整性（按单词），又确保了结构上的安全性。

实际应用建议

在安企CMS中，这些内容截断过滤器在许多场景下都非常有用：

• 文章列表/新闻列表： 在展示文章标题和简介时，可以使用 truncatechars 或 truncatewords 来统一简介的长度，保持列表整齐。
• 产品/服务展示： 产品描述如果包含丰富的HTML格式，但需要在卡片或列表视图中显示摘要时，truncatechars_html 或 truncatewords_html 能够完美地胜任，既保留格式又控制长度。
• 用户评论/留言预览： 在后台或前台显示用户评论的摘要时，也可以使用这些过滤器。
• 多站点内容同步： 如果您利用安企CMS的多站点管理功能，在不同站点之间同步内容摘要，这些过滤器也能帮助您确保显示的一致性。

在选择使用哪个过滤器时，关键在于您要处理的内容是纯文本还是包含HTML，以及您更倾向于按字符精确控制，还是按单词保持语义完整。无论哪种情况，都建议您在实际应用到生产环境前，进行充分的测试，以确保内容显示符合预期。

通过灵活运用安企CMS提供的这些内容截断过滤器，我们不仅能够提升网站的视觉美观度，更能够优化用户体验，让用户在有限的页面空间内，高效地获取到核心信息。

常见问题 (FAQ)

1. 过滤器中的数字参数（例如 truncatechars:9 中的 9）具体指什么？ 这个数字参数指的是你希望内容显示的最大长度。对于 truncatechars 和 truncatechars_html，它指的是最大字符数；对于 truncatewords 和 truncatewords_html，它指的是最大单词数。值得注意的是，如果内容被截断并添加了省略号（...），这三个省略号也会计入你设定的总长度中。

2. 如果我截断了内容，但不想显示省略号怎么办？ 安企CMS内置的 truncatechars、truncatewords、truncatechars_html 和 truncatewords_html 过滤器在内容被截断时，默认都会自动添加省略号。目前，这些过滤器没有直接提供选项来禁用省略号的显示。如果您有特殊需求，可能需要考虑自定义一个过滤器来实现这一功能，但这超出了本篇文章的讨论范围。

3. 在处理包含 HTML 标签的内容时，我应该优先选择 truncatechars_html 还是 truncatechars？ 当您的内容包含任何 HTML 标签时，强烈建议您使用 truncatechars_html 或 truncatewords_html。这是因为常规的 truncatechars 或 truncatewords 过滤器只会按纯文本方式截断，可能会在标签中间截断内容，导致 HTML 结构损坏，从而影响页面布局和显示。而带有 _html 后缀的过滤器则会智能地识别并正确闭合未完成的 HTML 标签，确保页面结构的完整性。