💻 欢迎参加 6 月 3 日 MS Build 上的 VS Code 直播活动。

树视图 API

树视图 API 允许扩展在 Visual Studio Code 的侧边栏中显示内容。这些内容以树状结构呈现，并符合 VS Code 内置视图 的样式。

例如，内置的“引用搜索视图”扩展会将引用搜索结果显示为一个独立的视图。

References Search View

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

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

树视图 API 基础

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

package.json 贡献

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

以下是我们扩展第一个版本的 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"
  }
}

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

您必须为视图指定标识符和名称，并可以将其贡献到以下位置：

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

树数据提供程序

第二步是为您注册的视图提供数据，以便 VS Code 能够显示它们。为此，您应该首先实现 TreeDataProvider。我们的 TreeDataProvider 将提供节点依赖项数据，但您也可以使用提供其他类型数据的提供程序。

此 API 中有两个必须实现的方法：

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

当用户打开树视图时，getChildren 方法将被调用且不带 element 参数。此时，您的 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）。

注意：对于 1.74.0 之前的 VS Code 版本，您必须在 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 组中显示为第三位。

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

注意：如果您想为特定的树节点显示操作，可以通过使用 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());

查看 tree-view-sample 中的 nodeDependencies.ts 以获取实现代码。

TreeView

如果您想以编程方式对视图执行某些 UI 操作，可以使用 window.createTreeView 代替 window.registerTreeDataProvider。这将提供对视图的访问权限，您可以使用它来执行视图操作。

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

查看 tree-view-sample 中的 ftpExplorer.ts 以获取实现代码。

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