Language 类的实例化对象用于管理语法解析器，以及与交互相关的编程语言元信息

使用方法 new Language(data, parser, extraExtensions⁠?, name⁠?) 进行实例化，创建一个 language 语法对象

实例化中各参数的具体介绍如下：

• 第一个参数 data：一个 facet 动态配置项，包含与当前解析器所针对的编程语言的与交互相关的元信息（例如代码自动补全的参考源、行注释符的信息、括号自动闭合的信息等）
  需要同时将该参数的值设置为对应解析器的语法树的顶级节点的 node prop 节点属性 languageDataProp 的值（由于文档可能支持多种语言，将元信息与语法树的顶级节点相绑定，就可以在用户编辑不同编程语言所对应的内容时，加载相应的元信息）
  与交互相关的编程语言元信息

  与交互相关的编程语言元信息包括行注释符号、自动补全、缩进策略、括号匹配等

  虽然这些信息在语法解析器（第二个参数 parser）里都已经包含，但是语法解析器是用于处理编辑器里（已存在）的文本内容（以提供高亮、代码折叠等功能），并不直接与编辑交互相关

  所以要单独提供与编辑交互相关的信息，以便实现类似 toggle 切换注释等交互功能

  用对象来表示这些元信息，可以具有以下字段

  • commentTokens 属性：与注释相关，可以继续细分为 block 块级注释（包含字段 open 和 close 分别表示块级注释的起始符号和结束符号），以及 line 行注释
  • autocomplete 属性：与自动补全相关
  • closeBrackets 属性：与括号匹配相关
  • indentOnInput 属性：与自动缩进相关

  这些属性的值具体应该如何设置，可以参考官方预制的一系列语言包

  对比

  在 CodeMirror 提供了一些属性和方法，用于配置和读取 language data（与交互相关的）编程语言元信息：

  • @codemirror/language 模块导出的方法 defineLanguageFacet(baseData)：基于传入的 baseData 元信息对象，生成一个 facet，用于在初始化 class Language 类的时侯，为编辑器添加（交互相关的）编程语言元信息
    该方法的返回值除了是一个 facet 还符合 lezer node prop 格式，这些元信息是与特定编程语言相关的，所以也要将该函数的返回值用作语法树的顶级节点的节点属性 languageDataProp 的值（如果使用 class LRLanguage 创建语言实例，则不需要手动将元信息添加语法树的顶级节点上，因为该类实例化时在内部已经完成了相关操作）
  • 语言实例 language 具有属性 data 它是一个 facet，用于设置/追加 language data 元信息
    该方式添加的元信息不需要再手动添加到语法树的顶级节点上，系统会自动处理
  • @codemirror/state 模块导出的静态属性 static EditorState.languageData：该变量是一个 facet，用于设置（交互相关的）非特定语言专属的元信息，适用于整个编辑器的元信息
    其实该 facet 在内部整合了所有与 language 相关的元信息，包括在实例化 class Language 类时所配置的针对特定语言的元信息，以及直接通过该 facet 所配置的不针对特定语言的元信息
  • @codemirror/state 模块的 EditorState 编辑器状态实例化对象的方法 languageDataAt(name, pos, side⁠?) 用于获取在给定位置 pos 与语言相关的元信息，这些信息与字段 name 相关（例如 commentTokens 表示与注释相关）
    通过该方法可以获取通过 EditorState.languageData 和 defineLanguageFacet(baseData) 所设置的元信息
  
  元信息是用对象来表示的，传递给方法 defineLanguageFacet(baseData⁠) 进行处理，返回一个 facet 就可以作为 data 参数的值（记得还需要同时配置解析器 parser，将该参数值作为语法树的顶级节点的 languageDataProp 节点属性的值）
  js

  import{ Language, defineLanguageFacet, languageDataProp } from '@codemirror/language'
  
  // 使用方法 defineLanguageFacet 对元信息进行处理
  const data = defineLanguageFacet({
    commentTokens: {
      line: "//",
      block: {
        open: "/*",
        close: "*/"
      }
    },
  });
  
  // 假设这里的 parser 采用的是 Lezer 生成的解析器
  // 需要对其进行配置，以将 data 参数（作为顶级节点的 `languageDataProp` 节点属性）绑定到语法树上
  // refer to https://github.com/codemirror/language/blob/main/src/language.ts#L185-L188
  const parserWithMetadata = parser.configure({
    // 将 data 为 top 节点设置 languageDataProp 节点属性
    props: [languageDataProp.add(type => type.isTop ? data : undefined)]
  });
  
  // 实例化，使用经过配置的解析器 parserWithMetadata
  new Language(data, parserWithMetadata);
  

  说明

  参数 data 所设置的值需要和解析器顶级节点的节点属性 languageDataProp 的值一致，由于 language 对象方法 findRegions 会基于两者来判断/寻找编辑器的文档各部分分别采用什么语言进行解析（文档内容可能是存在嵌套语言的情况，例如 HTML 文档里嵌套了 JavaScript 和 CSS 内容）

