附件

附件是可下载的资源，如 pdf 或样例项目的 ZIP 归档，它们存储在附件族目录中。虽然不常见，但示例文件也可以提升到附件中以使其可下载。

用于附件的 AsciiDoc xref宏

可以使用 AsciiDoc xref 宏和附件的资源ID从页面、其他资源和导航文件中交叉引用附件。

示例1显示了带有附件的完全限定资源ID的 xref 宏的结构。

Example 1. Example 1. Xref macro structure for referencing an attachment
xref:version@component:module:attachment$file-coordinate-of-attachment.ext[optional link text]

作为最基本的使用方法， xref 宏由宏的前缀（ xref: ）、目标附件的资源ID和一组方括号（[]）组成。目标附件是当前页面引用的附件源文件。在当前页面的内容中，通过将其资源ID分配给 xref 宏来引用目标附件。当前页面是包含引用目标附件的 xref 宏的页面源文件。

在引用附件时，xref 宏的结构和行为与为其分配页面的资源 ID 时非常相似，但有三个不同之处：

  • 当将附件分配给 xref 宏时，附件的资源 ID 必须指定 attachment$ 族坐标，否则 Antora 将在运行时假定资源ID是页面的资源ID。

  • 片段(元素ID)不能附加到附件的资源ID的末尾。

  • 附件没有默认的引用文本。如果没有在 xref 宏中指定链接文本，则发布附件的 URL 将显示为当前页面中的链接文本。

需要指定多少个目标附件的资源 ID 坐标取决于与当前页面相关的目标附件的组件版本和模块。

创建到附件的链接

让我们分解 xref 宏和资源 ID 坐标，您需要从当前正在编辑的页面(当前页面)创建对附件(目标附件)的交叉引用。

  1. 在您的 IDE 或文本编辑器中，打开要在其中创建附件交叉引用的页面。在这一步和随后的步骤中，假设您已经打开了一个名为 satellites.adoc 的页面的源文件。satellites.adoc 是当前页面。

    Example 2. Example 2. satellites.adoc (current page)
    = System Satellites

The group maintains five satellites.

  2. 在当前页面的内容流中选择您希望显示目标附件链接的位置。输入 xref 宏的名称，后面跟着一个冒号 xref: 。

    Example 3. Example 3. satellites.adoc (current page)
    The group maintains five satellites.
See the xref:

  3. 让我们引用一个名为 flight-patterns.pdf 的附件的源文件。flight-patterns.pdf 和 satellites.adoc 属于相同的组件版本和模块。因此，只需要将目标附件的 attachment$ 族坐标和文件坐标分配给示例4中的 xref 宏即可。在宏的前缀后面直接输入目标附件的资源 ID 。

    Example 4. Example 4. satellites.adoc (current page)
    The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf

    由于 flight-patterns.pdf 存储在附件( attachments )目录的根目录下，因此它的文件坐标仅由其文件名和文件扩展名组成。目标附件的文件坐标始终从存储附件的附件目录的根目录计算。如果目标附件存储在附件目录的子目录中，则它的文件坐标必须指定附件相对目录路径，文件名和文件扩展名。（示例8提供了一个示例。）

  4. 直接在目标附件的资源 ID 之后，输入一个左方括号( [ )，然后输入一个右方括号( ] )。

    Example 5. Example 5. satellites.adoc (current page)
    The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf[]

  5. 让我们给 xref 宏添加一些链接文本，因为与页面不同，附件没有默认的引用文本。在宏的方括号之间，指定您想要在当前页面发布时作为链接显示到目标附件的文本。

    Example 6. Example 6. satellites.adoc (current page)
    The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf[flight pattern schedule]

    链接文本是可选的。有关详细信息，请参阅附件的链接文本。

  6. 在 xref 宏的结束方括号( ] )之后，继续输入您的内容。

    Example 7. Example 7. satellites.adoc (current page)
    The group maintains five satellites.
See the xref:attachment$flight-patterns.pdf[flight pattern schedule] for more details.

就这样！您使用 AsciiDoc xref 宏从当前页面 satellites.adoc 创建了对目标附件 flight-patterns.pdf 的交叉引用。

虽然前面的步骤使用属于相同组件版本和模块的目标附件和当前页面，但您可以从任何页面引用站点中的任何附件，而不管它属于哪个组件版本和模块。当目标附件和当前页面不属于同一模块或组件版本时，您需要指定额外的资源 ID 坐标。

