扩展助手

生成器上下文提供了几种实用方法,使编写扩展变得更容易。这些实用方法被称为助手,因为它们帮助您编写扩展。

访问助手

助手位于生成器上下文上,生成器上下文提供了GeneratorContext API。因此,要使用助手,您需要引用生成器上下文。

有两种方法可以获取生成器上下文。如果监听函数在扩展的register函数内定义,它们可以通过变量作用域从register函数中访问生成器上下文。否则,监听函数可以使用标准的this关键字引用生成器上下文。生成器上下文在注册监听函数时绑定到监听函数。

getVariables()

访问上下文变量的一种方法是通过对象解构(例如,{ playbook })接受它们作为注册函数或事件监听函数的第一个参数。但是,在某些情况下,可能仅在需要条件下才需要上下文变量。为了简化函数签名,您可以直接从生成器上下文中使用getVariables助手检索上下文变量。

以下是如何使用getVariables方法从生成器上下文(绑定到this)访问上下文变量的示例:

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

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

updateVariables(Object)

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

如果要删除变量,请将值指定为undefined。请注意,锁定的变量无法替换。

以下是一个示例,演示如何从监听器中替换playbooksiteCatalog变量:

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

您还可以使用updateVariables方法将新变量引入上下文。站点生成器将不会识别或使用这些变量。但是,其他扩展或同一扩展中的监听器可以使用它们。

stop(Integer)

stop助手方法提供了一种通过有序关闭停止生成器操作的方法。此方法接受一个可选的退出代码值,不返回值。

调用此方法会导致上下文发出contextStoppedcontextClosed事件。如果记录的任何消息超过失败级别阈值,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已构建完成!')
  })
}

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

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

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