资源ID坐标

坐标语法和顺序

资源ID包含五个坐标:版本、组件、模块、族和文件。Antora 根据文件、标准目录集和组件版本描述符中的信息为这些坐标赋值，从而为源文件构造资源ID。您可以使用分配给资源的资源 ID 坐标序列从任何其它资源引用资源，而不管每个资源属于哪个组件版本。

图1 显示了坐标类型及其在完全限定资源 ID 中的顺序。

Figure 1. Figure 1. Fully qualified resource ID

完全限定资源 ID 是指定了其所有坐标的资源 ID 。您可能不需要经常使用资源的完全限定资源 ID 。引用资源时指定的资源ID坐标的数量取决于：

当前页面相对于目标资源的组件版本和模块，
目标资源的族，和
用于引用目标资源的 AsciiDoc 语法。

目标资源是通过在 AsciiDoc 宏、include 指令或其他语法中指定其资源 ID 来引用的资源源文件。当前页是包含引用目标资源的 AsciiDoc 语法的页文件。

Figure 2. Figure 2. The current page, with the filename satellites.adoc, containing an xref macro referencing a resource

在图2中，satellites.adoc 是当前页面，文件名为 modes.adoc 的资源是被 xref 宏引用的目标资源。以下部分描述了如何确定目标资源的每个坐标的值以及什么时候使用每个坐标。

版本坐标

版本坐标与目标资源所属的组件的版本值相同。版本的值被分配给版本键。版本键可以在定义了资源的组件版本 antora.yml 文件中指定或者在剧本中指定了 Antora 从哪里收集组件版本文件的内容源上。

版本坐标应该用于引用同一组件的不同版本或不同组件的特定版本中的资源。当在资源ID中输入版本坐标时，它应该始终是第一个坐标，并以 @ 号结束。如果未指定组件坐标，则将使用当前组件。如果在没有指定版本坐标的情况下指定了组件坐标，则将选择该组件的最新版本。

组件坐标

组件坐标是目标资源所属的组件的名称。组件名称由定义资源组件版本的 antora.yml 文件中的 name 键指定。

当目标资源和当前页面属于不同的文档组件时，必须使用组件坐标。组件名在资源 ID 中的模块坐标之前输入，后面直接跟一个冒号( : )。如果在没有指定版本坐标的情况下指定了组件坐标，则将选择该组件的最新版本。

模块坐标

模块坐标是目标资源所属的模块的名称。模块名来源于存储资源的模块目录。

当目标资源和当前页面属于不同的模块时，必须使用模块坐标。如果族坐标存在，则在族坐标之前输入模块名;如果族坐标不存在，则在文件坐标之前输入模块名。模块名后面直接跟一个冒号( : )。

当模块坐标以内置 AsciiDoc 宏的名称结束时，例如 link, kbd, menu 等，您可能必须通过在宏名称前加上反斜杠来转义该部分坐标。例如，模块坐标(如 monolink 和 redmenu )可能需要在资源 ID 中以 mono\link 和 red\menu 的形式输入。

族坐标

族坐标标识目标资源所属的族名称。该族名称来自存储资源的 family 目录。在构建资源 ID 时，从族名称的末尾去除 s ，并将其替换为美元符号($)。有效的族坐标是 page$, image$, partial$, example$, 和 attachment$ 。

是否需要在资源 ID 中输入族坐标取决于：

目标资源的族，和
用于引用目标资源的 AsciiDoc 语法。

例如，如果使用 xref 宏引用一个页面，则不需要 page$ 族坐标，因为当没有指定族坐标时，xref 宏默认会应用它。下表根据引用的资源和引用资源的语法列出了何时需要族坐标。

被引用的资源引用资源的语法是否需要族坐标

被引用的资源	引用资源的语法	是否需要族坐标
Attachment	Xref宏	是的，需要 `attachment$` 坐标。
Example	include 指令	是的，需要 `example$` 坐标
Image	块图像宏	不，不需要族坐标。参见添加块图像和图像资源ID示例。
内联图像宏	不，不需要族坐标。参见添加内联图像和图像资源ID示例。
Xref宏	是的，需要 `image$` 坐标。
Page	Xref宏	不，不需要族坐标。请参阅 Xref宏和页面链接。
include 指令	不，不需要族坐标。参见 include Page 。
Partial	include 指令	是的，需要 `partial$` 坐标。参见 include Partial

Attachment

Xref宏

是的，需要 attachment$ 坐标。

Example

include 指令

是的，需要 example$ 坐标

Image

块图像宏

不，不需要族坐标。参见添加块图像和图像资源ID示例。

内联图像宏

不，不需要族坐标。参见添加内联图像和图像资源ID示例。

Xref宏

是的，需要 image$ 坐标。

Page

Xref宏

不，不需要族坐标。请参阅 Xref宏和页面链接。

include 指令

不，不需要族坐标。参见 include Page 。

Partial

include 指令

是的，需要 partial$ 坐标。参见 include Partial

文件坐标

文件坐标指定目标资源的源文件相对于族目录的路径。文件坐标必须指定资源的文件扩展名，除非：

目标资源没有文件扩展名，如 Dockerfile 和
目标资源是部分或示例资源。

存储在族目录根目录中的资源的文件坐标是资源的源文件的名称及其文件扩展名。

Example 1. Example 1. Resource stored at root of family directory

📂 modules
  📂 admin
    📂 pagesAlian (1)
      📄 modes.adoc (2)

1	pages 族目录
2	存储在 pages 目录根目录的页

例如，modes.adoc 的文件坐标是 modes.adoc 。因为它存储在 pages 族目录的根目录中。

如果目标资源位于族目录的子目录中，则文件坐标必须指定目标资源的族相对目录路径。

Example 2. Example 2. Resource stored in subdirectory of family directory

📂 modules
  📂 admin
    📂 pagesAlian
      📄 modes.adoc (1)
      📂 fields (2)
        📂 level (3)
          📄 routes.adoc (4)
          📄 terrain.adoc (5)

1	页面存储在 `pages` 目录的根部
2	`pages` 目录中的子目录
3	`fields` 中的子目录
4	存储在 `level` 的子目录中
5	存储在 `level` 的子目录中

如示例2中所示，页面 terrain.adoc 存储在 level 子目录中。terrain.adoc 的文件坐标是 fields/level/terrain.adoc 。如果 modes.adoc（当前页面）引用 terrain.adoc（目标资源），则目标资源的资源 ID 中指定的文件坐标是 fields/level/terrain.adoc 。如果 terrain.adoc（当前页面）引用 modes.adoc（目标资源），则目标资源的资源 ID 中指定的文件坐标是 modes.adoc。请记住，目标资源的文件坐标始终是从族目录计算的。

当目标资源和当前页面都位于家族目录的同一个子目录中时，可以使用相对路径标记 ./ 来缩写目标资源文件坐标的族相对目录路径。

Example 3. Example 3. Resources stored in the same subdirectory

📂 modules
  📂 admin
    📂 pagesAlian
      📂 fields
        📂 level
          📄 routes.adoc (1)
          📄 terrain.adoc (2)

1	存储在 level 子目录中的页面
2	存储在 level 子目录中的页面

如示例3中所示，页面 routes.adoc 和 terrain.adoc 都存储在 level 子目录中。如果 routes.adoc（当前页面）引用 terrain.adoc（目标资源），则目标资源的资源 ID 中指定的文件坐标可以指定为 ./terrain.adoc，而不是 fields/level/terrain.adoc。