在安企CMS的模板设计中，为了页面的美观和布局的统一性，我们经常需要对文章标题进行字符截断，并在截断后自动添加省略号。AnQiCMS 提供了简洁高效的模板过滤器来实现这一需求，让内容展示更加灵活。

核心原理：理解 AnQiCMS 模板过滤器

在 AnQiCMS 的模板体系中，借助其强大的 Django-like 模板引擎，我们可以方便地使用“过滤器”（Filters）对数据进行处理和格式化。这些过滤器能够对变量进行加工，例如改变大小写、格式化时间，或是我们当前关注的——截断字符串。

对于文章标题的字符截断并添加省略号，AnQiCMS 提供了 truncatechars 过滤器。它的作用是：当字符串的字符数量超过指定长度时，会自动截断多余的字符，并在末尾添加 ... 作为省略号。值得注意的是，truncatechars 在计算字符数时，会包含自动添加的省略号。

过滤器的基本使用语法如下： {{ 变量 | 过滤器名称 : 参数 }}

在这里，变量 指代你希望截断的字符串（如文章标题），过滤器名称 即 truncatechars，而 参数 则是你想要保留的最大字符数量。

实战演练：在模板中应用标题截断

接下来，我们通过具体的模板代码示例，看看如何在 AnQiCMS 模板中对文章标题进行截断。

场景一：文章列表页标题截断

在网站的文章列表页（如首页最新文章、分类文章列表等），标题通常需要保持在一定长度内，以避免布局混乱。这时，archiveList 标签配合 truncatechars 过滤器是理想选择。

假设我们要在一个文章列表中展示文章标题，并限制其长度为 30 个字符：

{# 假设我们正在循环输出文章列表，变量名为 archives #}
{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <li>
        <a href="{{item.Link}}">
            {# 对文章标题 item.Title 进行字符截断，并限制在 30 个字符以内 #}
            <h5>{{item.Title | truncatechars:30 }}</h5>
            <div>{{item.Description}}</div>
            {# ... 其他文章信息 ... #}
        </a>
    </li>
    {% empty %}
    <li>
        当前没有可展示的文章。
    </li>
    {% endfor %}
{% endarchiveList %}

在这个例子中，item.Title 是我们获取到的文章标题。通过 | truncatechars:30，系统会自动检查标题长度，如果超过 30 个字符，就会从第 27 个字符处开始截断，并在其后添加 ...，总长度最终为 30 个字符。

场景二：单一文章标题截断（非列表场景）

虽然在文章详情页，通常会显示完整的标题，但在某些特殊布局下，例如页面侧边栏或自定义模块中需要引用当前文章标题的精简版，同样可以使用 truncatechars 过滤器。

假设在一个侧边栏模块中，需要展示当前页面的文章标题，并将其限制在 20 个字符：

{# 获取当前文章的详情，假定变量 archive 已可用 #}
{# 如果 archive 未直接可用，可以使用 archiveDetail 标签获取，例如：
   {% archiveDetail currentArchive with name="Title" %}
   <h3>{{ currentArchive | truncatechars:20 }}</h3>
#}
<div>
    <h3>{{archive.Title | truncatechars:20 }}</h3>
    <p>{{archive.Description | truncatechars:50 }}</p>
</div>

这里，archive.Title 代表当前文章的标题。同样，| truncatechars:20 会确保标题在 20 个字符内显示，并自动添加省略号。

额外提示：处理包含 HTML 的标题

虽然文章标题通常是纯文本，但如果你的网站内容或某些特殊字段的“标题”可能包含 HTML 标签（例如，通过自定义字段输入），直接使用 truncatechars 可能会破坏 HTML 结构。针对这种情况，AnQiCMS 提供了 truncatechars_html 过滤器。它在截断时会智能地尝试保持 HTML 标签的完整性，防止出现未闭合的标签。

同时，为了确保包含 HTML 的内容能够被浏览器正确解析而不是作为纯文本显示，通常需要配合 |safe 过滤器。

{# 假设 item.RichTitle 是一个可能包含 HTML 的标题 #}
<h5>{{item.RichTitle | truncatechars_html:50 | safe }}</h5>

在这个例子中，truncatechars_html:50 会在保留 HTML 结构的前提下，将标题截断到 50 个字符，并添加省略号。| safe 则告诉模板引擎，这段内容是安全的 HTML，无需进行转义。

注意事项

  • 选择合适的截断长度： 截断的长度需要根据实际的页面设计和阅读习惯来决定。过短可能信息不足，过长则失去截断的意义。建议在实际环境中多进行测试和调整。
  • 中文字符处理： AnQiCMS 基于 Go 语言开发，其字符串处理天然支持 Unicode。这意味着 truncatechars 过滤器在处理中文字符时，一个汉字会被正确地计为一个字符，而不会出现半个汉字被截断的情况。
  • SEO 考量： 虽然截断文章标题主要为了前端显示美观，但请记住，页面的 title 标签（通常通过 TDK 标签设置）应当包含完整的、针对搜索引擎优化的标题。模板中的截断通常只影响列表或卡片等局部展示，而非页面的核心 SEO 标题。

通过合理运用 AnQiCMS 提供的 truncatechars 过滤器，我们可以轻松实现文章标题的字符截断和省略号的自动添加，从而优化网站的视觉呈现和用户体验。

常见问题 (FAQ)

  1. 问：如何在截断后显示的省略号字符（...）可以自定义为其他符号，例如 ... [更多]？ 答： 在 AnQiCMS 提供的 truncatechars 过滤器中，省略号（...）是其内置行为的一部分，文档中未提及直接配置或修改该默认省略号字符的参数。如果需要自定义省略号后的内容，可能需要通过更复杂的模板逻辑（如使用 if 条件判断字符串长度，然后手动拼接截断后的内容和自定义后缀），或者考虑自定义模板函数来实现，但这通常超出了简单过滤器能提供的功能。

  2. 问：如果我的文章标题本身就包含 HTML 标签，直接使用 truncatechars 截断后会出问题吗？ 答： 是的，如果文章标题包含 HTML 标签（例如 <strong>我的标题</strong>），直接使用 truncatechars 过滤器可能会按字符数直接截断标签，导致 HTML 结构被破坏，从而影响页面渲染。为了避免这种情况，AnQiCMS 提供了 truncatechars_html 过滤器。这个过滤器在截断时会尝试保持 HTML 标签的完整性。在使用 truncatechars_html 时，通常还需要配合 |safe