图像

图像是存储在图像族目录中的源文件，例如照片、图表和屏幕截图。使用 AsciiDoc 图像宏，可以将图像插入任何页面或部分，而不管它属于哪个模块或组件版本。AsciiDoc 支持 PNG 、JPG 、 SVG 和 GIF (静态和动画)图像文件格式。

块和内联图像宏

有两种 AsciiDoc 图像宏类型，块和内联。块图像显示为页面上的离散元素。

Example 1. Example 1. Block image macro

This is a paragraph.

image::resource-id-of-target-image.ext[]

内联图像显示在另一个元素的流中，例如段落或边栏块。

Example 2. Example 2. Inline image macro

This sentence contains an inline image:resource-id-of-target-image.ext[] image.

从图像宏链接到资源

使用 xref 元素属性，您可以引用页面、附件、元素，甚至是页面中嵌入的图像中的另一个图像。

Example 3. Example 3. xref element attribute assigned to an image macro

image::resource-id-of-target-image.ext[xref=resource-id.ext]

添加块图像

在此页面上，您将学习：

Asciidoc 块图像宏的结构。
如何使用其资源ID插入块图像。

Asciidoc 块图像宏

AsciiDoc 块状图像宏用于将图像源文件嵌入到部分或页面中。块状图像宏接受 PNG、JPG、SVG和GIF（静态和动画）图像文件的 Antora 资源 ID 作为值。

当 Antora 运行时，块图像宏引用的图像文件被嵌入并显示为发布页面中的离散元素。例如，该段下面的 SVG 图像使用块图像宏嵌入到该页中。

块图像宏观结构

例1显示了块图像宏的结构。

Example 4. Example 1. Block image macro

This is a paragraph.

image::resource-id-of-target-image.ext[optional attribute,optional attribute] (1)

This is another paragraph.

1	块图像由宏名称后的两个冒号( `::` )指定。它的前面是一个空行，它自己在一行中输入，然后后跟一个空行。

至少，一个块状图像宏由宏前缀（ image:: ）、目标图像的资源ID和一组方括号（[]）组成。目标图像是当前页面引用的图像源文件。将其资源ID分配给当前页面内容中的内联或块状图像宏以引用目标图像。当前页面是包含引用目标图像的图像宏的页面源文件。

下面更详细地描述示例1中显示的块图像宏的每个部分。

image::: 块图像宏以宏的名称 image 开头，后面跟着两个冒号( :: )。
resource ID of target image: 图像宏接受图像源文件的资源ID作为其值。该值直接在跟随宏名称（ image:: ）的第二个冒号之后输入。需要指定目标图像的资源ID坐标取决于目标图像相对于当前页面的组件版本和模块。当从图像宏引用图像时，您无需在目标图像的资源ID中包含 image$ 族坐标。它会在运行时自动应用。
[optional attribute,optional attribute]: 块图像宏在目标图像的资源ID的末尾用一组方括号( [] )完成。可以将括号保留为空，也可以将一个或多个可选属性分配为方括号内的逗号分隔列表。

下一节嵌入块图像将逐步解释如何设置块图像宏。

嵌入块图像

让我们分解块图像宏和使用块图像宏将图像(目标图像)插入页面(当前页面)所需的资源ID坐标。

在您的 IDE 或文本编辑器中打开要插入图像的页面。在此练习中，我们打开了文件 satellites.adoc 。 satellites.adoc 是当前页面。
在 satellites.adoc 中，让我们嵌入块状图像 console.svg 。
在新行开头，输入宏的名称，后面跟着两个冒号 image:: 。确保在前面的元素(例如段落或源块)和放置图像宏的行之间有一个空白行。
Example 5. Example 2. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::
```
在两个冒号后直接输入目标图像文件的资源ID。在这个例子中，console.svg 和 satellites.adoc 属于同一个组件版本和模块，并且目标图像存储在 images 族目录的根目录中。因此，只需要将 console.svg 的文件名和扩展名分配为块状图像宏的值。
Example 6. Example 3. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::console.svg
```
注意，console.svg 的资源ID不包括它的族坐标。Antora 自动将 image$ 族坐标应用于分配给图像宏的资源 ID 。
在目标图像的资源ID后面，直接输入一个左方括号([)，然后输入一个右方括号(])。
Example 7. Example 4. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::console.svg[]
```
在这个例子中，我们没有对块图像宏应用任何可选属性;但是，您可以将一个或多个属性指定为方括号内的逗号分隔列表。
在最后一个方括号(])后按 kbd:[Enter]两次，以在图像宏后插入新行。
Example 8. Example 5. satellites.adoc (current page)
```
After scanning your badge, you should see this screen.

image::console.svg[]

