包含一个示例

可以使用AsciiDoc包含指令和示例的资源ID将示例插入到站点中的任何页面或部分中。

如果您不熟悉Antora资源ID及其坐标，请参阅：

示例的AsciiDoc包含指令

AsciiDoc包含指令将示例源文件中的内容插入到部分或页面中。包含指令接受示例、部分和页面的Antora资源ID作为值。

示例1展示了带有示例的完全限定资源ID的包含指令的结构。因为包含指令用于引用其他资源，所以在将示例的资源ID分配给包含指令时，必须在示例的资源ID中指定example$家族坐标。

示例1. 分配了示例的完全限定资源ID的包含指令 
include::version@component:module:example$file-coordinate-of-target-example.ext[可选属性]

包含指令由指令前缀（include::）、目标示例的资源ID和一组方括号（[]）组成。您可以在方括号内指定可选属性，作为由逗号分隔的键值对。 目标示例 是当前页面引用的示例的源文件。通过将其资源ID分配给当前页面的包含指令，引用目标示例。 当前页面 是包含引用目标示例的包含指令的页面源文件。

当Antora运行时，从目标示例中插入的内容将插入到当前页面中，插入位置为包含指令输入的位置。插入到当前页面后，目标示例的内容将被转换。这意味着当前页面的组件版本、模块、属性和其他元素将被应用于或可能影响从目标示例中包含的内容。

将示例插入页面

让我们分解AsciiDoc包含指令和资源ID坐标，以便将一个目标示例插入到当前页面中。

  1. 在您的IDE或纯文本编辑器中，打开您想要插入示例的页面。在这一步和随后的步骤中，让我们假设您已经打开了文件phases.adoc。

    示例文件通常被插入到源代码块中。示例2展示了在当前页面中设置了标题和分配语言的源代码块。

    示例2. phases.adoc（当前页面） 
    .第一个测试阶段
[,js]
----

----

    当前页面phases.adoc属于组件版本mapper 8.0和模块testing，如 示例3所示。

    示例3. 分配给mapper 8.0的目录和文件 
    📄 antora.yml (1)
📂 modules
  📂 testing (2)
    📂 examples (3)
      📄 timer.js
    📂 pages (4)
      📄 index.adoc
      📄 phases.adoc
    1 将组件版本定义为mapper 8.0
    2 定义testing模块
    3 将后续文件定义为示例
    4 将后续文件定义为页面

  2. 在当前页面中，选择要插入示例内容的行。在该行的开头，输入指令名称，后跟两个冒号，include::。

    示例4. phases.adoc（当前页面） 
    .第一个测试阶段
[,js]
----
include::
----

  3. 让我们引用目标示例timer.js，从当前页面。将目标示例的资源ID分配给包含指令。因为timer.js和phases.adoc属于相同的组件版本和模块（参见 示例3），因此只需要指定目标示例的 example$家族坐标和文件坐标。

    示例5. phases.adoc（当前页面） 
    .第一个测试阶段
[,js]
----
include::example$timer.js
----

    timer.js示例的文件坐标是timer.js。目标示例的文件坐标仅包含其文件名和文件扩展名，因为timer.js存储在examples目录的根目录中。

    默认情况下，当未指定坐标时，包含指令会假定家族坐标为page$。如果您忘记使用example$坐标，Antora将报告错误，因为它将无法找到示例。

  4. 在目标示例的资源ID之后，用一对方括号（[]）完成指令。

    示例6. phases.adoc（当前页面） 
    .第一个测试阶段
[,js]
----
include::example$timer.js[]
----

    包含指令的方括号可以包含一组可选属性，如lines、tag或tags。这些属性以逗号分隔的键值对形式输入。有关lines、tag和tags语法的详细信息，请参阅AsciiDoc包含指令文档。

就是这样！您已经创建了一个包含指令，将目标示例插入到当前页面中。

前面的说明向您展示了如何在页面中插入示例的最常见情况——目标示例和当前页面属于相同的组件版本和模块，并且目标示例存储在examples文件夹的根目录中。然而，如果目标示例存储在examples目录的子目录中，其文件坐标必须指定 示例相对目录路径以及其文件名和文件扩展名。

示例7. current-page.adoc 
include::example$target-example-filename.ext[] (1)

