在日常的网站运营中，尤其是发布长篇内容时，为文章内容添加一个清晰的目录（或称“内容导航”）对于提升用户体验至关重要。它不仅能帮助访客快速了解文章结构，便捷地跳转到感兴趣的章节，还能在一定程度上优化页面的SEO表现。AnQiCMS提供了一个非常实用的功能，可以让我们在前端模板中轻松实现文章内容的目录展示。

理解AnQiCMS如何生成文章目录

AnQiCMS在处理文章内容时，会智能地解析内容中的标题标签（如<h1>、<h2>、<h3>等）。这些标题信息被提取出来，并以结构化的数据形式提供给前端模板使用，这就是我们所说的ContentTitles。这项功能尤其适用于文章详情页，能让访客对文章脉络一目了然。

在前端模板中显示文章目录的步骤

要在AnQiCMS的前端模板中显示文章目录，主要涉及定位模板文件、获取目录数据，以及循环遍历并渲染这些数据。

第一步：定位文章详情页模板

首先，我们需要找到文章详情页对应的模板文件。根据AnQiCMS的模板制作约定，文章详情页的模板通常位于模板目录下的{模型table}/detail.html，或者您在后台为特定文章或分类设置的自定义模板文件中。

第二步：使用archiveDetail标签获取ContentTitles数据

在文章详情页模板中，AnQiCMS提供了archiveDetail标签来获取当前文章的详细信息，其中就包含了ContentTitles。ContentTitles返回的是一个数组（Go语言中的slice），数组中的每一个元素都代表文章内容中的一个标题，并且包含以下几个关键信息：

  • Title: 标题的文本内容。
  • Tag: 标题的HTML标签类型，例如”H2”、”H3”等。
  • Level: 标题的层级，通常H1为1级，H2为2级，以此类推。
  • Prefix: 标题可能存在的前缀，比如自动生成的序号“1.”、“1.1.”等。

您可以通过以下方式获取这些数据：

{%- archiveDetail contentTitles with name="ContentTitles" %}

这里，我们将获取到的目录数据赋值给了contentTitles这个变量，方便后续使用。

第三步：通过循环遍历渲染目录

获取到contentTitles变量后，因为它是一个数组，我们需要使用AnQiCMS模板引擎的for循环标签来遍历它，并将每个标题信息渲染到页面上。在渲染时，我们可以结合每个标题的Tag和Level属性来控制目录的层级显示和样式。

例如，您可以这样构建您的文章目录：

{# 假设您在文章详情页的侧边栏或内容顶部显示目录 #}

{%- archiveDetail contentTitles with name="ContentTitles" %} {# 获取当前文章的目录数据，并赋值给 contentTitles 变量 #}
{%- if contentTitles %} {# 只有当存在目录数据时才显示目录框 #}
<div class="article-toc"> {# 这是目录的容器，您可以根据需要添加CSS类进行样式控制 #}
    <h3>文章目录</h3>
    <nav>
        <ul>
        {% for item in contentTitles %}
            {#
                item.Tag: 标题的HTML标签，如"H2", "H3"
                item.Level: 标题的层级，如2, 3
                item.Prefix: 标题前缀，如"1.", "1.1."
                item.Title: 标题的纯文本内容
                `slugify` 过滤器是假设存在的一个用于生成URL友好ID的过滤器。
                如果AnQiCMS模板中没有内置类似功能，您可能需要手动确保HTML内容中的标题有对应的ID，或者使用JavaScript在前端动态生成锚点。
            #}
            <li class="toc-item toc-{{ item.Tag | lower }}" style="margin-left: {{ (item.Level - 1) * 15 }}px;">
                <a href="#{{ item.Tag | lower }}-{{ item.Title | slugify }}">{{ item.Prefix }} {{ item.Title }}</a>
            </li>
        {% endfor %}
        </ul>
    </nav>
</div>
{%- endif %}

在上面的代码中，我们：

  • 使用{%- ... %}语法来移除标签生成的空白行，保持HTML输出的整洁。
  • 通过{% if contentTitles %}判断，确保只有当文章确实有标题时才显示目录框。
  • 为每个目录项添加了toc-item和toc-h2（或其他标签名）的CSS类，以及基于item.Level的内联margin-left样式，以便通过CSS轻松实现目录的层级感。
  • 为<a>标签的href属性生成了一个锚点链接。需要特别注意的是，为了使这个锚点链接有效，您的文章内容中的实际标题（如<h2>文章标题</h2>）也必须拥有对应的id属性，例如<h2 id="h2-文章标题">文章标题</h2>。AnQiCMS在内容渲染时通常会自动为标题添加ID，但具体生成规则您可能需要在实际测试中确认或查阅更详细的开发文档。为了生成URL友好的ID，我们示例中假设使用slugify过滤器，如果AnQiCMS不提供，您可能需要自行处理。

进一步优化与美化

  • CSS样式定制： 您可以根据您的网站设计，通过修改.article-toc、.toc-item、.toc-h2等CSS类，来调整目录的字体、颜色、背景、缩进等外观。
  • JavaScript交互： 为了更佳的用户体验，您还可以引入JavaScript代码来实现：
    • 平滑滚动： 点击目录项时，页面平滑滚动到对应章节。
    • 高亮当前章节： 当用户滚动页面时，自动高亮当前屏幕可视区域内的目录项。
    • 目录折叠/展开： 对于标题层级较多的文章，提供折叠和展开目录的功能。

通过以上步骤和优化建议，您可以轻松地在AnQiCMS的前端模板中实现功能完善且美观的文章目录，从而显著提升网站内容的阅读体验。

常见问题 (FAQ)

  1. 为什么我按照步骤添加了代码，但前端页面上目录没有显示出来？ 首先，请确认您的文章内容中是否实际使用了H1、H2、H3等标题标签。AnQiCMS的ContentTitles功能是基于这些标题标签来提取目录信息的。其次，检查您是否在文章详情页的模板文件中添加了代码，并且模板文件路径和代码本身没有语法错误。最后，如果您的文章内容是通过Markdown编辑器输入的，请确保后台的全局设置中已开启Markdown编辑器的支持。

  2. 点击目录项后，页面无法跳转到对应的标题位置，这是为什么？ 这种情况通常是因为目录链接的href属性（锚点）与文章内容中实际标题的id属性不匹配。为了使锚点跳转生效，每个目录项的<a>标签的href值（例如#h2-文章标题）必须与文章内容中对应标题的id属性值（例如<h2 id="h2-文章标题">文章标题</h2>）完全一致。AnQiCMS通常会智能地为内容中的标题生成ID，但在某些自定义情况下，您可能需要检查并确保它们匹配。如果AnQiCMS没有自动为标题添加ID，您可能需要通过修改文章内容，或在前端使用JavaScript动态为标题添加ID。

  3. 如何实现点击目录项后页面平滑滚动，而不是生硬地跳跃？ 实现平滑滚动需要借助前端JavaScript。您可以利用现代浏览器提供的scrollIntoView()方法的behavior: 'smooth'选项，或者引入轻量级的JavaScript库（如jQuery的animate()方法）来实现。您需要编写JavaScript代码来监听目录项的点击事件，然后获取目标锚点，并调用相应的滚动方法。同时，也可以结合监听页面滚动事件来高亮当前可见的目录项