Back to Details

syncfusion-winforms-gradient-label

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing GradientLabel

实现 GradientLabel

An enhanced label control for Windows Forms that provides gradient backgrounds, attractive shading, custom borders, and visual styling capabilities for creating appealing UI labels.
一款面向 Windows Forms 的增强型标签控件，支持渐变背景、美观阴影、自定义边框和视觉样式配置，可用于创建极具吸引力的 UI 标签。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Gradient Labels: Create labels with gradient backgrounds and color transitions
  • Decorative Headers: Design visually appealing section headers and titles
  • Styled Text Display: Implement fancy labels with custom shading and borders
  • UI Enhancement: Add visual appeal to form labels and descriptive text
  • Custom Branding: Create branded labels with specific color schemes
  • Informational Panels: Build attractive informational labels with background effects
当你需要完成以下需求时可使用本技能：
  • 渐变标签：创建带有渐变背景和色彩过渡效果的标签
  • 装饰性页眉：设计视觉效果出色的分区页眉和标题
  • 样式化文本展示：实现带有自定义阴影和边框的精美标签
  • UI 增强：为表单标签和描述性文本添加视觉吸引力
  • 自定义品牌标识：使用特定配色方案创建符合品牌调性的标签
  • 信息面板：构建带有背景效果的美观信息标签

Component Overview

组件概述

The GradientLabel is an enhanced label control derived from the standard Windows Forms Label that provides:
  • Multiple gradient styles (Horizontal, Vertical, Diagonal, PathRectangle, PathEllipse)
  • Solid and pattern background options
  • Customizable 3D and 2D borders
  • Multi-color gradient support
  • XML serialization for state persistence
  • Full compatibility with standard Label functionality
Key Capabilities:
  • Gradient background with BrushInfo class
  • 6 gradient styles for different visual effects
  • Pattern backgrounds with multiple styles
  • Border customization (sides, styles, colors)
  • Text appearance control including disabled state
  • Save/load gradient settings to XML
  • Inherits all standard Label features (text, font, alignment)
GradientLabel 是派生自标准 Windows Forms Label 的增强型标签控件，提供以下能力：
  • 多种渐变样式（水平、垂直、对角线、路径矩形、路径椭圆）
  • 纯色和图案背景选项
  • 可自定义的 3D 和 2D 边框
  • 多色渐变支持
  • 支持 XML 序列化实现状态持久化
  • 完全兼容标准 Label 的所有功能
核心能力：
  • 基于 BrushInfo 类实现的渐变背景
  • 6 种渐变样式适配不同视觉效果
  • 多种样式的图案背景
  • 边框自定义（边、样式、颜色）
  • 包含禁用态在内的文本外观控制
  • 支持将渐变设置保存/加载为 XML 格式
  • 继承所有标准 Label 特性（文本、字体、对齐方式）

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: Starting new implementation, setting up dependencies, first-time usage
Topics covered:
  • Assembly deployment and NuGet packages
  • Control dependencies for GradientLabel
  • Adding via Visual Studio designer (toolbox drag-drop)
  • Adding via code (manual instantiation)
  • Basic initialization and configuration
  • Simple gradient setup examples
  • Namespace requirements
📄 阅读： references/getting-started.md
适用场景： 首次实现、配置依赖、首次使用时阅读
涵盖主题：
  • 程序集部署与 NuGet 包
  • GradientLabel 的控件依赖
  • 通过 Visual Studio 设计器添加（工具箱拖拽）
  • 通过代码添加（手动实例化）
  • 基础初始化与配置
  • 简单渐变设置示例
  • 命名空间要求

Background Styling

背景样式设置

📄 Read: references/background-styling.md
When to read: Configuring gradients, setting colors, customizing background appearance
Topics covered:
  • BackgroundColor property and BrushInfo class
  • Brush styles (Solid, Pattern, Gradient, None)
  • Gradient styles (ForwardDiagonal, BackwardDiagonal, Horizontal, Vertical, PathRectangle, PathEllipse)
  • BackColor and ForeColor properties
  • PatternStyle options for pattern backgrounds
  • GradientColors array for multi-color gradients
  • Creating custom color transitions
  • Complete styling examples
📄 阅读： references/background-styling.md
适用场景： 配置渐变、设置颜色、自定义背景外观时阅读
涵盖主题：
  • BackgroundColor 属性与 BrushInfo 类
  • 画刷样式（纯色、图案、渐变、无）
  • 渐变样式（正向对角线、反向对角线、水平、垂直、路径矩形、路径椭圆）
  • BackColor 和 ForeColor 属性
  • 图案背景的 PatternStyle 选项
  • 支持多色渐变的 GradientColors 数组
  • 创建自定义色彩过渡效果
  • 完整样式示例