include::example$path/to/target-example-filename.ext[] (2)

include::example$./target-example-filename.ext[] (3)
1 当目标示例存储在examples目录的根目录中时，目标示例的文件坐标。
2 当目标示例存储在examples目录的子目录中时，目标示例的文件坐标。
3 当目标示例和当前页面存储在具有平行家族相对目录路径的子目录中时，目标示例的文件坐标。这是一个高级用例。

此外，当目标示例和当前页面不属于相同模块或组件版本时，您需要指定额外的资源ID坐标。以下各节提供了显示各种资源ID场景的示例。

文件坐标与示例-相对目录路径

当目标示例存储在examples目录的子目录中时，其examples相对目录路径在文件坐标中是必需的。

示例8. 当目标示例存储在示例目录的子目录中时的文件坐标 
include::example$path/to/target-example-filename.ext[可选属性]

让我们使用属于组件版本的文件作为本节示例的基础，参见示例9。

示例9. 分配给grid-twist 2.5的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 将组件版本定义为grid-twist 2.5
2 定义名为ROOT的模块
3 将后续文件定义为示例
4 examples中包含示例源文件的子目录
5 将后续文件定义为页面

让我们从interface-loader.adoc中引用job.yml。如上所示的示例9，示例和页面属于ROOT模块。在示例10中，interface-loader.adoc页面（当前页面）中的包含指令引用job.yml文件（目标示例）。

示例10. interface-loader.adoc（当前页面） 
[,yaml]
----
include::example$providers/job.yml[]
----

如示例10所示，家族坐标为example$，job.yml的文件坐标为providers/job.yml。job.yml的文件坐标由其examples相对目录路径、文件名和文件扩展名组成，因为它存储在providers子目录中。

在特殊情况下，目标示例的examples相对目录路径和当前页面的pages相对目录路径平行时，examples相对目录路径可以用相对路径标记./替换。

包含另一个模块中的示例

当目标示例和当前页面不属于同一模块时，您必须在包含指令中指定目标示例的模块、家族和文件坐标。

示例 11. 将模块、家族和文件坐标分配给包含指令 
include::module:example$target-example-filename.ext[可选属性] (1)

include::module:example$path/to/target-example-filename.ext[可选属性] (2)
1 当目标示例和当前页面属于同一组件版本但不属于同一模块时，将目标示例的模块、example$和文件坐标分配给包含指令。当目标示例存储在examples家族目录的根目录时，目标示例的文件坐标是其文件名和文件扩展名。
2 如果目标示例存储在examples目录的子目录中，则目标示例的文件坐标必须指定其examples相对目录路径、文件名和文件扩展名。

让我们使用在示例 12中显示的组件版本中属于基础示例的文件。

示例 12. 分配给 mapper 8.0 的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 将组件版本定义为mapper 8.0
2 定义ROOT模块
3 将后续文件定义为示例
4 定义testing模块
5 将后续文件定义为示例
6 将后续文件定义为页面

让我们将warm-up.js示例插入到index.adoc页面中。这意味着源文件warm-up.js是目标示例，index.adoc是当前页面。如上所示的示例 12，index.adoc页面属于testing模块，warm-up.js示例属于ROOT模块。

示例 13显示了在index.adoc中引用示例warm-up.js的包含指令。目标示例的模块、example$和文件坐标被分配给包含指令。

示例 13. index.adoc（当前页面） 
[,js]
----
include::ROOT:example$warm-up.js[]
----

如示例 13所示，目标示例的模块坐标是ROOT，其家族坐标是example$，文件坐标是warm-up.js。

包含另一个组件的示例

当目标示例和当前页面不属于同一文档组件时，在分配包含指令的资源ID时，需指定示例的版本、组件、模块、系列和文件坐标。

示例 14. 分配给包含指令的版本、组件、模块、系列和文件坐标 
include::version@component:module:example$target-example-filename.ext[] (1)

include::version@component:module:example$path/to/target-example-filename.ext[] (2)

