模式引用

数据类型

此参考中的属性值类型：

模式	有效的 Highlight.js 模式
scope	有效的语法范围：`title.class.inherited`
regexp	JavaScript 正则表达式文字（推荐）或表示正则表达式的字符串。（注意使用字符串时，正确的转义很关键）
boolean	JavaScript 布尔值：`true`或`false`
string	JavaScript 字符串
number	JavaScript 编号
object	JavaScript 对象：`{ ... }`
array	JavaScript 数组：`[ ... ]`

语言属性

这些属性只在语言级别有效（即，它们很多只存在于最顶层的语言对象上，如果在子模式中指定则没有意义）。

name

type: string

该语言的规范名称，即“JavaScript”等。

unicodeRegex

type: boolean

表示所讨论的语法是否使用 Unicode（u标志）正则表达式。（默认为假）

case_insensitive

type: boolean

语言关键字和正则表达式不区分大小写。仅用于顶级模式。（默认为false）

aliases

type: array of strings

可用于在 HTML 类和调用getLanguage中识别语言的附加名称列表（除了由文件名给出的规范名称）。

classNameAliases

type: object

您的语法使用的任何自定义范围名称及其支持的等效项的映射表。也许你的语言有一个“slots”的概念，大致对应于其他语言中的变量。这允许您编写语法代码，例如：

{
  classNameAliases: {
    slot: "variable",
    "message-name": "string"
  },
  contains: [
    {
      scope: "slot",
      begin: // ...
    }
  ]
}

最终的 HTML 输出将呈现具有 CSS 类的插槽hljs-variable。存在此功能是为了使语法维护者在维护语法时更容易用自己的语言思考。

有关所有受支持范围名称的列表，请参阅范围参考。

disableAutodetect

type: boolean

禁用此语言的自动检测。（默认为 false，表示启用自动检测）

编译器扩展

注意

这在很大程度上取决于编译器内部，并且从次要版本到次要版本可能不稳定。 目前仅推荐用于第一方语法。

type: 编译器扩展数组，即: (mode, parentMode) -> {}

这允许语法扩展模式编译器以添加自己的语法糖，从而使阅读和编写语法更容易。目的是我们使用语法来“test”新的编译器扩展，如果它们表现良好，则将它们提升到核心库中。

mode

传入模式对象

parentMode

模式的父模式（顶级语言模式为null）

例如，让我们看一个行为良好的小扩展，它允许我们写成 match 来更好地表达“匹配单个事物，然后结束模式”的意图。

compilerExtensions: [
  (mode, _parentMode) => {
    // first some quick sanity checks
    if (!mode.match) return;

    // then check for users doing things that would make no sense
    if (mode.begin || mode.end) throw new Error("begin & end are not supported with match");

    // copy the match regex into begin
    mode.begin = mode.match;

    // cleanup: delete our syntactic construct
    delete mode.match;
  }
]

编译器扩展函数不返回任何内容。他们预计会改变模式本身。

模式属性

className

11.0 版后已弃用：改为使用scope。

scope

11.0 版中的新功能。

type: scope

给定模式的范围。范围在 HTML 标记中转换为 CSS 类名。

多个模式可以具有相同的范围。当一种语言对于单引号或双引号中的字符串具有多种语法变体时，这很有用。

