syncfusion-winforms-gradient-panel

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Gradient Panels

实现渐变面板

This skill guides you through implementing the Syncfusion GradientPanel control in Windows Forms applications. GradientPanel is a panel-derived container control that provides advanced background customization with gradients, patterns, and solid colors.
本技能将指导你在 Windows Forms 应用中实现 Syncfusion GradientPanel 控件。GradientPanel 是派生自面板的容器控件,支持通过渐变、图案和纯色实现高级背景自定义。

When to Use This Skill

什么时候使用本技能

Use this skill when you need to:
  • Container with gradient backgrounds - Create visually appealing panels with gradient color transitions
  • Grouped controls with styling - Group related controls in a styled container panel
  • Pattern backgrounds - Use checkerboard, dots, stripes, or other pattern backgrounds
  • Visual separation - Create distinct visual sections with custom backgrounds
  • Styled containers - Replace standard panels with visually rich alternatives
  • Custom borders - Apply 2D or 3D borders with various styles
  • Scrollable containers - Create auto-scrolling panels for large content areas
  • Background images - Combine gradient effects with background images
当你需要实现以下需求时可使用本技能:
  • 带渐变背景的容器 - 创建带有渐变色过渡的美观面板
  • 带样式的分组控件 - 将相关控件分组放入带样式的容器面板中
  • 图案背景 - 使用棋盘格、圆点、条纹或其他图案作为背景
  • 视觉分隔 - 通过自定义背景创建清晰的视觉分区
  • 样式化容器 - 用视觉效果更丰富的替代方案替换标准面板
  • 自定义边框 - 应用不同样式的2D或3D边框
  • 可滚动容器 - 为大内容区域创建自动滚动面板
  • 背景图片 - 结合渐变效果和背景图片使用

Component Overview

组件概述

GradientPanel is a panel-derived control that acts as a container for other controls. It extends the standard Panel with advanced background rendering capabilities.
Key capabilities:
  • Multiple background styles: Solid colors, gradient transitions, pattern fills
  • Gradient directions: Forward/backward diagonal, horizontal, vertical, path-based
  • Border customization: 2D and 3D borders with multiple styles
  • Image backgrounds: Support for background images with layout options
  • Auto-scrolling: Automatic scroll bars for content overflow
  • Auto-sizing: Automatic panel resizing based on content
Control type: Container control (inherits from Panel)
Assembly:
Syncfusion.Shared.Base.dll
Namespace:
Syncfusion.Windows.Forms.Tools
GradientPanel 是派生自面板的控件,可作为其他控件的容器。它在标准 Panel 的基础上扩展了高级背景渲染能力。
核心能力:
  • 多种背景样式:纯色、渐变过渡、图案填充
  • 渐变方向:正向/反向对角线、水平、垂直、基于路径
  • 边框自定义:支持多种样式的2D和3D边框
  • 图片背景:支持背景图片及多种布局选项
  • 自动滚动:内容溢出时自动显示滚动条
  • 自动尺寸:根据内容自动调整面板大小
控件类型: 容器控件(继承自 Panel)
程序集:
Syncfusion.Shared.Base.dll
命名空间:
Syncfusion.Windows.Forms.Tools

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门

📄 Read: references/getting-started.md
  • Assembly deployment and NuGet installation
  • Adding GradientPanel via Designer (toolbox)
  • Adding GradientPanel via code
  • Basic setup and initial configuration
  • First gradient panel examples
When to read: Starting a new implementation, need installation guidance, first-time setup
📄 阅读: references/getting-started.md
  • 程序集部署和 NuGet 安装
  • 通过 Designer(工具箱)添加 GradientPanel
  • 通过代码添加 GradientPanel
  • 基础设置和初始配置
  • 首个渐变面板示例
适用阅读场景: 启动新的实现、需要安装指导、首次设置时

Background Styles and Customization

背景样式和自定义

📄 Read: references/background-styles.md
  • Solid color backgrounds
  • Pattern backgrounds (53 pattern styles)
  • Gradient backgrounds (7 gradient directions)
  • BrushInfo configuration
  • Color blending and combinations
  • BackColor vs BackgroundColor properties
