图片资源ID示例

您可以将图像插入站点中的任何页面，而不考虑目标图像文件所属的模块或组件版本。在本页中，您将学习如何根据图像所属的版本、组件和模块为图像宏分配正确的资源ID坐标，并将其与要嵌入图像的页面相关联。

有关块图像宏和内联图像宏的概述以及如何将它们添加到页面的分步说明，请参见：

如果您不熟悉 Antora 资源 ID 或其坐标，请参见
TIP

本页上的所有示例，无论它们用来演示概念的图像宏是什么，都适用于块图像宏和内联图像宏。

在模块中使用图像

使用图像宏引用的大多数图像可能属于与当前页面相同的模块和组件版本。在这种情况下，AsciiDoc 图像宏只需要将目标图像的资源ID的文件坐标作为一个值来分配。

NOTE

目标图像是当前页面引用的图像源文件。通过将目标图像的资源 ID 分配给当前页面内容中的内联或块图像宏来引用目标图像。当前页面是包含引用目标图像的图像宏的页面源文件。

目标图像文件坐标的结构取决于目标图像是存储在 images 族目录的根目录还是存储在 images 目录的子目录中。

Example 1. Example 1. current-page.adoc
image:target-image-filename.ext[optional attribute] (1)

image:path/to/target-image-filename.ext[optional attribute] (2)

image:./target-image-filename.ext[optional attribute] (3)
1 目标图像存储在 images 目录的根目录时的文件坐标。
2 当目标图像存储在 images 目录的子目录中时，目标图像的文件坐标。
3 当目标图像和当前页面存储在具有相同族相对目录路径的子目录中时，目标图像的文件坐标。这是一个高级用例。

下面几节提供了展示不同文件坐标结构的示例。

在图像目录根的文件坐标

当目标图像存储在 images 族目录的根目录时，文件坐标是目标图像的文件名和文件扩展名。记住，目标图像的文件坐标总是从 images 族目录的根计算得到的。

Example 2. Example 2. File coordinate in an image macro when the target image is stored at the root of an images directory
image::target-image-filename.ext[optional attribute]

让我们使用属于组件版本 colorado 5.2 的文件作为本节示例的基础。组件版本的源文件根据示例3中列出的一 组标准目录 分配给模块和系列。

Example 3. Example 3. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📄 wilderness-map.jpg
    📂 pagesAlian (4)
      📄 ridge.adoc
1 将组件版本定义为 colorado 5.2
2 定义一个名为 la-garita 的模块
3 在 images 目录放置图片文件
4 在 pages 目录创建页面

使用属于 la-garita 模块的两个文件，在 ridge.adoc 页面中插入 wilderness-map.jpg 图像。这意味着源文件 wilderness-map.jpg 是目标图像，ridge.adoc 是当前页面。

示例4显示了在 ridge.adoc 页面（当前页面）中引用 wilderness-map.jpg 图像（目标图像）的块状图像宏。当目标图像和当前页面属于同一个模块时，只需要在图像宏中输入目标图像资源ID的文件坐标。

Example 4. Example 4. ridge.adoc (current page)
The trailhead is north of town.

image::wilderness-map.jpg[]

在示例4中，wilderness-map.jpg 图像的文件坐标是 wilderness-map.jpg 。它的文件坐标仅由其文件名和文件扩展名组成，因为 wilderness-map.jpg 存储在 images 目录的根目录下。

如果目标图像存储在 images 目录的子目录中，则其文件坐标必须指定图像相对目录路径、文件名和文件扩展名。当目标图像存储在子目录中时，请参阅带有图像相对目录路径的文件坐标示例。

图像相对目录路径的文件坐标

当目标图像存储在 images 目录的子目录中时，在其文件坐标中需要目标图像的 images 相对目录路径。

Example 5. Example 5. File coordinate in an image macro when the target image is stored in a subdirectory of an images directory
image::path/to/target-image-filename.ext[optional attribute]

让我们使用示例6中所示的组件版本的页面作为本节示例的基础。

