补全项的插入文本、附加编辑和命令分别解决什么？

结论

insertText 决定接受补全时替换范围里写下什么。additionalTextEdits 在同一轮里改其他位置，通常用来补 import。command 在插入完成后额外执行一个命令。三者不要互相替代。

展开

用户选中补全项时，编辑器先用 insertText 替换 range。insertText 可以是普通字符串，也可以是 SnippetString，这样能放占位符和光标停止点。

additionalTextEdits 是同一批 WorkspaceEdit 语义下的额外文本修改，例如在文件顶部加一行 import fs from "fs"。约束是不能和主插入范围重叠。重叠时编辑器无法稳定合并，导入可能插到错误位置，或者补全直接失败。

command 在文本已经插入之后执行。适合触发参数提示、跳到新文件、通知语言服务器「用户接受了这项」。不要用命令再去改同一处文本来模拟 insertText，那样会多一次撤销步骤，光标也不稳定。

filterText 控制怎么匹配用户已输入的前缀，sortText 控制排序，label 只负责显示。三个可以不同，例如显示中文说明，过滤仍按英文关键字。

preselect 和 commitCharacters 是体验细节。提交字符要谨慎，句点、括号这类字符很容易误提交。

容易讲错的点

• 附加编辑不是「插入完成后再发一次 edit」。它和主插入同一轮应用。
• 异步补全里文档版本可能已经变了。返回前看 token.isCancellationRequested，范围要用返回时仍有效的位置。
• 补全列表不要每次都算全工作区符号。该项还没被选中时，用 resolveCompletionItem 再补文档和附加编辑。