定义扩展

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

要定义扩展，首先要创建一个新的 JavaScript 文件（此处为：扩展文件）。我们将扩展文件命名为 my-extension.js。在扩展文件中，创建一个函数，并将其赋值给模块导出的 register 属性。我们将此导出称为 register 函数。通过导出函数，Antora 可以访问该函数。

Example 1. my-extension.js

'use strict'

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

如果你喜欢下面风格，可以将函数定义从导出语句中分离出来。

Example 2. my-extension.js

'use strict'

const register = () => {
}

module.exports = { register }

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

使用 "use strict" 语句作为扩展文件的开头是一种很好的做法。该语句可在所有版本的 Node.js 中启用严格模式。https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode[严格模式^] 激活了 JavaScript 的受限变体，可以捕捉常见的编程错误。我们将在本文档的其余示例中排除它，但假设它一直存在。

本例使用箭头函数语法定义寄存器函数。您也可以使用更正式的 function () {} 语法，访问生成器上下文时需要使用该语法。

将脚本放入 playbook 软件仓库。之后，你可以将其发布到软件包仓库（如 npmjs.com），以便在不同站点或分支之间共享。

到目前为止，我们的扩展实际上什么也没做。由于 register 函数是一种监听器，你可以利用它在 playbook 生成后立即执行操作。让我们用它来打声招呼。

Example 3. my-extension.js

module.exports.register = () => {
  console.log('Hello from Antora!')
}

虽然这是个有趣的小把戏，但并不是我们真正想要的。我们要做的是更深入地了解生成器的机制，这样我们才能做一些真正的工作，或许还能修改 Antora 正在处理的内容。为此，我们需要获取生成器上下文。

如果可以绑定 register 函数，即使用 function 关键字或等价关键字定义了该函数，Antora 将把生成器上下文绑定到其 this 关键字上。this 关键字是扩展程序访问生成器上下文的一种方式。

Example 4. my-extension.js

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

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

Example 5. my-extension.js without binding

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

生成器上下文用于注册事件监听器。在此之前，我们先来看看访问上下文变量的可选参数。

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

所有事件监听器都可以检索 playbook，但在注册监听器时可能更早地需要它。下面是如何通过注册函数访问 playbook 的方法：

Example 6. my-extension.js

module.exports.register = function ({ playbook }) {
  console.log(`Antora is building the ${playbook.site.title}.`)
}

现在，让我们注册扩展，然后添加事件监听器。