CodeMirror 自动补全功能增强：支持异步补全源与变更映射

背景与问题分析

CodeMirror 6的自动补全功能(@codemirror/autocomplete)在实现与语言服务器协议(LSP)集成时面临一些挑战。LSP提供的CompletionItem不仅包含基本的补全标签，还可能包含额外的文本编辑操作(通过textEdit或additionalTextEdits字段)。例如，当自动补全来自其他文件的模块时，语言服务器可能会提供需要在文件顶部添加的import语句作为additionalTextEdit。

当前实现存在两个主要限制：

1. 虽然基础Completion能够映射文档变更，但无法正确处理textEdit和additionalTextEdits的变更映射
2. 在异步补全源获取期间发生的文档变更无法被追踪和映射

解决方案设计

经过讨论，CodeMirror维护者提出了优雅的解决方案：

1. 引入map方法：为CompletionResult添加map方法，签名设计为(CompletionResult, ChangeDesc) → CompletionResult。这个方法会在每次事务发生时被调用，包括补全获取期间的变更。

2. 变更追踪机制：自动补全插件内部已经跟踪了补全获取期间发生的事务变更，这些变更也会通过map方法处理。

技术实现细节

map方法的工作原理

map方法接收两个参数：

• 当前的CompletionResult
• 描述文档变更的ChangeDesc对象

开发者需要实现这个方法，确保补全结果中的位置信息能够正确映射到变更后的文档位置。这对于LSP补全特别重要，因为LSP使用行/列位置表示法，而CodeMirror使用绝对偏移量。

变更映射的处理流程

1. 在补全请求发起时，保存当前文档状态
2. 将LSP返回的位置信息转换为绝对偏移量
3. 使用保存的文档状态和ChangeDesc来映射这些偏移量
4. 处理补全结果时应用所有累积的变更

实际应用示例

以下是处理LSP补全的典型实现模式：

async function lspCompletionSource(context: CompletionContext) {
  const initialDoc = context.state.doc;
  const lspItems = await fetchLspCompletions();
  
  return {
    from: context.pos,
    options: lspItems.map(item => convertToCompletion(item)),
    map(result, changes) {
      // 映射所有补全项的位置信息
      const mappedOptions = result.options.map(option => {
        if (option.apply) {
          // 处理主文本编辑
          option.apply = mapLspEdit(option.apply, changes, initialDoc);
        }
        if (option.additionalTextEdits) {
          // 处理附加文本编辑
          option.additionalTextEdits = option.additionalTextEdits.map(
            edit => mapLspEdit(edit, changes, initialDoc)
          );
        }
        return option;
      });
      return { ...result, options: mappedOptions };
    }
  };
}

高级主题：类型扩展

虽然当前实现不支持泛型CompletionResult，开发者可以通过类型断言来处理自定义的Completion子类。例如：

interface LspCompletion extends Completion {
  lspItem: CompletionItem;
  additionalTextEdits: TextEdit[];
}

// 使用时进行类型断言
const result = {
  // ...其他属性
  options: completions as LspCompletion[]
} as CompletionResult;

最佳实践建议

1. 对于LSP集成，建议在补全请求发起时保存文档快照
2. 实现稳健的位置映射逻辑，处理可能的变更冲突
3. 考虑异步补全场景下的性能优化，避免不必要的重新计算
4. 在多用户协作编辑环境中，特别注意处理并发变更

总结

CodeMirror 6.14.0引入的map方法显著增强了自动补全功能的能力，使其能够更好地支持LSP集成和异步补全场景。通过正确处理文档变更映射，开发者现在可以实现更复杂的补全行为，如自动导入和跨文件引用。这一改进为构建更智能的代码编辑器提供了坚实基础。