When to read: Need gradient effects, pattern fills, color transitions, custom background styling
📄 阅读: references/background-styles.md
  • 纯色背景
  • 图案背景(53种图案样式)
  • 渐变背景(7种渐变方向)
  • BrushInfo 配置
  • 颜色混合与组合
  • BackColor 与 BackgroundColor 属性的区别
适用阅读场景: 需要实现渐变效果、图案填充、颜色过渡、自定义背景样式时

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md
  • Foreground and background colors
  • Font and text styling
  • Background images and layout modes
  • Combining gradients with images
  • Transparency and layering effects
When to read: Need text styling, background images, layered effects, font customization
📄 阅读: references/appearance-customization.md
  • 前景色和背景色
  • 字体和文本样式
  • 背景图片和布局模式
  • 渐变与图片结合使用
  • 透明度和分层效果
适用阅读场景: 需要文本样式、背景图片、分层效果、字体自定义时

Border Settings

边框设置

📄 Read: references/border-settings.md
  • 2D borders (FixedSingle) vs 3D borders (Fixed3D)
  • Border3DStyle options (Raised, Etched, Sunken, etc.)
  • BorderColor for 2D borders
  • BorderSides for selective borders
  • Visual border comparison
When to read: Need custom borders, 3D effects, border colors, selective border sides
📄 阅读: references/border-settings.md
  • 2D边框(FixedSingle)与3D边框(Fixed3D)的区别
  • Border3DStyle 选项(凸起、蚀刻、凹陷等)
  • 2D边框的 BorderColor 设置
  • 可选择展示的边框边
  • 边框视觉效果对比
适用阅读场景: 需要自定义边框、3D效果、边框颜色、选择性展示边框边时

Scroll and Auto-Size Settings

滚动和自动尺寸设置

📄 Read: references/scroll-sizing.md
  • AutoScroll for content overflow
  • AutoScrollMargin and AutoScrollMinSize
  • AutoSize behavior
  • AutoSizeMode (GrowOnly vs GrowAndShrink)
  • Container management with child controls
When to read: Content exceeds panel size, need auto-scrolling, dynamic panel sizing
📄 阅读: references/scroll-sizing.md
  • 内容溢出时的 AutoScroll 配置
  • AutoScrollMargin 和 AutoScrollMinSize 设置
  • AutoSize 行为说明
  • AutoSizeMode(仅增长/可增长可收缩)
  • 带子控件的容器管理
适用阅读场景: 内容超出面板尺寸、需要自动滚动、动态调整面板尺寸时

Quick Start

快速入门

Basic Gradient Panel via Code

通过代码实现基础渐变面板

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

namespace GradientPanelDemo
{
    public partial class Form1 : Form
    {
        private GradientPanel gradientPanel1;

        public Form1()
        {
            InitializeComponent();
            CreateGradientPanel();
        }

        private void CreateGradientPanel()
        {
            // Create GradientPanel
            gradientPanel1 = new GradientPanel();
            gradientPanel1.Size = new Size(400, 300);
            gradientPanel1.Location = new Point(20, 20);
            
            // Set gradient background (blue to red, forward diagonal)
            gradientPanel1.BackgroundColor = new BrushInfo(
                GradientStyle.ForwardDiagonal, 
                Color.Blue, 
                Color.Red
            );
            
            // Add border
            gradientPanel1.BorderStyle = BorderStyle.FixedSingle;
            gradientPanel1.BorderColor = Color.White;
            
            // Add to form
            this.Controls.Add(gradientPanel1);
            
            // Add child controls to the panel
            Label label = new Label();
            label.Text = "Gradient Panel Content";
            label.ForeColor = Color.White;
            label.BackColor = Color.Transparent;
            label.Location = new Point(20, 20);
            label.AutoSize = true;
            gradientPanel1.Controls.Add(label);
        }
    }
}
csharp
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Drawing;
using System.Drawing;
using System.Windows.Forms;

namespace GradientPanelDemo
{
    public partial class Form1 : Form
    {
        private GradientPanel gradientPanel1;

