在 AnQiCMS 文章详情页中自动生成并显示内容目录（ContentTitles）？

对于长篇内容，一个清晰的内容目录（或称“文章大纲”、“章节导航”）能够极大地提升用户的阅读体验。它不仅能帮助读者快速了解文章结构，还能让他们直接跳转到感兴趣的章节，从而提高内容的可读性和用户满意度。AnQiCMS 充分考虑到了这一需求，在文章详情页中提供了一种便捷的方式来自动生成并展示内容目录。

AnQiCMS 如何获取内容目录数据？

AnQiCMS 的强大之处在于其模板引擎能够智能地解析文章内容。当您在文章编辑时使用了标准的 HTML 标题标签（<h1>、<h2>、<h3>等，或在 Markdown 编辑器中使用了 #、##、### 等标记），AnQiCMS 会自动提取这些标题，并将它们整理成结构化的数据，供模板调用。

要获取这些结构化的内容目录数据，我们需要用到 archiveDetail 标签，并指定 name="ContentTitles"。这个标签会返回一个数组，其中包含了文章所有检测到的标题信息。

每个数组项都是一个对象，包含以下关键信息：

  • Title：标题的文本内容。
  • Tag：标题使用的 HTML 标签（例如 H1、H2）。
  • Level：标题的层级（H1 对应 Level 1，H2 对应 Level 2，以此类推），这对于目录的缩进和样式设计非常有用。
  • Prefix：如果标题内容中有序号（如 “1. 引言”），系统会自动提取这个前缀。

在模板中显示内容目录的步骤

要在文章详情页中展示内容目录，您需要对当前的详情页模板进行编辑。

第一步：找到并编辑文章详情页模板

通常情况下，文章详情页的模板文件位于您当前主题目录下的 archive/detail.html 或直接是 detail.html。如果您自定义了文章模型或特定文章的模板，请根据您的配置找到相应的模板文件。

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

在模板文件中，找到您希望显示内容目录的位置（通常在文章内容上方、侧边栏或文章内容内部的某个合适位置）。然后，使用 archiveDetail 标签将内容目录数据赋值给一个变量。例如，我们可以将其赋值给一个名为 contentTitles 的变量：

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

现在，contentTitles 变量就包含了文章中所有标题的结构化数据。

第三步：循环遍历 contentTitles 数据并渲染目录

由于 contentTitles 是一个数组，我们需要使用 for 循环来遍历它，并逐一显示每个标题。在循环中，您可以根据 item.Title、item.Tag 和 item.Level 来构建目录的 HTML 结构。

一个基本的目录显示代码可能如下所示：

{% archiveDetail contentTitles with name="ContentTitles" %}
{% if contentTitles %}
<div class="article-toc">
    <h4>文章目录</h4>
    <ul>
    {% for item in contentTitles %}
        {# 根据层级添加缩进样式，例如使用CSS类或内联样式 #}
        <li class="toc-level-{{ item.Level }}">
            <a href="#{{ item.Title|urlencode }}" title="{{ item.Title }}">
                {% if item.Prefix %}{{ item.Prefix }} {% endif %}{{ item.Title }}
            </a>
        </li>
    {% endfor %}
    </ul>
</div>
{% endif %}

代码解释：

  • {% if contentTitles %}：这是一个条件判断，确保只有当文章中存在标题时，内容目录才会被显示，避免空目录的出现。
  • <div class="article-toc">：为内容目录创建一个容器，方便后续的 CSS 样式控制。
  • <li class="toc-level-{{ item.Level }}">：这里利用 item.Level 为每个目录项生成一个独特的 CSS 类（例如 toc-level-1、toc-level-2），这让您可以轻松通过 CSS 为不同层级的标题设置不同的缩进、字体大小或颜色，从而直观地展示文章的层级结构。
  • href="#{{ item.Title|urlencode }}"：这行代码是为了实现点击目录项后页面能平滑滚动到对应章节。它假设文章内容中的标题（通过 Markdown 或富文本编辑器创建）会自动或通过自定义 JavaScript 生成对应的 id 属性，且 id 值与标题文本相关。|urlencode 过滤器用于确保标题中的特殊字符被正确编码，以便在 URL 中使用。
  • {% if item.Prefix %}{{ item.Prefix }} {% endif %}：如果标题带有数字或点号前缀，这里会将其显示出来。

完善内容目录的样式与交互

仅仅显示目录文本是不够的，您还需要通过 CSS 来美化目录，使其更具可读性。例如，您可以为不同 toc-level-X 的 <li> 元素设置不同的 margin-left 来实现缩进效果。

此外，为了实现点击目录项后平滑滚动到对应标题，并高亮当前阅读章节等高级交互，通常需要结合 JavaScript 来实现。这部分功能可以通过编写一些前端脚本来增强用户体验。例如，您可以监听目录项的点击事件，使用 scrollIntoView API 实现平滑滚动；或者在页面滚动时，检测当前可视区域的标题，并为对应的目录项添加 active 类。

通过以上步骤，您就能在 AnQiCMS 的文章详情页中自动生成并显示一个结构清晰、易于导航的内容目录了。

常见问题 (FAQ)

1. 为什么我的内容目录无法点击跳转到对应章节？

ContentTitles 标签主要负责提取文章中的标题文本和层级信息，但它并不会自动为这些标题生成 HTML id 属性。要实现点击跳转，您需要确保文章内容中的每个标题都有一个唯一的 id 属性。

  • 富文本编辑器： 部分高级富文本编辑器可能支持在编辑时为标题手动添加 id，或有插件能自动生成。
  • Markdown 编辑器： 如果您使用 Markdown 编辑器，很多 Markdown 解析器（如 GitHub Flavored Markdown）会自动为标题（#、## 等）生成 id 属性。例如，## 我的章节 可能会被解析为 <h2 id="我的章节">我的章节</h2>。如果您的 Markdown 解析器不支持，您可能需要手动添加，例如 ## 我的章节 {#my-chapter}。
  • JavaScript 辅助： 如果编辑器无法自动生成 id，您可以在前端通过 JavaScript 动态遍历文章内容中的所有标题（h1、h2 等），为它们生成唯一的 id，并更新目录中 <a> 标签的 href 属性。

2. 我的文章内容中明明使用了标题，为什么内容目录却不显示？

首先，请检查您的文章详情页模板中是否正确地添加了上述的代码片段。其次，请确保您在文章内容中使用的确实是标准的 HTML 标题标签（<h1> 到 <h6>）或 Markdown 语法中的对应标题标记（# 到 ######）。如果使用了其他自定义标签或仅仅是加粗文本，AnQiCMS 将无法识别并提取。最后，清除系统缓存并刷新页面，确保模板更改已生效。

3. 内容目录的层级（Level）是如何确定的，它有什么作用？

Level 属性是根据文章中标题标签的层级关系自动确定的。<h1> 对应 Level 1，<h2> 对应 Level 2，以此类推。这个 Level 属性在目录的样式设计中非常有用。您可以利用它为不同层级的标题设置不同的缩进、字体大小或颜色，从而在视觉上清晰地展示文章的逻辑结构和层次感，提升目录的可读性。例如，一级标题可以靠左对齐，二级标题向右缩进，三级标题进一步缩进