• 第二个参数 parser：一个语法解析器实例对象（要符合 Lezer 的抽象类 abstract class Parser）
• 第三个（可选）参数 extraExtensions⁠：一个数组，其值需要符合 type Extension，用于设置需要同步加载的插件，默认值是空数组 []
• 第四个（可选）参数 name：一个字符串，用于设置该编程语言的名称，默认值是 "" 空字符串

Language 类的实例化得到 language 对象，以下称作「语言实例」

language 语言实例对象包含一些属性和方法：

• extension 属性：实现该语言的一系列相关插件
  该属性值符合 type Extension 类型
  插件的构成

  根据源码该属性包含一系列插件，主要由 3 部分构成：

  • language facet 生成的插件，该 facet 的值就是当前 Language 类的实例
    可以通过该 facet 获取当前编辑器所激活的语言
  • EditorState.languageData facet 生成的插件，该 facet 包含当前语言（包括内嵌语言 sub language）相关的元信息
  • 实例化 language 时，通过参数 extraExtensions⁠ 所设置的需要同步加载的插件
• parser 属性：该语言所采用的语法解析器（要符合 Lezer 的抽象类 abstract class Parser）
• data 属性：该语言相关的元信息（一个 facet，就是实例化 language 时，通过第一个参数 data 所设置的元信息）
  也可以通过该 facet 添加额外的元信息，例如添加代码补全的相关信息
  通过该方式添加的元信息不需要再手动添加到语法树的顶级节点上，系统会自动处理
• name 属性：一个字符串，表示该语言的名称
• isActiveAt(state, pos, side?) 方法：查询当前语言是否在给定文档位置 pos（以字符偏移量表示）激活，返回一个布尔值
  参数 state 是编辑器文档状态对象
  如果该位置正好是两种不同的语言内容的分界线，（可选）参数 side 的值可以是 -1、0 或 1 这三个值之一，用于表示查询位置是偏向左侧还是右侧，默认值为 -1 表示以左侧的内容所采用的语言为准
• findRegions(state) 方法：获取在给定文档状态 state 中，使用该语言进行解析的文档范围，返回一个数组 {from: number, to: number}[] 表示范围
  嵌套语言

  如果文档里含有嵌套语言，如果这些它们是包含在当前语言里，那么返回的范围数组也会囊括该嵌套语言的内容

• allowsNesting 属性：一个布尔值，表示当前语言（其解析的内容）是否支持嵌套语言 nested language，默认值为 true

另外该模块还导出一个变量 sublanguageProp，它是一个 node prop 节点属性，用于将嵌套语言的元信息绑定到语法树的顶级节点上，其值是一个数组 Sublanguage[]（即其中的元素要符合 interface Sublanguage 类型）

将嵌套语言的元信息绑定到语法树的顶级节点上的流程，具体参考上文设置节点属性 languageDataProp 的示例

该模块还导出一些辅助函数，以进行语法解析相关操作

• syntaxTree(state) 方法：获取给定的编辑器状态对象 state 所对应的解析语法树，返回一个对象，它符合 class Tree 类型（该语法树可能只是对部分文档进行解析）
• ensureSyntaxTree(state, upto, timeout?) 方法：和上一个方法类似，获取给定的编辑器状态对象 state 所对应的解析语法树，返回一个对象，它符合 class Tree 类型
  不同在于该方法会让解析的文档内容至少达到 upto 位置（以字符偏移量表示），执行解析操作的最长时间限制在 timeout（默认值是 50）以内
• syntaxTreeAvailable(state, upto?) 方法：查询当前语法树是否覆盖到给定文档状态 state 的指定位置 upto（默认值是 state.doc.length 即整个文档的范围），返回一个布尔值
  如果还没有解析到给定位置 upto，那么后台运行的解析器可能会继续运行，但是不能保证最后会解析到目标位置，因为当解析器运行超过特定时间，或给定位置超出视口 viewport 时，解析器就会停止运行
• forceParsing(view, upto?, timeout?) 方法：强制执行解析操作，让语法树覆盖到给定位置 upto（默认值是 view.viewport.to 即编辑器视图的结尾），并更新编辑器状态以保证包含最新的语法树
  执行解析操作的最长时间限制在 timeout（默认值是 100）以内
  最后返回一个布尔值，表示在规定时间解析生成的语法树是否覆盖到给定位置 upto
• syntaxParserRunning(view) 方法：检查解析器当前是否在运行，返回一个布尔值

如果要自定义解析器，可能需要使用 class ParseContext，该类将编辑器内容作为上下文提供给解析器

LanguageSupport 类的实例化对象对 language 语言对象和所依赖的插件进行封装

