插件 API

Highlight.js 支持插件扩展。你可以通过 addPlugin 接口对插件进行扩展。译者注：也就是说可以在 Highlight.js 这个插件中扩展其他插件

// a plugin can be a class
addPlugin(new SimplePlugin());
addPlugin(new MoreComplexPlugin(options));

// or simply a keyed object of functions
addPlugin({
  'after:highlightElement': ({ el, result, text }) => {
    // ...
  }
});

插件类型

基于 Class 类的插件

这种方法更适用于需要进行配置项处理或状态管理的更复杂的插件。Highlight.js 会为你提供的 class 类创建实例，并在必要时执行其回调函数。

class DataLanguagePlugin {
  constructor(options) {
    self.prefix = options.dataPrefix;
  }

  'after:highlightElement'({ el, result, text }) {
    // ...
  }
}

hljs.addPlugin(new DataLanguagePlugin({ dataPrefix: 'hljs' }));
基于函数方式的插件

这种方式比较适合简单的插件。

hljs.addPlugin({
  'after:highlightElement': ({ el, result }) => {
    // move the language from the result into the dataset
    el.dataset.language = result.language;
  }
});

before:highlight

before:highlight({code, language})

该回调函数在 highlight 调用前执行，传递的参数为一个对象，该对象有以下两个属性：

  • code: 要高亮显示的代码。
  • language: 语言名称，会以该语言语法进行高亮处理

你的插件可以修改任何一个输入值，并将这些新值作为输入推送到语法高亮引擎中。如果你向对象中添加一个 result 键，那么该结果将作为总体结果返回，内部高亮代码甚至不会被调用。

如果你的插件计划自己递归调用 highlight 功能，则需要手动处理这个过程。每次调用 highlight 时，你插件的回调也会被调用，所以这是很容易陷入死循环的。你可能需要选择基于 class 类的方式，并添加一个保护程序，这样你的插件代码就能在高亮处理的初始调用时触发，而不会在你的插件本身进行内部调用时触发。

注意：自动检测语言的情况下所进行的高亮处理不会触发本回调函数。

该回调没有返回值。

after:highlight

after:highlight(result)

该回调函数在高亮处理结束后执行，它会传递一个 result 对象。你的插件可以对 result 对象进行任何修改，其会作为 highlight 调用所返回的最终结果。

注意：自动检测语言的情况下所进行的高亮处理不会触发本回调函数。

该回调没有返回值。

after:highlightElement

after:highlightElement({el, result, text})

该回调函数传递一个对象参数，其存在以下三个属性：

  • el: 已经高亮处理后的 HTML 元素。
  • result: 由 highlight 或 highlightAuto 方法返回的 result 对象。
  • text: 要进行语法高亮处理的原始文本。

该回调没有返回值。

before:highlightElement

before:highlightElement({el, language})

该回调函数传递一个包含两个属性的对象：

  • el: 即将进行高亮处理的 HTML 元素。
  • language: 由 class 属性所定义的语言（或未定义）。

其没有返回值。

已弃用

after:highlightBlock

自版本 10.7 起已弃用：请使用 after:highlightElement。

before:highlightBlock

自版本 10.7 起已弃用：请使用 before:highlightElement。