Enter the satellite position after the prompt.
```

就是这样!您已经使用 AsciiDoc 块图像宏完成了将目标图像( console.svg )插入当前页面( satellites.adoc )的工作。

了解更多

要了解如何嵌入属于其它模块、文档组件和版本的图像，请参见图像资源ID示例。

添加行内图像

在此页面上，您将学习：

Asciidoc 内联图像宏的结构。
如何使用其资源ID插入内联图像。

AsciiDoc 内联图像宏

AsciiDoc 内联图像宏用于将图像的源文件嵌入到部分或页面中。内联图像宏接受 PNG、JPG、SVG和GIF (静态和动画)图像文件的 Antora 资源ID作为值。

当 Antora 运行时，内联图像宏引用的图像文件被嵌入到另一个元素(如侧边栏块)的流中，并显示在发布的页面中。例如，这是一个使用内联图像宏嵌入到该段落中的 SVG 图像。

内联图像宏结构

示例1显示了内联图像宏的结构。

Example 9. Example 1. Inline image macro

This sentence contains an inline image:resource-id-of-target-image.ext[optional attribute,optional attribute] image. (1)

1	将内联图像输入到内容流中。它由宏名称后面的单个冒号( `:` )指定。

至少，内联图像宏由宏前缀（）组成。目标图像是当前页面引用的图像源文件。将其资源 ID 分配给当前页面内容中的内联或块状图像宏以引用目标图像。当前页面是包含引用目标图像的图像宏的页面源文件。

下面将更详细地描述示例1中显示的内联图像宏的每个部分。

image:: 内联图像宏以宏的名称 image 开头，后面跟着一个冒号( : )。
resource ID of target image: 图像宏接受图像源文件的资源 ID 作为其值。该值直接在跟随宏名称（ image: ）的冒号之后输入。需要指定目标图像的资源ID坐标取决于目标图像相对于当前页面的组件版本和模块。当从图像宏引用图像时，您无需在目标图像的资源ID中包含 image$ 族坐标。它会在运行时自动应用。
[optional attribute,optional attribute]: 内联图像宏在目标图像的资源 ID 的末尾用一组方括号( [] )完成。可以将括号保留为空，也可以将一个或多个可选属性分配为方括号内的逗号分隔列表。

下一节嵌入内联图像将逐步解释如何设置内联图像宏。

嵌入内联图像

让我们分解内联图像宏和使用内联图像宏将图像(目标图像)插入页面(当前页面)所需的资源ID坐标。

在您的 IDE 或文本编辑器中打开要插入图像的页面。在此练习中，我们打开了文件 satellites.adoc 。 satellites.adoc 是当前页面。
在 satellites.adoc 中，让我们嵌入内联图像 blue-dot.svg 。选择您想要目标图像显示的当前页面的内容流中的位置。输入宏的名称后跟一个冒号（ image: ）。
Example 10. Example 2. satellites.adoc (current page)
```
Look for the image:
```
在冒号后直接输入目标镜像文件的资源ID。在本例中，blue-dot.svg 和 satellites.adoc 属于相同的组件版本和模块，目标映像存储在 images 族目录的根目录中。因此，只需要将 blue-dot.svg 的文件名和扩展名分配为内联图像宏的值。
Example 11. Example 3. satellites.adoc (current page)
```
Look for the image:blue-dot.svg
```
注意，blue-dot.svg 的资源 ID 不包括它的族坐标。Antora 自动将 image$ 族坐标应用于分配给图像宏的资源 ID 。
在目标图像的资源 ID 后面，直接输入一个左方括号( [ )，然后输入一个右方括号( ] )。
Example 12. Example 4. satellites.adoc (current page)
```
Look for the image:blue-dot.svg[]
```
在这个例子中，我们没有对内联图像宏应用任何可选属性;但是，您可以将一个或多个属性指定为方括号内的逗号分隔列表。
在最后一个方括号( ] )后按一次kbd:[SPACE]空格键，在宏后面插入一个空格，然后继续输入内容。
Example 13. Example 5. satellites.adoc (current page)
```
Look for the image:blue-dot.svg[] on the console.
```

就是这样!您已经使用 AsciiDoc 内联图像宏将目标图像( blue-dot.svg )插入到当前页面( satellites.adoc )中。

了解更多

要了解如何嵌入属于其他模块、文档组件和版本的图像，请参见图像资源ID示例。

图片资源ID示例

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

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

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

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

在模块中使用图像

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

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

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

Example 14. 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 15. 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 16. 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 17. 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 18. 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 19. 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 20. Example 7. ridge.adoc (current page)

= La Garita Ridgeline

image::aerial/skyline.jpg[]

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

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

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

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

Example 21. 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 22. 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 23. 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 24. 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 25. 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 26. 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 27. 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 28. 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 29. 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 30. 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 31. 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 32. 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 33. 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 34. 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 35. Example 22. ridge.adoc (current page) in colorado 6.0

image::5.2@wilderness-map.jpg[]

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

图片中的资源链接

通过将 xref 属性分配给内联或块图像宏，可以创建从图像到页面、附件、图像或元素的链接。

Xref元素属性

在块图像宏和内嵌图像宏的属性列表中可以设置 xref 元素属性。xref 属性是可选的。无论是将其分配给块图像宏还是内嵌图像宏，它的结构和行为方式都是相同的。

xref 属性接受一个可发布资源（页面、附件或图像）的资源 ID 作为值。

Example 36. Example 1. Set the xref attribute and assign it a resource ID

image::an-image.jpg[xref=version@component:module:family$file.ext]

它还接受当前页面中指定的元素的ID。当分配给 xref 属性时，元素ID必须以散列符号( # )作为前缀。

Example 37. Example 2. Set the xref attribute and assign is an element ID

image::an-image.gif[xref=#fragment]

当您的站点发布并且访问者选择嵌入的图像时，它们将链接到已发布资源的 URL 或跳转到对应于指定元素 ID 的当前已发布页面中的锚点。

xref 属性是一个命名属性。如果您在图像宏中设置位置属性，例如 alt文本 、宽度或高度，请在设置 xref 或任何其他命名属性之前在属性列表中分配它们。

Example 38. Example 3. Optional positional and named attributes assigned to an image macro

image:an-image.svg[The image alt text,xref=version@component:module:family$file.ext,title="A tooltip for the image"]

在图像宏的属性列表中，位置属性和命名元素属性用逗号分隔。

从图像链接到页面

要从嵌入图像中引用页面，请在属性列表中设置 xref 属性，后面跟着等号( = )，然后是目标页面的资源ID。需要指定多少个目标页面的资源ID坐标取决于相对于当前页面的目标页面的组件版本和模块。

Example 39. Example 4. current-page.adoc

image::console.svg[xref=modes.adoc] (1)

1	分配给 `xref` 的资源 ID 只指定页面的文件坐标，因为在本例中，假设当前页面和目标页面属于相同的组件版本和模块。

示例4中显示的块图像宏将把图像 console.svg 嵌入到当前页面中，并创建从图像到目标页面的已发布 URL 的链接。

您还可以在页面的资源 ID 末尾附加片段以链接到页面内的元素。在示例5中，一个对应于 modes.adoc 内容中设置的元素ID protocols 的片段附加到 modes.adoc 的资源 ID 的末尾。

Example 40. Example 5. current-page.adoc

image::console.svg[xref=modes.adoc#protocols]

您还可以链接到当前页面中的元素ID。

从图像链接到附件

要从嵌入的图像引用附件，请在属性列表中设置 xref 属性，后面跟着等号( = )，然后是目标附件的资源ID。确保在分配给 xref 属性的值中指定了族坐标 attachment$ 。

示例6显示了一个内联图像宏，它在宏的属性列表中设置了三个位置属性，后面是命名的 xref 属性。为 xref 属性分配附件的资源ID。

Example 41. Example 6. current-page.adoc

Select the image:red-dot.jpg[Red circle,40,40,xref=telemetry:attachment$flight-patterns.pdf]. (1) (2)

1	位置属性是可选的。如果您确实在图像宏上设置了一个或多个位置属性，请在设置 `xref` 或任何其他命名属性之前在属性列表中分配它们。在本例中，位置属性 alt、width 和 height 按照图像宏接受的顺序设置。
2	分配给 `xref` 的资源ID指定目标附件的模块、`attachment$` 和文件坐标，因为在本例中，假设目标附件属于与当前页面不同的模块。当资源是附件时，总是需要 `attachment$` 坐标。

示例6中所示的内联图像宏将把图像 red-dot.jpg 嵌入到当前页面中，并创建一个从图像到目标附件的已发布 URL 的链接。

从图像到当前页面元素的深度链接

要在当前页面中引用元素，请将元素的 ID 分配给 xref 属性。当您将元素 ID 分配给 xref 属性时，在其前面加上哈希符号( # )。示例7显示了一个块图像宏，其中 xref 属性分配了一个元素 ID ，该元素 ID 对应于当前页面上的一个 ID 。

Example 42. Example 7. current-page.adoc

image::panorama.png[xref=#elevation] (1)

The range can be traversed by Cottonwood Pass, Independence Pass, or Hagerman Pass.

[#elevation] (2)
== Pass elevations

The passes usually open in late spring.

1	在属性列表中设置 `xref` 属性，后面是等号( `=` )、散列符号( `#` )，然后是与当前页面中分配给元素的 ID 相对应的元素 ID 。
2	在当前页面上设置并分配给某个节的元素 ID 。

例7中显示的块图像宏将把图像 panorama.png 嵌入到当前页面中，并创建一个链接，从图像到当前页面上的 Pass elevations 章节的开头。

了解更多

有关其它图像宏属性和有关元素 id 的更多信息，请参阅 AsciiDoc 文档。