在网站运营中，如何高效且美观地展示文章列表或卡片，同时避免冗长的内容占据过多空间，是一个普遍的挑战。特别是在首页、分类页或搜索结果页，我们常常需要截取文章的一部分内容作为摘要，并在其末尾优雅地加上省略号，以引导访客点击查看详情。AnQiCMS 充分考虑到了内容运营者的这一需求，通过灵活的模板标签和强大的过滤器，让这一操作变得非常简单和直观。

AnQiCMS如何处理文章摘要内容？

首先，了解 AnQiCMS 如何获取文章的摘要内容是关键。在 AnQiCMS 的后台，当你“添加文档”时，会有一个专门的“文档简介”字段。这个字段就是为了让你手动填写文章的简要介绍而设计的。如果这个字段没有填写，AnQiCMS 也非常智能，它会自动从“文档内容”中提取前150字作为默认的文档简介。这意味着，无论你是否手动编写摘要，AnQiCMS 都能为你提供一份基础的摘要内容。

在模板中，我们通常通过 archiveList 标签获取文章列表，每个文章项（item）都包含一个 Description 字段，这便是我们用来展示摘要的核心内容。

利用模板过滤器实现摘要截取和省略号添加

AnQiCMS 基于 Go 语言开发，但其模板引擎语法设计得非常贴近 Django 模板，易于理解和上手。为了实现摘要的截取和省略号的自动添加，AnQiCMS 内置了一系列功能强大的“过滤器”（Filters），这些过滤器能够直接作用于模板变量，实现多种文本处理需求。

1. 针对纯文本内容的截取：truncatechars 和 truncatewords

当你的摘要内容是纯文本，不包含任何 HTML 标签时，可以使用 truncatechars 或 truncatewords 过滤器。

  • truncatechars（按字符数截取） 这个过滤器会按照你指定的字符数量来截取文本，并在截取位置自动添加省略号（“…”）。它会严格按照字符数来计算，即使截断了半个单词，也会直接截取。

    例如，如果你希望摘要只显示前50个字符：

    {{ item.Description|truncatechars:50 }}

    无论是英文、中文还是其他语言，truncatechars 都能准确地按字符数进行截取，并自动处理省略号。

  • truncatewords（按单词数截取） 如果你更倾向于保持单词的完整性，避免在单词中间截断，那么 truncatewords 是更好的选择。它会按照你指定的单词数量截取文本，并在末尾添加省略号。

    例如，如果你想显示前20个单词：

    {{ item.Description|truncatewords:20 }}

    这个过滤器尤其适合英文内容，能让截取后的摘要更具可读性。

2. 针对富文本内容的智能截取：truncatechars_html 和 truncatewords_html

很多时候，文章的简介或摘要可能包含一些简单的 HTML 标签，比如加粗、斜体或者链接。如果直接使用 truncatechars 或 truncatewords 截取这样的富文本，可能会导致 HTML 结构被破坏，页面显示异常。为了解决这个问题，AnQiCMS 提供了专门用于处理 HTML 内容的过滤器：truncatechars_html 和 truncatewords_html。

这两个过滤器不仅能按字符或单词数量截取内容并添加省略号，更重要的是，它们会在截取时智能地修复被破坏的 HTML 标签，确保输出的 HTML 结构依然完整有效。使用这些过滤器时，为了让浏览器正确解析 HTML，我们还需要配合 |safe 过滤器。

  • truncatechars_html（按字符数截取 HTML 内容） 例如，截取包含 HTML 的文章内容的前100个字符：

    {{ item.Content|truncatechars_html:100|safe }}

    这里 item.Content 通常代表文章的完整内容字段，如果你希望用文章正文而非“文档简介”生成摘要，这个过滤器就显得尤为重要。

  • truncatewords_html（按单词数截取 HTML 内容） 例如，截取包含 HTML 的文章内容的前50个单词：

    {{ item.Content|truncatewords_html:50|safe }}

    同样，|safe 确保 HTML 内容不会被转义为纯文本。

实际操作与选择

在实际应用中，选择哪个过滤器取决于你的具体需求和摘要内容的特性：

  1. 摘要内容来源： 如果你主要使用“文档简介”字段，并且通常将其作为纯文本处理，那么 truncatechars 或 truncatewords 会很合适。
  2. 内容是否包含 HTML： 如果摘要可能包含样式或链接，或者你直接从文章正文 Content 字段截取摘要，那么 truncatechars_html 或 truncatewords_html 则是必选，它们会确保页面布局的整洁和正确性。
  3. 截取粒度： 按照固定字符长度还是按单词数截取，取决于设计上的偏好。例如，在中文语境下，truncatechars 往往更为常用，因为中文字符没有明显的“单词”概念，按字符数截取更符合直观。

通过在模板中简单地修改标签，比如将 {{ item.Description }} 改为 {{ item.Description|truncatechars:80 }}，AnQiCMS 就能帮助你轻松实现文章摘要的固定字符数截取和省略号添加，大大提升了内容列表页的阅读体验和美观度。

常见问题 (FAQ)

1. 为什么我使用了 truncatechars 过滤器后，摘要中的 HTML 标签被破坏了？

这是因为像 truncatechars 和 truncatewords 这样的过滤器是为纯文本设计的。当它们截取包含 HTML 标签的文本时，可能会在标签的中间截断，导致 HTML 结构不完整。为了避免这种情况，你应该使用专门处理 HTML 的过滤器，例如 truncatechars_html 或 truncatewords_html，并确保在输出时加上 |safe 过滤器，以允许浏览器解析 HTML。

2. 默认的省略号“…”可以更改为其他符号吗？

AnQiCMS 的 truncatechars 和 truncatewords 系列过滤器默认在截断后添加的是标准的省略号“…”。目前，这些过滤器没有直接提供参数来修改省略号的具体文本。通常情况下，如果需要修改，可能需要通过修改底层代码或在模板中进行二次处理（例如，先截取，再用 replace 过滤器替换默认省略号），但为了保持系统稳定性和未来升级的便利性，建议遵循默认设置。

3. 我的文章摘要是如何生成的？AnQiCMS 是自动截取正文还是有专门的摘要字段？

AnQiCMS 提供两种方式生成文章摘要：

  1. 手动填写： 在后台“添加文档”或“编辑文档”页面，有一个“文档简介”字段。如果你在此处填写了内容，系统会优先使用这个字段作为文章摘要。
  2. 自动提取： 如果你没有填写“文档简介”，AnQiCMS 会智能地从“文档内容”字段中自动提取前150个字符作为文章摘要。 在模板中，这个摘要内容通常通过 item.Description 变量来获取。