        public Form1()
        {
            InitializeComponent();
            CreateGradientPanel();
        }

        private void CreateGradientPanel()
        {
            // 创建 GradientPanel
            gradientPanel1 = new GradientPanel();
            gradientPanel1.Size = new Size(400, 300);
            gradientPanel1.Location = new Point(20, 20);
            
            // 设置渐变背景(蓝到红,正向对角线)
            gradientPanel1.BackgroundColor = new BrushInfo(
                GradientStyle.ForwardDiagonal, 
                Color.Blue, 
                Color.Red
            );
            
            // 添加边框
            gradientPanel1.BorderStyle = BorderStyle.FixedSingle;
            gradientPanel1.BorderColor = Color.White;
            
            // 添加到窗体
            this.Controls.Add(gradientPanel1);
            
            // 向面板添加子控件
            Label label = new Label();
            label.Text = "Gradient Panel Content";
            label.ForeColor = Color.White;
            label.BackColor = Color.Transparent;
            label.Location = new Point(20, 20);
            label.AutoSize = true;
            gradientPanel1.Controls.Add(label);
        }
    }
}

Solid Background Panel

纯色背景面板

csharp
// Create panel with solid color background
GradientPanel solidPanel = new GradientPanel();
solidPanel.BackgroundColor = new BrushInfo(Color.MediumBlue);
solidPanel.BorderStyle = BorderStyle.FixedSingle;
solidPanel.BorderColor = Color.Red;
csharp
// 创建纯色背景面板
GradientPanel solidPanel = new GradientPanel();
solidPanel.BackgroundColor = new BrushInfo(Color.MediumBlue);
solidPanel.BorderStyle = BorderStyle.FixedSingle;
solidPanel.BorderColor = Color.Red;

Pattern Background Panel

图案背景面板

csharp
// Create panel with pattern background
GradientPanel patternPanel = new GradientPanel();
patternPanel.BackgroundColor = new BrushInfo(
    PatternStyle.LargeCheckerBoard,
    Color.Turquoise,  // Foreground color
    Color.MediumBlue  // Background color
);
patternPanel.BorderStyle = BorderStyle.FixedSingle;
csharp
// 创建图案背景面板
GradientPanel patternPanel = new GradientPanel();
patternPanel.BackgroundColor = new BrushInfo(
    PatternStyle.LargeCheckerBoard,
    Color.Turquoise,  // 前景色
    Color.MediumBlue  // 背景色
);
patternPanel.BorderStyle = BorderStyle.FixedSingle;

Common Patterns

常用实现模式

Pattern 1: Form Section with Gradient Header

模式1:带渐变头部的窗体分区

csharp
// Create header panel with gradient
GradientPanel headerPanel = new GradientPanel();
headerPanel.Dock = DockStyle.Top;
headerPanel.Height = 80;
headerPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.FromArgb(0, 120, 215),
    Color.FromArgb(0, 80, 150)
);

// Add title label
Label titleLabel = new Label();
titleLabel.Text = "Application Header";
titleLabel.Font = new Font("Segoe UI", 18, FontStyle.Bold);
titleLabel.ForeColor = Color.White;
titleLabel.BackColor = Color.Transparent;
titleLabel.AutoSize = true;
titleLabel.Location = new Point(20, 25);
headerPanel.Controls.Add(titleLabel);

this.Controls.Add(headerPanel);
csharp
// 创建渐变头部面板
GradientPanel headerPanel = new GradientPanel();
headerPanel.Dock = DockStyle.Top;
headerPanel.Height = 80;
headerPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.FromArgb(0, 120, 215),
    Color.FromArgb(0, 80, 150)
);

// 添加标题标签
Label titleLabel = new Label();
titleLabel.Text = "Application Header";
titleLabel.Font = new Font("Segoe UI", 18, FontStyle.Bold);
titleLabel.ForeColor = Color.White;
titleLabel.BackColor = Color.Transparent;
titleLabel.AutoSize = true;
titleLabel.Location = new Point(20, 25);
headerPanel.Controls.Add(titleLabel);

this.Controls.Add(headerPanel);