Example 6. Example 6. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📂 aerial (4)
        📄 skyline.jpg
    📂 pagesAlian (5)
      📄 ridge.adoc
1 将组件版本定义为 colorado 5.2
2 定义一个名为 la-garita 的模块
3 在 images 目录下放置图片
4 images 中的子目录，包含图像的源文件
5 在 pages 目录下创建页面

让我们从 ridge.adoc 引用 skyline.jpg 。正如您在上面的示例6中所看到的，图片和页面属于 la-garita 模块。在示例7中，ridge.adoc 页面（当前页面）中的图像宏引用了 skyline.jpg 图像（目标图像）。

Example 7. Example 7. ridge.adoc (current page)
= La Garita Ridgeline

image::aerial/skyline.jpg[]

正如示例7所示，skyline.jpg 的文件坐标是 aerial/skyline.jpg 。skyline.jpg 的文件坐标由其图像相对目录路径、文件名和文件扩展名组成，因为它存储在子目录 aerial 中。

TIP

在特殊情况下，如果目标图像的图像相对目录路径和当前页面的页面相对目录路径是平行的，则文件坐标的图像相对目录路径可以用相对路径标记 ./. 代替。

使用来自另一个模块的图像

当目标图像与当前页面不属于同一个模块时，必须在图像宏中指定目标图像的模块坐标和文件坐标。

Example 8. Example 8. Module and file coordinates assigned to an image macro
image:module:target-image-filename.ext[optional attribute] (1)

image:module:path/to/target-image-filename.ext[optional attribute] (2)
1 当目标图像与当前页面不属于同一模块时，为图像宏分配目标图像的模块坐标和文件坐标。当目标映像存储在映像族目录的根目录中时，目标映像的文件坐标是它的文件名和文件扩展名。
2 如果目标映像存储在 images 目录的子目录中，则目标映像的文件坐标必须指定其 images 相对目录路径、文件名和文件扩展名。

让我们使用示例9中显示的组件版本的文件作为本节示例的基础。

Example 9. Example 9. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita (2)
    📂 images (3)
      📂 aerial (4)
        📄 skyline.jpg
    📂 pagesAlian (5)
      📄 ridge.adoc
      📄 willow-creek.adoc
  📂 ROOT (5)
    📂 images (7)
      📄 peak.svg
    📂 pagesAlian (8)
      📄 index.adoc
      📄 ranges.adoc
1 将组件版本定义为 Colorado 5.2
2 定义一个名为 la-garita 的模块
3 在images目录中放置图像文件
4 包含图像源文件的 images 中的子目录
5 将后续文件定义为页面
6 定义根(ROOT)模块
7 将后续文件定义为图像
8 将后续文件定义为页面

根据上面示例9展示的 colorado 5.2 组件版本，让我们将 peak.svg 图像插入到 willow-creek.adoc 页面中。这意味着源文件 peak.svg 是目标图像， willow-creek.adoc 是当前页面。

示例10展示了 willow-creek.adoc 页面（当前页面）中的内嵌图像宏，引用了图像文件 peak.svg （目标图像）。将目标图像的资源ID的模块和文件坐标分配给图像宏。willow-creek.adoc 页面属于 la-garita 模块。peak.svg 图像属于 ROOT 模块。

Example 10. Example 10. Insert peak.svg (target image) into willow-creek.adoc (current page)
The elevation is image:ROOT:peak.svg[] 10,067 ft (3,068 m).

正如示例10所示，目标图像的模块坐标为 ROOT ，其文件坐标为 peak.svg 。

在示例11中，让我们将 skyline.jpg 图像（目标图像）嵌入到 ranges.adoc （当前页面）中。skyline.jpg 图像属于 la-garita 模块，ranges.adoc 属于 ROOT 模块。

Example 11. Example 11. Insert skyline.jpg (target image) into ranges.adoc (current page)
image::la-garita:aerial/skyline.jpg[]

正如示例11所示，目标图像的模块坐标为 la-garita ，其文件坐标为 aerial/skyline.jpg ，因为它存储在图像族目录的 aerial 子目录中。

