Erstellen einer Formatierungs-Erweiterung

21. November 2016 von Johannes Rieken, @johannesrieken

Seit seiner Einführung bietet die Visual Studio Code-Erweiterungs-API Unterstützung für Quellcode-Formatierer. Die ersten von uns erstellten Sprach-Erweiterungen, z. B. für TypeScript, C# und Go, nutzten die Formatierungs-API. Wir haben diesen Blogbeitrag verfasst, um die Best Practices für die Implementierung von Formatierern zu erläutern.

Die Erweiterungs-API von VS Code folgt einer Reihe von Leitprinzipien. Der Kern dieser Prinzipien ist, dass VS Code das Grundgerüst bereitstellt und Erweiterungen die "Intelligenz". Das übliche Muster ist, dass VS Code die Benutzeroberfläche für ein Feature bereitstellt und die Erweiterungen die notwendigen Daten liefern, um es glänzen zu lassen.

Der Hauptvorteil der Nutzung der Erweiterungs-API für die Implementierung eines Formatierers liegt in der Bereitstellung der Aktionen Dokument formatieren und Auswahl formatieren. Diese Aktionen sind im Kontextmenü des Editors verfügbar, an Tastenkombinationen gebunden und in der Befehlspalette sichtbar. Die Verwendung der API führt zu einer konsistenten Benutzererfahrung über alle Formatierungs-Erweiterungen hinweg.

Die Formatierungs-API

Die unten stehenden Code-Schnipsel zeigen, was bei der Implementierung eines Formatierers zu tun und zu lassen ist. Die beste Vorgehensweise ist die Verwendung der Formatierungs-API und nicht die Erstellung einer neuen Aktion wie "Foo-Datei formatieren". Das vollständige Beispiel für die Erweiterung finden Sie auf 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')];
    }
  }
});

Vor kurzem haben wir die Funktion "Beim Speichern formatieren" hinzugefügt. Eine Erweiterung, die die Formatierungs-API ordnungsgemäß implementiert, unterstützt diese Funktion ohne zusätzlichen Code.

Tipp: Um dies zu nutzen, muss eine Formatierungs-Erweiterung über den API-Aufruf registerDocumentFormattingEditProvider registriert werden.

Mehrere Formatierer

Ein häufiges Missverständnis ist, dass man bei der Bereitstellung eines Formatierers alle Programmiersprachen unterstützen muss. Wenn eine Erweiterung sich mit registerDocumentFormattingEditProvider als Formatierer registriert, gibt sie mit einem DocumentSelector an, welche Programmiersprachen sie unterstützt. Mit dieser Information kann der Editor die Formatierungsaktionen aktivieren, wenn beispielsweise ein HTML-Dokument geöffnet ist. Ebenso deaktiviert der Editor die Formatierungsaktionen beim Anzeigen von Dokumenten, für die kein Formatierer registriert ist.

Was passiert, wenn es mehrere Formatierer für eine Sprache gibt? Das kann zu Problemen führen, wenn sich die Aktionen verschiedener Formatierer widersprechen. In der Oktober-Version haben wir Einstellungen hinzugefügt, um die mit VS Code ausgelieferten Standardformatierer zu aktivieren oder zu deaktivieren. Die beste Vorgehensweise für Erweiterungsautoren ist, eine ähnliche Einstellung hinzuzufügen, wie wir sie in VS Code vorgenommen haben, wie unten gezeigt.

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

Eine Erweiterung fügt Einstellungen über den Erweiterungspunkt contributes.configuration hinzu.

Formatierer im Marketplace

Zuletzt möchten wir die Bekanntheit von Formatierern erhöhen und haben dem Marketplace eine neue Kategorie "Formatierer" hinzugefügt. Wir haben sie mit beliebten Formatierungs-Erweiterungen bestückt und laden Formatierer-Autoren ein, ihre ebenfalls hinzuzufügen. Sie können auch Erweiterungspacks verwenden, um eine Formatierungs-Erweiterung mit anderen Erweiterungen für Ihre bevorzugte Sprache zu bündeln.

Zusammenfassung

Zusammenfassend lässt sich sagen, dass eine Erweiterung, die die Formatierungs-Erweiterungs-API ordnungsgemäß implementiert, Folgendes tun wird:

1. Formatierer über registerDocumentFormattingEditProvider registrieren.
2. Die Formatierungslogik gemäß der DocumentFormattingEditProvider-Schnittstelle implementieren.
3. Eine Einstellung zum Aktivieren / Deaktivieren des Formatierers haben.
4. Die Kategorie "Formatierer" zum Erweiterungsmanifest hinzufügen.

Wir sind mit der Feature-Arbeit für Formatierer noch nicht fertig. "Beim Einfügen formatieren", "Dateien im Ordner formatieren" und mehr stehen auf unserer Roadmap und wir warten gerne auf Ihr weiteres Feedback und Ihre Ideen.

#HappyCoding

Johannes Rieken, Mitglied des VS Code Teams
@johannesrieken