syncfusion-winforms-autolabel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion WinForms AutoLabel Control

Syncfusion WinForms AutoLabel 控件

The AutoLabel control is a Label-inspired control that lets you pair a label with any other control. Once paired, the AutoLabel automatically repositions itself as the labeled control's position changes, ensuring labels and controls always stay synchronized.

AutoLabel 控件是一款参照 Label 设计的控件，支持将标签与任意其他控件配对。配对完成后，当被绑定控件的位置发生变化时，AutoLabel 会自动调整自身位置，确保标签与控件始终保持同步。

When to Use This Skill

何时使用本技能

Use the AutoLabel control when you need to:

Add labels that automatically follow their associated controls
Create dynamic form layouts where controls can move
Implement complex form designs with FlowLayout manager
Ensure labels always stay positioned correctly relative to controls
Build forms that resize or reorganize controls dynamically
Create professional forms with consistent label-control spacing
Simplify form layout management with automatic positioning

当你需要实现以下需求时可以使用 AutoLabel 控件：

添加可自动跟随关联控件移动的标签
创建支持控件移动的动态表单布局
借助 FlowLayout 管理器实现复杂表单设计
确保标签始终相对于控件保持正确位置
构建可动态调整尺寸或重组控件的表单
打造标签与控件间距统一的专业表单
通过自动定位简化表单布局管理工作

Installation

安装

NuGet Installation

NuGet 安装

bash

Install-Package Syncfusion.Tools.Windows

bash

Install-Package Syncfusion.Tools.Windows

Assembly Reference

程序集引用

Add reference to:

```
Syncfusion.Shared.Base.dll
```

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

```
Syncfusion.Shared.Base.dll
```

Quick Start

快速入门

Basic Setup

基础配置

csharp

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);
        }
    }
}

csharp

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);
        }
    }
}

Designer Setup

设计器配置

Drag
```
AutoLabel
```
control from Toolbox to Form
Drag another control (e.g., TextBox) to the form
Right-click AutoLabel → Properties → Set
```
LabeledControl
```
to your control
Configure
```
Position
```
and
```
Gap
```
properties
The label will now auto-position relative to the control

将工具箱中的
```
AutoLabel
```
控件拖拽到表单上
再拖拽另一个控件（例如 TextBox）到表单上
右键点击 AutoLabel → 选择属性 → 将
```
LabeledControl
```
设置为你要绑定的控件
配置
```
Position
```
和
```
Gap
```
属性
现在标签会自动相对于绑定控件调整位置

Core Concepts

核心概念

Label-Control Pairing

标签-控件绑定

The AutoLabel pairs with any control through the

LabeledControl

property. Once paired, the label automatically tracks the control's position.

AutoLabel 通过

LabeledControl

属性与任意控件绑定，绑定完成后标签会自动追踪控件的位置。

Automatic Repositioning

自动重定位

When the labeled control moves, the AutoLabel automatically adjusts its position based on the

Position

and

Gap

settings.

当被绑定的控件移动时，AutoLabel 会根据

Position

和

Gap

设置自动调整自身位置。

FlowLayout Integration

FlowLayout 集成

FlowLayout managers treat AutoLabel-labeled control pairs as a single unit, enabling powerful dynamic form layouts.

FlowLayout 管理器会将 AutoLabel 和其绑定的控件视为一个整体单元，从而实现功能强大的动态表单布局。

Navigation Guide

导航指南

🚀 Getting Started

🚀 入门指南

📄 Read: references/getting-started.md

Installation and assembly deployment
Adding AutoLabel via Designer
Adding AutoLabel programmatically
Labeling a control
Basic configuration
Running your first AutoLabel application

📄 阅读： references/getting-started.md

安装与程序集部署
通过设计器添加 AutoLabel
通过代码添加 AutoLabel
绑定控件到标签
基础配置
运行你的第一个 AutoLabel 应用

📐 Positioning and Spacing

📐 定位与间距

📄 Read: references/positioning-spacing.md