Border Configuration

边框配置

📄 Read: references/border-configuration.md
When to read: Adding borders, customizing border styles, controlling border appearance
Topics covered:
  • BorderSides property (Left, Top, Right, Bottom, Middle, All)
  • BorderStyle options (Raised, Sunken, Flat, Etched, Bump, etc.)
  • BorderColor for 2D border colors
  • Border3DStyle enumeration
  • FixedSingle border mode
  • Selective side borders
  • 3D border effects
  • Complete border examples
📄 阅读： references/border-configuration.md
适用场景： 添加边框、自定义边框样式、控制边框外观时阅读
涵盖主题：
  • BorderSides 属性（左、上、右、下、中间、全部）
  • BorderStyle 选项（凸起、凹陷、平面、蚀刻、凸起浮雕等）
  • 2D 边框对应的 BorderColor 属性
  • Border3DStyle 枚举
  • FixedSingle 边框模式
  • 可选单边边框设置
  • 3D 边框效果
  • 完整边框示例

Foreground and Text Settings

前景与文本设置

📄 Read: references/foreground-text-settings.md
When to read: Configuring text appearance, setting font properties, managing disabled state
Topics covered:
  • Text property for label content
  • ForeColor for text color
  • DrawActiveWhenDisabled property
  • Font properties inherited from Label
  • Text alignment options (inherited)
  • TextAlign property usage
  • Disabled state appearance control
  • Text visibility and styling
📄 阅读： references/foreground-text-settings.md
适用场景： 配置文本外观、设置字体属性、管理禁用态效果时阅读
涵盖主题：
  • 存储标签内容的 Text 属性
  • 控制文本颜色的 ForeColor 属性
  • DrawActiveWhenDisabled 属性
  • 继承自 Label 的字体属性
  • 继承的文本对齐选项
  • TextAlign 属性用法
  • 禁用态外观控制
  • 文本可见性与样式设置

Serialization

序列化

📄 Read: references/serialization.md
When to read: Saving/loading gradient settings, persisting visual state, implementing themes
Topics covered:
  • XML serialization overview
  • Saving BackgroundColor to XML files
  • Loading BackgroundColor from XML files
  • XmlSerializer class usage
  • FileStream and XmlTextWriter implementation
  • Persisting gradient state across sessions
  • Theme save/load patterns
  • Complete serialization examples
📄 阅读： references/serialization.md
适用场景： 保存/加载渐变设置、持久化视觉状态、实现主题功能时阅读
涵盖主题：
  • XML 序列化概述
  • 将 BackgroundColor 保存到 XML 文件
  • 从 XML 文件加载 BackgroundColor 配置
  • XmlSerializer 类用法
  • FileStream 与 XmlTextWriter 实现
  • 跨会话持久化渐变状态
  • 主题保存/加载模式
  • 完整序列化示例

Quick Start

快速入门

Basic Gradient Label Setup

基础渐变标签设置

csharp
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Drawing;

// Create and configure GradientLabel
GradientLabel gradientLabel = new GradientLabel();
gradientLabel.Size = new Size(200, 60);
gradientLabel.Location = new Point(20, 20);

// Set gradient background (horizontal red to blue)
gradientLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.Red,
    Color.MediumBlue
);

// Set text properties
gradientLabel.Text = "Welcome";
gradientLabel.ForeColor = Color.White;
gradientLabel.Font = new Font("Arial", 14, FontStyle.Bold);

// Add to form
this.Controls.Add(gradientLabel);
csharp
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Drawing;

// 创建并配置 GradientLabel
GradientLabel gradientLabel = new GradientLabel();
gradientLabel.Size = new Size(200, 60);
gradientLabel.Location = new Point(20, 20);

// 设置渐变背景（水平从红到蓝）
gradientLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.Red,
    Color.MediumBlue
);

// 设置文本属性
gradientLabel.Text = "Welcome";
gradientLabel.ForeColor = Color.White;
gradientLabel.Font = new Font("Arial", 14, FontStyle.Bold);

// 添加到表单
this.Controls.Add(gradientLabel);

With Border Styling

带边框样式的实现

csharp
// Add 3D border effect
gradientLabel.BorderStyle = Border3DStyle.Raised;
gradientLabel.BorderSides = Border3DSide.All;
csharp
// 添加3D边框效果
gradientLabel.BorderStyle = Border3DStyle.Raised;
gradientLabel.BorderSides = Border3DSide.All;

