在日常网站运营中，我们经常会遇到这样的情况：文章详情页内容丰富，但列表页或推荐模块为了版面整洁，需要显示内容的精简版本，通常是截取一部分文本并在末尾加上省略号。安企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）。那里提供了每种过滤器的参数、详细使用方法和更多代码示例。