附件
附件是可下载的资源，例如PDF或示例项目的ZIP归档文件，这些资源存储在一个附件家族目录中。虽然不太常见，但可以将示例文件提升为附件，使其可下载。
用于附件的AsciiDoc xref宏
可以使用AsciiDoc xref宏和附件的资源ID从页面、其他资源和导航文件中进行交叉引用。
示例1展示了带有附件完全限定资源ID的xref宏结构。
xref:version@component:module:attachment$file-coordinate-of-attachment.ext[可选链接文本]至少，xref宏由宏的前缀（xref:）、目标附件的资源ID和一组方括号（[]）组成。 目标附件是当前页面引用的附件源文件。通过将其资源ID分配给当前页面内容中的xref宏来引用目标附件。 当前页面是包含引用目标附件的xref宏的页面源文件。
在引用附件时，xref宏的结构和行为与分配页面的资源ID时基本相同，但有三个不同之处：
您需要指定目标附件的资源ID坐标的数量取决于目标附件与当前页面的组件版本和模块的关系。
创建到附件的链接
-
在您的IDE或文本编辑器中打开要创建到附件的交叉引用的页面。在这一步和随后的步骤中，让我们假设您已经打开了名为satellites.adoc的页面的源文件。 satellites.adoc 是当前页面。
示例 2. satellites.adoc（当前页面）= 系统卫星 该组维护着五颗卫星。
-
选择当前页面内容流中要显示指向目标附件链接的位置。输入xref宏的名称，后跟一个冒号，
xref:。示例 3. satellites.adoc（当前页面）该组维护着五颗卫星。 查看 xref:
-
让我们引用一个名为flight-patterns.pdf的附件的源文件。 flight-patterns.pdf 和 satellites.adoc 属于同一组件版本和模块。因此，在示例 4中，只需要将目标附件的
attachment$家族坐标和文件坐标分配给xref宏。在宏的前缀之后，输入目标附件的资源ID。示例 4. satellites.adoc（当前页面）该组维护着五颗卫星。 查看 xref:attachment$flight-patterns.pdf
flight-patterns.pdf 的文件坐标仅由其文件名和文件扩展名组成，因为它存储在attachments目录的根目录中。目标附件的文件坐标始终是从存储附件的attachments家族目录的根目录计算出来的。如果目标附件存储在attachments目录的子目录中，则其文件坐标必须指定attachments相对目录路径、文件名和文件扩展名。（请参见示例 8）
-
在目标附件的资源ID之后，输入一个左方括号（
[），然后是一个右方括号（]）。示例 5. satellites.adoc（当前页面）该组维护着五颗卫星。 查看 xref:attachment$flight-patterns.pdf[]
-
让我们给xref宏添加一些链接文本，因为与页面不同，附件没有默认的引用文本。在宏的方括号之间指定您希望在发布当前页面时显示为指向目标附件的链接的文本。
示例 6. satellites.adoc（当前页面）该组维护着五颗卫星。 查看 xref:attachment$flight-patterns.pdf[飞行模式时间表]
链接文本是可选的。有关更多信息，请参阅附件链接文本。
-
在xref宏的右方括号（
]）之后，继续输入您的内容。示例 7. satellites.adoc（当前页面）该组维护着五颗卫星。 查看 xref:attachment$flight-patterns.pdf[飞行模式时间表] 以获取更多详细信息。
就是这样！您已经使用AsciiDoc xref宏从当前页面satellites.adoc创建了一个指向目标附件flight-patterns.pdf的交叉引用。
虽然前面的步骤使用了属于同一组件版本和模块的目标附件和当前页面，但您可以从任何页面引用站点中的任何附件，无论它属于哪个组件版本和模块。当目标附件和当前页面不属于同一模块或组件版本时，您需要在指定附件时始终添加attachment$家族坐标到xref宏的目标附件资源ID中。附加资源ID坐标。
xref:attachment$target-attachment-filename.ext[链接文本] (1)
xref:attachment$path/to/target-attachment-filename.ext[链接文本] (2)
xref:attachment$./target-attachment-filename.ext[链接文本] (3)
xref:module:attachment$file-coordinate-of-attachment.ext[链接文本] (4)
xref:version@component:module:attachment$file-coordinate-of-attachment.ext[链接文本] (5)
xref:component:module:attachment$file-coordinate-of-attachment.ext[链接文本] (6)
xref:version@module:attachment$file-coordinate-of-attachment.ext[链接文本] (7)
xref:version@attachment$file-coordinate-of-attachment.ext[链接文本] (8)| 1 | 当目标附件和当前页面属于同一组件版本和模块时，将目标附件的attachment$家族坐标和文件坐标分配给xref宏。当目标附件存储在attachments家族目录的根目录时，目标附件的文件坐标是其文件名和文件扩展名。 |
| 2 | 如果目标附件存储在attachments目录的子目录中，则目标附件的文件坐标必须指定其attachments相对目录路径、文件名和文件扩展名。 |
| 3 | 当目标附件和当前页面存储在具有平行家族相对目录路径的子目录中时，可以使用相对路径标记（./）缩写目标附件的文件坐标。这是一个高级用例。 |
| 4 | 当目标附件和当前页面不属于同一模块，但属于同一组件版本时，将目标附件的模块、attachment$和文件坐标分配给xref宏。 |
| 5 | 当目标附件和当前页面不属于同一组件版本时，将目标附件的版本、组件、模块、attachment$和文件坐标分配给xref宏。 |
| 6 | 如果未指定版本坐标，Antora将在运行时使用目标附件组件的最新版本来完成资源ID。此行为仅适用于目标附件和当前页面不属于同一组件版本的情况。 |
| 7 | 当目标附件不属于当前页面的版本和模块，但属于当前页面的同一组件时，将目标附件的版本、模块、attachment$和文件坐标分配给xref宏。 |
| 8 | 当目标附件不属于当前页面的版本，但属于当前页面的同一组件和模块时，将目标附件的版本、attachment$和文件坐标分配给xref宏。 |
附件的链接文本
您可以在AsciiDoc xref宏的方括号之间指定链接文本，或者可以将xref宏的方括号留空。 示例9 显示了一个被分配附件资源ID的xref宏。在xref宏的方括号之间没有指定链接文本。
下载 xref:attachment$practice-project.zip[] 来尝试一下！因为在示例9中的xref宏没有分配链接文本，Antora将显示xref目标作为链接文本。
下载 attachment$practice-project.zip 来尝试一下！
与页面不同，附件没有默认引用文本，因此最好始终指定链接文本以确保良好的阅读体验。
您可以通过在xref宏的方括号之间输入文本来指定链接文本。
下载 xref:attachment$practice-project.zip[示例项目] 来尝试一下！当在xref宏中指定链接文本时，Antora会在发布页面中将指定内容显示为附件的链接。
包含附件
您可以使用include指令将附件包含到AsciiDoc页面或部分中，而不是链接到附件。唯一的限制是文件必须是文本文件。将文本文件存储为附件可以在仍可下载的同时包含它。
以下是显示如何将附件文本包含到页面中的完整语法。
include::version@component:module:attachment$name-of-file.ext[可选属性]attachment$ 段告诉Antora在附件文件夹中查找文件。如果附件与页面位于同一组件版本和模块中，则目标可以以 attachment$ 段开头。
include::attachment$name-of-file.ext[可选属性]您可以在xref宏和include指令中同时使用同一个附件。