Common Patterns

常用模式

Pattern 1: Section Header with Vertical Gradient

模式1：带垂直渐变的分区页眉

csharp
// Create attractive section header
GradientLabel header = new GradientLabel
{
    Size = new Size(300, 50),
    Location = new Point(10, 10),
    Text = "User Information",
    Font = new Font("Segoe UI", 16, FontStyle.Bold),
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.White
};

// Vertical gradient from dark to light blue
header.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.DarkBlue,
    Color.LightSkyBlue
);

// Raised 3D border
header.BorderStyle = Border3DStyle.Raised;
csharp
// 创建美观的分区页眉
GradientLabel header = new GradientLabel
{
    Size = new Size(300, 50),
    Location = new Point(10, 10),
    Text = "User Information",
    Font = new Font("Segoe UI", 16, FontStyle.Bold),
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.White
};

// 垂直渐变从深蓝到浅天蓝
header.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.DarkBlue,
    Color.LightSkyBlue
);

// 凸起3D边框
header.BorderStyle = Border3DStyle.Raised;

Pattern 2: Multi-Color Gradient Label

模式2：多色渐变标签

csharp
// Create label with multiple gradient colors
GradientLabel colorfulLabel = new GradientLabel
{
    Size = new Size(250, 80),
    Text = "Special Offer!",
    Font = new Font("Arial", 18, FontStyle.Bold),
    ForeColor = Color.White,
    TextAlign = ContentAlignment.MiddleCenter
};

// Path rectangle gradient with 5 colors
colorfulLabel.BackgroundColor = new BrushInfo(
    GradientStyle.PathRectangle,
    new Color[]
    {
        Color.LavenderBlush,
        Color.LemonChiffon,
        Color.DarkKhaki,
        Color.SandyBrown,
        Color.LightSeaGreen
    }
);
csharp
// 创建带有多色渐变的标签
GradientLabel colorfulLabel = new GradientLabel
{
    Size = new Size(250, 80),
    Text = "Special Offer!",
    Font = new Font("Arial", 18, FontStyle.Bold),
    ForeColor = Color.White,
    TextAlign = ContentAlignment.MiddleCenter
};

// 路径矩形渐变搭配5种颜色
colorfulLabel.BackgroundColor = new BrushInfo(
    GradientStyle.PathRectangle,
    new Color[]
    {
        Color.LavenderBlush,
        Color.LemonChiffon,
        Color.DarkKhaki,
        Color.SandyBrown,
        Color.LightSeaGreen
    }
);

Pattern 3: Styled Status Label

模式3：样式化状态标签

csharp
// Create status indicator label
GradientLabel statusLabel = new GradientLabel
{
    Size = new Size(150, 30),
    Text = "Active",
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.DarkGreen,
    Font = new Font("Arial", 10, FontStyle.Bold)
};

// Horizontal gradient (light green)
statusLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.LightGreen,
    Color.PaleGreen
);

// Flat border with custom color
statusLabel.BorderStyle = Border3DStyle.Flat;
statusLabel.BorderSides = Border3DSide.All;
statusLabel.BorderColor = Color.DarkGreen;
csharp
// 创建状态指示标签
GradientLabel statusLabel = new GradientLabel
{
    Size = new Size(150, 30),
    Text = "Active",
    TextAlign = ContentAlignment.MiddleCenter,
    ForeColor = Color.DarkGreen,
    Font = new Font("Arial", 10, FontStyle.Bold)
};

// 水平渐变（浅绿色系）
statusLabel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.LightGreen,
    Color.PaleGreen
);

// 自定义颜色的平面边框
statusLabel.BorderStyle = Border3DStyle.Flat;
statusLabel.BorderSides = Border3DSide.All;
statusLabel.BorderColor = Color.DarkGreen;

Key Properties

核心属性

Background Properties