使用来自另一个docs组件的图像

当目标图像和当前页面属于不同的文档组件时，您必须在图像宏中至少指定目标图像的组件、模块和文件坐标。您几乎总是要指定版本坐标。

Example 12. Example 12. Version, component, module, and file coordinates assigned to an image macro
image:version@component:module:target-image-filename.ext[optional attribute] (1)

image:version@component:module:path/to/target-image-filename.ext[optional attribute] (2)

image:component:module:file-coordinate-of-target-image.ext[optional attribute] (3)
1 当目标图像与当前页面不属于同一组件版本时，将为图像宏分配目标图像的版本、组件、模块和文件坐标。当目标映像存储在映像族目录的根目录中时，目标映像的文件坐标是它的文件名和文件扩展名。
2 如果目标映像存储在 images 目录的子目录中，则目标映像的文件坐标必须指定其 images 相对目录路径、文件名和文件扩展名。
3 如果没有指定版本坐标，Antora 将在运行时使用目标映像组件的最新版本来完成资源ID。此行为仅适用于目标图像和当前页面属于不同文档组件的情况。

让我们使用组件版本 colorado 5.2 (例13)和 wyoming 1.0 (例14)的文件作为本节示例的基础。

Example 13. Example 13. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 images (3)
      📄 peak.svg
    📂 pagesAlian (4)
      📄 index.adoc
      📄 ranges.adoc
1 将组件版本定义为 Colorado 5.2
2 定义根(ROOT)模块
3 将后续文件定义为图像
4 将后续源文件定义为页面
Example 14. Example 14. Directories and files assigned to wyoming 1.0
📄 antora.yml (1)
📂 modules
  📂 sierra-madre (2)
    📂 images (3)
      📄 panorama.png
    📂 pagesAlian (4)
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 将组件版本定义为 wyoming 1.0
2 定义 sierra-madre 命名模块
3 将后续文件定义为图像
4 将后续源文件定义为页面

使用示例13和示例14中的文件，让我们将 panorama.png 图像（目标图像）插入到 ranges.adoc（当前页面）中。图像 panorama.png 属于 wyoming 1.0 的 sierra-madre 模块。在示例15中，分配给图像宏的资源ID指定了目标图像的版本、组件、模块和文件坐标，因为目标图像属于 wyoming 1.0 组件版本，而当前页面属于 colorado 5.2 。

Example 15. Example 15. Insert panorama.png (target image) as a block image into ranges.adoc (current page)
image::1.0@wyoming:sierra-madre:panorama.png[]

正如示例15所示，目标图像的版本坐标为 1.0 ，其组件坐标为 wyoming ，模块坐标为 sierra-madre ，文件坐标为 panorama.png 。

现在，在示例16中，让我们将 peak.svg（目标图像）插入到 wilderness-areas.adoc 页面（当前页面）中。peak.svg 图像属于组件版本 colorado 5.2 。wilderness-areas.adoc 页面属于组件版本 wyoming 1.0 。

Example 16. Example 16. wilderness-areas.adoc (current page)
image:5.2@colorado::peak.svg[] Bridger Peak is in the Sierra Madre range.

请注意，在示例16中，资源 ID 中似乎缺少模块坐标 ROOT 。当在资源ID中指定组件坐标且目标图像属于 ROOT 模块时，模块坐标 ROOT 无需显式指定。但是，您仍然必须输入在模块坐标后跟随的冒号（:）。您可以在 peak.svg 文件坐标之前直接看到这个冒号。这个速记法仅在指定组件坐标且目标图像的模块坐标为 ROOT 的情况下有效。在所有其他需要模块坐标的情况下，都必须指定模块的名称。

您可能已经注意到，示例15和示例16中都指定了版本坐标。如果不指定版本，则 Antora 将在运行时使用目标图像最新组件版本的版本坐标完成目标图像的资源ID。

使用图像的最新版本

TIP

此行为仅适用于目标图像和当前页面属于不同文档组件的情况!

