文档选择器

扩展程序可以根据语言、文件类型和位置的文档选择器来过滤其功能。本主题讨论文档选择器、文档方案以及作者应该注意的扩展。

文本文档不在磁盘上

并非所有文本文档都存储在磁盘上，例如新创建的文档。除非指定，否则文档选择器适用于所有文档类型。使用DocumentFilter scheme属性可以缩小某些方案的范围，例如{ scheme: 'file', language: 'typescript' }存储在磁盘上的 TypeScript 文件。

文档选择器

Visual Studio Code 扩展 API 将特定于语言的功能（例如 IntelliSense）与通过DocumentSelector类型的文档选择器相结合。它们是一种将功能范围缩小到特定语言的简单机制。

下面的代码片段为 TypeScript 文件注册了一个HoverProvider，文档选择器是typescript语言标识符字符串。

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

文档选择器不仅仅是语言标识符，更复杂的选择器可以使用 DocumentFilter通过路径 glob 模式根据scheme文件位置进行过滤：pattern

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

下一个代码片段使用scheme过滤器并将其与语言标识符组合。该untitled方案适用于尚未保存到磁盘的新文件。

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

文件方案

文档的内容scheme经常被忽视，但却是重要的信息。大多数文档都保存在磁盘上，扩展作者通常假设他们正在使用磁盘上的文件。例如，使用简单的typescript选择器，假设磁盘上有 TypeScript 文件。然而，在某些情况下，这种假设过于宽松，{ scheme: 'file', language: 'typescript' }应该使用更明确的选择器。

当功能依赖于从磁盘读取文件/向磁盘写入文件时，这一点的重要性就体现出来了。查看下面的片段：

// ???? 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}`);
  }
});

上面的悬停提供程序想要显示磁盘上文档的大小，但它无法检查文档是否实际存储在磁盘上。例如，它可能是新创建的但尚未保存。正确的方法是告诉 VS Code 该提供程序只能处理磁盘上的文件。

// ???? 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}`);
    }
  }
);

概括

文档通常存储在文件系统上，但并非总是如此：有无标题文档、Git 使用的缓存文档、来自远程源（如 FTP）的文档等等。如果您的功能依赖于磁盘访问，请确保在该file方案中使用文档选择器。

下一步

要了解有关 VS Code 扩展性模型的更多信息，请尝试以下主题：

11/1/2023