使用方法 new LanguageSupport(language, support?) 进行实例化，根据一个 supportLanguage 对象，它将给定的 language 语法对象，和一系列（为了支持该语言实现相关功能的依赖性）插件 support 打包起来

LanguageSupport 类的实例化得到 supportLanguage 对象，以下称作「语言支持性封装实例」

supportLanguage 语言支持性封装实例对象包含一些属性：

• extension 属性：一个插件（符合 type Extension 类型），包括 language 语法对象，以及一系列所依赖的支持性插件
  提示

  该类的实例化对象自身就可以作为插件（与该属性值相同）

  所以上述语言包一般会导出一个（与所支持的编程语言）同名的函数，调用该函数返回的值就是一个 class LanguageSupport 的实例化对象，然后可以将该对象作为插件，在初始化编辑器将其添加到配置参数的里

  js

  import {EditorView, basicSetup} from "codemirror"
  // 官方为 HTML 提供了语言包 @codemirror/lang-html
  // 该语言包导出了一个（和该编程语言名称相同的）函数 html
  import {html} from "@codemirror/lang-html"
  
  const view = new EditorView({
    parent: document.body,
    // 调用该函数 html() 生成一个插件，将该语言及其相关依赖插件添加到编辑器上
    extensions: [basicSetup, html()]
  })
  

• language 属性：语言实例对象
• support 属性：（为了支持该语言实现相关功能的）依赖性插件，即实例化 LanguageSupport 时所传递的参数 support 的值
  提示

  如果所关联的语言对象支持嵌套语言，那么该参数应该包含嵌套语言所依赖的相关插件

自动按需加载语言包是代码编辑器的常见需求，即编辑器根据用户所选择打开的源代码文件，（基于其元信息，例如拓展名）动态异步加载对应的语言包。LanguageDescription 类就是用于存储这些与编程语言相关的元信息，提供统一的接口以便开发者可以管理多种语言包

使用该类的静态方法 LanguageDescription.of(spec) 进行实例化，基于配置对象 spec ，为一种编程语言创建一个 languageDescription 语言描述性对象

实例化配置对象 spec 具有的属性：

• name 属性：字符串，用于设置编程语言的名称
• alias 属性：一个数组，其元素是一个个字符串，用于设置编程语言的别名
• extensions 属性：一个数组，其元素是一个个字符串，用于设置（使用该编程语言编写的）源文件的拓展名（即文件的后缀名）
• filename（可选）属性：一个正则表达式对象，用于设置该编程语言所编写的源文件名称所需匹配的模式
• load（可选）方法：一个函数 fn() → Promise<LanguageSupport> 用于异步加载对应的 LanguageSupport 语言支持性封装实例
• support（可选）属性：一个 LanguageSupport 语言支持性封装实例

LanguageDescription 类的实例化得到 languageDescription 对象，以下称作「语言描述性实例」

languageDescription 语言描述性实例对象包含一些属性：

• name 属性：编程语言的名称
• alias 属性：一个数组，其元素是一个个字符串，表示编程语言的别名
• extensions 属性：一个数组，其元素是一个个字符串，表示（使用该编程语言编写的）源文件的拓展名（即文件的后缀名）
• filename 属性：有两种类型，可能是一个正则表达式对象，表示（使用该编程语言所编写的）源文件名称所需匹配的模式；也可能是 undefined，表示（使用该编程语言所编写的）源文件名称没有特定的约束
• support 属性：有两种类型，可能是一个 LanguageSupport 语言支持性封装实例对象；也可能是 undefined
• load() 方法：一个异步函数 Promise<LanguageSupport> 用于动态加载相应的 LanguageSupport 语言支持性封装实例对象

该类还提供两个静态方法，以便基于源文件的元信息，匹配加载合适的语言包：

• static LanguageDescription.matchFilename(descs, filename) 静态方法：根据给定的 filename 源文件名称（字符串）对数组 descs 里的元素（一个个语言描述性实例）进行查询，返回第一个匹配的语言描述性实例，如果没有找到合适的就返回 null
  查询时首先基于语言描述性实例的文件名称的正则表达式模式进行匹配，然后再基于扩展名（即文件的后缀）进行匹配
• static LanguageDescription.matchLanguageName(descs, name, fuzzy?) 静态方法：根据给定的字符串 name 对数组 descs 里的元素（一个个语言描述性实例）进行查询，返回第一个编程语言的名称（或别名）与参数 name 相匹配的语言描述性实例，如果没有找到合适的就返回 null
  参数 name 是大小写敏感的；（可选）参数 fuzzy 是一个布尔值（默认为 true），表示是否启用模糊匹配，如果没有完全匹配时，会进一步采用部分匹配的情况，即编程语言的名称（或别名）出现在字符串 name 里面，如果编程语言的名称少于 3 个字符，则匹配时前后都需要是非单词型字符（例如空格）才算成功