Example 8. Example 8. Resource ID patterns for a target attachment in relation to a current page
xref:attachment$target-attachment-filename.ext[link text] (1)

xref:attachment$path/to/target-attachment-filename.ext[link text] (2)

xref:attachment$./target-attachment-filename.ext[link text] (3)

xref:module:attachment$file-coordinate-of-attachment.ext[link text] (4)

xref:version@component:module:attachment$file-coordinate-of-attachment.ext[link text] (5)

xref:component:module:attachment$file-coordinate-of-attachment.ext[link text] (6)

xref:version@module:attachment$file-coordinate-of-attachment.ext[link text] (7)

xref:version@attachment$file-coordinate-of-attachment.ext[link text] (8)
1 当目标附件和当前页面属于相同的组件版本和模块时，将目标附件的 attachment$ 族坐标和文件坐标分配给 xref 宏。当目标附件存储在附件族目录的根目录中时，目标附件的文件坐标是它的文件名和文件扩展名。
2 如果目标附件存储在附件目录的子目录中，则目标附件的文件坐标必须指定其附件的相对目录路径、文件名和文件扩展名。
3 当目标附件和当前页面存储在具有并行相对族目录路径的子目录中时，目标附件的文件坐标可以使用相对路径标记（./）进行缩写。这是一种高级用法。
4 当目标附件和当前页面不属于同一个模块，但它们属于同一个组件版本时，将目标附件的模块、attachment$ 和文件坐标分配给 xref 宏。
5 当目标附件和当前页面不属于同一组件版本时，将目标附件的版本、组件、模块、attachment$ 和文件坐标分配给 xref 宏。
6 如果没有指定版本坐标，那么 Antora 将在运行时使用目标附件组件的最新版本来完成资源 ID 。此行为仅在目标附件和当前页面不属于同一组件版本时才适用。
7 当目标附件不属于与当前页面相同的版本和模块，但它确实属于与当前页面相同的组件时，将目标附件的版本、模块、attachment$ 和文件坐标分配给 xref 宏。
8 当目标附件不属于与当前页面相同的版本，但它确实属于与当前页面相同的组件和模块时，将目标附件的版本、attachment$ 和文件坐标分配给 xref 宏。

附件链接和页面链接有许多相似之处。请参阅 创建页面链接 以获取更多示例，展示如何构建目标资源的资源 ID ，当它不属于当前页面所在的模块，组件版本或版本时。只需记住，将 attachment$ 族坐标始终添加到目标附件的资源 ID 中，然后将其分配给 xref 宏。

附件的链接文本

您可以在 AsciiDoc xref 宏的方括号之间指定链接文本，也可以将 xref 宏的方括号保留为空。示例9展示了为附件分配资源 ID 的 xref 宏。在 xref 宏的方括号之间没有指定链接文本。

Example 9. Example 9. Xref macro without specified link text
Download xref:attachment$practice-project.zip[] to try it out!

因为示例9中的 xref 宏没有分配链接文本，所以 Antora 将在发布的页面中将附件的 URL 显示为链接文本。

Download https://docs.example.com/component/version/module/_attachments/practice-project.zip to try it out!

当您不指定链接文本时，Antora 将使用已发布附件的 URL 进行显示。(与页面不同，附件没有默认的引用文本。)

可以通过在 xref 宏的方括号之间输入链接文本来指定链接文本。

Example 10. Example 10. Xref macro with specified link text
Download xref:attachment$practice-project.zip[the sample project] to try it out!

当在 xref 宏中指定链接文本时，Antora 将指定的内容显示为已发布页面中指向附件的链接。

包含一个附件

您可以使用 include 指令将附件包含到一个 AsciiDoc 页面或部分中，而不是链接到附件。唯一的限制是文件必须是文本文件。将文本文件存储为附件允许在包含它的同时仍可下载。

下面是展示如何将附件文本包含到页面中的完整语法。

include::version@component:module:attachment$name-of-file.ext[optional attributes]

attachment$ 段告诉 Antora 在附件文件夹中查找该文件。如果附件与页面位于相同的组件版本和模块中，则目标可以从 attachment$ 段开始。

include::attachment$name-of-file.ext[optional attributes]

可以在 xref 宏和 include 指令中使用相同的附件。

了解更多

还可以在 导航文件 和 图像宏 中创建指向附件的链接。