Pattern 2: Content Container with Scroll

模式2:带滚动的内容容器

csharp
// Create scrollable content container
GradientPanel contentPanel = new GradientPanel();
contentPanel.Dock = DockStyle.Fill;
contentPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.WhiteSmoke,
    Color.LightGray
);
contentPanel.AutoScroll = true;
contentPanel.AutoScrollMargin = new Size(5, 5);

// Add multiple child controls that exceed panel size
for (int i = 0; i < 20; i++)
{
    Button btn = new Button();
    btn.Text = $"Button {i + 1}";
    btn.Location = new Point(10, 10 + (i * 40));
    btn.Size = new Size(200, 30);
    contentPanel.Controls.Add(btn);
}

this.Controls.Add(contentPanel);
csharp
// 创建可滚动内容容器
GradientPanel contentPanel = new GradientPanel();
contentPanel.Dock = DockStyle.Fill;
contentPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.WhiteSmoke,
    Color.LightGray
);
contentPanel.AutoScroll = true;
contentPanel.AutoScrollMargin = new Size(5, 5);

// 添加多个超出面板尺寸的子控件
for (int i = 0; i < 20; i++)
{
    Button btn = new Button();
    btn.Text = $"Button {i + 1}";
    btn.Location = new Point(10, 10 + (i * 40));
    btn.Size = new Size(200, 30);
    contentPanel.Controls.Add(btn);
}

this.Controls.Add(contentPanel);

Pattern 3: Sidebar Panel with Pattern

模式3:带图案的侧边栏面板

csharp
// Create sidebar with pattern background
GradientPanel sidebarPanel = new GradientPanel();
sidebarPanel.Dock = DockStyle.Left;
sidebarPanel.Width = 200;
sidebarPanel.BackgroundColor = new BrushInfo(
    PatternStyle.DarkDownwardDiagonal,
    Color.Gray,
    Color.DarkGray
);
sidebarPanel.BorderStyle = BorderStyle.Fixed3D;
sidebarPanel.Border3DStyle = Border3DStyle.Etched;

this.Controls.Add(sidebarPanel);
csharp
// 创建带图案背景的侧边栏
GradientPanel sidebarPanel = new GradientPanel();
sidebarPanel.Dock = DockStyle.Left;
sidebarPanel.Width = 200;
sidebarPanel.BackgroundColor = new BrushInfo(
    PatternStyle.DarkDownwardDiagonal,
    Color.Gray,
    Color.DarkGray
);
sidebarPanel.BorderStyle = BorderStyle.Fixed3D;
sidebarPanel.Border3DStyle = Border3DStyle.Etched;

this.Controls.Add(sidebarPanel);

Pattern 4: Card-Style Panel Group

模式4:卡片式面板组

csharp
private void CreateCardPanels()
{
    FlowLayoutPanel container = new FlowLayoutPanel();
    container.Dock = DockStyle.Fill;
    container.Padding = new Padding(10);
    
    // Create multiple card-style panels
    for (int i = 0; i < 6; i++)
    {
        GradientPanel card = new GradientPanel();
        card.Size = new Size(180, 150);
        card.Margin = new Padding(5);
        card.BackgroundColor = new BrushInfo(
            GradientStyle.PathRectangle,
            Color.AliceBlue,
            Color.SteelBlue
        );
        card.BorderStyle = BorderStyle.FixedSingle;
        card.BorderColor = Color.SteelBlue;
        
        // Add card content
        Label cardTitle = new Label();
        cardTitle.Text = $"Card {i + 1}";
        cardTitle.Font = new Font("Segoe UI", 12, FontStyle.Bold);
        cardTitle.BackColor = Color.Transparent;
        cardTitle.AutoSize = true;
        cardTitle.Location = new Point(10, 10);
        card.Controls.Add(cardTitle);
        
        container.Controls.Add(card);
    }
    
    this.Controls.Add(container);
}
csharp
private void CreateCardPanels()
{
    FlowLayoutPanel container = new FlowLayoutPanel();
    container.Dock = DockStyle.Fill;
    container.Padding = new Padding(10);
    
    // 创建多个卡片式面板
    for (int i = 0; i < 6; i++)
    {
        GradientPanel card = new GradientPanel();
        card.Size = new Size(180, 150);
        card.Margin = new Padding(5);
        card.BackgroundColor = new BrushInfo(
            GradientStyle.PathRectangle,
            Color.AliceBlue,
            Color.SteelBlue
        );
        card.BorderStyle = BorderStyle.FixedSingle;
        card.BorderColor = Color.SteelBlue;
        
        // 添加卡片内容
        Label cardTitle = new Label();
        cardTitle.Text = $"Card {i + 1}";
        cardTitle.Font = new Font("Segoe UI", 12, FontStyle.Bold);
        cardTitle.BackColor = Color.Transparent;
        cardTitle.AutoSize = true;
        cardTitle.Location = new Point(10, 10);
        card.Controls.Add(cardTitle);
        
        container.Controls.Add(card);
    }
    
    this.Controls.Add(container);
}