DocInput 类用于将 CodeMirror 文档内容（class Text 类的实例）转换为 Lezer 所支持的格式 TypeScript interface Input（所以该类的实例化对象也符合 interface Input）

使用方法 new DocInput(doc) 进行实例化，参数 doc 是一个 Text 类的实例，表示 CodeMirror 文档内容

• foldService 变量：一个 facet 动态配置项，用于注册代码折叠服务
  其输入值是一个函数 fn(state: EditorState, lineStart: number, lineEnd: number) 基于传入的行范围 lineStart 和 lineEnd，计算出可折叠范围
  如果可以找到就返回一个对象 {from: number, to: number} 表示可折叠范围（from 是该行的开始位置，采用文档里的字符偏移量表示，to 表示可折叠范围的结束位置，可能超出该行的末尾 lineEnd）；如果基于该行没有找到可折叠范围，则返回 null
  通过该方式可以不依赖语法树，为编辑器添加代码折叠信息，例如在 @codemirror/lang-markdown 模块里将标题设置为可折叠
  ts

  const headerIndent = foldService.of((state, start, end) => {
    for (let node: SyntaxNode | null = syntaxTree(state).resolveInner(end, -1); node; node = node.parent) {
      if (node.from < start) break
      let heading = node.type.prop(headingProp)
      if (heading == null) continue
      let upto = findSectionEnd(node, heading)
      if (upto > end) return {from: end, to: upto}
    }
    return null
  })
  

• foldNodeProp 变量：它是一个 node prop 节点属性，用于为语法树上特定的节点类型设置可折叠信息
  通过该方式添加的折叠信息是依赖语法树的，要基于节点类型进行配置，大概流程如下：
  1. 通过调用 node prop 的方法 foldNodeProp.add(match: Object<T> | fn(type: NodeType) → T | undefined) 为特定的节点类型设置折叠信息
  
  传入的参数可以是一个对象，以键值对的方式为不同的节点类型设置折叠信息，键名是节点类型的名称；也可以传入一个函数 fn(type: NodeType) 动态为不同节点类型 type 设置折叠信息
  该节点属性的值（如果是采用对象的方式，则是键名对应的值；如果是采用函数的形式，则是该函数的返回值）是一个函数 fn(node: SyntaxNode, state: EditorState) → {from: number, to: number} | null 称为 fold function 折叠区域计算函数，因为它是基于当前语法树上的节点 node 和编辑器状态 state，返回一个对象，表示该节点对应的可折叠范围（以文档里的字符偏移量来表示）{from: number, to: number}，如果该节点不能折叠则返回 null
  foldInside 辅助函数

  @codemirror/language 模块提供了一个内置的折叠区域计算函数 foldInside，针对常见的可折叠场景，即节点的两端都是分别含有一个分界符的，折叠范围是分界符里面的内容

  如果通过 foldNodeProp 为特定节点类型设置可折叠信息时，该节点的两端都是分别含有一个分界符的，就可以直接适用 foldInside 作为折叠函数

  2. 调用该方法会返回一个函数（符合 TypeScript type NodePropSource 类型），然后将该返回值传递给 NodeSet.extend 方法或 LRParser.configure 方法将这些信息添加到解析器上（也可以在初始化解析器时，作为其配置对象的属性 ParserConfig.props 的值）
  
  例如在 @codemirror/lang-javascript 模块里将一系列节点设置为可折叠
  js

  export const javascriptLanguage = LRLanguage.define({
    // ...
    parser: parser.configure({
      props: [
        // ...
        foldNodeProp.add({
          // 为一系列节点类型设置折叠信息
          // 由于这些节点的两端都是分别含有一个分界符的（常见的可折叠场景）
          // 所以折叠区域计算函数采用内置辅助函数 foldInside
          "Block ClassBody SwitchBody EnumBody ObjectExpression ArrayExpression ObjectType": foldInside,
          // 对于注释块节点，它的折叠方式比较特别
          // 需要保留前后 2 个字符，即折叠后的形式为 /*...*/
          // 所以这里手动计算折叠区域
          BlockComment(tree) { return {from: tree.from + 2, to: tree.to - 2} }
        })
        // ...
      ]
    })
    // ...
  });
  

如果要判断文档里的某一行是否可折叠，可以使用方法 foldable(state, lineStart, lineEnd) 基于传入的行范围 lineStart 和 lineEnd 查找可折叠范围，如果找到就返回一个对象 {from: number, to: number} 以表示折叠范围；如果不可折叠则返回 null。该方法会首先查询通过 foldService 配置的折叠信息，如果没有相关信息则继续查询通过 foldNodeProp 配置的折叠信息

该模块提供了一系列 command 指令，用于以编程式的方式来折叠（或展开）代码文本