Position property (Left, Top, Side, Custom)
Gap setting between label and control
DX and DY properties for fine control
Custom positioning with mouse
Spacing best practices

📄 阅读： references/positioning-spacing.md

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

🎨 Appearance and Theming

🎨 外观与主题

📄 Read: references/appearance-theming.md

AutoSize for automatic label sizing
BackColor and ForeColor customization
Font settings
TextAlign property
SkinManager theming (Office 2016 styles)
Visual styles

📄 阅读： references/appearance-theming.md

实现标签自动尺寸调整的 AutoSize 属性
BackColor 和 ForeColor 自定义
字体设置
TextAlign 属性
SkinManager 主题（Office 2016 风格）
视觉样式

⚡ Events

⚡ 事件

📄 Read: references/events.md

PropertyChanged event
Handling label-control updates
Event arguments
Common event scenarios

📄 阅读： references/events.md

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

🎯 Overview and Use Cases

🎯 概述与使用场景

📄 Read: references/overview.md

Component architecture
FlowLayout integration
Form layout patterns
When to use AutoLabel vs standard Label

📄 阅读： references/overview.md

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

Common Patterns

常见用法模式

Pattern 1: Simple Form with Left-Aligned Labels

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

csharp

// 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);

csharp

// 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);

Pattern 2: Top-Aligned Labels (Vertical Form)

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

csharp

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

csharp

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

Pattern 3: Custom Positioned Labels

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

csharp

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

csharp

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

Pattern 4: Themed Form with AutoLabels

模式4：带AutoLabel的主题化表单

csharp

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);

csharp

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);

Pattern 5: FlowLayout with AutoLabel Pairs

模式5：带AutoLabel配对的FlowLayout布局

csharp

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);

csharp

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);

Key Properties Reference

核心属性参考

Property	Type	Default	Description
`LabeledControl`	Control	null	The control that this label is paired with
`Position`	AutoLabelPosition	Left	Relative position: Left, Top, Side, Custom
`Gap`	int	0	Horizontal and vertical gap between label and control
`DX`	int	0	Horizontal distance from label left to control left
`DY`	int	0	Vertical distance from label top to control top
`AutoSize`	bool	false	Automatically resize based on font size
`Text`	string	""	Label text content
`TextAlign`	ContentAlignment	TopLeft	Text alignment within label
`BackColor`	Color	Control	Background color of the label
`ForeColor`	Color	ControlText	Text color of the label
`Font`	Font	-	Font for the label text

