Skip to main content

API

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

核心​

hljs.highlight(code, {language, ignoreIllegals})

核心高亮功能。接受代码以高亮显示（字符串）和选项列表（对象）。该 language 参数必须存在并指定用于高亮显示的语法的语言名称或别名。这 ignoreIllegals 是一个可选参数，即使在检测到语言的非法语法而不是抛出异常的情况下，真正强制高亮显示完成时也是如此。

返回具有以下属性的对象：

  • language: 语言名称，与传入的名称相同languageName，返回以保持一致highlightAuto
  • relevance: 表示相关性分数的整数值
  • value: 带有高亮标记的 HTML 字符串
  • top：当前模式堆栈的顶部
  • illegal: boolean 表示是否发现任何非法匹配
  • code：原始原始代码

自动高亮​

hljs.highlightAuto(code, languageSubset)

使用语言检测高亮显示。接受带有要高亮显示的代码字符串和一个可选的语言名称和别名数组，将检测限制为仅这些语言。也可以使用 设置子集 configure，但如果设置了本地参数，则会覆盖该选项。

返回具有以下属性的对象：

  • language: 检测到的语言
  • relevance: 表示相关性分数的整数值
  • value: 带有高亮标记的 HTML 字符串
  • secondBest：具有相同结构的对象，用于第二好的启发式检测语言（可能不存在）

高亮元素​

hljs.highlightElement(element)

将高亮显示应用于包含代码的 DOM 节点。

此函数用于在页面加载后或在第三方 JavaScript 框架的初始化代码中动态应用高亮显示。

该函数默认使用语言检测，但您可以在 classDOM 节点的属性中指定语言。有关所有可用的语言名称和范围，请参阅 范围参考。

高亮全部​

将高亮显示应用于页面上匹配配置的所有元素 cssSelector。默认 cssSelector 值为'pre code'，它高亮显示所有代码块。这可以在页面 onload 事件触发之前或之后调用。

全局配置​

hljs.configure(options)

配置选项：

  • classPrefix：在生成的标记中类名之前添加的字符串前缀，用于向后兼容样式表。
  • languages：一组语言名称和别名，将自动检测限制为仅这些语言。
  • languageDetectRe: 一个正则表达式，用于配置 CSS 类名如何映射到语言（允许类名，例如 color-as-php 与 language-php 的默认值等）
  • noHighlightRe：一个正则表达式，用于配置要完全跳过哪些 CSS 类。
  • cssSelector: 一个 CSS 选择器，用于配置受 hljs.highlightAll. 默认为.'pre code'
  • ignoreUnescapedHTML：不要在控制台中记录有关代码块中未转义 HTML 的警告
  • throwUnescapedHTMLHTMLInjectionError：当 highlightElement 被要求高亮显示包含未转义 HTML 的内容时抛出

接受一个对象，该对象表示具有要更新的值的选项。其他选项不变

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
});

注册语言​

hljs.registerLanguage(languageName, languageDefinition)

以指定名称将新语言添加到库中。主要在内部使用。

  • languageName: 一个带有被注册语言名称的字符串
  • languageDefinition: 一个函数，它返回一个表示语言定义的对象。该函数被传递给 hljs 对象，以便能够使用其中定义的常用正则表达式。

注销语言​

hljs.unregisterLanguage(languageName)

从库中删除一种语言及其别名。主要在内部使用。

  • languageName: 带有被删除语言名称的字符串。

注册别名​

hljs.registerAliases(alias|aliases, {languageName})

languageName 为在 key 下定义的指定语言名称添加新的语言别名或别名。

  • alias|aliases: 已注册别名的字符串或数组
  • languageName: 指定的语言名称 registerLanguage。

语言列表​

hljs.listLanguages()

返回语言名称列表。

获取语​​言​

hljs.getLanguage(name)

按名称或别名查找语言。

如果找到，则返回语言对象，undefined 否则返回。

版本号​

hljs.versionString

以字符串形式返回完整的 Highlight.js 版本，即："11.0.1".

安全模式​

hljs.safeMode()

启用安全模式。这是默认模式，为生产使用提供最可靠的体验。

调试模式​

hljs.debugMode()

启用调试/开发模式。

注意

这种模式故意让 Highlight.js 更加脆弱！它应该只用于测试和本地开发（语言或库本身）。

例如，如果一个新版本突然出现了只影响一种语言的严重错误（或重大更改）：

  • 在安全模式下，所有其他语言都会继续高亮显示。损坏的语言将显示为代码块，但没有任何高亮显示（就好像它是纯文本一样）。
  • 在调试模式下，所有高亮显示都会停止，并且会抛出 JavaScript 错误。