– 代理会话日，2月19日

树视图 API

树视图 API 允许扩展在 Visual Studio Code 的侧边栏中显示内容。此内容结构化为树形，并符合 VS Code 内置视图 的样式。

例如，内置的“查找所有引用”视图扩展将引用搜索结果显示为单独的视图。

References Search View

“查找所有引用”结果显示在“引用：结果”树视图中，该树视图位于“引用”视图容器中。

本指南将教你如何编写一个扩展，为 Visual Studio Code 贡献树视图和视图容器。

树视图 API 基础

为了解释树视图 API，我们将构建一个名为“Node Dependencies”（Node 依赖项）的示例扩展。此扩展将使用树视图显示当前文件夹中的所有 Node.js 依赖项。添加树视图的步骤是在 package.json 中贡献树视图，创建一个 TreeDataProvider，并注册 TreeDataProvider。你可以在 vscode-extension-samples GitHub 仓库的 tree-view-sample 中找到此示例扩展的完整源代码。

package.json 贡献

首先，你必须让 VS Code 知道你正在贡献一个视图，使用 package.json 中的 contributes.views 贡献点。

这是我们扩展的第一个版本的 package.json

{
  "name": "custom-view-samples",
  "displayName": "Custom view Samples",
  "description": "Samples for VS Code's view API",
  "version": "0.0.1",
  "publisher": "alexr00",
  "engines": {
    "vscode": "^1.74.0"
  },
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "nodeDependencies",
          "name": "Node Dependencies"
        }
      ]
    }
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  },
  "devDependencies": {
    "@types/node": "^10.12.21",
    "@types/vscode": "^1.42.0",
    "typescript": "^3.5.1",
    "tslint": "^5.12.1"
  }
}

注意：如果你的扩展的目标 VS Code 版本低于 1.74，则必须在 activationEvents 中显式列出 onView:nodeDependencies。

你必须为视图指定一个标识符和名称，并且可以贡献到以下位置

  • explorer：侧边栏中的资源管理器视图
  • debug：侧边栏中的“运行和调试”视图
  • scm：侧边栏中的源代码管理视图
  • test：侧边栏中的测试资源管理器视图
  • 自定义视图容器

树数据提供器

第二步是为已注册的视图提供数据，以便 VS Code 可以在视图中显示数据。为此，你应该首先实现 TreeDataProvider。我们的 TreeDataProvider 将提供节点依赖项数据，但你可以拥有提供其他类型数据的提供器。

此 API 中有两个必要的方法需要实现

  • getChildren(element?: T): ProviderResult<T[]> - 实现此方法以返回给定 element 或根的子项（如果没有传递 element）。
  • getTreeItem(element: T): TreeItem | Thenable<TreeItem> - 实现此方法以返回在视图中显示的元素的 UI 表示形式（TreeItem）。

当用户打开树视图时，将不带 element 调用 getChildren 方法。从那里，你的 TreeDataProvider 应该返回你的顶级树项。在我们的示例中，顶级树项的 collapsibleState 为 TreeItemCollapsibleState.Collapsed，这意味着顶级树项将显示为折叠状态。将 collapsibleState 设置为 TreeItemCollapsibleState.Expanded 将导致树项显示为展开状态。将 collapsibleState 保持为默认值 TreeItemCollapsibleState.None 表示树项没有子项。对于 collapsibleState 为 TreeItemCollapsibleState.None 的树项，将不会调用 getChildren。

这是一个提供节点依赖项数据的 TreeDataProvider 实现示例

import * as vscode from 'vscode';
import * as fs from 'fs';
import * as path from 'path';

export class NodeDependenciesProvider implements vscode.TreeDataProvider<Dependency> {
  constructor(private workspaceRoot: string) {}

  getTreeItem(element: Dependency): vscode.TreeItem {
    return element;
  }

