树视图 API

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

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

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

本指南教你如何编写一个为 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"
  }
}

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

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

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

树数据提供程序

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

在此 API 中，你需要实现两个必要的方法：

`getChildren(element?: T): ProviderResult` - 实现此方法以返回给定 `element` 的子项，或者返回根（如果未传递 `element`）。
`getTreeItem(element: T): TreeItem | Thenable` - 实现此方法以返回将在视图中显示的元素的 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` - 如果你的树数据可以更改并且你想要更新树视图，请实现此方法。

将以下内容添加到你的 `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` 视图将出现在视图容器的“视图”菜单中

视图操作

操作以行内图标的形式显示在你的单个树项上、树项上下文菜单中以及视图顶部（视图标题中）。操作是通过在 `package.json` 中添加贡献来设置在这些位置显示的命令。

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

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

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

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());

有关实现，请参阅 tree-view-sample 中的 `nodeDependencies.ts`。

TreeView

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

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

有关实现，请参阅 tree-view-sample 中的 `ftpExplorer.ts`。

05/08/2025