定义一个扩展

Antora扩展是一个名为register的导出JavaScript函数。Antora在生成器启动后（playbook构建完成后）立即调用该函数。该函数通常会添加事件监听器，用于监听生成器事件。事件监听器将钩入Antora生成器的生命周期，完成扩展的大部分工作。

要定义一个扩展，首先创建一个新的JavaScript文件（以下简称：扩展文件）。我们将命名这个扩展为my-extension.js。在扩展文件中，创建一个函数并将其赋值给模块导出的register属性。我们将这个导出称为注册函数。导出函数允许Antora访问它。

示例 1. my-extension.js

'use strict'

module.exports.register = () => {
}

如果你更喜欢，可以将函数定义与导出语句分开。

示例 2. my-extension.js

'use strict'

const register = () => {
}

module.exports = { register }

或者，你可以将扩展定义为一个基于类的扩展。

在扩展文件中以'use strict'语句开始是一个良好的做法。这个语句在所有版本的Node.js中启用严格模式。严格模式激活了JavaScript的一种受限变体，可以捕获常见的编程错误。我们将在文档的这一部分的其余示例中排除它，但假定它始终存在。

这个示例使用箭头函数语法定义了注册函数。你也可以使用更正式的function () {}语法，这样你就可以访问生成器上下文。

将脚本放入playbook存储库中。稍后，你可以将其发布到诸如npmjs.com之类的包存储库，以在不同站点或分支之间共享。

到目前为止，我们的扩展实际上并没有做任何事情。由于注册函数是一种监听器，你可以利用它在playbook构建完成后立即执行一个动作。让我们用它来打个招呼。

示例 3. my-extension.js

module.exports.register = () => {
  console.log('来自Antora的问候！')
}

虽然这是一个有趣的技巧，但并不是我们的目标。我们想要的是更深入地了解生成器的机制，以便可以进行一些真正的工作，甚至修改Antora正在处理的内容。为此，我们需要获取生成器上下文。

如果注册函数可以被绑定，也就是说它是使用function关键字或等效方式定义的，Antora将会将生成器上下文绑定到其this关键字。this关键字是扩展可以访问生成器上下文的一种方式。

示例 4. my-extension.js

module.exports.register = function () {
  this.on(...)
}

或者，如果函数将生成器上下文作为第一个参数接受（使用任何以字母开头的名称），Antora将把它作为函数的第一个参数传递，而不是将其绑定到this关键字。

示例 5. my-extension.js 不绑定

module.exports.register = (context) => {
  context.on(...)
}

生成器上下文是用于注册事件监听器的。在我们到达那里之前，让我们看看用于访问上下文变量的可选参数。

注册函数的第一个位置参数（或者如果函数将生成器上下文声明为第一个参数，则为第二个参数）是一个上下文变量对象。该对象包括playbook和扩展配置。你应该使用对象解构来从这个对象中提取单个变量。

所有事件监听器都可以检索playbook，但在注册监听器时可能需要它。以下是如何从注册函数中访问playbook：

示例 6. my-extension.js

module.exports.register = function ({ playbook }) {
  console.log(`Antora正在构建${playbook.site.title}。`)
}