syncfusion-winforms-editable-listbox

实现 Syncfusion Windows Forms EditableList

本指南全面介绍如何实现和自定义 EditableList 控件。这是一种功能强大的列表框组件，支持内联编辑、项目管理和丰富的自定义选项，可用于 Windows Forms 应用程序。

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 在 Windows Forms 应用程序中实现 EditableList 控件
• 启用列表项的内联编辑，直接在列表框中进行编辑
• 管理动态列表，让用户在运行时添加、编辑或删除项目
• 通过 DataSource 或手动输入填充列表
• 将 AutoComplete 功能与编辑用 TextBox 集成
• 自定义外观，包括嵌入式控件、滚动和布局
• 为可编辑列表应用现代主题（Metro、Office2016）
• 处理编辑事件和用户交互
• 配置停靠边距和控件大小
• 在 EditableList 中设置嵌入式控件（Button、TextBox、ListBox）

EditableList 控件适用于需要用户编辑集合、录入表单数据、管理标签，或通过内联列表编辑提升易用性的界面。

组件概览

EditableList（也称为 Editable ListBox）是一种复合控件，结合了 ListBox、TextBox 和可选的 Button，可提供内联编辑功能。用户可以选择项目，并直接在列表界面中编辑。

主要功能：

• 内联编辑：点击项目即可直接在原位编辑
• DataSource 绑定：连接数据源或手动填充
• 嵌入式控件：访问和配置子 Button、TextBox 和 ListBox
• AutoComplete 集成：编辑时提供智能文本建议
• 现代样式：支持 Metro 和 Office2016 主题及配色方案
• 灵活布局：支持 AutoScroll、停靠边距和大小配置
• 外观自定义：控制按钮的可见性和外观

嵌入式控件：

• Button：用于执行其他操作的可选按钮（由 WantButton 属性控制）
• TextBox：用于内联编辑选中的项目
• ListBox：包含列表项目，并提供完整的 ListBox 功能

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和程序集部署
• 通过 Visual Studio 设计器添加控件
• 通过代码以编程方式添加控件
• 所需的命名空间导入
• 基本初始化和设置
• 了解嵌入式控件

填充和编辑列表

📄 阅读： references/populating-editing.md

• 通过 DataSource 绑定填充
• 通过属性编辑器手动填充
• 运行时编辑工作流
• 项目选择和内联编辑流程
• ListBox.Items 操作
• 完整代码示例（C# 和 VB.NET）

外观和行为配置

📄 阅读： references/appearance-behavior.md

• 嵌入式控件概览和访问方式
• 为大型列表配置 AutoScroll
• 使用停靠边距控制布局
• 使用 WantButton 属性控制按钮可见性
• 控件大小和位置
• 实用配置示例

AutoComplete 集成

📄 阅读： references/autocomplete-integration.md

• 设置 AutoComplete 组件
• 将 AutoComplete 与 EditableList TextBox 关联
• 配置建议的数据源
• AutoCompleteModes 选项
• Form 加载事件实现
• 完整集成示例

样式和主题

📄 阅读： references/styling-themes.md

• 视觉样式（Default、Metro、Office2016）
• 应用 Style 属性
• Office2016 配色方案（Colorful、White、DarkGray、Black）
• 确保窗体间主题一致
• 完整样式代码示例

快速入门

基本实现（设计器）

1. 通过工具箱添加控件：

   • 在 Visual Studio 设计器中打开窗体
   • 在工具箱中找到 EditableList（Syncfusion Controls 部分）
   • 将其拖放到窗体上
   • 程序集会自动添加

2. 在“属性”窗口中配置：

   • 设置 Size、Location 和其他基本属性
   • 展开 ListBox 属性以配置项
   • 设置 Style 属性以获得现代外观

基本实现（代码）

using Syncfusion.Windows.Forms.Tools;

namespace MyWinFormsApp
{
    public partial class Form1 : Form
    {
        private EditableList editableList1;
        
        public Form1()
        {
            InitializeComponent();
            SetupEditableList();
        }
        
        private void SetupEditableList()
        {
            // Create and initialize
            this.editableList1 = new EditableList();
            this.editableList1.Location = new System.Drawing.Point(20, 20);
            this.editableList1.Size = new System.Drawing.Size(300, 200);
            
            // Populate items
            this.editableList1.ListBox.Items.AddRange(new object[] {
                "Item 1",
                "Item 2", 
                "Item 3"
            });
            
            // Apply modern style
            this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
            
            // Add to form
            this.Controls.Add(this.editableList1);
        }
    }
}

Imports Syncfusion.Windows.Forms.Tools