  getChildren(element?: Dependency): Thenable<Dependency[]> {
    if (!this.workspaceRoot) {
      vscode.window.showInformationMessage('No dependency in empty workspace');
      return Promise.resolve([]);
    }

    if (element) {
      return Promise.resolve(
        this.getDepsInPackageJson(
          path.join(this.workspaceRoot, 'node_modules', element.label, 'package.json')
        )
      );
    } else {
      const packageJsonPath = path.join(this.workspaceRoot, 'package.json');
      if (this.pathExists(packageJsonPath)) {
        return Promise.resolve(this.getDepsInPackageJson(packageJsonPath));
      } else {
        vscode.window.showInformationMessage('Workspace has no package.json');
        return Promise.resolve([]);
      }
    }
  }

  /**
   * Given the path to package.json, read all its dependencies and devDependencies.
   */
  private getDepsInPackageJson(packageJsonPath: string): Dependency[] {
    if (this.pathExists(packageJsonPath)) {
      const toDep = (moduleName: string, version: string): Dependency => {
        if (this.pathExists(path.join(this.workspaceRoot, 'node_modules', moduleName))) {
          return new Dependency(
            moduleName,
            version,
            vscode.TreeItemCollapsibleState.Collapsed
          );
        } else {
          return new Dependency(moduleName, version, vscode.TreeItemCollapsibleState.None);
        }
      };

      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));

      const deps = packageJson.dependencies
        ? Object.keys(packageJson.dependencies).map(dep =>
            toDep(dep, packageJson.dependencies[dep])
          )
        : [];
      const devDeps = packageJson.devDependencies
        ? Object.keys(packageJson.devDependencies).map(dep =>
            toDep(dep, packageJson.devDependencies[dep])
          )
        : [];
      return deps.concat(devDeps);
    } else {
      return [];
    }
  }

  private pathExists(p: string): boolean {
    try {
      fs.accessSync(p);
    } catch (err) {
      return false;
    }
    return true;
  }
}

class Dependency extends vscode.TreeItem {
  constructor(
    public readonly label: string,
    private version: string,
    public readonly collapsibleState: vscode.TreeItemCollapsibleState
  ) {
    super(label, collapsibleState);
    this.tooltip = `${this.label}-${this.version}`;
    this.description = this.version;
  }

  iconPath = {
    light: path.join(__filename, '..', '..', 'resources', 'light', 'dependency.svg'),
    dark: path.join(__filename, '..', '..', 'resources', 'dark', 'dependency.svg')
  };
}

注册 TreeDataProvider

第三步是将上述数据提供器注册到你的视图。

这可以通过以下两种方式完成

  • vscode.window.registerTreeDataProvider - 通过提供注册的视图 ID 和上述数据提供器来注册树数据提供器。

    const rootPath =
  vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders.length > 0
    ? vscode.workspace.workspaceFolders[0].uri.fsPath
    : undefined;
vscode.window.registerTreeDataProvider(
  'nodeDependencies',
  new NodeDependenciesProvider(rootPath)
);

  • vscode.window.createTreeView - 通过提供注册的视图 ID 和上述数据提供器来创建树视图。这将访问 TreeView，你可以使用它来执行其他视图操作。如果你需要 TreeView API，请使用 createTreeView。

    vscode.window.createTreeView('nodeDependencies', {
  treeDataProvider: new NodeDependenciesProvider(rootPath)
});

这是扩展在运行中的样子

View

更新树视图内容

我们的节点依赖项视图很简单，一旦显示数据，就不会更新。但是，在视图中添加一个刷新按钮并使用 package.json 的当前内容更新节点依赖项视图会很有用。为此，我们可以使用 onDidChangeTreeData 事件。

  • onDidChangeTreeData?: Event<T | undefined | null | void> - 如果你的树数据可以更改并且你想更新树视图，请实现此方法。

将以下内容添加到你的 NodeDependenciesProvider 中。

  private _onDidChangeTreeData: vscode.EventEmitter<Dependency | undefined | null | void> = new vscode.EventEmitter<Dependency | undefined | null | void>();
  readonly onDidChangeTreeData: vscode.Event<Dependency | undefined | null | void> = this._onDidChangeTreeData.event;

  refresh(): void {
    this._onDidChangeTreeData.fire();
  }

