替换生成函数

Antora的站点生成器是作为一系列步骤实现的。每个步骤由一个函数执行。这些函数被称为生成函数。生成函数可能包含生成函数可能执行的关键子步骤的函数，比如convertDocument。

生成器从生成器上下文中检索这些函数。这些函数也可以通过Antora扩展以编程方式检索和替换。因此，这些生成函数被设计为可替换的，提供了一种更强大的扩展Antora的方式。

在扩展中替换函数确实会增加代码在Antora的主要版本之间发生故障的风险。

获取函数

与上下文变量一样，生成函数可以从生成器上下文中获取。可以通过在contextStarted事件的监听器内调用getFunctions方法或之后的任何时刻来检索生成函数。该方法返回一个键值对对象，其中键是函数名称，值是函数对象。

内置生成函数直到发出contextStarted事件才可用。

以下是一个示例，展示了如何在扩展中检索aggregateContent函数，假设this绑定到生成器内容。

this.once('contextStarted', () => {
  const { aggregateContent } = this.getFunctions()
})

检索生成函数的一个原因是将其用作实用程序。例如，如果您的扩展需要像Antora一样加载AsciiDoc，您可能会为此目的检索loadAsciiDoc函数。以下是一个示例：

this.once('contentClassified', (contentCatalog, siteAsciiDocConfig) => {
  const { loadAsciiDoc } = this.getFunctions()
  const page = contentCatalog.resolvePage('ROOT::index.adoc')
  const scopedAsciiDocConfig = contentCatalog.getComponentVersion(page.src.component, page.src.version).asciidoc
  const doc = loadAsciiDoc(page, contentCatalog, scopedAsciiDocConfig || siteAsciiDocConfig)
  const sections = doc.findBy({ context: 'section' }, (it) => it !== doc.getHeader())
  console.log(sections.map((it) => it.getTitle()))
})

检索生成函数的另一个原因是装饰（又名包装）它。在这种情况下，您需要用装饰后的函数替换原始函数。或者，您可以用自己的实现替换原始函数。

替换函数

替换生成函数使您能够覆盖Antora站点生成器中的步骤。

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

只需将要替换的函数传递给replaceFunctions即可。对于未替换的任何函数，生成器将默认使用内置函数。

以下是一个示例，展示了如何在扩展中替换publishFiles函数：

module.exports.register = function () {
  this.replaceFunctions({
    async publishFiles () {
      console.log('今天不发布')
      return []
    }
  })
}

替换函数的时间很重要。如果直接在register方法中替换函数（在发出contextStarted事件之前），它将阻止Antora需要和注册相应的内置函数。如果在contextStarted监听器中替换函数，则该函数将替换已经被需要和注册的相应内置函数。

当替换函数很重要。如果直接在register方法中替换函数（在发出contextStarted事件之前），它将阻止Antora需要和注册相应的内置函数。如果在contextStarted监听器中替换函数，则该函数将替换已经被需要和注册的相应内置函数。

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

函数参考

可以由扩展替换的函数列表，以及它们的签名，如下所示：

  • 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源代码。