• foldCode 变量：一个 Command 指令，折叠选中的行（如果选中行是可折叠的）
• unfoldCode 变量：一个 Command 指令，展开选中行（如果选中的行是处于折叠状态时）
• toggleFold 变量：一个 Command 指令，切换光标所在的行的折叠状态
• foldAll 变量：一个 Command 指令，折叠所有在（语法树）顶级的可折叠区域
  注意

  但是对于较大的文档（为了节省性能）可能并没有解析完全，所以使用该命令时，可能并不能保证所有顶级可折叠区域都实现了折叠

• unfoldAll 变量：一个 Command 指令，展开所有折叠

该模块还导出了一个变量 foldKeymap 为上文列出 command 指令设置快捷键。该变量的值是一个数组（里面的每个元素都符合 TypeScript interface KeyBinding），具体映射关系如下：

• Ctrl-Shift-[（macOS 则是 Cmd-Alt-[）绑定 foldCode 指令
• Ctrl-Shift-]（macOS 则是 Cmd-Alt-]）绑定 unfoldCode 指令
• Ctrl-Alt-[ 绑定 foldAll 指令
• Ctrl-Alt-] 绑定 unfoldAll 指令

然后通过 facet keymap 将该变量所配置的快捷键添加到编辑器上

该模块还提供了一些更底层的 API 以控制折叠状态

• foldedRanges(state) 方法：获取给定文档状态 state 里面的所有折叠范围，返回一个 DecorationSet 类的实例（包含一系列 Replacing decoration 替换型装饰器，表示一个个折叠范围）
• foldState 变量：一个 state field 自定义的编辑器状态字段，其值是一个 DecorationSet 类的实例（包含一系列 Replacing decoration 替换型装饰器，表示一个个折叠范围），用于将折叠范围保存在编辑器状态里
  可以将其传递给编辑器状态对象的方法 editorState.toJSON 将编辑器状态和折叠信息序列化为 JSON 对象保存起来，然后通过静态方法 EditorState.fromJSON 将其反序列化还原编辑器器状态及其折叠信息
• foldEffect 变量：一个 StateEffectType 类的实例化对象，通过调用其方法 foldEffect.of({from: number, to: number}) 创建一个相应类型的 stateEffect 对象实例，将该自定义变更效应 stateEffect 添加到 transaction 事务中，以触发折叠给定的范围
• unfoldEffect 变量：一个 StateEffectType 类的实例化对象，通过调用其方法 unfoldEffect.of({from: number, to: number}) 创建一个相应类型的 stateEffect 对象实例，将该自定义变更效应 stateEffect 添加到 transaction 事务中，以触发展开给定的范围

通过方法 codeFolding(config⁠?) 配置折叠后的占位符样式，该方法返回一个插件，以便添加到编辑器（在实例化编辑器视图时，添加到配置对象的属性 config.extensions 上）

该方法的（可选）参数 config 是一个配置对象，具有一些方法和属性：

• placeholderDOM（可选）属性：一个函数 fn(view: EditorView, onclick: fn(event: Event), prepared: any) → HTMLElement 用于创建一个占位符元素 HTMLElement，显示在文档里发生了代码折叠的位置
  其中 onclick 为该元素设置点击事件的响应函数，以展开该折叠范围
  如果配置对象设置了 preparePlaceholder 属性（一个函数），则这里的第三个参数 prepared 就会获取该属性对应函数的返回值，否则该参数的值就是 null
• placeholderText（可选）属性：一个字符串，用于设置占位符的内容，默认值为 ...
  该字符串会带有 CSS class 类名 cm-foldPlaceholder

• preparePlaceholder（可选）属性：一个函数 fn(state: EditorState, range: {from: number, to: number}) → any 基于给定的折叠范围 range 进行一些预处理，返回一个值对该折叠进行描述（例如折叠的字符串数量）
  属性所设置的函数的返回值会传递给配置对象的另一个属性 placeholderDOM 用于创建占位符元素

通过方法 foldGutter(config?) 配置编辑器的侧边栏，该方法返回一个插件，以便添加到编辑器（在实例化编辑器视图时，添加到配置对象的属性 config.extensions 上），然后在相应的可折叠行的前方就会显示一个指示器 indicator（例如三角形图标）以指示其折叠状态，而且该指示器是可点击的，以触发折叠/展开代码

该方法（可选）参数 config 是一个配置对象，具有一些方法和属性：

• markerDOM（可选）属性：一个函数 fn(open: boolean) → HTMLElement 用于创建一个折叠状态指示器 HTMLElement，显示在侧边栏表示对应行的代码折叠状态
• openText（可选）属性：一个字符串，默认值是 "⌄"，用于表示对应行处于未折叠（可折叠）状态
• closedText（可选）属性：一个字符串，默认值是 "›"，用于表示对应行处于已折叠状态

