建立格式化程式擴充套件

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