> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-fix-cloud-button-text-1773163393.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 选择工具箱

Selection Toolbox API 允许扩展在画布上选择节点时添加自定义操作按钮。这为所选项目（节点、组等）提供了对上下文敏感命令的快速访问。

## 基本用法

要向选择工具箱添加命令，您的扩展需要：

1. 使用标准[命令接口](https://docs.comfy.org/custom-nodes/js/javascript_commands_keybindings)定义命令
2. 实现 `getSelectionToolboxCommands` 方法来指定工具箱中显示哪些命令

注意：每当进行新选择时，`getSelectionToolboxCommands` 方法会为选择集中的每个项目调用。

```javascript theme={null}
app.registerExtension({
  name: "MyExtension",
  commands: [
    {
      id: "my-extension.duplicate-special",
      label: "特殊复制",
      icon: "pi pi-copy",
      function: (selectedItem) => {
        // 您的命令逻辑
        console.log("使用特殊行为复制选定的节点");
      }
    }
  ],
  getSelectionToolboxCommands: (selectedItem) => {
    // 返回要在工具箱中显示的命令 ID 数组
    return ["my-extension.duplicate-special"];
  }
});
```

## 命令定义

选择工具箱的命令使用标准的 ComfyUI 命令接口：

```javascript theme={null}
{
  id: string,          // 命令的唯一标识符
  label: string,       // 按钮工具提示的显示文本
  icon?: string,       // 按钮的图标类（可选）
  function: (selectedItem) => void  // 单击时执行的函数
}
```

`function` 接收选定的项作为参数，允许您对当前选择执行操作。

## 图标选项

选择工具箱按钮支持与其他 UI 元素相同的图标库：

* PrimeVue 图标：`pi pi-[icon-name]`（例如 `pi pi-star`）
* Material Design 图标：`mdi mdi-[icon-name]`（例如 `mdi mdi-content-copy`）

## 动态命令可见性

每次选择更改时都会调用 `getSelectionToolboxCommands` 方法，允许您根据选择的内容显示不同的命令：

```javascript theme={null}
app.registerExtension({
  name: "ContextualCommands",
  commands: [
    {
      id: "my-ext.align-nodes",
      label: "对齐节点",
      icon: "pi pi-align-left",
      function: () => {
        // 对齐多个节点
      }
    },
    {
      id: "my-ext.configure-single",
      label: "配置",
      icon: "pi pi-cog",
      function: () => {
        // 配置单个节点
      }
    }
  ],
  getSelectionToolboxCommands: (selectedItem) => {
    const selectedItems = app.canvas.selectedItems;
    const itemCount = selectedItems ? selectedItems.size : 0;
    
    if (itemCount > 1) {
      // 为多个项目显示对齐命令
      return ["my-ext.align-nodes"];
    } else if (itemCount === 1) {
      // 为单个项目显示配置
      return ["my-ext.configure-single"];
    }
    
    return [];
  }
});
```

## 使用选定的项目

通过应用程序的画布对象访问有关选定项目的信息。`selectedItems` 属性是一个 Set，包含节点、组和其他画布元素：

```javascript theme={null}
app.registerExtension({
  name: "SelectionInfo",
  commands: [
    {
      id: "my-ext.show-info",
      label: "显示选择信息",
      icon: "pi pi-info-circle",
      function: () => {
        const selectedItems = app.canvas.selectedItems;
        
        if (selectedItems && selectedItems.size > 0) {
          console.log(`选择了 ${selectedItems.size} 个项目`);
          
          // 遍历选定的项目
          selectedItems.forEach(item => {
            if (item.type) {
              console.log(`项目：${item.type}（ID: ${item.id}）`);
            }
          });
        }
      }
    }
  ],
  getSelectionToolboxCommands: () => ["my-ext.show-info"]
});
```

## 完整示例

这是一个展示各种选择工具箱功能的简单示例：

```javascript theme={null}
app.registerExtension({
  name: "SelectionTools",
  commands: [
    {
      id: "selection-tools.count",
      label: "计数选择",
      icon: "pi pi-hashtag",
      function: () => {
        const count = app.canvas.selectedItems?.size || 0;
        app.extensionManager.toast.add({
          severity: "info",
          summary: "选择计数",
          detail: `您选择了 ${count} 个项目`,
          life: 3000
        });
      }
    },
    {
      id: "selection-tools.copy-ids",
      label: "复制 ID",
      icon: "pi pi-copy",
      function: () => {
        const items = Array.from(app.canvas.selectedItems || []);
        const ids = items.map(item => item.id).filter(id => id !== undefined);
        
        if (ids.length > 0) {
          navigator.clipboard.writeText(ids.join(', '));
          app.extensionManager.toast.add({
            severity: "success",
            summary: "已复制",
            detail: `已复制 ${ids.length} 个 ID 到剪贴板`,
            life: 2000
          });
        }
      }
    },
    {
      id: "selection-tools.log-types",
      label: "记录类型",
      icon: "pi pi-info-circle",
      function: () => {
        const items = Array.from(app.canvas.selectedItems || []);
        const typeCount = {};
        
        items.forEach(item => {
          const type = item.type || 'unknown';
          typeCount[type] = (typeCount[type] || 0) + 1;
        });
        
        console.log("选择类型：", typeCount);
      }
    }
  ],
  
  getSelectionToolboxCommands: (selectedItem) => {
    const selectedItems = app.canvas.selectedItems;
    const itemCount = selectedItems ? selectedItems.size : 0;
    
    if (itemCount === 0) return [];
    
    const commands = ["selection-tools.count", "selection-tools.log-types"];
    
    // 仅在项目有 ID 时显示复制命令
    const hasIds = Array.from(selectedItems).some(item => item.id !== undefined);
    if (hasIds) {
      commands.push("selection-tools.copy-ids");
    }
    
    return commands;
  }
});
```

## 注意事项

* 必须在设置中启用选择工具箱：`Comfy.Canvas.SelectionToolbox`
* 在 `getSelectionToolboxCommands` 中引用命令之前，必须在 `commands` 数组中定义命令
* 选择更改时工具箱会自动更新
* 每当进行新选择时，`getSelectionToolboxCommands` 方法会为选择集中的每个项目调用
* 使用 `app.canvas.selectedItems`（一个 Set）来访问所有选定的项目，包括节点、组和其他画布元素
* 为了向后兼容，`app.canvas.selected_nodes` 仍然存在，但只包含节点