{
  scope: "title.function.call",
  begin: /[a-z]+\(/
}

有关范围和 CSS 类的详细信息，请参阅范围参考。

begin

type: regexp or array of regexp

正则表达式启动模式。例如，字符串的单引号或 C 样式注释的两个正斜杠。如果不存在，则begin默认为匹配任何内容的正则表达式，因此模式立即启动。

这也可能是一个数组。请看下面。

beginScope

11.0 版中的新功能。

type: scope
type: numeric index of scopes (when begin is an array)

这可用于将范围应用于仅开始匹配部分。

{
  begin: /def/,
  beginScope: "keyword"
}

您还可以beginScope通过将数组传递给begin来单独高亮显示具有不同范围的匹配部分。

{
  begin: [
    /function!/,
    /\s+/,
    hljs.IDENT_RE
  ],
  beginScope: {
    1: "keyword",
    3: "title"
  },
}

这将高亮显示function!作为keyword，同时高亮显示函数的名称作为title。之间的空格会被匹配，但不会高亮显示。

注意

在内部，数组中的每个正则表达式都成为更大的串联正则表达式中的一个捕获组。如果您的正则表达式使用捕获组（或引用），它们将被自动重命名，以便它们继续工作而无需任何更改。

endScope

11.0 版中的新功能。

type: scope
type: numeric index of scopes (when end is an array)

这与匹配的内容具有相同的行为，beginScope但适用于 end 匹配的内容。

{
  begin: /FIRST/,
  end: /LAST/,
  endScope: "built_in"
}

match

11.0 版中的新功能。

type: regexp or array of regexp

begin当不需要end表达式时，这只是语法糖。它可能不能与beginorend键一起使用（这没有意义）。它的存在只是为了帮助使语法更具可读性。

{
  scope: "title",
  match: /Fish/
}

这相当于：

{
  scope: "title",
  begin: /Fish/
}

on:begin

type: callback (matchData, response)

此回调在检测到开始匹配时触发。matchData包括典型的正则表达式匹配数据；完整匹配、匹配组等。该response对象用于告诉解析器它应该如何处理匹配。它也可以用来临时存储数据。

response.data- 一个简单的对象数据存储。可用于构建更复杂的规则，其中结束规则取决于开始等的内容。
response.ignoreMatch()- 假装这场比赛从未发生过。未进入该模式。继续尝试当前模式contains列表中的后续模式

有关用法示例，请END_SAME_AS_BEGIN参见modes.js。

end

type: regexp

结束模式的正则表达式。例如，字符串的单引号或单行注释的“$”（行尾）。

通常情况下，开头的正则表达式定义了整个模式并且不需要任何特殊的结尾。例如，可以定义一个跨越所有数字的数字。begin: "\\b\\d+"

如果不存在，则end默认为匹配任何内容的正则表达式，因此模式立即结束（在可能匹配任何子contains模式之后）。

有时，模式不能自行结束，而是隐含地以其包含（parent）模式结束。

on:end

type: callback (matchData, response)

此回调在检测到结束匹配时触发。matchData包括典型的正则表达式匹配数据；完整匹配、匹配组等。该response对象用于告诉解析器它应该如何处理匹配。它还可以用于检索从开始回调存储的数据。

response.data- 一个简单的对象数据存储。可用于构建更复杂的规则，其中结束规则取决于开始等的内容。
response.ignoreMatch()- 假装这场比赛从未发生过。未进入该模式。继续尝试当前模式contains列表中的后续模式

有关用法示例，请END_SAME_AS_BEGIN参见modes.js。

beginKeywords

type: string

用于代替begin以关键字开头的模式以避免不必要的重复：

{
  begin: '\\b(class|interface)\\b',
  keywords: 'class interface'
}

… 通常可以缩写为：

{
  beginKeywords: 'class interface'
}

这个属性只允许一个简单的空格分隔关键字列表。如果您确实需要的附加功能，keywords或者您只需要此模式的更多关键字，您可以keywords将beginKeywords。

提示

beginKeywords还会检查.关键字之前或之后的a，如果找到则将无法匹配。这是为了避免方法调用或属性访问的误报。前任。会匹配，而不会匹配。class A { ... }A.class == B.class

endsWithParent

type: boolean

指示模式在其父模式结束时结束的标志。

这可以通过例子得到最好的证明。在 CSS 语法中，选择器有一组包含在符号“{” and “}”中的规则。个别规则用“;”分隔但最后一条规则可以省略终止分号：

p {
  width: 100%;
  color: red
}

简单的end: /;/规则是有问题的——解析器可能会“;”在寻找它永远也找不到(或者以后找不到)-跳过了应该高亮显示的有效内容。这就是endsWithParent有用的地方:

{
  scope: 'rules',
  begin: /\{/,
  end: /\}/,
  contains: [
    {
      scope: 'rule',
      end: ';', 
      endsWithParent: true
    }
  ]
}

endsParent

type: boolean

在当前模式关闭后立即强制关闭父模式。

这用于没有易于表达的结束词位但可以在找到最后一个有趣的子模式后关闭的模式。

这是一个在 Elixir 中定义函数的两种方法的示例，一种使用关键字do，另一种使用逗号：

def foo :clear, list do
  :ok
end

def foo, do: IO.puts "hello world"

请注意，在第一种情况下，函数标题后的参数列表也可能包含逗号。如果我们只对高亮显示标题感兴趣，我们可以告诉它在其自身之后结束函数定义：

{
  scope: 'function',
  beginKeywords: 'def', 
  end: hljs.MATCH_NOTHING_RE,
  contains: [
    {
      scope: 'title',
      begin: hljs.IDENT_RE,
      endsParent: true
    }
  ]
}

end: hljs.MATCH_NOTHING_RE确保函数永远不会自行结束。

keywords

type: object / string / array

关键字定义有三种形式。

一串以空格分隔的关键字，|后为可选项：

'for while if|0 else weird_voodoo|10 ...'

一组关键字（可选项|）：

[
  "for",
  "while",
  "if|0"
]

信息

建议使用数组形式（每行一个关键字）而不是字符串，以简化以后的维护。这是核心库的语法部分所遵循的样式。

描述多组关键字和（可选）用于定位它们的模式的对象：

{
  keyword: [ 'for', 'while', 'if|0' ],
  literal: [ 'true', 'false' ],
  $pattern: /\w+/
}

有关更详细的说明，请参阅语言定义指南。

illegal

type: regexp or array

为模式定义非法符号的正则表达式或数组。当解析器发现非法匹配时，它可能会立即完全停止解析整个语言（请参阅参考资料ignoreIllegals）。通过快速排除一种语言（当发现非法匹配时），巧妙地使用非法语言可以极大地提高自动检测能力。

{
  illegal: /%/,
  // or using an array
  illegal: [ /%/, /cookies/ ]
}

excludeBegin, excludeEnd

type: boolean

从模式内容中排除开始或结束匹配。例如，在CSS语法中，规则以分号结束。然而，从视觉上看，最好不要把分号视为规则内容的一部分。使用excludeEnd: true强制在分号前关闭规则的<span>元素。

分号仍然被规则消耗，并且不能被其他后续规则匹配。

returnBegin

type: boolean

将刚找到的开始语义返回到解析器。当子模式的开头是一个复杂的表达式时，使用它不仅应该在父模式中找到，而且还应该根据子模式的规则进行解析。

注意

由于解析器有效地返回，因此很可能在此处创建无限循环，因此请谨慎使用！

returnEnd

type: boolean

将刚刚找到的结束语义返回到解析器。例如，这用于解析嵌入到 HTML 中的 JavaScript。以 HTML 结束标签</script>则无法使用 JavaScript 规则解析。因此，它会返回到知道如何处理它的父 HTML 模式。

注意

由于解析器有效地返回，因此很可能在此处创建无限循环，因此请谨慎使用！

contains

type: array

可以在模式中找到的子模式列表。有关详细说明，请参阅语言定义指南。

starts

type: mode

当前模式结束后将立即启动的模式。新模式不会包含在当前模式中。

目前，此属性用于高亮显示 HTML 中包含的 JavaScript 和 CSS。标记<script>并<style>启动使用另一种语言定义来解析其内容的子模式。

variants

type: array

修改模式的主要定义，有效地将其扩展为几个类似的模式，每个模式的所有属性都由变体增强或覆盖：

{
  scope: 'string',
  contains: ['self', hljs.BACKSLASH_ESCAPE],
  relevance: 0,
  variants: [
    {begin: /"/, end: /"/},
    {begin: /'/, end: /'/, relevance: 1}
  ]
}

提示

variants对包含contains: ['self']有非常具体的行为。让我们考虑上面的例子。虽然您可能认为这将允许您在任何其他字符串中嵌入任何类型的字符串(双引号或单引号)，但它并没有。

这些变量被编译成两种离散模式:

{ scope: 'string', begin: /"/, contains: ['self', ... ] }
{ scope: 'string', begin: /'/, contains: ['self', ... ] }

每个模式self仅指新的扩展模式，而不是带有变体的原始模式（编译后不再存在）。

subLanguage

type: string or array

用另一种语言高亮显示模式的全部内容。

使用此属性时，没有必要定义内部解析规则，如关键字scope等。此外，由于子语言已经将文本包装在自己的<span class="language-name">标签中，因此建议避免使用该属性。

属性的值控制将使用哪种或哪些语言高亮显示：

语言名称：使用指定语言显式高亮显示
空数组：自动检测所有可用的语言
语言名称数组：自动检测限制在指定集合

skip

type: boolean

跳过该模式的任何标记处理，确保它与开始和结束词位一起保持其父缓冲区的一部分。当它需要复杂的解析时，它与父级的子语言一起工作。

包含在 HTML 中 PHP 解析：

<p><? echo 'PHP'; /* ?> */ ?></p>

包含在/* .. */的中?>不应该是 php 语法结束标志，需要正确找到匹对?>的结束标志

{
  begin: /<\?/, end: /\?>/,
  subLanguage: 'php',
  contains: [{begin: '/\\*', end: '\\*/', skip: true}]
}

没有skip: true的每条注释都会导致解析器退回到 HTML 模式。

数据类型​

语言属性​

name​

unicodeRegex​

case_insensitive​

aliases​

classNameAliases​

disableAutodetect​

编译器扩展​

mode​

parentMode​

模式属性​

className​

scope​

begin​

beginScope​

endScope​

match​

on:begin​

end​

on:end​

beginKeywords​

endsWithParent​

endsParent​

keywords​

illegal​

excludeBegin, excludeEnd​

returnBegin​

returnEnd​

contains​

starts​

variants​

subLanguage​

skip​

数据类型

语言属性

name

unicodeRegex

case_insensitive

aliases

classNameAliases

disableAutodetect

编译器扩展

mode

parentMode

模式属性

className

scope

begin

beginScope

endScope

match

on:begin

end

on:end

beginKeywords

endsWithParent

endsParent

keywords

illegal

excludeBegin, excludeEnd

returnBegin

returnEnd

contains

starts

variants

subLanguage

skip