Public Class Form1
    Private editableList1 As EditableList
    
    Public Sub New()
        InitializeComponent()
        SetupEditableList()
    End Sub
    
    Private Sub SetupEditableList()
        ' Create and initialize
        Me.editableList1 = New EditableList()
        Me.editableList1.Location = New System.Drawing.Point(20, 20)
        Me.editableList1.Size = New System.Drawing.Size(300, 200)
        
        ' Populate items
        Me.editableList1.ListBox.Items.AddRange(New Object() {
            "Item 1",
            "Item 2",
            "Item 3"
        })
        
        ' Apply modern style
        Me.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016
        
        ' Add to form
        Me.Controls.Add(Me.editableList1)
    End Sub
End Class

常见模式

模式 1：DataSource 绑定

// Bind to a data source
List<string> dataSource = new List<string>();
dataSource.Add("Product A");
dataSource.Add("Product B");
dataSource.Add("Product C");

this.editableList1.ListBox.DataSource = dataSource;

模式 2：运行时编辑工作流

User Interaction:
1. Click on an item to select it
2. Click again to enter edit mode (TextBox appears)
3. Edit the text in the TextBox
4. Change focus (click elsewhere, press Tab)
5. List updates automatically with edited value

模式 3：为大型列表启用 AutoScroll

// Enable automatic scrollbars
this.editableList1.AutoScroll = true;
this.editableList1.AutoScrollMargin = new System.Drawing.Size(2, 2);
this.editableList1.AutoScrollMinSize = new System.Drawing.Size(3, 3);

模式 4：编辑时显示按钮

// Display button on the right during editing
this.editableList1.WantButton = true;

// Handle button click if needed
this.editableList1.Button.Click += (s, e) => {
    MessageBox.Show("Button clicked!");
};

模式 5：应用现代主题

// Apply Office2016 theme with color scheme
this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
this.editableList1.Office2016ColorScheme = ScrollBarOffice2016ColorScheme.Colorful;

关键属性和事件

基本属性

属性	描述	示例
ListBox	访问内嵌的 ListBox 控件	editableList1.ListBox.Items.Add("Item")
TextBox	访问用于编辑的 TextBox 控件	editableList1.TextBox.Text
Button	访问可选按钮控件	editableList1.Button.Click += Handler
WantButton	编辑时显示/隐藏按钮	editableList1.WantButton = true
AutoScroll	启用自动滚动条	editableList1.AutoScroll = true
Style	视觉外观样式	editableList1.Style = Appearance.Office2016
DockPadding	停靠控件的内边距	editableList1.DockPadding.All = 5

常见事件

通过内嵌控件访问事件：

// ListBox events
this.editableList1.ListBox.SelectedIndexChanged += ListBox_SelectedIndexChanged;
this.editableList1.ListBox.Click += ListBox_Click;

// TextBox events
this.editableList1.TextBox.TextChanged += TextBox_TextChanged;
this.editableList1.TextBox.Leave += TextBox_Leave;

// Button events (if WantButton = true)
this.editableList1.Button.Click += Button_Click;

常见用例

用例 1：标签管理系统

用户需要管理标签，并能够以内联方式添加、编辑和删除标签。 → 使用 DataSource 绑定 + 启用内联编辑 + 添加项选择处理

用例 2：动态类别列表

用户希望有一个设置窗体，可以直接在列表中编辑类别。 → 手动填充项 + 使用 WantButton 实现删除功能 + 设置样式以获得现代 UI

用例 3：电子邮件收件人列表

用户需要一个可编辑的电子邮件地址列表，并提供自动完成建议。 → 集成 AutoComplete + 使用 DataSource 提供建议 + 在 TextBox.Leave 上进行验证

用例 4：待办事项列表管理器

用户希望有一个简单的待办事项列表，并支持内联编辑。 → 使用基本设置 + 运行时编辑 + 处理 ListBox 事件以标记任务完成

用例 5：首选项编辑器

用户需要一个窗体，让用户能够以列表形式编辑配置值。 → 使用 DataSource 绑定 + 应用主题外观 + 设置停靠内边距以调整布局

提示和最佳实践

1. 对动态数据使用 DataSource：绑定到集合以自动更新
2. 处理 TextBox.Leave 事件：在编辑完成时验证输入
3. 启用 AutoScroll：列表项较多时启用，以防内容溢出
4. 应用一致的主题：在窗体的所有控件上使用相同的 Style
5. 访问内嵌控件：配置 Button、TextBox、ListBox 以实现全面自定义
6. 考虑使用 AutoComplete：改善可预测输入的用户体验
7. 测试编辑流程：确保单击即可编辑的行为流畅
8. 设置合适的尺寸：提供足够的高度，以便舒适地查看和编辑列表项

故障排除

问题：项无法编辑 → 确保正确处理焦点，并检查 TextBox 是否可访问

问题：滚动条未显示 → 设置 AutoScroll = true，并配置 AutoScrollMinSize

问题：主题未应用 → 确认已设置 Style 属性；对于 Office2016 样式，还需设置 Office2016ColorScheme

问题：AutoComplete 无法使用 → 检查 Form_Load 中是否使用正确的参数调用了 AutoComplete.SetAutoComplete()

问题：编辑时按钮不可见 → 将 WantButton 属性设置为 true