如何将长文本内容截断并显示省略号？
在日常网站运营中，我们经常会遇到这样的情况：文章详情页内容丰富，但列表页或推荐模块为了版面整洁，需要显示内容的精简版本，通常是截取一部分文本并在末尾加上省略号。安企CMS深知内容展示的重要性，提供了非常便捷且强大的工具来处理这类需求。
让我们一起来看看如何在安企CMS中，优雅地实现长文本内容的截断并显示省略号，让网站界面既美观又专业。
内容截断的需求与价值
在许多内容展示场景，例如首页的文章列表、专题页的文章摘要、侧边栏的推荐内容，或是SEO元描述（Description），我们都需要控制文本的显示长度。过长的文本会占用过多空间，打乱页面布局，影响用户的第一印象；而经过精心截断并辅以省略号的短文本，则能更高效地传达信息，吸引用户点击查看完整内容。这不仅优化了用户体验，也有助于提升页面整体的视觉美感和内容的可读性。
安企CMS的解决方案：文本截断过滤器
安企CMS的模板系统基于Django模板引擎语法，提供了多种内置的“过滤器”（Filters）来帮助我们轻松处理内容。针对文本截断的需求，主要有以下几个实用过滤器：truncatechars、truncatewords，以及它们对应的HTML安全版本truncatechars_html和truncatewords_html。
1. 按字符截断：truncatechars
这个过滤器会根据您指定的字符数来截断文本。无论中英文，它都会精确地计算字符数量，并在截断处添加省略号（...）。需要注意的是，这个省略号本身也包含在您设定的字符数之内。
使用方式：
{{ 您的文本变量|truncatechars:数字 }}
示例：
假设我们有一段文本{{ archive.Description }}，想要截取前20个字符：
{{ archive.Description|truncatechars:20 }}
如果archive.Description是“这是一个很长很长的文档描述，需要被截断显示。”
那么输出结果可能是：“这是一个很长很长的文档…”
何时使用： 当您需要严格控制显示文本的像素宽度，或者在处理中文内容时，truncatechars非常有用，因为它不区分单词，只按字符数截断。
2. 按单词截断：truncatewords
与truncatechars不同，truncatewords是根据单词数量来截断文本的。它会尽量保持单词的完整性，并在最后一个完整单词之后添加省略号。同样，省略号也计入您设定的单词数中。
使用方式：
{{ 您的文本变量|truncatewords:数字 }}
示例：
假设文本变量{{ archive.Description }}是“This is a very long description for an article that needs to be truncated.”，我们想截取前10个单词：
{{ archive.Description|truncatewords:10 }}
输出结果可能是：“This is a very long description for an article that…”
何时使用： 在处理英文或其他以空格分隔单词的语言时，truncatewords通常能提供更自然、更流畅的阅读体验，避免单词被生硬地从中间截断。
3. 处理HTML内容：truncatechars_html 和 truncatewords_html
很多时候，我们的内容（比如文章正文的一部分）可能包含HTML标签，例如<b>加粗、<a>链接、<p>段落等。如果直接使用truncatechars或truncatewords，可能会导致HTML标签被错误截断，从而破坏页面的结构，甚至引发显示异常。
为了解决这个问题，安企CMS提供了truncatechars_html和truncatewords_html这两个增强型过滤器。它们能够在截断文本的同时，智能地闭合所有未闭合的HTML标签，确保输出的HTML结构是完整且有效的。
使用方式：
{{ 您的HTML文本变量|truncatechars_html:数字|safe }}
{{ 您的HTML文本变量|truncatewords_html:数字|safe }}
请注意，当您处理包含HTML的内容时，无论是否使用截断过滤器，都应该在末尾加上|safe过滤器。|safe的作用是告诉模板引擎，这段内容是安全的，不需要进行HTML实体转义，直接按HTML解析显示。
示例：
假设{{ archive.Content }}包含HTML代码：“
这是一段重要的内容，其中包含加粗和链接，需要被截断。
”，我们希望截取前25个字符并保持HTML结构：{{ archive.Content|truncatechars_html:25|safe }}
输出结果可能是：“
这是一段重要的内容，其中包含加粗和链接…
” 请注意，即使截断了，<b>和<a>标签也得到了正确的闭合。
何时使用： 任何可能包含HTML标签的文本内容，如文章摘要从正文自动提取、分类描述、单页面内容等，都需要优先考虑使用带_html后缀的截断过滤器。
在安企CMS模板中的具体应用
在安企CMS中，这些过滤器可以应用于几乎所有需要展示文本的地方，尤其是配合列表标签使用。
例如，在您的文章列表模板（通常是{模型table}/list.html）中，您可能会使用archiveList标签来获取文档列表：
{% archiveList archives with type="list" limit="10" %}
{% for item in archives %}
<li>
<a href="{{ item.Link }}">
<h5>{{ item.Title }}</h5>
{# 截取文章描述，显示前100个字符 #}
<div>{{ item.Description|truncatechars:100 }}</div>
{# 如果描述可能包含HTML，使用以下方式 #}
{# <div>{{ item.Description|truncatechars_html:100|safe }}</div> #}
<div>
<span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
<span>阅读量：{{ item.Views }}</span>
</div>
</a>
</li>
{% empty %}
<li>
当前没有可用的文章。
</li>
{% endfor %}
{% endarchiveList %}
在文章详情页的侧边栏推荐模块，如果需要展示简短的标题：
{% archiveList relatedArchives with type="related" limit="5" %}
{% for item in relatedArchives %}
<li>
<a href="{{ item.Link }}">
<h6>{{ item.Title|truncatechars:15 }}</h6> {# 截取推荐文章标题的前15个字符 #}
</a>
</li>
{% endfor %}
{% endarchiveList %}
您也可以在调用分类详情或单页详情时，对它们的描述或内容进行截断：
{# 假设在分类列表页，需要截取分类描述 #}
{% categoryDetail categoryDescription with name="Description" %}
<p>{{ categoryDescription|truncatewords_html:30|safe }}</p>
{# 在单页面模板中，可能需要截取部分内容作为摘要 #}
{% pageDetail pageContent with name="Content" %}
<div class="page-summary">{{ pageContent|truncatechars_html:200|safe }}</div>
实践建议与注意事项
- 选择合适的截断长度： 并没有一个通用的“**”长度。这取决于您的设计布局、目标语言和内容类型。您需要反复测试，在不同设备上查看效果，找到一个既能保持页面整洁，又能提供足够信息吸引用户点击的平衡点。
- 内容类型决定过滤器： 记住，如果您的文本内容可能包含HTML标签，务必使用
_html后缀的过滤器（如truncatechars_html），并添加|safe。对于纯文本，truncatechars或truncatewords就足够了。 - 保持一致性： 在网站的不同区域，对相似内容应用统一的截断规则，有助于提升整体的专业度和用户体验。
- 测试与调整： 即使设定了长度，也建议在实际网站上发布一些测试内容，并检查显示效果。不同字体、字号、排版都会影响最终的视觉效果。
通过合理运用安企CMS提供的文本截断过滤器，您可以轻松掌控网站内容的呈现方式，为访客提供一个更加清爽、高效且专业的浏览体验。
常见问题（FAQ）
Q1: 过滤器中的数字参数，是包含还是不包含省略号（...）的长度？
A1: 在安企CMS的文本截断过滤器中（如truncatechars和truncatewords），您设定的数字是包含省略号的长度的。例如，如果您设定truncatechars:10，那么最终显示的内容（包括省略号）总长度将不超过10个字符。
Q2: 如果我的内容本身就很短，不足以被截断，会怎么样？
A2: 如果原始内容的长度不足以达到您设定的截断长度，那么内容将不会被截断，也不会显示省略号。过滤器只会原样输出这段短文本，不会进行任何修改。
Q3: 我在哪里可以找到这些过滤器的更多详细文档和示例？
A3: 您可以在安企CMS的官方模板开发文档中找到关于所有过滤器的详细说明。具体来说，可以查阅“模板制作”分类下的“标签和用法”以及“更多过滤器”文档（在您的文档集合中对应design-tag.md和tag-filters.md）。那里提供了每种过滤器的参数、详细使用方法和更多代码示例。