syncfusion-winforms-autolabel

Syncfusion WinForms AutoLabel 控件

AutoLabel 控件是一种受 Label 启发的控件，可让你将标签与其他任意控件配对。配对后，随着被标注控件的位置变化，AutoLabel 会自动重新定位，确保标签和控件始终保持同步。

何时使用此技能

在以下情况下使用 AutoLabel 控件：

• 添加可自动跟随关联控件的标签
• 创建控件可移动的动态表单布局
• 使用 FlowLayout 管理器实现复杂表单设计
• 确保标签始终相对于控件正确定位
• 构建可动态调整大小或重新排列控件的表单
• 创建标签与控件间距一致的专业表单
• 通过自动定位简化表单布局管理

安装

NuGet 安装

Install-Package Syncfusion.Shared.Base

程序集引用

添加对以下程序集的引用：

• Syncfusion.Shared.Base.dll

快速入门

基本设置

using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

namespace AutoLabelDemo
{
    public partial class Form1 : Form
    {
        private AutoLabel autoLabel1;
        private TextBoxExt textBoxExt1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create a control to label (e.g., TextBox)
            textBoxExt1 = new TextBoxExt();
            textBoxExt1.Location = new System.Drawing.Point(150, 50);
            textBoxExt1.Size = new System.Drawing.Size(200, 20);
            
            // Create AutoLabel
            autoLabel1 = new AutoLabel();
            autoLabel1.Text = "Username:";
            autoLabel1.Font = new System.Drawing.Font("Segoe UI", 9F, System.Drawing.FontStyle.Regular);
            
            // Pair the label with the control
            autoLabel1.LabeledControl = textBoxExt1;
            autoLabel1.Position = AutoLabelPosition.Left;
            autoLabel1.Gap = 10;
            
            // Add to form
            this.Controls.Add(textBoxExt1);
            this.Controls.Add(autoLabel1);
        }
    }
}

设计器设置

1. 从工具箱将 AutoLabel 控件拖到窗体上
2. 将另一个控件（例如 TextBox）拖到窗体上
3. 右键单击 AutoLabel → 属性 → 将 LabeledControl 设置为你的控件
4. 配置 Position 和 Gap 属性
5. 现在，标签会相对于控件自动定位

核心概念

标签与控件配对

AutoLabel 通过 LabeledControl 属性与任意控件配对。配对后，标签会自动跟踪控件的位置。

自动重新定位

被标注控件移动时，AutoLabel 会根据 Position 和 Gap 设置自动调整自身位置。

FlowLayout 集成

FlowLayout 管理器会将 AutoLabel 标注的控件对视为一个整体，从而支持强大的动态表单布局。

导航指南

🚀 入门

📄 阅读： references/getting-started.md

• 安装和程序集部署
• 通过设计器添加 AutoLabel
• 以编程方式添加 AutoLabel
• 为控件添加标签
• 基本配置
• 运行你的第一个 AutoLabel 应用程序

📐 定位与间距

📄 阅读： references/positioning-spacing.md

• Position 属性（Left、Top、Side、Custom）
• 标签与控件之间的 Gap 设置
• 用于精细控制的 DX 和 DY 属性
• 使用鼠标自定义定位
• 间距最佳实践

🎨 外观与主题

📄 阅读： references/appearance-theming.md

• 使用 AutoSize 自动调整标签大小
• 自定义 BackColor 和 ForeColor
• 字体设置
• TextAlign 属性
• SkinManager 主题（Office 2016 样式）
• 视觉样式

⚡ 事件

📄 阅读： references/events.md

• PropertyChanged 事件
• 处理标签与控件的更新
• 事件参数
• 常见事件场景

🎯 概述与使用场景

📄 阅读： references/overview.md

• 组件架构
• FlowLayout 集成
• 表单布局模式
• 何时使用 AutoLabel，何时使用标准 Label

常见模式

模式 1：标签左对齐的简单表单

// Create form fields with left-aligned labels
AutoLabel nameLabel = new AutoLabel();
nameLabel.Text = "Name:";
nameLabel.LabeledControl = nameTextBox;
nameLabel.Position = AutoLabelPosition.Left;
nameLabel.Gap = 10;

AutoLabel emailLabel = new AutoLabel();
emailLabel.Text = "Email:";
emailLabel.LabeledControl = emailTextBox;
emailLabel.Position = AutoLabelPosition.Left;
emailLabel.Gap = 10;

this.Controls.Add(nameTextBox);
this.Controls.Add(nameLabel);
this.Controls.Add(emailTextBox);
this.Controls.Add(emailLabel);

模式 2：标签顶部对齐（垂直表单）

