扩展助手
生成器上下文提供了几种实用方法,使编写扩展变得更容易。这些实用方法被称为助手,因为它们帮助您编写扩展。
访问助手
助手位于生成器上下文上,生成器上下文提供了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已构建完成!')
})
}
当您启用此扩展并使用--log-level=info
选项运行Antora时,您将在终端中看到以下消息:
[12:24:37.731] INFO (extension-name): 让人们知道。playbook已构建完成!
检索日志记录器实例的一个更简单的方法是使用getLogger(String)方法。