如果在资源 ID 中未指定版本，且目标图像和当前页面属于不同的文档组件，则 Antora 使用目标图像组件的最新版本的版本坐标在运行时完成资源 ID 。

让我们使用属于 colorado 5.2（上一节的示例13）、wyoming 1.0（上一节的示例14）和 wyoming 1.5（下面的示例17）的文件作为本节示例的基础。

Example 17. Example 17. Directories and files assigned to wyoming 1.5
📄 antora.yml (1)
📂 modules
  📂 sierra-madre
    📂 images
      📄 panorama.png
    📂 pagesAlian
      📄 elevation.adoc
      📄 wilderness-areas.adoc
1 定义组件版本为 wyoming 1.5

让我们从 index.adoc 引用 panorama.png 图像（目标图像）。index.adoc 属于 colorado 5.2 组件版本。有两个名为 panorama.png 的文件属于 wyoming 组件，sierra-madre 模块和图像家族。一个 panorama.png 属于版本 1.0 ，另一个 panorama.png 属于版本 1.5 。

示例18展示了从 index.adoc（当前页面）引用 panorama.png（目标图像）的块图像宏。请注意，目标图像的版本坐标未指定。

Example 18. Example 18. index.adoc (current page)
image::wyoming:sierra-madre:panorama.png[]

当 Antora 运行时，它将根据其版本排序规则和最新版本标准，确定 wyoming 组件的最新版本为 wyoming 1.5 。由于示例 18 未指定版本坐标，Antora 将使用最新 wyoming 组件的版本坐标（即 1.5 ）完成分配给图像宏的资源 ID 。

WARNING

仅当在资源 ID 中未指定版本坐标且目标图像和当前页面属于不同组件时，才适用于链接到最新版本。如果未在资源 ID 中指定版本和组件坐标，则 Antora 假定目标图像属于与当前页面相同的组件版本，并使用当前页面的版本和组件坐标来完成目标图像的资源ID。

使用来自相同组件的其他版本的图像

当当前页面和目标图像属于同一组件，但目标图像属于组件的不同版本时，您将指定版本、模块(如果它与当前页面的模块不同)和文件坐标。

Example 19. Example 19. current-page.adoc
image:version@module:file-coordinate-of-target-image.ext[optional attribute] (1)

image:version@file-coordinate-of-target-image.ext[optional attribute] (2)
1 当目标映像与当前页面不属于同一版本和模块时，将为映像宏分配目标映像的版本、模块和文件坐标。
2 当目标图像与当前页面不属于同一版本时，将为图像宏分配目标图像的版本和文件坐标。

让我们使用组件版本 colorado 5.2 (例20)和组件版本 colorado 6.0 (例21)的文件作为本节示例的基础。

Example 20. Example 20. Directories and files assigned to colorado 5.2
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 images
      📄 wilderness-map.jpg
    📂 pagesAlian
      📄 index.adoc
      ...
1 将组件版本定义为 colorado 5.2
Example 21. Example 21. Directories and files assigned to colorado 6.0
📄 antora.yml (1)
📂 modules
  📂 la-garita
    📂 pagesAlian
      📄 index.adoc
      📄 ridge.adoc
      📄 willow-creek.adoc
1 将组件版本定义为 colorado 6.0

请注意，示例20中的 colorado 5.2 组件版本具有图像 wilderness-map.jpg 。但是，示例21中的 colorado 6.0 没有这样的图像文件。

让我们从属于 colorado 6.0 组件版本的 ridge.adoc 页面（当前页面）中引用属于 colorado 5.2 的图像 wilderness-map.jpg（目标图像）。这两个资源都属于 la-garita`模块。在示例22中，图像 `wilderness-map.jpg（目标图像）嵌入到页面 ridge.adoc（当前页面）中。

Example 22. Example 22. ridge.adoc (current page) in colorado 6.0
image::5.2@wilderness-map.jpg[]

如例22所示，目标图像的版本坐标为 5.2 ，其文件坐标为 wilderness-map.jpg 。