AutoLabel addressLabel = new AutoLabel();
addressLabel.Text = "Address:";
addressLabel.LabeledControl = addressTextBox;
addressLabel.Position = AutoLabelPosition.Top;
addressLabel.Gap = 5;
addressLabel.AutoSize = true;

模式 3：自定义定位的标签

AutoLabel customLabel = new AutoLabel();
customLabel.Text = "Custom:";
customLabel.LabeledControl = myControl;
customLabel.Position = AutoLabelPosition.Custom;
customLabel.DX = -100;  // 100 pixels to the left
customLabel.DY = 15;    // 15 pixels down from control top

模式 4：使用 AutoLabel 的主题化表单

using Syncfusion.Windows.Forms;

// Apply Office 2016 theme to all labels
SkinManager.SetVisualStyle(label1, VisualTheme.Office2016Colorful);
SkinManager.SetVisualStyle(label2, VisualTheme.Office2016Colorful);
SkinManager.SetVisualStyle(label3, VisualTheme.Office2016Colorful);

模式 5：使用 AutoLabel 配对的 FlowLayout

FlowLayoutPanel flowPanel = new FlowLayoutPanel();
flowPanel.FlowDirection = FlowDirection.TopDown;
flowPanel.Dock = DockStyle.Fill;

// FlowLayout treats AutoLabel + Control as one unit
flowPanel.Controls.Add(firstNameTextBox);
flowPanel.Controls.Add(firstNameLabel);  // Paired with firstNameTextBox
flowPanel.Controls.Add(lastNameTextBox);
flowPanel.Controls.Add(lastNameLabel);   // Paired with lastNameTextBox

// Labels automatically move with their controls
this.Controls.Add(flowPanel);

关键属性参考

属性	类型	默认值	描述
LabeledControl	Control	null	与此标签配对的控件
Position	AutoLabelPosition	Left	相对位置：Left、Top、Side、Custom
Gap	int	0	标签与控件之间的水平和垂直间距
DX	int	0	标签左侧到控件左侧的水平距离
DY	int	0	标签顶部到控件顶部的垂直距离
AutoSize	bool	false	根据字体大小自动调整尺寸
Text	string	""	标签文本内容
TextAlign	ContentAlignment	TopLeft	标签内的文本对齐方式
BackColor	Color	Control	标签的背景颜色
ForeColor	Color	ControlText	标签的文本颜色
Font	Font	-	标签文本的字体

位置选项

位置	行为
Left	标签显示在控件左侧
Top	标签显示在控件上方
Side	标签显示在控件侧面（右侧）
Custom	使用 DX 和 DY 或鼠标拖动手动定位

事件

事件	描述
PropertyChanged	当 LabeledControl、Gap 或 Position 属性更改时触发

最佳实践

1. 先配对再添加：先设置 LabeledControl，再将其添加到窗体，以确保正确初始化

2. 使用 Gap 设置间距：使用 Gap 属性代替手动定位，以保持间距一致

3. 选择合适的位置：

   • 水平布局的窗体使用 Left
   • 堆叠式／垂直布局的窗体使用 Top
   • 仅在必要时使用 Custom

4. 启用 AutoSize：对于不换行的标签，设置 AutoSize = true

5. 与 FlowLayout 集成：利用 FlowLayout 将标签和控件作为一个整体处理

6. 保持主题一致：为窗体中的所有 AutoLabel 应用相同的视觉样式

7. 测试移动效果：确认控件动态重新定位时，标签会跟随移动

8. 避免重叠：确保 Gap 和位置设置可防止标签与控件重叠

视觉样式

通过 SkinManager 支持的主题：

• Office2016Colorful
• Office2016Black
• Office2016DarkGray
• Office2016White

SkinManager.SetVisualStyle(this.autoLabel1, VisualTheme.Office2016Colorful);

框架支持

• .NET Framework 4.5 及更高版本
• .NET 6.0、.NET 7.0、.NET 8.0（Windows）
• .NET Core 3.1（Windows）

其他资源

• Syncfusion AutoLabel 文档
• API 参考
• 知识库文章
• GitHub 示例

故障排除

问题：标签未随控件移动

• 确保已设置 LabeledControl 属性
• 确认标签和控件都已添加到同一个容器
• 检查控件的位置是否确实发生了变化

问题：标签位置不正确

• 调整 Gap 属性以设置间距
• 如需微调，使用 DX 和 DY
• 确认 Position 属性设置正确

问题：标签与控件重叠

• 增大 Gap 值
• 选择其他 Position（例如，使用 Top 代替 Left）
• 检查控件尺寸是否留有足够空间

问题：主题未应用

• 确保已引用 SkinManager 程序集
• 确认主题受支持（仅限 Office 2016 系列）
• 将控件添加到窗体后再应用主题