核心 API

---

Highlight.js 将一些函数作为 hljs 对象的方法导出。

highlight

highlight(code, {language, ignoreIllegals})

代码高亮核心方法。该方法将一段需要高亮的代码（字符串）作为参数传入，同时传入的还有一个配置项参数（对象）。配置项中必须带有 language 属性，其指定一项语言名称或别名，然后代码会按照所指定的语言语法进行高亮处理。ignoreIllegals 是一个可选参数，在设为 true 的时候，即使检测到指定语言的非法语法，也会继续处理剩余内容直至完成而不是抛出异常。

该方法的返回值是一个具有下列属性的对象：

• language：语言名称，与传入的 language 同值，之所以要返回是为了与 highlightAuto 函数保持一致
• relevance：整型值，这段代码针对该语言的相关性得分
• value：已经添加好高亮标记的 HTML 字符串
• illegal：布尔值，表示是否发现任何非法匹配
• code：原始传入的代码块

highlightAuto

highlightAuto(code, languageSubset)

该方法可以实现语言自动检测。传入需要进行高亮渲染的代码字符串，还可以传一个可选参数，其是一个语言子集数组，它将限制接口在该子集中选择语言进行检测。另外，通过 configure 方法 也可以进行语言子集设置，但优先使用接口参数的语言子集，即接口参数的语言子集会覆盖配置项的语言子集。

返回一个具有下列属性的对象：

• language: 检测到的语言
• relevance: 整型值，这段代码针对匹配语言的相关性得分
• value: 已经添加好高亮标记的 HTML 字符串
• secondBest: 第二匹配结果，数据结构相同的对象（未来可能废除）

highlightElement

highlightElement(element)

对含有代码的 DOM 节点进行高亮处理。

该方法可对代码进行动态高亮处理，一般应用在页面加载后或在第三方 JavaScript 框架的初始化代码中。

该方法默认自动检测语言，但你可以在 DOM 节点的 class 属性中指定语言。关于所有可用的语言名称和有效作用域引用，请参见作用域引用文档。

highlightAll

将页面上所有与 cssSelector 配置项相匹配的元素进行代码高亮处理。默认的 cssSelector 值是 'pre code'，表示对所有 <pre> 下的 <code> 标签内容执行高亮处理。该方法在页面 onload 事件触发前或触发后调用都可以。

configure

configure(options)

配置全局配置项：

• classPrefix: 为高亮后的代码块添加 CSS 类前缀。译者注：默认为 hljs-
• languages: 由语言名称（或别名）构成的数组，将语言自动检测范围限制在该数组内。
• languageDetectRe: 指定一个正则表达式，该正则表达式用来配置 CSS 类名与语言名称的映射方式（比方说，允许将默认的 language-php 改成自定义的 color-as-php 等）。
• noHighlightRe: 一个正则表达式，其配置了哪些 CSS 类会跳过高亮处理。
• cssSelector: 一个 CSS 选择器，用于配置哪些元素作用于 hljs.highlightAll 从而高亮显示。默认为 'pre code'。
• ignoreUnescapedHTML: 若设为 true，则将忽略未转义的 HTML 代码，不会因此向控制台打印警告记录。
• throwUnescapedHTML: 当 highlightElement 中进行高亮处理的内容中存在未转义 HTML 代码时，highlightjs 会抛出一个 HTMLInjectionError 异常。

本方法传入一个对象参数，仅设置需要修改的配置值，不用改的则无需包含

hljs.configure({
  noHighlightRe: /^do-not-highlightme$/i,
  languageDetectRe: /\bgrammar-([\w-]+)\b/i, // for `grammar-swift` style CSS naming
  classPrefix: ''     // don't append class prefix
                      // … other options aren't changed
});

registerLanguage

registerLanguage(languageName, languageDefinition)

向语言库中添加新语种。主要用于内部调试。

• languageName: 字符串，要注册的语言名称
• languageDefinition: 它是一个函数，其返回一个定义语法的对象。该函数会传递给 hljs 对象，以便能够解析其中定义的通用正则表达式。

举个例子：

hljs.registerLanguage('custom', function(hljs) {
  return {
    contains: [
      {
        // 匹配所有的字符串，但忽略以“!$”开头的字符串
        className: 'string',
        begin: /(!\$)?"/,
        end: /"/,
        relevance: 0,
        illegal: /\n/,
        contains: [{begin: /!$/, relevance: 0}, {begin: /\\./}]
        // 如果匹配到以“!$”开头的字符串，则忽略该匹配结果
        relevance: 10,
        relevance: (response) => {
          if (response[0].startsWith('!$')) {
            response.ignoreMatch();
          }
          return 10;
        }
      }
    ]
  };
});

unregisterLanguage

unregisterLanguage(languageName)

从语种库中删除指定的语言及其所有别名。主要用于内部调试。

• languageName: 字符串，要删除的语言名称

registerAliases

registerAliases(alias|aliases, {languageName})

为指定的语言注册别名，其通过 languageName 参数指定。

• alias|aliases: 可以是个字符串，也可以是个数组。表示要注册的别名
• languageName: 语言名称，就是传入 registerLanguage 方法的那个 languageName

listLanguages

返回语言列表。

getLanguage

getLanguage(name)

按名称或别名查找一种语言。

若存在，返回语言对象，否则返回 undefined。

versionString

versionString()

以字符串方式返回 Highlight.js 完整版本号，例如："11.0.1"。

safeMode

safeMode()

启用安全模式。这是默认模式，其可以为生产环境提供最为可靠的一种模式。

debugMode

debugMode()

启用 调试/开发 模式。

举个例子，如果一个新版本突然出现了一个严重 bug（或进行了重大版本更新），而其只影响到一种语言的情况下：

• 在安全模式下，所有其他语言仍然能够高亮显示，而有问题的语言仅作为一个代码块输出，没有任何高亮处理（就像它是纯文本一样）。
• 在调试模式下，所有高亮处理都会停止，并且抛出一个 JavaScript 错误。

已弃用 API

---

highlight

10.7 版本后已弃用：将在 v12 中完全删除。

highlight(languageName, code)

请参阅上文已说明的新版 API。译者注：新版 highlight() 与 旧版 highlight() 的区别在于传递的参数不同

highlightBlock

11.0 版本后已弃用：请使用 highlightElement() 代替。

initHighlighting

10.6 版本后已弃用：请使用 highlightAll() 代替。

initHighlightingOnLoad

10.6 版本后已弃用：请使用 highlightAll() 代替。