在AnQiCMS前台模板中动态展示文档内容标题：ContentTitles的循环与应用

在使用AnQiCMS进行网站内容运营时，我们经常需要为用户提供更好的阅读体验和导航便利，其中一个非常实用的功能就是自动生成文章目录（Table of Contents）。AnQiCMS在这方面考虑得非常周到，它能自动提取文档内容中的标题，并以 ContentTitles 的形式提供给前台模板使用。今天，我们就来深入了解如何在你的AnQiCMS前台模板中循环并展示这些 ContentTitles。

深入理解 ContentTitles：文档内容标题的魔力

首先，让我们明确 ContentTitles 是什么。当你在AnQiCMS后台编辑文档内容时，通常会使用H1、H2、H3等标题标签来组织文章结构。AnQiCMS非常智能地将这些内容中的标题自动解析并收集起来，生成一个包含所有层级标题的列表，这就是 ContentTitles。它不是文章的固定字段，而是根据文章正文内容动态生成的。

这个功能对于提升用户体验和SEO都有着显著的帮助：

  • 提升用户体验：读者可以一目了然地看到文章的整体框架，快速定位到感兴趣的章节。
  • 优化SEO：一个结构清晰、带有目录的文章更容易被搜索引擎理解，有助于提升文章的排名。

ContentTitles 返回的是一个数组（或者说是列表），列表中的每一个元素都是一个包含标题信息的对象。每个对象通常包含以下几个关键属性：

  • Title：标题的实际文本内容。
  • Tag：标题所使用的HTML标签，例如 h2、h3。
  • Level：标题的层级，数字越小表示层级越高（例如，h1的Level是1，h2的Level是2）。
  • Prefix：如果标题有序号前缀（例如“1.1 AnQiCMS简介”），这里会包含“1.1”。

如何获取 ContentTitles 数据源

在AnQiCMS的前台模板中，要获取 ContentTitles 数据，我们需要用到 archiveDetail 标签。这个标签专门用于获取当前文档的详细信息。

如果你正在一个文档详情页，比如 detail.html，那么 archiveDetail 标签会自动获取当前页面的文档数据。我们只需要通过 name="ContentTitles" 参数，就能指定我们想要获取的是文档的标题列表。

例如，你可以这样来定义一个变量 contentTitles，让它承载从当前文档中提取的所有标题：