背景属性

  • BackgroundColor: Gets/sets background color and styles using BrushInfo class
  • BackgroundColor.Style: Brush style (Solid, Pattern, Gradient, None)
  • BackgroundColor.GradientStyle: Gradient direction (Horizontal, Vertical, ForwardDiagonal, BackwardDiagonal, PathRectangle, PathEllipse)
  • BackgroundColor.BackColor: Starting color for gradient
  • BackgroundColor.ForeColor: Ending color for gradient
  • BackgroundColor.PatternStyle: Pattern style when using Pattern mode
  • BackgroundColor.GradientColors: Array of colors for multi-color gradients
  • BackgroundColor：通过 BrushInfo 类获取/设置背景颜色和样式
  • BackgroundColor.Style：画刷样式（纯色、图案、渐变、无）
  • BackgroundColor.GradientStyle：渐变方向（水平、垂直、正向对角线、反向对角线、路径矩形、路径椭圆）
  • BackgroundColor.BackColor：渐变起始颜色
  • BackgroundColor.ForeColor：渐变结束颜色
  • BackgroundColor.PatternStyle：图案模式下的图案样式
  • BackgroundColor.GradientColors：多色渐变对应的颜色数组

Border Properties

边框属性

  • BorderSides: Sides that display border (Left, Top, Right, Bottom, Middle, All)
  • BorderStyle: 3D border style (Raised, RaisedOuter, RaisedInner, Sunken, SunkenOuter, SunkenInner, Etched, Bump, Adjust, Flat)
  • BorderColor: Color for 2D border (effective when BorderStyle is FixedSingle)
  • BorderSides：显示边框的边（左、上、右、下、中间、全部）
  • BorderStyle：3D 边框样式（凸起、外凸起、内凸起、凹陷、外凹陷、内凹陷、蚀刻、凸起浮雕、调整、平面）
  • BorderColor：2D 边框颜色（仅当 BorderStyle 设为 FixedSingle 时生效）

Text Properties (Inherited from Label)

文本属性（继承自 Label）

  • Text: Label text content
  • Font: Font used for text display
  • ForeColor: Text color
  • TextAlign: Text alignment (ContentAlignment enum)
  • DrawActiveWhenDisabled: Whether text draws normally when control is disabled
  • Text：标签文本内容
  • Font：文本展示使用的字体
  • ForeColor：文本颜色
  • TextAlign：文本对齐方式（ContentAlignment 枚举）
  • DrawActiveWhenDisabled：控件禁用时是否正常绘制文本

Standard Label Properties

标准 Label 属性

  • All properties from System.Windows.Forms.Label are available
  • Size, Location, Enabled, Visible, etc.
  • 支持 System.Windows.Forms.Label 的所有属性
  • 包括 Size、Location、Enabled、Visible 等

Common Use Cases

常见使用场景

Form Section Headers

表单分区页眉

Create visually distinct section headers for grouping related controls in forms.
为表单中分组的相关控件创建视觉区分度高的分区页眉

Dashboard Panels

仪表盘面板

Build attractive informational panels and status displays in dashboard applications.
在仪表盘应用中构建美观的信息面板和状态展示组件

Branding Elements

品牌元素

Implement company branding with custom color schemes and gradient effects.
通过自定义配色方案和渐变效果实现企业品牌标识落地

Status Indicators

状态指示器

Design eye-catching status labels with color-coded gradients (success, warning, error).
使用颜色编码的渐变设计醒目的状态标签（成功、警告、错误）

Decorative Text

装饰性文本

Add visual appeal to important text, announcements, or promotional messages.
为重要文本、公告或促销信息增加视觉吸引力

Theme-Based Labeling

主题化标签

Create themed labels that can be saved and loaded via serialization.
创建可通过序列化保存和加载的主题化标签

Related Skills

相关技能

  • AutoLabel - Automatic label positioning and sizing
  • GradientPanel - Panels with gradient backgrounds
  • AutoLabel - 自动标签定位与尺寸调整
  • GradientPanel - 带渐变背景的面板

Notes

注意事项

  • GradientLabel derives from System.Windows.Forms.Label, so all standard Label functionality is available
  • The BrushInfo class provides the gradient and styling capabilities
  • BackgroundColor property is the key to customization
  • BorderColor only works when BorderStyle is set to FixedSingle
  • Gradient colors array first entry matches BackColor, last entry matches ForeColor
  • XML serialization allows persisting gradient settings across application sessions
  • Performance is optimized for typical usage; avoid excessive gradient complexity for large numbers of controls
  • GradientLabel 派生自 System.Windows.Forms.Label，因此支持所有标准 Label 功能
  • BrushInfo 类提供渐变和样式配置能力
  • BackgroundColor 属性是自定义的核心
  • BorderColor 仅在 BorderStyle 设为 FixedSingle 时生效
  • 渐变色数组的第一个元素对应 BackColor，最后一个元素对应 ForeColor
  • XML 序列化支持跨应用会话持久化渐变设置
  • 已针对常规使用场景做了性能优化，大量使用控件时避免过度复杂的渐变效果