• domEventHandlers（可选）属性：一个对象，以键值对的形式为该侧边栏设置 DOM 事件监听器，键名是 DOM 事件名称，对应的值是事件回调函数
  其中事件处理函数的形式是 fn(view: EditorView, line: BlockInfo, event: Event) → boolean
  它接收三个参数：
  • 第一个参数 view 是编辑器视图
  • 第二个参数 line 是一个 class BlockInfo 类的实例，表示触发该事件所对应的行信息
  • 第三个参数 event 是事件对象
  提示

  该方法在内部已经为 click 事件预设了一个处理函数，以实现（当用户点击指示器时）切换对应行的折叠状态

  不过也可以自定义一个 click 事件的处理函数以覆盖内置的处理函数

  
  事件处理函数最后返回一个布尔值，如果为 true 表示该事件已经处理完成，则针对该事件所设置的（优先级较低的）回调函数就不会执行；如果为 false 则还会继续执行针对同类型事件的其他回调函数
• foldingChanged（可选）属性：一个函数 fn(update: ViewUpdate) → boolean 该函数返回一个布尔值，以控制当视图更新时是否要重新渲染侧边栏的折叠指示器

• indentService 变量：一个 facet 动态配置项，用于注册代码缩进服务
  其输入值是一个函数 fn(context: IndentContext, pos: number) → number | null | undefined 基于缩进上下文 context（一个 class IndentContext 实例对象）计算给定位置 pos 所在的行的缩进量/缩进深度，返回值有多种类型分别对应不同的缩进情况：
  • 如果该函数返回一个数字，表示该行的缩进所占据的列数 column number
  • 如果返回 null 表示无法确定该行的缩进，应该继承上一行的缩进
  • 如果返回 undefined 表示继续执行下一个代码缩进服务（或通过 indentNodeProp 基于语法树）计算该行的缩进量
  IndentContext

  class IndentContext 管理/提供编辑器计算缩进所需的上下文

  通过方法 new IndentContext(sate, options?) 进行实例化，以基于 state 编辑器文档状态获取缩进上下文，在后文将该类的实例化对象称作「缩进上下文」

  实例化时（可选）参数 options 是一个对象（默认值是 {}），用于配置计算缩进的相关规则，具有如下属性：

  • overrideIndentation（可选）属性：一个函数 fn(pos: number) → number（传递给计算缩进的辅助函数）用于覆盖行缩进的计算方式，特别是在实现区域缩进（例如通过方法 indentRange）时很有用
    由于在区域缩进的场景中，后续行的缩进值一般是参考之前的行，但有时候也可能需要进行重新缩进（与执行区域缩进之前的原始状态相比）
    如果配置了此属性，则区域缩进时每处理到一行都会先调用该函数，如果返回 -1 表示该行保存原来缩进量；如果返回其他数值，则更新其缩进
  • simulateBreak（可选）属性：一个数值（表示文档中的位置，以字符偏移量计算），将其视作换行的位置
    在实现 newlineAndIndent command 指令（一般与 Enter 键相绑定）的内部逻辑时会配置该属性
  • simulateDoubleBreak（可选）属性：一个布尔值，如果同时设置了上一个属性 simulateBreak，将给定的位置视作执行了两次换行

  提示

  该类一般不会通过手动进行实例化，而是在配置 facet indentService 时，它的实例化对象作为（facet 的输入值，一个函数）参数提供给开发者直接使用

  缩进上下文 indentContent 对象提供一系列的属性和 helper function 获取针对特定 pos 位置的缩进信息：

  • unit 属性：一个数值，表示缩进单位，即每次缩进对应占据的列数 column number
  • state 属性：该缩进上下所依赖的文档状态
  • lineAt(pos, bias?) 方法：获取给定位置 pos 所在行的信息，返回值是一个对象 {text: string, from: number} 其中属性 text 表示该行的文本内容，from 表示该行开头位置（以字符偏移量计算）
    如果该位置 pos 正好是发生换行，则基于参数 bias（可以是数值 -1 或 1 两者之一，默认值是 1）来决定所要解析的是前面还是后面的行
    该方法会将模拟换行 simulateBreak 也纳入考虑
  • textAfterPos(pos, bias?) 方法：获取给定位置 pos 所在行（在该位置）之后的内容，如果该行（在该位置）之后内容很多，则只返回最多 100 个字符。第二个（可选）参数 bias 其作用和前一个方法一样
  • column(pos, bias?) 方法：获取给定（在文档中）位置 pos 所对应的列数 column number
  • countColumn(line, pos?) 方法：获取给定字符串 line 的位置 pos（默认值是 pos=line.length 即该字符串的结尾位置）所对应的列数 column number

  说明

  前面两个 helper function 辅助函数参数 pos 都是以字符串偏移量来表示位置的，但是如果文档/字符串里包含 Tab 字符，由于 Tab 字符的大小（占据的列数）是可以通过配置 facet 改变的（默认对应 4 列），所以字符偏移量一般和列数可能并不相同（即使只有一行文本内容）

  • lineIndent(pos, bias?) 方法：获取给定位置 pos 所在行的缩进量
  • simulateBreak 属性：一个数字（表示文档中的位置，以字符偏移量计算），表示该上下文会将该位置视作换行的位置，如果没有配置则返回 null
  
  通过该方式可以不依赖语法树，为编辑器添加代码缩进信息
