參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

樹檢視 API

樹檢視 API 允許擴充套件在 Visual Studio Code 的側邊欄中顯示內容。此內容以樹形結構組織，並符合 VS Code 內建檢視 的樣式。

例如，內建的“引用搜索檢視”擴充套件將引用搜索結果顯示為單獨的檢視。

References Search View

“查詢所有引用”結果顯示在“引用”檢視容器中的“引用：結果”樹檢視中。

本指南將教你如何編寫一個向 Visual Studio Code 貢獻樹檢視和檢視容器的擴充套件。

樹檢視 API 基礎

為了解釋樹檢視 API，我們將構建一個名為“節點依賴項”的示例擴充套件。此擴充套件將使用樹檢視顯示當前資料夾中的所有 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 之前的 VS Code 版本，則必須在 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 會發出一個 activationEvent 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 組中顯示為第 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://www.npmjs.com/).\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 以瞭解其實現。

09/11/2025