创建格式化程序扩展

2016年11月21日，作者：Johannes Rieken，@johannesrieken

自推出以来，Visual Studio Code 扩展 API 就一直支持源代码格式化程序。我们构建的第一个语言扩展，例如 TypeScript、C# 和 Go，都使用了格式化 API。我们撰写此博客是为了解释实现格式化程序的最佳实践。

VS Code 的扩展 API 遵循一套指导原则。这些原则的精髓是 VS Code 提供框架，而扩展提供“智能”。常见的模式是 VS Code 提供围绕某个功能的 UI，而扩展提供使该功能出彩所需的数据。

使用扩展 API 实现格式化程序的核心优势在于提供了格式化文档和格式化选区操作。这些操作在编辑器上下文菜单中可用，绑定到键盘快捷键，并在命令面板中可见。使用 API 可以使所有格式化程序扩展的用户体验保持一致。

格式化 API

下面的代码片段展示了在实现格式化程序时应该做什么和不应该做什么。最佳实践是使用格式化 API，而不是创建新的操作，例如“格式化 Foo 文件”。完整的扩展示例可在 GitHub 上找到。

// 👎 formatter implemented as separate command
vscode.commands.registerCommand('extension.format-foo', () => {
  const { activeTextEditor } = vscode.window;

  if (activeTextEditor && activeTextEditor.document.languageId === 'foo-lang') {
    const { document } = activeTextEditor;
    const firstLine = document.lineAt(0);

    if (firstLine.text !== '42') {
      const edit = new vscode.WorkspaceEdit();
      edit.insert(document.uri, firstLine.range.start, '42\n');

      return vscode.workspace.applyEdit(edit);
    }
  }
});

// 👍 formatter implemented using API
vscode.languages.registerDocumentFormattingEditProvider('foo-lang', {
  provideDocumentFormattingEdits(document: vscode.TextDocument): vscode.TextEdit[] {
    const firstLine = document.lineAt(0);
    if (firstLine.text !== '42') {
      return [vscode.TextEdit.insert(firstLine.range.start, '42\n')];
    }
  }
});

最近，我们添加了“保存时格式化”功能。正确实现格式化 API 的扩展无需任何新代码即可支持此功能。

提示：要利用此功能，格式化扩展需要使用 registerDocumentFormattingEditProvider API 调用进行注册。

多个格式化程序

一个常见的误解是，当贡献格式化程序时，您必须支持所有编程语言。当扩展通过 registerDocumentFormattingEditProvider 注册为格式化程序时，它会通过 DocumentSelector 指明它支持哪些编程语言。有了这些信息，当例如打开 HTML 文档时，编辑器就可以启用格式化操作。同样，当显示未注册格式化程序的文档时，编辑器将禁用格式化操作。

当一种语言有多个格式化程序时会发生什么？当不同格式化程序的操作相互矛盾时，这可能会成为一个问题。在十月版本中，我们添加了设置来启用或禁用 VS Code 自带的默认格式化程序。最佳实践是扩展作者添加类似的设置，就像我们在 VS Code 中所做的那样，如下所示。

"html.format.enable": true,
"javascript.format.enable": true,
"typescript.format.enable": true,
"json.format.enable": true

扩展通过 contributes.configuration 扩展点添加设置。

市场中的格式化程序

最后，我们希望提高格式化程序的知名度，并在市场中添加了新的 “格式化程序”类别。我们已经用流行的格式化扩展填充了它，并邀请格式化程序作者也添加他们的扩展。您还可以使用扩展包将格式化程序扩展与您喜欢的语言的其他扩展捆绑在一起。

总结

总而言之，一个正确实现格式化扩展 API 的扩展将执行以下操作：

通过 registerDocumentFormattingEditProvider 注册格式化程序。
根据 DocumentFormattingEditProvider 接口实现格式化逻辑。
拥有一个用于启用/禁用格式化程序的设置。
将“Formatters”类别添加到扩展清单中。

我们尚未完成格式化程序的功能开发。“粘贴时格式化”、“格式化文件夹中的文件”等更多功能正在我们的路线图上，我们期待您提供更多反馈和想法。

#HappyCoding

Johannes Rieken，VS Code 团队成员
@johannesrieken