TreeItem 可视化增强

树节点的显示质量决定插件的专业度。本章聚焦 TreeItem 的视觉层：图标、描述、悬停提示、颜色标记，让节点信息一目了然。

图标 iconPath

iconPath 支持三种图标来源：

import * as vscode from 'vscode';

// 1. 内置主题图标（推荐）
node.iconPath = new vscode.ThemeIcon('file-code');
node.iconPath = new vscode.ThemeIcon('git-branch');

// 2. 文件图标（随文件类型）
node.iconPath = vscode.Uri.file(
  path.join(__dirname, 'media', 'custom.svg')
);

// 3. 带颜色的主题图标
node.iconPath = new vscode.ThemeIcon(
  'circle-filled',
  new vscode.ThemeColor('charts.red')
);

内置图标常用

图标 ID	含义
file	文件
file-code	代码文件
file-text	文本文件
folder	文件夹
folder-opened	打开文件夹
database	数据库
cloud	云
package	包
warning	警告
error	错误

图标加载模式

// 异步加载图标
node.iconPath = {
  light: vscode.Uri.file(
    path.join(__dirname, 'media', 'icon-light.svg')
  ),
  dark: vscode.Uri.file(
    path.join(__dirname, 'media', 'icon-dark.svg')
  )
};

resourceUri 文件关联

关联文件后自动获得文件类型图标与颜色：

// 关联 .ts 文件 → 自动显示 TS 图标
node.resourceUri = vscode.Uri.file('/path/to/file.ts');

// 关联特定类型
node.resourceUri = vscode.Uri.joinPath(baseUri, 'index.ts');

效果	说明
自动图标	按扩展名匹配文件图标主题
文件颜色	主题中的文件类型配色
关联操作	支持文件相关命令

description 描述信息

次要信息显示在 label 右侧（灰色小字）：

// 字符串描述
node.description = '12 个文件';

// 布尔描述（显示复选框样式）
node.description = true;

// 带状态图标
node.description = '$(cloud) 已同步';

场景	示例
统计信息	文件 (23)
状态标记	已保存 / 修改中
附加说明	当前分支: main
位置信息	src/

tooltip 悬停提示

丰富的信息通过 tooltip 展示：

// 简单文本
node.tooltip = '这是一个文件节点';

// MarkdownString（支持格式化）
node.tooltip = new vscode.MarkdownString(
  `**文件**: ${node.label}\n\n` +
  `**路径**: \`${node.uri.fsPath}\`\n\n` +
  `**大小**: 2.3 KB`
);

MarkdownString 能力

const tip = new vscode.MarkdownString();
tip.appendText('文件信息:\n');
tip.appendCodeblock('console.log("hi")', 'javascript');
tip.appendMarkdown('[查看文档](command:myExt.openDoc)');
tip.supportThemeIcons = true;  // 支持 $(icon) 语法

高亮与颜色装饰

主题色文本

// label 使用主题色
node.label = {
  label: '错误节点',
  color: new vscode.ThemeColor('charts.red'),
  highlights: [[0, 2]]  // 高亮 "错误" 部分
};

description 着色

node.description = {
  label: '已修改',
  color: new vscode.ThemeColor('charts.yellow')
};

常用主题色

颜色	含义
charts.red	错误/删除
charts.green	成功/新增
charts.yellow	警告/修改
charts.blue	信息
errorForeground	错误文字
warningForeground	警告文字

Badge 标记

badge 显示节点右侧的小徽章：

// 带徽章的节点
node.badge = {
  value: 5,                        // 数字
  tooltip: '5 个未读消息',
  backgroundColor: new vscode.ThemeColor('badge.background')
};

常见 badge 用途

用途	value
未读数量	unreadCount
错误数量	errorCount
文件数量	files.length
更新状态	'更新' 文本

禁用 badge

node.badge = { value: 0 };  // 0 时不显示
// 或直接不设置

完整示例：状态增强的 Git 树

import * as vscode from 'vscode';

class GitNode extends vscode.TreeItem {
  constructor(
    label: string,
    state: vscode.TreeItemCollapsibleState,
    private fileStatus: 'modified' | 'added' | 'deleted' | 'clean' | undefined
  ) {
    super(label, state);

    // 根据状态配置图标与颜色
    switch (fileStatus) {
      case 'modified':
        this.iconPath = new vscode.ThemeIcon(
          'edit',
          new vscode.ThemeColor('charts.yellow')
        );
        this.description = '已修改';
        break;
      case 'added':
        this.iconPath = new vscode.ThemeIcon(
          'add',
          new vscode.ThemeColor('charts.green')
        );
        this.description = '已新增';
        break;
      case 'deleted':
        this.iconPath = new vscode.ThemeIcon(
          'trash',
          new vscode.ThemeColor('charts.red')
        );
        this.description = '已删除';
        break;
      default:
        this.iconPath = new vscode.ThemeIcon('file');
    }

    // 悬停提示
    this.tooltip = new vscode.MarkdownString(
      `**文件**: \`${label}\`\n\n` +
      `**状态**: ${this.description ?? '正常'}`
    );
  }
}

class GitTreeProvider implements vscode.TreeDataProvider<GitNode> {
  private changedFiles = new Map<string, GitNode['fileStatus']>();

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

  getChildren(element?: GitNode): vscode.ProviderResult<GitNode[]> {
    if (element) {
      return [];
    }
    // 模拟变更文件列表
    return [
      new GitNode('src/app.ts', vscode.TreeItemCollapsibleState.None, 'modified'),
      new GitNode('src/utils.ts', vscode.TreeItemCollapsibleState.None, 'added'),
      new GitNode('src/old.ts', vscode.TreeItemCollapsibleState.None, 'deleted'),
      new GitNode('README.md', vscode.TreeItemCollapsibleState.None, undefined)
    ];
  }
}

可视化增强速查

需求	实现
内置图标	new ThemeIcon('id')
彩色图标	ThemeIcon + ThemeColor
文件类型图标	设置 resourceUri
右侧小字	description
悬停详情	tooltip（MarkdownString）
文字着色	label/description 对象 + color
徽章计数	badge.value
主题适配	使用主题色而非硬编码

常见问题

问题	处理
图标不显示	检查 ThemeIcon ID 拼写
颜色无效	确认使用 ThemeColor 对象
tooltip 不换行	用 MarkdownString 而非纯字符串
badge 不显示	value 需大于 0

TreeItem 可视化增强让数据树信息密度更高、更专业，是提升插件体验的「最后一公里」。