升级至 v11.0

重大变更概述

欢迎升级到 v11.0。这是一次主版本更新，因此包含一些重大变更。以下是这些更新的完整清单。

常用语言组

默认的 highlight.min.js 脚本移除了一些不再那么主流的语言：

  • apache
  • http
  • nginx
  • properties
  • coffeescript

如果你需要其中任何一项，你始终可以编译一个自定义脚本库。

参阅：https://github.com/highlightjs/highlight.js/issues/2848

语言文件

如果你通过 Node.js 或 CDN 直接引用了下列文件，请特别关注这一点。

  • htmlbars 已被移除。替代为 handlebars。
  • c-like 已被移除。改用 c，cpp 或 arduino。
  • sql_more 已被移除。替代为 sql 或更具体的第三方语法。

语言别名

本项更新会影响到使用了以下语言别名的项目。

  • php3、php4、php5、 php6、 php7 和 php8 已经被废除。请使用 php 替代。
  • zsh 已废除。请使用 sh 或 bash 替代。
  • freepascal、lazarus、lpr 和 lpm 已废除。使用 delphi 替代。

如果有需要，你也可以轻松自行注册上述别名。下面举例如何恢复 PHP 别名：

hljs.registerAliases(["php3","php4","php5","php6","php7","php8"],{ languageName: "php" })

样式与 CSS

  • .hljs 元素的默认 padding 增加到 1em，原本为 0.5em。如果你的页面设计要求较小边距，那你需要修改 CSS 覆盖该 padding。
  • School Book 主题的背景中不再拥有分隔线，改为纯色背景了。不过能在 10-stable 分支里找到原来的图像资源和 CSS 文件，只要你愿意你也可以手动将它们拷贝到你的项目中。
  • 为了贴合新版 GitHub 语法高亮样式，github 主题发生了重大更改。如果你更喜欢老版主题，可以手动从 10-stable 分支拷贝到你的项目中。
  • 随着 GitHub 和 GitHub Gist 的融合，github-gist 主题已被移除，仅留下 github 主题。该旧版主题也是可以通过 10-stable 分支拷贝下来使用.
  • CSS 选择器 .hljs 所指明的范围更大了，不仅能命中 code.hljs（内联代码），还能命中 pre code.hljs（代码块）。如果你使用了不同的元素，你可能需要修改你的 CSS 文件，让这些样式能应用到元素上。
  • 所有 Base16 主题现在都放到 styles/base16 目录中了，这就意味着会删掉一些 CSS 文件。你使用的主题若有所影响，注意要从新位置引用文件。
语法范围
  • .meta-string 已移除 / 已弃用。请改用 .meta .string（嵌套）。
  • .meta-keyword 已移除 / 已弃用。请改用 .meta .keyword（嵌套）。

行为变更

  • 插件回调 after:highlightElement 现在改成 DOM 更新后触发，而不是更新前。
API 修改
  • highlight() 方法的 ignoreIllegals 选项现在默认值为 true，之前为 false。
  • highlight(language,code, ...args) 接口不再接受 continuation 作为它的第四个参数。
  • highlight(language,code, ...args) 接口已废弃（将在 v12.0 中删除）。

新接口的函数签名是 highlight(code, {options})。（请参阅API 文档）

曾经，使用旧 API 的代码：

// highlight(language, code, ignoreIllegals, continuation)
highlight("javascript", "var a = 5;", true)

…现在升级为新 API，如下所示：

// highlight(code, {language, ignoreIllegals})
highlight("var a = 5;", {language: "javascript", ignoreIllegals: true})

新 API 是刻意取消 continuation 参数的，因为它接下来只有内部库会用到。

  • initHighlighting() 已弃用（将于 v12.0 中删除）。
  • initHighlightingOnLoad() 已弃用（将于 v12.0 中删除）。

请替代为 highlightAll()（参阅 API 文档）。旧函数现在仅充当 highlightAll() 的函数别名。新函数可以在 DOM 加载完之前或之后调用，不管哪种情况下都能完成全部功能，不再像以前一样要单独调用。

注意：highlightAll() 不像以前的函数那样可以防止对自身重复调用。你的代码逻辑中需要注意规避这种情况。
  • highlightBlock() 已弃用（将于 v12.0 中删除）。

请替代为 highlightElement()（参阅 API 文档）。这一项仅仅是函数命名更改。

注意：传递给 before:highlightElement 回调的对象参数，该对象第一个属性的 key 值现在改为 el 了，原本为 block。

返回值修改

  • highlightAuto() 返回的对象中，key second_best 命名改为 secondBest。
  • highlightElement() 的返回对象现在没有 re 属性了，改成 relevance。
  • highlight() 返回值中修改了一些属性的名称，包括 _top、_emitter 和 _illegalBy，这样可以更直白的表明这些是库内部的“私有”属性。你要避免使用这些属性，因为它们是一些随时都在改变的字段。
  • highlight() 返回的 relevance 属性不再固定为偶数。
  • highlight 元素 现在统一使用 language-[name] class 对代码块进行标记。

这一条在以前是不统一的。有些元素会添加 [name] class 作为标记，有些则是使用语言代称，甚至有些不添加任何 class。现在，改成固定添加 language-[name] class，这对内层的 span 元素也是这种情况，会添加 language- 前缀。

功能删减
  • 核心库现在不再允许 HTML 自动传递了。如需使用，请改用插件替代，相关插件问题请参阅 #2889。

举个例子：

<pre><code class="lang-js">
var a = 4;
<span class="yellow">var a = 4;</span>
</code></pre>

像这样未转义的 HTML 现在会被直接忽略（即高亮处理之前会被剔除），并且在控制台记录一条警告。所有需要进行高亮处理的 HTML 都应正确转义，避免 HTML / JS 注入攻击的风险。

  • fixMarkup 已删除。

此函数已在 v10.2 中被弃用。提供随机字符串实用程序不是我们的宗旨。你可能需要自己实现替代方案 参阅：#2534

  • CSS_NUMBER_MODE 已删除。

该规则过于宽泛，无法将其纳入库核心，因此已被删除。

  • lexemes 模型属性已被删除。

请使用新的 keywords.$pattern 替代。

之前：

{
  keywords: "do.it start.now begin.later end.immediately"
  lexemes: /[a-z.]+/
}

现在：

{
  keywords: {
    $pattern: /[a-z.]+/
    keyword: "do.it start.now begin.later end.immediately",
  }
}

如上所示，如果你的 keywords 属性还不是一个对象，需要先将其转换成对象类型。

  • endSameAsBegin 模型属性已被删除。

请改用新的 END_SAME_AS_BEGIN 模型规则 / 函数。

  • 已删除 useBR 配置。

该配置选项在 v10.1 已被弃用。请改用扩展插件，或者仅仅是简单地在 CSS 中加入 white-space: pre 即可实现对应功能。参阅：#2559

  • tabReplace 配置已被删除。

该配置选项在 v10.5 已被弃用。若需要保留缩进，可改用扩展插件或预渲染内容。参阅：#2874

其他

  • 在 正则表达式 工具中，join 已重命名为 _eitherRewriteBackreferences，不过这部分内容只会在内部库中用到，请不必关注。

从 v9.x 升级

即便你打算从 v9 版本直接升级，也是有必要看看 v10 版本中的重大变更项，其中会有一些你需要关注的地方：