Key Properties

核心属性

Background Properties

背景属性

PropertyTypeDescription
BackgroundColor
BrushInfo
Sets gradient, pattern, or solid background using BrushInfo
BackColor
Color
Standard background color (use BackgroundColor for gradients)
BackgroundImage
Image
Background image for the panel
BackgroundImageLayout
ImageLayout
Layout mode: Stretch, Tile, Center, Zoom
属性类型描述
BackgroundColor
BrushInfo
通过 BrushInfo 设置渐变、图案或纯色背景
BackColor
Color
标准背景色(渐变请使用 BackgroundColor)
BackgroundImage
Image
面板的背景图片
BackgroundImageLayout
ImageLayout
布局模式:拉伸、平铺、居中、缩放

Border Properties

边框属性

PropertyTypeDescription
BorderStyle
BorderStyle
FixedSingle (2D) or Fixed3D (3D borders)
Border3DStyle
Border3DStyle
3D style: Raised, Etched, Sunken, Bump, etc.
BorderSingle
ButtonBorderStyle
2D style: Solid, Dotted, Dashed, Inset, Outset
BorderColor
Color
Color for 2D borders (requires FixedSingle)
BorderSides
Border3DSide
Specifies which sides have borders: All, Top, Bottom, Left, Right
属性类型描述
BorderStyle
BorderStyle
FixedSingle(2D)或 Fixed3D(3D边框)
Border3DStyle
Border3DStyle
3D样式:凸起、蚀刻、凹陷、凸起凹陷等
BorderSingle
ButtonBorderStyle
2D样式:实线、点线、虚线、内凹、外凸
BorderColor
Color
2D边框的颜色(需搭配 FixedSingle 使用)
BorderSides
Border3DSide
指定展示边框的边:全部、顶部、底部、左侧、右侧

Scroll and Sizing Properties

滚动和尺寸属性

PropertyTypeDescription
AutoScroll
bool
Enable automatic scroll bars when content exceeds panel
AutoScrollMargin
Size
Margin width during auto scroll
AutoScrollMinSize
Size
Minimum logical size for auto scroll region
AutoSize
bool
Automatically size panel based on content
AutoSizeMode
AutoSizeMode
GrowOnly or GrowAndShrink resizing behavior
属性类型描述
AutoScroll
bool
内容超出面板时启用自动滚动条
AutoScrollMargin
Size
自动滚动时的边距宽度
AutoScrollMinSize
Size
自动滚动区域的最小逻辑尺寸
AutoSize
bool
根据内容自动调整面板尺寸
AutoSizeMode
AutoSizeMode
仅增长或可增长可收缩的调整行为

Text and Font Properties

文本和字体属性

PropertyTypeDescription
Font
Font
Font style for text in the panel
ForeColor
Color
Color for text and graphics
属性类型描述
Font
Font
面板中文本的字体样式
ForeColor
Color
文本和图形的颜色

Common Use Cases

常见使用场景

Use Case 1: Application Dashboard

场景1:应用仪表盘

Use GradientPanel as a dashboard background with gradient styling to create visual hierarchy and modern appearance.
使用 GradientPanel 作为仪表盘背景,通过渐变样式创建视觉层级和现代化外观。

