syncfusion-winforms-autolabel（同步融合 winform 自动标签）

Syncfusion WinForms AutoLabel Control

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.

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

Installation

NuGet Installation

Install-Package Syncfusion.Tools.Windows

Assembly Reference

Add reference to:

• Syncfusion.Shared.Base.dll

Quick Start

Basic Setup

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

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

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.

Automatic Repositioning

When the labeled control moves, the AutoLabel automatically adjusts its position based on the Position and Gap settings.

FlowLayout Integration

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

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

📐 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

🎨 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

⚡ Events

📄 Read: references/events.md

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

🎯 Overview and Use Cases

📄 Read: references/overview.md

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

Common Patterns

Pattern 1: Simple Form with Left-Aligned Labels

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

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

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

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

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

Position Options

Events

Best Practices

1. Pair Before Adding: Set LabeledControl before adding to form for proper initialization
2. Use Gap for Spacing: Use the Gap property instead of manual positioning for consistent spacing
3. Choose Appropriate Position:

- Use Left for horizontal forms - Use Top for stacked/vertical forms - Use Custom only when necessary

1. Enable AutoSize: Set AutoSize = true for labels that don't wrap text
2. FlowLayout Integration: Leverage FlowLayout to treat label-control pairs as units
3. Consistent Theming: Apply the same visual style to all AutoLabels in a form
4. Test Movement: Verify labels follow controls when controls are repositioned dynamically
5. Avoid Overlapping: Ensure Gap and positioning prevent label-control overlap

Visual Styles

Supported themes via SkinManager:

• Office2016Colorful
• Office2016Black
• Office2016DarkGray
• Office2016White

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)

Additional Resources

• Syncfusion AutoLabel Documentation
• API Reference
• Knowledge Base Articles
• GitHub Samples

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