{% archiveDetail contentTitles with name="ContentTitles" %}
    {# 在这里，contentTitles 变量就已经包含了文档的标题列表 #}
    {% comment %} 后续我们将在这个标签内部，或者在其作用域内使用 contentTitles {% endcomment %}
{% endarchiveDetail %}

如果你希望获取特定ID文档的 ContentTitles，也可以通过 id 参数来指定：

{% archiveDetail otherContentTitles with name="ContentTitles" id="10" %}
    {# otherContentTitles 变量将包含ID为10的文档的标题列表 #}
{% endarchiveDetail %}

循环与展示：将标题呈现在页面上

一旦我们通过 archiveDetail 标签获取到了 ContentTitles 列表，接下来就是如何在模板中循环遍历这个列表，并将其美观地展示出来。AnQiCMS的模板引擎支持类似Django模板的语法，因此我们可以使用 for 循环标签来处理。

通常，我们会将这些标题组织成一个文章目录。以下是一个基本的代码示例，展示了如何循环 contentTitles 并显示每个标题：

{% archiveDetail contentTitles with name="ContentTitles" %}
    {% if contentTitles %} {# 确保有标题才显示目录 #}
        <div class="article-toc">
            <h3>文章目录</h3>
            <ul>
                {% for item in contentTitles %}
                    {# 利用item.Level来控制缩进，这里简单地乘以一个像素值 #}
                    <li class="{{item.Tag}}" style="margin-left: {{ item.Level|add:-1|mul:20 }}px;">
                        {# 通常会为每个标题生成一个可点击的链接，并指向文章正文对应的锚点 #}
                        {# 注意：这里的锚点（#heading-{{ loop.index }}）需要在文章正文中手动添加对应ID，或通过JavaScript动态生成 #}
                        <a href="#heading-{{ loop.index }}">
                            {% if item.Prefix %}{{item.Prefix}} {% endif %}{{item.Title}}
                        </a>
                    </li>
                {% endfor %}
            </ul>
        </div>
    {% endif %}
{% endarchiveDetail %}

在这段代码中，我们：

  • 使用 {% if contentTitles %} 来判断 contentTitles 是否为空，避免在没有标题时显示一个空目录。
  • 使用 {% for item in contentTitles %} 遍历每一个标题对象。
  • item.Tag 可以作为CSS类名，方便你根据标题标签（如 h2、h3）进行不同的样式设计。
  • item.Level 可以用于控制目录的缩进，模拟标题的层级结构。我们利用AnQiCMS内置的过滤器，将层级减1（因为h1通常不需要缩进），再乘以一个像素值，实现视觉上的层次感。
  • item.Prefix 可以选择性地显示标题前的序号。
  • item.Title 则是标题的实际文字。

请注意，上述示例中的 href="#heading-{{ loop.index }}" 部分是一个常用的实践，用于创建文章目录的内部跳转链接。要使这些链接真正发挥作用，你需要在文章正文的实际标题元素上添加对应的 id 属性。例如，如果 loop.index 是 1，那么文章正文的第一个标题（比如一个 <h2> 标签）就需要有 id="heading-1"。这通常需要你在后台编辑内容时手动添加，或者通过一些前端脚本或后端处理来动态实现。

结合实际应用：更进一步的思考

  1. 样式和结构：你可以为 article-toc 和 li 元素定义丰富的CSS样式，例如设置不同的字体大小、颜色，或者使用边框、背景色来美化目录。item.Tag 和 item.Level 提供了很好的粒度来控制不同层级标题的显示效果。
  2. 交互式目录：通过结合少量的JavaScript，你可以让文章目录更具交互性。例如，当用户滚动页面时，目录中当前阅读到的标题会自动高亮显示；或者点击目录项时，页面平滑滚动到相应位置。
  3. 内容编辑规范：为了让 ContentTitles 功能发挥最大效用，在后台编辑文章时，请务必养成良好的习惯，使用适当的HTML标题标签（H1、H2、H3等）来组织内容结构，而不是仅仅通过加粗、改变字号来模拟标题。规范的HTML结构是AnQiCMS正确提取 ContentTitles 的基础。

通过这些灵活的标签和简单的循环逻辑，你可以轻松地在AnQiCMS网站的前台模板中实现动态的文章目录，极大地提升网站内容的专业性和用户友好度。

常见问题解答 (FAQ)

  1. 问：为什么我的文章内容已经使用了H标签，但 ContentTitles 却不显示任何内容？

    • 答：这可能是因为你的文章内容中没有使用标准的 H1 到 H6 标签来定义标题，或者这些标题内容非常短。AnQiCMS会根据后台内容编辑器中识别到的HTML标题标签来生成 ContentTitles。请检查你的文章内容，确保标题是作为HTML的 <h2>>、<h3>> 等结构而非仅通过样式来呈现的。同时，如果文章标题极短或者只有一个，系统可能也会认为无需生成目录。

  2. 问：我能否控制 ContentTitles 只显示特定层级的标题，例如只显示H2和H3？

    • 答：完全可以。在模板循环 contentTitles 列表时，你可以使用AnQiCMS模板引擎的 if 逻辑判断标签，根据 item.Level 或 item.Tag 属性进行筛选。例如，只显示H2和H3标题，你可以这样修改循环内部的代码： 
      
{% for item in contentTitles %}
    {% if item.Level == 2 or item.Level == 3 %}
        <li class="{{item.Tag}}" style="margin-left: {{ item.Level|add:-1|mul:20 }}px;">
            <a href="#heading-{{ loop.index }}">
                {% if item.Prefix %}{{item.Prefix}} {% endif %}{{item.Title}}
            </a>
        </li>
    {% endif %}
{% endfor %}

  3. 问：ContentTitles 生成的目录项点击后，如何才能跳转到文章正文对应的位置？

    • 答：要实现点击目录项跳转，你需要确保文章正文中的每个实际标题元素都带有一个唯一的 id 属性，并且这个 id 与目录项的 href 属性值相匹配。一种常见的做法是，在你的 archiveDetail 标签输出 Content 内容时，通过一些后端处理或JavaScript动态为正文中的H标签添加ID。例如，如果你的目录项链接是 href="#heading-1"，那么文章正文的第一个标题就需要有 id="heading-1"。你可以使用JavaScript来遍历正文中的H