include::component:module:example$file-coordinate-of-target-example.ext[] (3)
1 当目标示例和当前页面不属于同一组件版本时，将目标示例的版本、组件、模块、系列和文件坐标分配给包含指令。当目标示例存储在示例系列目录的根目录时，目标示例的文件坐标是其文件名和文件扩展名。
2 如果目标示例存储在示例目录的子目录中，目标示例的文件坐标必须指定其示例相对目录路径、文件名和文件扩展名。
3 如果未指定版本坐标，Antora将在运行时使用目标示例组件的最新版本来完成资源ID。此行为仅适用于目标示例和当前页面属于不同文档组件的情况。

让我们使用属于组件版本mapper 8.0（示例 15）和grid-twist 2.5（示例 16）的文件作为本节示例的基础。

示例 15. 分配给 mapper 8.0 的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 将组件版本定义为mapper 8.0
2 定义ROOT模块
3 将后续文件定义为示例
4 定义testing模块
5 将后续文件定义为示例
6 将后续文件定义为页面
示例 16. 分配给 grid-twist 2.5 的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 将组件版本定义为grid-twist 2.5
2 定义名为ROOT的模块
3 将后续文件定义为示例
4 示例中包含示例源文件的子目录
5 将后续文件定义为页面

使用来自示例 15和示例 16的文件，让我们从interface-loader.adoc（当前页面）引用warm-up.js（目标示例）。warm-up.js示例属于组件版本mapper 8.0。interface-loader.adoc页面属于组件版本grid-twist 2.5。

在示例 17中显示的包含指令将warm-up.js示例的内容嵌入到interface-loader.adoc页面中。

示例 17. interface-loader.adoc（当前页面） 
[,js]
----
include::8.0@mapper:ROOT:example$warm-up.js[]
----

如示例 17所示，目标示例的版本坐标为8.0，组件坐标为mapper，模块坐标为ROOT，系列坐标为example$，文件坐标为warm-up.js。您还可以将warm-up.js的资源ID指定为8.0@mapper::example$warm-up.js（注意模块坐标ROOT似乎缺失）。当指定目标示例的组件坐标，并且目标示例属于ROOT模块时，模块坐标ROOT无需显式指定。但是，您仍需输入冒号（:）以表示模块坐标后的内容。这种简写仅在指定组件坐标且目标示例的模块坐标为ROOT时有效。

使用示例的最新版本

仅当目标示例和当前页面属于不同的文档组件时才适用此行为！

如果在分配给包含指令的资源ID中未指定版本，且目标示例和当前页面不属于同一组件，Antora将在运行时使用目标示例组件的最新版本的版本坐标来完成资源ID。

让我们使用属于组件版本 mapper 8.0（示例18）、mapper 8.1（示例19）和 grid-twist 2.5（示例20）作为本节示例的基础的文件。

示例18. 分配给mapper 8.0的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 将组件版本定义为 mapper 8.0
示例19. 分配给mapper 8.1的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📄 warm-up.js
  📂 testing (4)
    📂 examples (5)
      📄 timer.js
    📂 pages (6)
      📄 index.adoc
      📄 phases.adoc
1 将组件版本定义为 mapper 8.1
示例20. 分配给grid-twist 2.5的目录和文件 
📄 antora.yml (1)
📂 modules
  📂 ROOT (2)
    📂 examples (3)
      📂 providers (4)
        📄 job.yml
    📂 pages (5)
      📄 interface-loader.adoc
1 将组件版本定义为 grid-twist 2.5

让我们从当前页面的 interface-loader.adoc 页面引用目标示例 timer.js（目标示例）。 interface-loader.adoc 属于组件版本 grid-twist 2.5。有两个名为 timer.js 的文件属于 mapper 组件，testing 模块和 examples 系列。一个 timer.js 属于版本 8.0，另一个 timer.js 属于版本 8.1。

示例21显示了一个包含指令，引用了 timer.js（目标示例）从 interface-loader.adoc（当前页面）。请注意，目标示例的版本坐标未指定。

示例21. interface-loader.adoc（当前页面） 
[,js]
----
include::mapper:testing:example$timer.js[]
----

当Antora运行时，它将根据其版本排序规则和最新版本标准，将 mapper 8.1 识别为 mapper 组件的最新版本。因为在示例21中未指定版本坐标，Antora将使用最新的 mapper 组件中的版本坐标 — 8.1 — 来完成分配给包含指令的资源ID。

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

了解更多

AsciiDoc 和 Asciidoctor 资源