syncfusion-winforms-gradient-panel
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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.dllNamespace:
Syncfusion.Windows.Forms.ToolsGradientPanel 是派生自面板的控件,可作为其他控件的容器。它在标准 Panel 的基础上扩展了高级背景渲染能力。
核心能力:
- 多种背景样式:纯色、渐变过渡、图案填充
- 渐变方向:正向/反向对角线、水平、垂直、基于路径
- 边框自定义:支持多种样式的2D和3D边框
- 图片背景:支持背景图片及多种布局选项
- 自动滚动:内容溢出时自动显示滚动条
- 自动尺寸:根据内容自动调整面板大小
控件类型: 容器控件(继承自 Panel)
程序集:
Syncfusion.Shared.Base.dll命名空间:
Syncfusion.Windows.Forms.ToolsDocumentation 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
背景属性
| Property | Type | Description |
|---|---|---|
| | Sets gradient, pattern, or solid background using BrushInfo |
| | Standard background color (use BackgroundColor for gradients) |
| | Background image for the panel |
| | Layout mode: Stretch, Tile, Center, Zoom |
| 属性 | 类型 | 描述 |
|---|---|---|
| | 通过 BrushInfo 设置渐变、图案或纯色背景 |
| | 标准背景色(渐变请使用 BackgroundColor) |
| | 面板的背景图片 |
| | 布局模式:拉伸、平铺、居中、缩放 |
Border Properties
边框属性
| Property | Type | Description |
|---|---|---|
| | FixedSingle (2D) or Fixed3D (3D borders) |
| | 3D style: Raised, Etched, Sunken, Bump, etc. |
| | 2D style: Solid, Dotted, Dashed, Inset, Outset |
| | Color for 2D borders (requires FixedSingle) |
| | Specifies which sides have borders: All, Top, Bottom, Left, Right |
| 属性 | 类型 | 描述 |
|---|---|---|
| | FixedSingle(2D)或 Fixed3D(3D边框) |
| | 3D样式:凸起、蚀刻、凹陷、凸起凹陷等 |
| | 2D样式:实线、点线、虚线、内凹、外凸 |
| | 2D边框的颜色(需搭配 FixedSingle 使用) |
| | 指定展示边框的边:全部、顶部、底部、左侧、右侧 |
Scroll and Sizing Properties
滚动和尺寸属性
| Property | Type | Description |
|---|---|---|
| | Enable automatic scroll bars when content exceeds panel |
| | Margin width during auto scroll |
| | Minimum logical size for auto scroll region |
| | Automatically size panel based on content |
| | GrowOnly or GrowAndShrink resizing behavior |
| 属性 | 类型 | 描述 |
|---|---|---|
| | 内容超出面板时启用自动滚动条 |
| | 自动滚动时的边距宽度 |
| | 自动滚动区域的最小逻辑尺寸 |
| | 根据内容自动调整面板尺寸 |
| | 仅增长或可增长可收缩的调整行为 |
Text and Font Properties
文本和字体属性
| Property | Type | Description |
|---|---|---|
| | Font style for text in the panel |
| | Color for text and graphics |
| 属性 | 类型 | 描述 |
|---|---|---|
| | 面板中文本的字体样式 |
| | 文本和图形的颜色 |
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
最佳实践
- Use BackgroundColor for gradients - Use with
BackgroundColorfor gradients/patterns, notBrushInfoBackColor - Match border to style - Use FixedSingle for 2D borders, Fixed3D for 3D borders
- Transparent child controls - Set child control to show gradient
BackColor = Color.Transparent - High contrast text - Use contrasting for text visibility over gradients
ForeColor - Consistent gradients - Use similar gradient directions across related panels
- Enable AutoScroll - For panels with many child controls that may exceed size
- BorderColor with FixedSingle - only works with
BorderColorBorderStyle.FixedSingle - PathRectangle for cards - Use or
GradientStyle.PathRectanglefor card-like effectsPathEllipse - Performance - Minimize gradient panels in high-frequency update scenarios
- Designer preview - Use Designer to preview gradients and adjust colors interactively
- 渐变使用 BackgroundColor 设置 - 使用带的
BrushInfo设置渐变/图案,不要使用BackgroundColorBackColor - 边框与样式匹配 - 2D边框使用 FixedSingle,3D边框使用 Fixed3D
- 子控件设置透明 - 将子控件的以显示渐变效果
BackColor = Color.Transparent - 文本高对比度 - 使用对比鲜明的保证渐变背景上的文本可见性
ForeColor - 渐变方向统一 - 相关面板使用相近的渐变方向保持一致性
- 启用自动滚动 - 当面板包含大量可能超出尺寸的子控件时启用
- BorderColor 搭配 FixedSingle 使用 - 仅在
BorderColor模式下生效BorderStyle.FixedSingle - 卡片使用 PathRectangle 渐变 - 使用或
GradientStyle.PathRectangle实现类卡片效果PathEllipse - 性能优化 - 在高频更新的场景中减少渐变面板的使用
- 设计器预览 - 使用 Designer 预览渐变效果,交互式调整颜色
Related Skills
相关技能
- AutoLabel: ../implementing-autolabels/ - Styled labels that complement gradient panels
- Layout Controls: Other container controls for panel-based layouts
- AutoLabel: ../implementing-autolabels/ - 可与渐变面板搭配使用的样式化标签
- 布局控件: 其他用于面板布局的容器控件