扩展辅助函数

生成器上下文提供了多种实用方法，使编写扩展更容易。这些实用方法被称为助手，因为它们可以帮助你编写扩展。

Access helpers

帮助程序位于提供 GeneratorContext API 的生成器上下文中。因此，要使用这些帮助程序，需要有一个生成器上下文的引用。

获取生成器上下文的方法有两种。如果监听函数是在扩展的 register 函数中定义的，则可以通过变量范围的方式从 register 函数中访问生成器上下文。否则，监听函数可以使用标准的 this 关键字引用生成器上下文。在监听函数注册时，生成器上下文将与监听函数绑定。

getVariables()

访问上下文变量的一种方法是使用对象解构（如 { playbook }），通过注册函数或事件监听器函数的第一个参数接受它们。不过，在某些情况下，上下文变量可能只是有条件地需要。为了简化函数签名，可以使用 getVariables 辅助函数直接从生成器上下文中获取上下文变量。

下面是一个示例，说明如何使用 getVariables 方法从生成器上下文（绑定到 this）访问上下文变量：

const { playbook, contentCatalog } = this.getVariables()

请注意，参数解构仍然是注册函数访问扩展配置对象的唯一方法。

updateVariables(Object)

updateVariables 辅助方法提供了一种添加或替换上下文变量的方法。该方法接受一个 Object 类型的参数，其中对象的键是变量名，值是变量值。该方法不返回值。

如果要删除变量，请将其值指定为 undefined。请记住，锁定的变量不能被替换。

下面的示例展示了如何从监听器中替换 playbook 和 siteCatalog 变量：

playbook = JSON.parse(JSON.stringify(playbook))
siteCatalog = new Proxy(siteCatalog, {})
this.updateVariables({ playbook, siteCatalog })

您也可以使用 updateVariables 方法在上下文中引入新变量。网站生成器不会识别或使用这些变量。不过，其他扩展或同一扩展中的监听器可以使用它们。

stop(Integer)

stop 辅助方法提供了一种通过有序关闭来停止发生器运行的方法。该方法接受一个可选的退出代码值，但不返回值。

调用该方法时，上下文会发出 contextStopped 和 contextClosed 事件。如果记录的消息超过故障级别阈值，Antora 将以非零的退出代码退出。否则，Antora 将以指定的退出代码退出，如果没有指定退出代码，则以零退出代码退出（即成功退出）。

如果您只需要部分运行 Antora，而不想抛出错误让 Antora 停止，那么 stop 助手就非常有用。您可以用它来预热缓存或执行引用验证。请注意，如果在 sitePublished 事件之前在任何监听器中调用 stop，Antora 将不会发布网站。

下面的示例展示了如何在监听器中向 Antora 发送停止处理的信号：

console.log('Our work is done here. Wrap it up.')
this.stop()

getLogger(String)

通过 getLogger 辅助方法，可以检索日志记录器的实例。

下面的示例展示了如何获取日志记录器实例并在监听器中使用它：

module.exports.register = function () {
  const logger = this.getLogger('extension-name')
  this.on('playbookBuilt', () => {
    logger.info('Let it be known. The playbook has been built!')
  })
}

在启用该扩展（以及 --log-level=info 选项）后运行 Antora，您将在终端中看到以下信息：

[12:24:37.731] INFO (extension-name): Let it be known. The playbook has been built!

require(String)

require 辅助方法允许您在 Antora 安装的上下文中要求使用库。该方法接受一个字符串类型的参数，即 require 请求（即 Node.js 模块或模块中源文件的名称）。该方法返回指定模块或源文件导出的对象。如果请求无法解析，该方法将抛出一个错误，代码为 MODULE_NOT_FOUND。

在编写扩展时，您有时可能需要访问 Antora 提供的代码。例如日志记录器、ContentCatalog 或像 parseResourceId 这样的实用程序。通过这种方法，您无需声明对 Antora 的依赖性就可以访问这些代码。由于扩展在 Antora 的上下文中运行，因此这种依赖是隐含的。该方法提供了一种要求该代码的方法。

下面的示例展示了如何从监听器获取当前正在运行的网站生成器版本：

const { name, version } = this.require('@antora/site-generator/package')
console.log(`Running ${name} version ${version}`)

由于扩展已经在网站生成器的上下文中运行，因此这里有一个稍微简单的方法来实现同样的结果：

const { name, version } = this.require('../package')
console.log(`Running ${name} version ${version}`)

举个更实际的例子，你可以使用 require 辅助方法为扩展创建一个子日志记录器。通常，您会在 register 函数中创建子日志记录器，然后在整个扩展中访问日志记录器的同一实例。

module.exports.register = function () {
  const logger = this.require('@antora/logger')('extension-name')
  this.on('playbookBuilt', () => {
    logger.info('Let it be known. The playbook has been built!')
  })
}

在启用该扩展（以及 --log-level=info 选项）后运行 Antora，您将在终端中看到以下信息：

[12:24:37.731] INFO (extension-name): Let it be known. The playbook has been built!

检索日志记录器实例的更简单方法是使用 getLogger(String) 方法。