本文翻译自官方文档：https://confluence.atlassian.com/pages/viewpage.action?pageId=182682099

将目录宏添加到页面，可以帮助读者直接跳到他们正在寻找的信息。

这个宏非常适用于：

  • 包含大量信息的大页面

  • 将页面中的章节标题构建到一个整洁的目录中

这个宏很受欢迎，因为它可以帮助您浏览冗长的页面。该宏通过在标题1下嵌套标题2并逐步缩进来组织目录，如下图所示。

截图：目录宏整齐地组织了冗长的博客内容。


使用Table of Contents宏

在页面中添加Table of Contents宏：

  1. 从编辑器工具栏中，选择插入(Insert) > 其它宏（Other Macros）。
  2. 从Confluence content类别中选择Table of Contents。
  3. 输入一些参数。
  4. 点击Insert。 

然后，您可以发布您的页面以查看宏的效果。

截图：设置目录宏的参数。


修改宏参数

宏参数用于设置宏的行为。

要更改宏参数：

  1. 在编辑器中，点击宏占位符并选择“编辑（Edit）”。
  2. 根据需要设置参数，然后选择“插入（Insert）”。

这是此宏中可用的参数列表。

参数

默认值

描述

Output Type
(type)

list

  • list — 列表样式，生成典型的列表类型目录。
  • flat — 平铺样式，生成一系列水平排放的链接。

Display Section Numbering
(outline) 

clear

选中此参数，可以显示标题的编号，例如：1.1、1.2、1.3。

List Style
(style) 

disc

为每个目录条目选择样式。您可以使用任何有效的CSS样式。 例如：

  • none — 无样式
  • circle —  样式是圆形
  • disc — 样式是实心圆。这是典型的项目符号列表，用于此示例中的列表。
  • square — 样式是方形
  • decimal — 按编号 (1, 2, 3, 4, 5)
  • lower-alpha — 按字母顺序排列 (a, b, c, d, e)
  • lower-roman — 按小写罗马数字 (i, ii, iii, iv, v, vi)
  • upper-roman — 按大写罗马数字（I、II、III、IV、V、VI）

Heading Indent
(indent) 


根据CSS设置缩进列表。输入10px，将依次缩进每级标题10px。例如，1级标题将缩进10像素，2级标题将再缩进10像素。

Separator
(separator) 

brackets

此参数仅适用于flat列表。您可以输入以下任何值：

  • brackets — 每一项都用方括号括起来：[ ]。
  • braces — 每一项都用大括号括起来：{}。
  • parens — 每项都用括号括起来： ( )。
  • pipe — 每一项都由管道符分隔：|。
  • anything — 每一项都由您输入的值来分隔。您可以输入任何文本作为分隔符，例如“***”。如果使用自定义分隔符，请注意文本显示与输入的内容完全连接，没有额外的空格来进一步分隔字符。

Minimum Heading Level
(minLevel) 

1

选择最高的标题级别以开始您的目录列表。例如，输入2将包括级别2和更低的标题，但不包括级别1的标题。

Maximum Heading Level
(maxLevel) 

7

选择要包括的最低标题级别。例如，输入2将包括级别1和2，但不包括级别3及以下的标题。

Include Headings
(include) 


根据特定条件过滤要包括的标题。您可以使用通配符。有关构建正则表达式字符串的示例，请参阅Sun's Regex documentation。


Exclude Headings
(exclude) 


根据特定条件过滤要排除的标题。您可以使用通配符。有关构造正则表达式字符串的示例，请参阅Sun's Regex documentation。


Printable
(printable) 

checked

默认情况下，目录宏设置为可打印。如果清除该复选框，则打印页面时目录将不可见。


CSS Class Name
(class) 


如果您的CSS样式表中有自定义目录宏样式，请使用此参数输出具有指定类属性的<div>标签内的目录宏。

Absolute URL
(absoluteUrl )

默认情况下，目录宏中的链接是指向当前页面的相对URL。如果选中，目录中的链接将是完整的URL。当您在另一个页面中包含一个带有目录的页面，并且想要控制链接应该将用户带到哪里时，此设置很有用。

如果Confluence存储格式或wiki标记中使用的参数名称与浏览器中使用的参数名称不同，则会在参数名下方用括号列出，例如（example）。

例子

以下示例基于此目录：

过滤后的目录

此示例过滤标题以包括包含“Favourite”的标题，但排除以“Things”结尾的标题。该列表采用大写罗马数字样式。

参数值
List Styleupper-roman
Include Headings
Favourite.*
Exclude Headings
.*Things

目录的显示效果如下：

平铺目录

此示例过滤呈现方括号中包含“Unknown”的平铺目录（默认是list列表）。

ParameterValue
Output Type
flat
Maximum Heading Level
2
Include Headings
Unknown.*

目录的显示效果如下：

其它添加方式

用键盘输入添加宏

输入左大括号{，然后输入宏名称的几个起始字符，就可以看到一个相关的宏列表。

通过wiki标记添加宏

当您想在编辑器之外添加宏时，这非常有用。例如作为侧边栏、空间页眉或页脚中的自定义内容。

Macro name: toc

Macro body: None.

此示例显示了一个列表类型的目录。

{toc:printable=true|style=square|maxLevel=2|indent=5px|minLevel=2|class=bigpink|exclude=[1//2]|type=list|outline=true|include=.*}
CODE

此示例显示了一个平铺类型的目录。

{toc:printable=true|maxLevel=2|minLevel=2|class=bigpink|exclude=[1//2]|type=flat|outline=true|separator=pipe|include=.*}
CODE

Notes and known issues

  • 在模板中使用目录宏时，在预览模板本身时会看到错误。但是目录宏适用于人们从模板创建的页面 - 目录在他们保存页面后显示。（这是因为模板不是页面，并且目录宏仅适用于页面。）
  • 目录宏仅显示页面或博文内容。 例如，您不能在评论中使用它来添加目录。