• indentNodeProp 变量：它是一个 node prop 节点属性，用于为语法树上特定的节点类型设置缩进信息
  通过该方式添加的缩进信息是依赖语法树的，要基于节点类型进行配置，大概流程如下：
  1. 通过调用 node prop 的方法 indentNodeProp.add(match: Object<T> | fn(type: NodeType) → T | undefined) 为特定的节点类型设置缩进信息
  
  传入的参数可以是一个对象，以键值对的方式为不同的节点类型设置缩进信息，键名是节点类型的名称；也可以传入一个函数 fn(type: NodeType) 动态为不同节点类型 type 设置缩进信息
  该节点属性的值（如果是采用对象的方式，则是键名对应的值；如果是采用函数的形式，则是该函数的返回值）是一个函数 fn(context: TreeIndentContext) → number | null 称为 indentation strategy 缩进策略，它基于语法树的缩进上下文 context（一个 class TreeIndentContext 实例对象）计算当前节点类型缩进量/缩进深度，如果返回一个数字，表示该节点对应的缩进所占据的列数 column number；如果返回 null，表示无法确定该节点类型的缩进
  TreeIndentContext

  class TreeIndentContext 将缩进信息与语法树相关联，在后文将该类的实例化对象称作「语法树的缩进上下文」

  提示

  该类一般不会通过手动进行实例化，而是在配置 node prop indentNodeProp 时，它的实例化对象作为参数提供给开发者直接使用，例如在 @codemirror/lang-python 模块里基于语法树设置缩进信息

  该类 extends 继承自 class indentContext 类，除了具有父类的一系列的属性和 helper function 辅助函数，还有一些额外的属性和方法以提供基于语法树节点 syntax node 的缩进信息：

  • pos 属性：表示当前所计算的缩进对应（在文档中）位置
  • node 属性：表示当前采用哪个节点的缩进策略
  • textAfter 属性：一个字符串，表示当前所在行于 this.pos 位置之后的内容，如果该行（在该位置）之后内容很多，则只返回最多 100 个字符
  • baseIndent 属性：一个数字，表示 this.node 节点的 reference line 参考行的缩进量/基础缩进量），一般就是该节点的第一行的缩进量
    但如果该节点的起始行并不是占于行首，而是由更高层级的节点包裹，则需要跳过这些节点，直到占据行首的祖先节点，以其缩进量作为当前节点的基础缩进量
  • baseIndentFor(node) 方法：返回一个数字，表示给定的节点 node 的基础缩进量
  • continue() 方法：继续查找当前节点的父节点的缩进量，返回一个数字或 null
  
  该模块针对常见的多行缩进场景，内置了一些 indentation strategy 缩进策略或工厂函数（调用它们可以返回相应的缩进策略）：
  • delimitedIndent({closing: string, align⁠?: boolean, units⁠?: number}) 函数：工厂函数，用于为带有分隔符（一般由成对的符号构成，开始分隔符和闭合分隔符）的节点生成缩进策略
    该方法的配置参数对象的各属性的具体说明如下
    • 第一个参数 closing 是一个字符串，用于设置所需检测的闭合符号（通常是括号，例如 ")"、"]" 或 "}"），由于单独包含闭合分隔符的行是采用不同的缩进策略。如果该行的起始字符与闭合符号匹配，表示它是该节点的结束行，则该行采用该节点的基础缩进量；如果不是结束行，而是该节点的内容区块，则该行缩进量由 unites 决定
    • 第二个（可选）参数 align 是一个布尔值（默认值为 true），用于设置该节点的内容区块的缩进策略。如果为 true（而且起始行是由 non-skipped 非跳过节点包裹）则内容区块的行对齐到开始分隔符的结尾；如果是 false 则内容区块的行比该节点的基础缩进量多出 units 个缩进单位
      js

      // 参数 align 为 true 时
      foo(bar,
          baz) // 该内容块会对齐到开始分隔符 ( 的结尾
      

    • 第三个（可选）参数 units 是一个数字（默认值是 1），用于设置内容块的缩进需要比该节点的基础缩进量多几个缩进单位
      缩进单位

      通过 facet indentUnit 配置缩进单位，默认值是 2 个空格

    
    该工厂函数最后返回一个缩进策略（函数）fn(context: TreeIndentContext) → number，用于配置 node prop indentNodeProp
  • continuedIndent({except⁠?: RegExp, units⁠?: number} = {}) 函数：工厂函数，用于为续行生成缩进策略
    函数具有多行参数，或链式调用等场景会出现续行，这些行的默认缩进量比（所属节点的）基础缩进量多一个缩进单位，通过该工厂所生成缩进策略可以针对特定情况自定缩进量
    该方法的配置参数对象的各属性的具体说明如下
    • 第一个（可选）参数 except 是一个正则表达式对象，当该行的内容匹配时，则该行的缩进量采用 units 个缩进量
    • 第二个（可选）参数 units 是一个数字，用于设置正则表达式所匹配的行采用几个缩进单位
    
    该工厂函数最后返回一个缩进策略（函数）fn(context: TreeIndentContext) → number，用于配置 node prop indentNodeProp
  • flatIndent(context: TreeIndentContext) → number 缩进策略，将节点的内容块都对齐到它的 base indentation 基础缩进量
  2. 调用该方法会返回一个函数（符合 TypeScript type NodePropSource 类型），然后将该返回值传递给 NodeSet.extend 方法或 LRParser.configure 方法将这些信息添加到解析器上（也可以在初始化解析器时，作为其配置对象的属性 ParserConfig.props 的值）

