🚀 在 VS Code 中

文档选择器

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

不在磁盘上的文本文档

并非所有文本文档都存储在磁盘上,例如,新创建的文档。除非另有说明,文档选择器适用于所有文档类型。使用 DocumentFilter scheme 属性来缩小到特定方案,例如 { scheme: 'file', language: 'typescript' } 用于存储在磁盘上的 TypeScript 文件。

文档选择器

Visual Studio Code 扩展 API 通过 DocumentSelector 类型,将语言特定功能(如 IntelliSense)与文档选择器结合使用。它们是将功能缩小到特定语言的简易机制。

以下代码片段为 TypeScript 文件注册了 HoverProvider,文档选择器是 typescript 语言标识符字符串。

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

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

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 扩展性模型的更多信息,请尝试以下主题