Dokument-Selektoren

Erweiterungen können ihre Funktionen basierend auf Dokument-Selektoren nach Sprache, Dateityp und Speicherort filtern. Dieses Thema behandelt Dokument-Selektoren, Dokument-Schemata und worauf Erweiterungsautoren achten sollten.

Textdokumente, die sich nicht auf der Festplatte befinden

Nicht alle Textdokumente werden auf der Festplatte gespeichert, z. B. neu erstellte Dokumente. Sofern nicht anders angegeben, gilt ein Dokument-Selektor für alle Dokumenttypen. Verwenden Sie die `scheme`-Eigenschaft von DocumentFilter, um bestimmte Schemata einzugrenzen, z. B. { scheme: 'file', language: 'typescript' } für TypeScript-Dateien, die auf der Festplatte gespeichert sind.

Dokument-Selektoren

Die Visual Studio Code Extension API kombiniert sprachspezifische Funktionen wie IntelliSense mit Dokument-Selektoren über den DocumentSelector-Typ. Sie sind ein einfacher Mechanismus, um Funktionalität auf eine bestimmte Sprache einzugrenzen.

Der unten stehende Snippet registriert einen HoverProvider für TypeScript-Dateien, und der Dokument-Selektor ist die `typescript`-Sprachidentifikatorzeichenfolge.

vscode.languages.registerHoverProvider('typescript', {
  provideHover(doc: vscode.TextDocument) {
    return new vscode.Hover('For *all* TypeScript documents.');
  }
});

Ein Dokument-Selektor kann mehr als nur ein Sprachidentifikator sein, und komplexere Selektoren können DocumentFilter verwenden, um nach `scheme` und Dateispeicherort über ein `pattern`-Pfad-Glob-Muster zu filtern.

vscode.languages.registerHoverProvider(
  { pattern: '**/test/**' },
  {
    provideHover(doc: vscode.TextDocument) {
      return new vscode.Hover('For documents inside `test`-folders only');
    }
  }
);

Der nächste Snippet verwendet den `scheme`-Filter und kombiniert ihn mit einem Sprachidentifikator. Das `untitled`-Schema gilt für neue Dateien, die noch nicht auf der Festplatte gespeichert wurden.

vscode.languages.registerHoverProvider(
  { scheme: 'untitled', language: 'typescript' },
  {
    provideHover(doc: vscode.TextDocument) {
      return new vscode.Hover('For new, unsaved TypeScript documents only');
    }
  }
);

Dokument-Schema

Das `scheme` eines Dokuments wird oft übersehen, ist aber eine wichtige Information. Die meisten Dokumente werden auf der Festplatte gespeichert, und Erweiterungsautoren gehen typischerweise davon aus, dass sie mit einer Datei auf der Festplatte arbeiten. Zum Beispiel wird bei einem einfachen `typescript`-Selektor davon ausgegangen, dass es sich um TypeScript-Dateien auf der Festplatte handelt. Es gibt jedoch Szenarien, in denen diese Annahme zu lax ist und ein expliziterer Selektor wie { scheme: 'file', language: 'typescript' } verwendet werden sollte.

Die Bedeutung davon kommt zum Tragen, wenn Funktionen das Lesen/Schreiben von Dateien von/zur Festplatte betreffen. Schauen Sie sich den unten stehenden Snippet an.

// 👎 too lax
vscode.languages.registerHoverProvider('typescript', {
  provideHover(doc: vscode.TextDocument) {
    const { size } = fs.statSync(doc.uri.fsPath); // ⚠️ what about 'untitled:/Untitled1.ts' or others?
    return new vscode.Hover(`Size in bytes is ${size}`);
  }
});

Der obige Hover-Provider möchte die Größe eines Dokuments auf der Festplatte anzeigen, prüft aber nicht, ob das Dokument tatsächlich auf der Festplatte gespeichert ist. Es könnte sich zum Beispiel um eine neu erstellte und noch nicht gespeicherte Datei handeln. Der richtige Weg wäre, VS Code mitzuteilen, dass der Provider nur mit Dateien auf der Festplatte arbeiten kann.

// 👍 only works with files on disk
vscode.languages.registerHoverProvider(
  { scheme: 'file', language: 'typescript' },
  {
    provideHover(doc: vscode.TextDocument) {
      const { size } = fs.statSync(doc.uri.fsPath);
      return new vscode.Hover(`Size in bytes is ${size}`);
    }
  }
);

Zusammenfassung

Dokumente werden normalerweise im Dateisystem gespeichert, aber nicht immer: Es gibt unbenannte Dokumente, von Git verwendete Cache-Dokumente, Dokumente von Remote-Quellen wie FTP usw. Wenn Ihre Funktion auf Festplattenzugriff angewiesen ist, stellen Sie sicher, dass Sie einen Dokument-Selektor mit dem `file`-Schema verwenden.

Nächste Schritte

Um mehr über das VS Code-Erweiterbarkeitsmodell zu erfahren, probieren Sie diese Themen aus:

• Erweiterungsmanifestdatei - Referenz zur VS Code package.json-Erweiterungsmanifestdatei
• Contribution Points - Referenz zu VS Code Contribution Points