Use Case 2: Form Sections

场景2:窗体分区

Divide forms into logical sections using GradientPanels with different background styles for visual organization.
使用不同背景样式的 GradientPanel 将窗体划分为逻辑分区,实现视觉上的结构化。

Use Case 3: Sidebar Navigation

场景3:侧边栏导航

Create sidebars with gradient or pattern backgrounds to distinguish navigation areas from content areas.
创建带渐变或图案背景的侧边栏,将导航区域与内容区域区分开。

Use Case 4: Header/Footer Sections

场景4:头部/底部区域

Use gradient panels for headers and footers with horizontal gradients for professional appearance.
使用带水平渐变的渐变面板作为头部和底部,打造专业的外观。

Use Case 5: Content Grouping

场景5:内容分组

Group related controls (buttons, labels, inputs) in gradient panels for better visual organization.
将相关控件(按钮、标签、输入框)分组放入渐变面板中,优化视觉组织结构。

Use Case 6: Card-Based Layouts

场景6:卡片式布局

Create card-style UI with individual GradientPanels for each card, using PathRectangle gradients.
使用单独的 GradientPanel 创建卡片式UI,搭配 PathRectangle 渐变实现卡片效果。

Use Case 7: Themed Containers

场景7:主题化容器

Apply consistent theming across application using gradient panels with unified color schemes.
通过统一配色的渐变面板在整个应用中应用一致的主题。

Use Case 8: Scrollable Content Areas

场景8:可滚动内容区域

Large content areas that need automatic scrolling with styled backgrounds.
需要自动滚动的大内容区域,同时需要带样式的背景。

Best Practices

最佳实践

  1. Use BackgroundColor for gradients - Use
    BackgroundColor
    with
    BrushInfo
    for gradients/patterns, not
    BackColor
  2. Match border to style - Use FixedSingle for 2D borders, Fixed3D for 3D borders
  3. Transparent child controls - Set child control
    BackColor = Color.Transparent
    to show gradient
  4. High contrast text - Use contrasting
    ForeColor
    for text visibility over gradients
  5. Consistent gradients - Use similar gradient directions across related panels
  6. Enable AutoScroll - For panels with many child controls that may exceed size
  7. BorderColor with FixedSingle -
    BorderColor
    only works with
    BorderStyle.FixedSingle
  8. PathRectangle for cards - Use
    GradientStyle.PathRectangle
    or
    PathEllipse
    for card-like effects
  9. Performance - Minimize gradient panels in high-frequency update scenarios
  10. Designer preview - Use Designer to preview gradients and adjust colors interactively
  1. 渐变使用 BackgroundColor 设置 - 使用带
    BrushInfo
    BackgroundColor
    设置渐变/图案,不要使用
    BackColor
  2. 边框与样式匹配 - 2D边框使用 FixedSingle,3D边框使用 Fixed3D
  3. 子控件设置透明 - 将子控件的
    BackColor = Color.Transparent
    以显示渐变效果
  4. 文本高对比度 - 使用对比鲜明的
    ForeColor
    保证渐变背景上的文本可见性
  5. 渐变方向统一 - 相关面板使用相近的渐变方向保持一致性
  6. 启用自动滚动 - 当面板包含大量可能超出尺寸的子控件时启用
  7. BorderColor 搭配 FixedSingle 使用 -
    BorderColor
    仅在
    BorderStyle.FixedSingle
    模式下生效
  8. 卡片使用 PathRectangle 渐变 - 使用
    GradientStyle.PathRectangle
    PathEllipse
    实现类卡片效果
  9. 性能优化 - 在高频更新的场景中减少渐变面板的使用
  10. 设计器预览 - 使用 Designer 预览渐变效果,交互式调整颜色

Related Skills

相关技能

  • AutoLabel: ../implementing-autolabels/ - Styled labels that complement gradient panels
  • Layout Controls: Other container controls for panel-based layouts
  • AutoLabel: ../implementing-autolabels/ - 可与渐变面板搭配使用的样式化标签
  • 布局控件: 其他用于面板布局的容器控件