Extension Helpers :: Antora Docs

访问助手

助手位于生成器上下文上，生成器上下文提供了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将以指定的退出代码退出，或者如果未指定退出代码，则以零退出代码（即成功）退出。

stop助手对于只需要部分运行Antora并且不想引发错误以使Antora停止的情况很有用。您可以用它来预热缓存或执行引用验证。请注意，如果在sitePublished事件之前在任何监听器中调用stop，Antora将不会发布站点。

以下是一个示例，演示如何在监听器中向Antora发出停止处理的信号：

console.log('我们的工作完成了。结束吧。')
this.stop()

getLogger(String)

getLogger助手方法允许您检索日志记录器的实例。

以下是一个示例，演示如何检索日志记录器的实例并在监听器中使用它：

module.exports.register = function () {
  const logger = this.getLogger('extension-name')
  this.on('playbookBuilt', () => {
    logger.info('让人们知道。playbook已构建完成！')
  })
}

当您启用此扩展并使用--log-level=info选项运行Antora时，您将在终端中看到以下消息：

[12:24:37.731] INFO (extension-name): 让人们知道。playbook已构建完成！

require(String)

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

在编写扩展时，有时您可能需要访问Antora提供的代码。示例包括日志记录器、ContentCatalog或类似parseResourceId的实用函数。此方法允许您在不必声明对Antora的依赖关系的情况下要求此代码。由于扩展在Antora的上下文中运行，因此该依赖关系是隐式的。该方法提供了一种要求该代码的方式。

以下是一个示例，演示如何从监听器中获取当前运行的站点生成器版本：

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

由于扩展已在站点生成器的上下文中运行，因此以下是实现相同结果的一种稍微简化的方式：

const { name, version } = this.require('../package')
console.log(`运行 ${name} 版本 ${version}`)

对于一个更实际的示例，您可以使用require助手方法为您的扩展创建一个子日志记录器。通常，您会在register函数中这样做，然后在整个扩展中访问相同的日志记录器实例。

module.exports.register = function () {
  const logger = this.require('@antora/logger')('extension-name')
  this.on('playbookBuilt', () => {
    logger.info('让人们知道。playbook已构建完成！')
  })
}