• indentUnit 变量：一个 facet 动态配置项，其输入值是一个字符串，用于设置缩进单元（一次缩进）采用插入什么具体的字符串序列，一般是相同的空白字符（如空格符或制表符），默认值是两个空格符
• indentOnInput() 方法：返回一个插件，将其添加到编辑器（在实例化编辑器视图时，添加到配置对象的属性 config.extensions 上）可以启用输入时自动重新缩进 reindentation 的功能
  说明

  该方法需要同步为编辑器配置语言相关的元信息，其中字段 indentOnInput 用于设置与自动缩进相关的元信息，其值需要是一个正则表达式

  每当输入新文本时，如果从行首到光标位置的文本内容与该正则表达式匹配时，光标所在行将被自动缩进

  正则表达式建议以 ^ 开头，以 $ 结尾，确保所匹配的内容就是从行首直到光标位置（而不是该行中间内容的部分匹配），避免触发不必要的重新缩进

  例如正则表达式 /^\s*\}$/ 表示以闭合的大括号 } 作为该行的首字符时，该行会自动重新缩进

• getIndentation(context, pos) 方法：基于给定的上下文 context（可能是 EditorState 编辑器状态对象或 IndentContext 缩进上下文实例）获取位置 pos 所在行的缩进量，返回一个数字表示缩进所占的列数 column number，如果无法获取到明确的缩进量则返回 null
  编辑器会先遍历所有通过 facet indentService 注册的函数，若其中返回数字或 null 就会停止遍历；若返回 undefined 会继续执行下一个函数，如果没有 indentService 提供缩进值，就会回退到基于语法树的 indentNodeProp 策略，即基于节点类型推断缩进量
• getIndentUnit(state) 方法：获取当前编辑器状态中缩进单元所占据的列数 column number
  如果（通过 facet indentUnit 所设置）表示缩进单位的字符串中包含 \t 制表符，则在计算缩进单元所占据的列数时，需要依据 facet tabSize（用于设置制表符的大小/占据的列宽）的值
• indentString(state, cols) 方法：生成一个字符串，用于作为特定缩进量的占位符，它需要覆盖从 0 到 cols 的列宽距离
  如果（通过 facet indentUnit 所设置）表示缩进单位的字符串中包含 \t 制表符，则生成的字符串优先采用 \t 符号来构建，不足再由空格符来凑
  对比

  有两个 facet 用于配置基本的缩进量：

  • @codemirror/state 模块导出静态属性 EditorState.tabSize 是一个 facet，用于配置 tab size 制表符 \t 的大小，即占据的列宽 column number（默认值为 4）
  • @codemirror/language 模块导出的变量 indentUnit 是一个 facet，用于设置缩进单元（一次缩进）采用插入什么具体的字符串序列

  但是只有在配置 indentUnit 时使用了 \t 制表符，即表示缩进的占位字符串中使用了制表符，EditorState.tabSize 的配置才对文档中的缩进有影响

  两者的具体介绍和区别见论坛的两个讨论：

  • TabSize seems to be ignored (config help requested)
  • CodeMirror 6 set indentation unit

• indentRange(state, from, to) 方法：对于编辑器文档 state 中触及范围 from 到 to 的行执行自动缩进，返回一个 ChangeSet 类的实例（将传递给方法 view.dispatch 以实现缩进的变更）
  注意

  该方法一般是对选定的多行进行批量缩进，或在粘贴多行内容时进行自动排版

  但 auto-indent 的结果不一定是增加缩进，而是基于上下文修正缩进