# ComboTreeBox

**Repository Path**: 3162289690/ComboTreeBox

## Basic Information

- **Project Name**: ComboTreeBox
- **Description**: WinForms ComboTreeBox control
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ComboTreeBox 控件使用说明

## 概述

`ComboTreeBox` 是一个基于 WinForms 的树形下拉选择控件，继承自 `System.Windows.Forms.Control`，通过组合 `TextBox`、`Button` 和 `TreeView` 控件实现专业的树形选择体验。

## 特性

- ✅ 标准下拉选择体验
- ✅ +
- ✅ 智能空间定位（下方空间不足时自动向上弹出）
- ✅ 灵活的节点管理
- ✅ 专业的视觉效果

## 项目结构

```
ComboTreeBox/
├── ComboTreeBox.csproj      # WinForms 控件类库项目
├── ComboTreeBox.cs          # 核心控件实现
└── TestApp/                 # 演示应用
    ├── TestApp.csproj
    ├── Form1.cs             # 演示界面
    └── Program.cs           # 入口程序
```

## 编译与引用

### 编译控件库

```bash
# 进入项目目录
cd ComboTreeBox

# 编译 Release 版本
dotnet build ComboTreeBox.csproj -c Release

# 生成的 DLL 路径
# bin/Release/net48/ComboTreeBox.dll
```

### 在项目中引用

**方法一：通过 NuGet（待发布）**

```bash
Install-Package ComboTreeBox
```

**方法二：手动引用**

1. 在 Visual Studio 中右键项目 → 添加 → 引用
2. 浏览到 `ComboTreeBox.dll` 文件
3. 添加引用

**方法三：在设计器中使用**

1. 在 Visual Studio 工具箱中右键 → 选择项
2. 点击「浏览」按钮
3. 选择 `ComboTreeBox.dll`
4. 控件将出现在工具箱中，可直接拖放到窗体

## 使用方法

### 基础用法

```csharp
using ComboTreeBox;

// 创建控件
ComboTreeBox comboTreeBox = new ComboTreeBox();
comboTreeBox.Location = new Point(10, 10);
comboTreeBox.Size = new Size(250, 24);
this.Controls.Add(comboTreeBox);

// 添加节点
TreeNode electronics = new TreeNode("电子产品");
electronics.Nodes.Add("手机");
electronics.Nodes.Add("笔记本电脑");
comboTreeBox.TreeView.Nodes.Add(electronics);

// 监听选择变化
comboTreeBox.SelectedNodeChanged += ComboTreeBox_SelectedNodeChanged;

private void ComboTreeBox_SelectedNodeChanged(object sender, EventArgs e)
{
    var combo = (ComboTreeBox)sender;
    if (combo.SelectedNode != null)
    {
        MessageBox.Show($"选中节点: {combo.SelectedNode.Text}");
    }
}
```

### 带业务数据的节点

```csharp
// 创建带业务数据的节点
TreeNode category = new TreeNode("电子产品")
{
    Tag = new { CategoryId = "CAT001", Name = "电子产品" }
};

TreeNode product = new TreeNode("iPhone 15")
{
    Tag = new { ProductId = "P001", Price = 5999, Stock = 100 }
};

category.Nodes.Add(product);
comboTreeBox.TreeView.Nodes.Add(category);

// 获取选中节点的业务数据
var selectedData = comboTreeBox.SelectedNode?.Tag as dynamic;
if (selectedData != null)
{
    Console.WriteLine($"产品ID: {selectedData.ProductId}");
    Console.WriteLine($"价格: {selectedData.Price}");
}
```

## 属性说明

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `SelectedNode` | `TreeNode` | `null` | 获取或设置当前选中的节点 |
| `TreeView` | `TreeView` | - | 获取内部的 TreeView 控件（可直接操作） |
| `Text` | `string` | `""` | 获取或设置文本框显示的文本 |
| `DroppedDown` | `bool` | `false` | 获取或设置下拉面板的显示状态 |
| `DropDownWidth` | `int` | `200` | 下拉面板宽度 |
| `DropDownHeight` | `int` | `250` | 下拉面板高度 |

## 事件说明

| 事件 | 说明 |
|------|------|
| `SelectedNodeChanged` | 当选中节点发生变化时触发 |

## 键盘操作

| 按键 | 功能 |
|------|------|
| `↓` / `Space` | 打开下拉面板 |
| `↑` / `↓` | 在树节点间移动选择 |
| `←` / `→` | 折叠/展开当前节点 |
| `Enter` | 确认选择并关闭面板 |
| `Esc` | 关闭下拉面板 |

## 高级用法

### 自定义 TreeView 样式

```csharp
// 隐藏连接线
comboTreeBox.TreeView.ShowLines = false;

// 启用整行选择
comboTreeBox.TreeView.FullRowSelect = true;

// 启用复选框（多选场景）
comboTreeBox.TreeView.CheckBoxes = true;

// 自定义背景色
comboTreeBox.TreeView.BackColor = Color.LightGray;

// 自定义字体
comboTreeBox.TreeView.Font = new Font("微软雅黑", 10);
```

### 动态添加节点

```csharp
// 添加根节点
TreeNode newRoot = new TreeNode("新分类");
comboTreeBox.TreeView.Nodes.Add(newRoot);

// 添加子节点到选中节点下
if (comboTreeBox.SelectedNode != null)
{
    TreeNode childNode = new TreeNode("子节点");
    comboTreeBox.SelectedNode.Nodes.Add(childNode);
    comboTreeBox.SelectedNode.Expand();
}
```

### 节点路径显示

```csharp
private string GetNodeFullPath(TreeNode node)
{
    if (node == null) return string.Empty;
    
    string path = node.Text;
    TreeNode parent = node.Parent;
    
    while (parent != null)
    {
        path = parent.Text + " / " + path;
        parent = parent.Parent;
    }
    
    return path;
}

// 使用
string fullPath = GetNodeFullPath(comboTreeBox.SelectedNode);
// 示例输出: "电子产品 / 平板电脑 / iPad Pro"
```

## 演示应用

### 运行演示

```bash
dotnet run --project TestApp/TestApp.csproj -c Release
```

### 演示功能

| 功能 | 说明 |
|------|------|
| 下拉选择 | 点击下拉按钮弹出树形选择面板 |
| 节点信息展示 | 显示选中节点的名称、路径和 Tag 值 |
| 清除选择 | 清空当前选中状态 |
| 展开/折叠 | 展开或折叠所有节点 |
| 动态添加节点 | 输入名称后添加新节点 |

## 注意事项

1. **资源释放**：控件已实现 `IDisposable` 接口，在 Form 关闭时会自动释放资源
2. **线程安全**：WinForms 控件应在 UI 线程中操作
3. **Tag 属性**：建议使用 `Tag` 属性存储业务数据，避免直接修改节点文本

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-04-29 | 初始版本 |

## 许可证

MIT License