TreeView 选项与交互配置

createTreeView 的选项参数决定了视图的交互能力：是否显示全折叠按钮、能否多选、支持拖拽、焦点如何管理。正确配置这些选项，视图才能符合用户的预期。

createTreeView 选项总览

import * as vscode from 'vscode';

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,

  // 交互选项
  showCollapseAll: true,        // 标题栏显示全折叠按钮
  canSelectMany: true,          // 支持多选
  dragAndDrop: true,            // 支持拖拽
  manuallyManageFocus: false    // 焦点由视图管理
});

showCollapseAll 全折叠

标题栏显示「全部折叠」按钮：

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,
  showCollapseAll: true
});

配置	效果
true	标题栏出现折叠全部按钮
false	不显示

适用场景：树层级较深时，用户需要快速收起全部节点。

canSelectMany 多选

允许用户用 Ctrl/Cmd 或 Shift 多选节点：

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,
  canSelectMany: true
});

// 监听选中变化
treeView.onDidChangeSelection((event) => {
  const selected = event.selection;  // 选中数组
  console.log(`选中 ${selected.length} 个节点`);
  selected.forEach((node) => {
    console.log(node.label);
  });
});

多选能力

交互	行为
Ctrl+点击	追加/取消选中
Shift+点击	范围选中
右键菜单	命令接收节点数组

配合右键菜单

多选时右键菜单命令收到数组：

vscode.commands.registerCommand('myExt.deleteNodes', (nodes: Node[]) => {
  // nodes 可能是单个节点或数组
  const list = Array.isArray(nodes) ? nodes : [nodes];
  list.forEach((node) => console.log(`删除 ${node.label}`));
});

dragAndDrop 拖拽

启用树的拖拽能力：

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,
  dragAndDrop: true
});

搭配拖拽控制器

const controller = new DragDropController();

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,
  dragAndDrop: true
});

启用后实现 TreeDragAndDropController（详见右键菜单与拖拽章节）。

manuallyManageFocus 焦点管理

控制视图焦点是否由代码管理：

const treeView = vscode.window.createTreeView('myExt.tree', {
  treeDataProvider: provider,
  manuallyManageFocus: true   // 焦点由插件管理
});

配置	行为
false（默认）	点击节点自动获得焦点
true	焦点变化需代码控制

手动管理焦点

// 程序化聚焦节点
treeView.reveal(node, { focus: true });

// 清除焦点
treeView.reveal(undefined, { focus: true });

适用场景：需要精确控制键盘导航的复杂视图。

选项组合场景

文件管理器

const treeView = vscode.window.createTreeView('myExt.files', {
  treeDataProvider: fileProvider,
  showCollapseAll: true,
  canSelectMany: true,
  dragAndDrop: true
});

任务列表

const treeView = vscode.window.createTreeView('myExt.tasks', {
  treeDataProvider: taskProvider,
  showCollapseAll: false,
  canSelectMany: false
});

搜索结果

const treeView = vscode.window.createTreeView('myExt.search', {
  treeDataProvider: searchProvider,
  canSelectMany: true,
  manuallyManageFocus: true
});

常用视图方法

方法	作用
reveal(element, options)	定位/展开/聚焦节点
refresh()	刷新视图
onDidExpandElement	展开事件
onDidCollapseElement	折叠事件
onDidChangeSelection	选中变化事件
dispose()	销毁视图

完整示例：任务管理器

import * as vscode from 'vscode';

interface Task {
  id: string;
  label: string;
  completed: boolean;
  children?: Task[];
}

class TaskNode extends vscode.TreeItem {
  constructor(public readonly task: Task) {
    super(task.label, task.children
      ? vscode.TreeItemCollapsibleState.Collapsed
      : vscode.TreeItemCollapsibleState.None);

    this.iconPath = new vscode.ThemeIcon(
      task.completed ? 'check' : 'circle-outline',
      new vscode.ThemeColor(
        task.completed ? 'charts.green' : 'charts.blue'
      )
    );
    this.description = task.completed ? '已完成' : '进行中';
    this.contextValue = 'task';
  }
}

class TaskProvider implements vscode.TreeDataProvider<TaskNode> {
  private _onDidChangeTreeData =
    new vscode.EventEmitter<TaskNode | undefined | null>();
  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;

  private tasks: Task[] = [
    { id: '1', label: '需求分析', completed: true },
    { id: '2', label: '开发', completed: false },
    { id: '3', label: '测试', completed: false }
  ];

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

  getChildren(element?: TaskNode): TaskNode[] {
    const list = element ? element.task.children ?? [] : this.tasks;
    return list.map((task) => new TaskNode(task));
  }

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

export function activate(context: vscode.ExtensionContext) {
  const provider = new TaskProvider();

  // 配置全部交互选项
  const treeView = vscode.window.createTreeView('myExt.tasks', {
    treeDataProvider: provider,
    showCollapseAll: true,
    canSelectMany: true,
    dragAndDrop: true
  });
  context.subscriptions.push(treeView);

  // 选中变化：显示摘要
  treeView.onDidChangeSelection((event) => {
    const count = event.selection.length;
    vscode.window.setStatusBarMessage(
      `选中 ${count} 个任务`,
      2000
    );
  });

  // 多选批量操作
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.completeTasks', (nodes: TaskNode[]) => {
      const list = Array.isArray(nodes) ? nodes : [nodes];
      list.forEach((node) => {
        node.task.completed = true;
      });
      provider.refresh();
    })
  );
}

选项配置速查

选项	值	效果
showCollapseAll	true	显示全折叠按钮
canSelectMany	true	支持多选
dragAndDrop	true	支持拖拽
manuallyManageFocus	true	焦点由代码管理

常见问题

问题	处理
全折叠按钮不显示	确认 showCollapseAll: true
多选无效	确认 canSelectMany: true
拖拽无响应	实现 TreeDragAndDropController
焦点错乱	使用 manuallyManageFocus 管理

合理配置 TreeView 选项，让视图交互符合预期，是构建专业数据面板的细节功夫。