属性	类型	默认值	描述
`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	-	标签文本字体

Position Options

位置选项

Position	Behavior
Left	Label appears to the left of the control
Top	Label appears above the control
Side	Label appears on the side (right) of the control
Custom	Manual positioning using DX and DY or mouse drag

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

Events

事件

Event	Description
`PropertyChanged`	Fired when LabeledControl, Gap, or Position properties change

事件	描述
`PropertyChanged`	当 LabeledControl、Gap 或 Position 属性发生变化时触发

Best Practices

最佳实践

Pair Before Adding: Set
```
LabeledControl
```
before adding to form for proper initialization
Use Gap for Spacing: Use the
```
Gap
```
property instead of manual positioning for consistent spacing
Choose Appropriate Position:
- Use
```
Left
```
  for horizontal forms
- Use
```
Top
```
  for stacked/vertical forms
- Use
```
Custom
```
  only when necessary
Enable AutoSize: Set
```
AutoSize = true
```
for labels that don't wrap text
FlowLayout Integration: Leverage FlowLayout to treat label-control pairs as units
Consistent Theming: Apply the same visual style to all AutoLabels in a form
Test Movement: Verify labels follow controls when controls are repositioned dynamically
Avoid Overlapping: Ensure Gap and positioning prevent label-control overlap

先绑定再添加：添加到表单前先设置
```
LabeledControl
```
以确保正确初始化
使用Gap设置间距：优先使用
```
Gap
```
属性而非手动定位，保证间距统一
选择合适的位置：
- 水平表单使用
```
Left
```
- 堆叠/垂直表单使用
```
Top
```
- 仅在必要时使用
```
Custom
```
开启AutoSize：对于不需要换行的标签设置
```
AutoSize = true
```
FlowLayout集成：利用FlowLayout将标签-控件对视为整体单元
主题统一：表单内所有AutoLabel应用相同的视觉样式
测试移动效果：验证控件动态重定位时标签可以正确跟随
避免重叠：确保Gap和定位设置不会导致标签与控件重叠

Visual Styles

视觉样式

Supported themes via SkinManager:

Office2016Colorful
Office2016Black
Office2016DarkGray
Office2016White

csharp

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

通过SkinManager支持的主题：

Office2016Colorful
Office2016Black
Office2016DarkGray
Office2016White

csharp

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

Framework Support

框架支持

.NET Framework 4.5 and above
.NET 6.0, .NET 7.0, .NET 8.0 (Windows)
.NET Core 3.1 (Windows)

.NET Framework 4.5 及以上版本
.NET 6.0、.NET 7.0、.NET 8.0（Windows平台）
.NET Core 3.1（Windows平台）

Additional Resources

额外资源

Related Controls

Troubleshooting

问题排查

Issue: Label doesn't move with control

Ensure
```
LabeledControl
```
property is set
Verify both label and control are added to the same container
Check that the control's position is actually changing

Issue: Label positioning is off

Adjust
```
Gap
```
property for spacing
Use
```
DX
```
and
```
DY
```
for fine-tuning if needed
Verify
```
Position
```
property is set correctly

Issue: Label overlaps control

Increase
```
Gap
```
value
Choose different
```
Position
```
(e.g., Top instead of Left)
Check control sizes allow sufficient space

Issue: Theme not applied

Ensure SkinManager assembly is referenced
Verify theme is supported (Office 2016 variants only)
Apply theme after adding control to form

问题：标签不随控件移动

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

问题：标签定位偏移

调整
```
Gap
```
属性修改间距
必要时使用
```
DX
```
和
```
DY
```
进行精细调整
确认
```
Position
```
属性设置正确

问题：标签与控件重叠

增大
```
Gap
```
值
选择不同的
```
Position
```
（例如用Top代替Left）
检查控件尺寸是否预留了足够空间

问题：主题未生效

确认已引用SkinManager程序集
确认使用的主题受支持（仅Office 2016系列主题）
在把控件添加到表单后再应用主题

syncfusion-winforms-autolabel

Original

Translation

Syncfusion WinForms AutoLabel Control

Syncfusion WinForms AutoLabel 控件

When to Use This Skill

何时使用本技能

Installation

安装

NuGet Installation

NuGet 安装

Assembly Reference

程序集引用

Quick Start

快速入门

Basic Setup

基础配置

Designer Setup

设计器配置

Core Concepts

核心概念

Label-Control Pairing

标签-控件绑定

Automatic Repositioning

自动重定位

FlowLayout Integration

FlowLayout 集成

Navigation Guide

导航指南

🚀 Getting Started

🚀 入门指南

📐 Positioning and Spacing

📐 定位与间距

🎨 Appearance and Theming

🎨 外观与主题

⚡ Events

⚡ 事件

🎯 Overview and Use Cases

🎯 概述与使用场景

Common Patterns

常见用法模式

Pattern 1: Simple Form with Left-Aligned Labels

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

Pattern 2: Top-Aligned Labels (Vertical Form)

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

Pattern 3: Custom Positioned Labels

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

Pattern 4: Themed Form with AutoLabels

模式4：带AutoLabel的主题化表单

Pattern 5: FlowLayout with AutoLabel Pairs

模式5：带AutoLabel配对的FlowLayout布局

Key Properties Reference

核心属性参考

Position Options

位置选项

Events

事件

Best Practices

最佳实践

Visual Styles

视觉样式

Framework Support

框架支持

Additional Resources

额外资源

Related Controls

相关控件

Troubleshooting

问题排查