现在我们有一个刷新方法，但没有人调用它。我们可以添加一个命令来调用刷新。

在你的 package.json 的 contributes 部分中，添加

    "commands": [
            {
                "command": "nodeDependencies.refreshEntry",
                "title": "Refresh",
                "icon": {
                    "light": "resources/light/refresh.svg",
                    "dark": "resources/dark/refresh.svg"
                }
            },
    ]

并在扩展激活中注册该命令

import * as vscode from 'vscode';
import { NodeDependenciesProvider } from './nodeDependencies';

export function activate(context: vscode.ExtensionContext) {
  const rootPath =
    vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders.length > 0
      ? vscode.workspace.workspaceFolders[0].uri.fsPath
      : undefined;
  const nodeDependenciesProvider = new NodeDependenciesProvider(rootPath);
  vscode.window.registerTreeDataProvider('nodeDependencies', nodeDependenciesProvider);
  vscode.commands.registerCommand('nodeDependencies.refreshEntry', () =>
    nodeDependenciesProvider.refresh()
  );
}

现在我们有一个可以刷新节点依赖项视图的命令，但视图上的按钮会更好。我们已经为命令添加了一个 icon，因此当我们将其添加到视图时，它将显示该图标。

在你的 package.json 的 contributes 部分中，添加

"menus": {
    "view/title": [
        {
            "command": "nodeDependencies.refreshEntry",
            "when": "view == nodeDependencies",
            "group": "navigation"
        },
    ]
}

激活

重要的是，你的扩展仅在用户需要你的扩展提供的功能时才被激活。在这种情况下，你应该考虑仅在用户开始使用视图时激活你的扩展。VS Code 会自动为你执行此操作，当你的扩展声明视图贡献时。VS Code 会在用户打开视图时发出激活事件 onView:${viewId}（对于上面的示例，为 onView:nodeDependencies）。

注意：对于 VS Code 低于 1.74.0 的版本，你必须在 package.json 中显式注册此激活事件，以便 VS Code 在此视图上激活你的扩展

"activationEvents": [
       "onView:nodeDependencies",
],

视图容器

视图容器包含在活动栏或面板中与内置视图容器一起显示的视图列表。内置视图容器的示例是源代码管理和资源管理器。

View Container

要贡献一个视图容器，你应该首先使用 package.json 中的 contributes.viewsContainers 贡献点注册它。

你必须指定以下必需字段

  • id - 你正在创建的新视图容器的 ID。
  • title - 将显示在视图容器顶部的名称。
  • icon - 在活动栏中显示视图容器时将显示的图像。
"contributes": {
  "viewsContainers": {
    "activitybar": [
      {
        "id": "package-explorer",
        "title": "Package Explorer",
        "icon": "media/dep.svg"
      }
    ]
  }
}

或者，你可以通过将其置于 panel 节点下，将此视图贡献到面板。

"contributes": {
  "viewsContainers": {
    "panel": [
      {
        "id": "package-explorer",
        "title": "Package Explorer",
        "icon": "media/dep.svg"
      }
    ]
  }
}

将视图贡献到视图容器

创建视图容器后，你可以使用 package.json 中的 contributes.views 贡献点。

"contributes": {
  "views": {
    "package-explorer": [
      {
        "id": "nodeDependencies",
        "name": "Node Dependencies",
        "icon": "media/dep.svg",
        "contextualTitle": "Package Explorer"
      }
    ]
  }
}

视图还可以有一个可选的 visibility 属性，可以设置为 visible、collapsed 或 hidden。此属性仅受 VS Code 在首次使用此视图打开工作区时的尊重。之后，可见性设置为用户选择的内容。如果你有一个包含许多视图的视图容器，或者如果你的视图对你的扩展的每个用户并非都很有用，请考虑将视图设置为 collapsed 或 hidden。一个 hidden 视图将出现在视图容器的“视图”菜单中

Views Menu

视图操作

