更换生成器函数

Antora 的生成器是一系列步骤，其中每一步都由一个函数执行。这些函数被称为生成器函数。生成器函数还包括生成器函数可能执行的关键子步骤的函数，如 loadAsciiDoc。生成器从生成器上下文中获取这些函数。因此，这些生成器函数被设计为可替换的，为扩展 Antora 提供了更强大的方式。具体来说，扩展程序可以检索和替换这些函数。

替换扩展中的函数确实会增加代码在不同主要 Antora 版本之间被破坏的风险。

获取函数

与上下文变量一样，生成器上下文中也有生成器函数。可以通过调用 getFunctions 方法获取生成器函数。该方法会返回一个键值对对象，其中键是函数名称，值是函数对象。内置的生成器函数在 contentStarted 事件发生前不可用。

下面的示例展示了如何在扩展中检索 aggregateContent 函数，假设该函数与生成器内容绑定。

const { aggregateContent } = this.getFunctions()

您可能想要检索一个函数，以便对其进行包装。无论如何，有趣的部分会在替换函数时发生。

替换函数

可以通过向 replaceFunctions 方法传递函数来替换生成器函数。该方法接受与 getFunctions 方法相同的对象签名，其中键是函数名，值是函数对象。

您只需指定要替换的函数。对于未被扩展名替换的函数，生成器将返回到使用其自身的函数。

下面的示例展示了如何替换扩展中的 publishFiles 函数：

module.exports.register = function () {
  this.replaceFunctions({
    async publishFiles () {
      console.log('Not publishing today')
      return []
    }
  })
}

何时替换函数很重要。如果直接在 register 方法中替换函数，Antora 将无法要求和注册相应的内置函数。如果在 contextStarted 监听器函数中替换函数，该函数将替换已注册的相应内置函数。该事件为您提供了委托（即封装）内置函数的机会，如图所示：

module.exports.register = function () {
  this.on('contextStarted', () => {
    const delegate = this.getFunctions().publishFiles
    this.replaceFunctions({
      async publishFiles (playbook, catalogs) {
        console.log('It\'s publish time!')
        return delegate.call(this, playbook, catalogs)
      }
    })
  })
}

替换函数时，必须遵守函数的签名。与注册函数和事件监听器函数一样，生成器函数会自动绑定到生成器上下文。

函数参考

可以用扩展名替换的函数列表及其签名如下：

  • aggregateContent(playbook): Promise<Object>

  • buildNavigation(contentCatalog, siteAsciiDocConfig): NavigationCatalog

  • classifyContent(playbook, contentAggregate, siteAsciiDocConfig): ContentCatalog

  • convertDocument(file, contentCatalog, siteAsciiDocConfig): File

  • convertDocuments(contentCatalog, siteAsciiDocConfig): void

  • createPageComposer(playbook, contentCatalog, uiCatalog, env): Function

  • extractAsciiDocMetadata(doc): Object

  • loadAsciiDoc(file, contentCatalog, config): Document

  • loadUi(uiCatalog): Promise<UiCatalog>

  • mapSite(playbook, publishablePages): File[]

  • produceRedirects(playbook, contentCatalog): File[]

  • publishFiles(playbook, catalogs): Promise<Object[]>

  • resolveAsciiDocConfig(playbook): Object

要了解有关这些功能的更多信息，请查阅 Antora 源代码。