操作作为内联图标显示在你的单个树项上，在树项上下文菜单中，以及在视图标题的视图顶部。操作是你在 package.json 中添加贡献来显示在这些位置的命令。

要贡献到这三个位置，你可以使用 package.json 中的以下菜单贡献点

  • view/title - 显示视图标题中操作的位置。主操作或内联操作使用 "group": "navigation"，其余是次要操作，位于 ... 菜单中。
  • view/item/context - 显示树项操作的位置。内联操作使用 "group": "inline"，其余是次要操作，位于 ... 菜单中。

你可以使用 when 子句 来控制这些操作的可见性。

View Actions

示例

"contributes": {
  "commands": [
    {
      "command": "nodeDependencies.refreshEntry",
      "title": "Refresh",
      "icon": {
        "light": "resources/light/refresh.svg",
        "dark": "resources/dark/refresh.svg"
      }
    },
    {
      "command": "nodeDependencies.addEntry",
      "title": "Add"
    },
    {
      "command": "nodeDependencies.editEntry",
      "title": "Edit",
      "icon": {
        "light": "resources/light/edit.svg",
        "dark": "resources/dark/edit.svg"
      }
    },
    {
      "command": "nodeDependencies.deleteEntry",
      "title": "Delete"
    }
  ],
  "menus": {
    "view/title": [
      {
        "command": "nodeDependencies.refreshEntry",
        "when": "view == nodeDependencies",
        "group": "navigation"
      },
      {
        "command": "nodeDependencies.addEntry",
        "when": "view == nodeDependencies"
      }
    ],
    "view/item/context": [
      {
        "command": "nodeDependencies.editEntry",
        "when": "view == nodeDependencies && viewItem == dependency",
        "group": "inline"
      },
      {
        "command": "nodeDependencies.deleteEntry",
        "when": "view == nodeDependencies && viewItem == dependency"
      }
    ]
  }
}

默认情况下，操作按字母顺序排序。要指定不同的排序，请添加 @，后跟你想要的顺序。例如，navigation@3 将导致该操作显示在 navigation 组中的第 3 位。

你可以通过创建不同的组来进一步分隔 ... 菜单中的项目。这些组名是任意的，按组名字母顺序排序。

注意： 如果你想为特定的树项显示操作，你可以通过使用 TreeItem.contextValue 定义树项的上下文，并在 when 表达式中指定 viewItem 键的上下文值来做到这一点。

示例

"contributes": {
  "menus": {
    "view/item/context": [
      {
        "command": "nodeDependencies.deleteEntry",
        "when": "view == nodeDependencies && viewItem == dependency"
      }
    ]
  }
}

欢迎内容

如果你的视图可以为空，或者你想向另一个扩展的空视图添加欢迎内容，你可以贡献 viewsWelcome 内容。一个空视图是没有 TreeView.message 并且树为空的视图。

"contributes": {
  "viewsWelcome": [
    {
      "view": "nodeDependencies",
      "contents": "No node dependencies found [learn more](https://npmjs.net.cn/).\n[Add Dependency](command:nodeDependencies.addEntry)"
    }
  ]
}

Welcome Content

欢迎内容支持链接。通过约定，单独一行上的链接是一个按钮。每个欢迎内容还可以包含一个 when 子句。有关更多示例，请参阅 内置 Git 扩展。

TreeDataProvider

扩展编写者应以编程方式注册 TreeDataProvider 以填充视图中的数据。

vscode.window.registerTreeDataProvider('nodeDependencies', new DepNodeProvider());

请参阅 nodeDependencies.ts 在 tree-view-sample 中获取实现。

TreeView

如果你想以编程方式对视图执行一些 UI 操作，你可以使用 window.createTreeView 代替 window.registerTreeDataProvider。这将访问该视图，你可以使用它来执行视图操作。

vscode.window.createTreeView('ftpExplorer', {
  treeDataProvider: new FtpTreeDataProvider()
});

请参阅 ftpExplorer.ts 在 tree-view-sample 中获取实现。

3/4/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.