syncfusion-winforms-gradientpanelext

实现 GradientPanelExt

一种增强型 Windows Forms 面板控件，提供渐变背景、圆角、边框元素以及折叠/展开功能，可用于创建精致的容器面板。

何时使用此技能

在以下情况下使用此技能：

• 渐变容器面板：创建带渐变背景、可容纳其他控件的面板
• 圆角面板：设计圆角半径可自定义的现代 UI 面板
• 边框元素：向面板边框添加文本、图像、按钮或控件（独特功能）
• 可折叠区块：实现带动画效果的可展开/折叠面板区块
• 样式化容器：构建带自定义背景、外观精美的容器面板
• 登录/对话框面板：创建带渐变效果的美观登录表单或对话框
• 仪表板区块：设计标题和控件位于边框中的仪表板面板

组件概述

GradientPanelExt 是标准 Panel 控件的增强版本，提供：

• 多种渐变样式（Horizontal、Vertical、Diagonal、PathRectangle、PathEllipse）
• 可配置半径的圆角
• 元素系统——在面板边框中承载文本、图像、折叠控件和 .NET 控件
• 图案和纯色背景选项
• 折叠/展开动画支持
• 多色渐变支持
• 可作为其他 WinForms 控件的容器

主要功能：

• 使用 BrushInfo 类设置渐变背景
• 使用 CornerRadius 创建圆角矩形外观
• 元素集合（CollapsePrimitive、ImagePrimitive、TextPrimitive、HostPrimitive）
• 使用 BorderGap 控制间距
• 可设置速度和延迟的折叠/展开动画
• 支持背景图像
• 像标准 Panel 一样承载子控件

独特功能——元素： GradientPanelExt 最强大的功能是能够在面板边框中添加“元素”——文本标签、图像、折叠按钮，甚至是放置在顶部、底部、左侧或右侧边框中的完整 .NET 控件。

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 开始新的实现、设置依赖项或首次使用时

涵盖主题：

• 程序集部署（Syncfusion.Shared.Base）
• NuGet 包安装
• 通过 Visual Studio 设计器添加（从工具箱拖放）
• 通过代码添加（手动实例化）
• 基本面板初始化和配置
• 向面板添加子控件
• PrimitiveCollection 编辑器简介
• 简单的渐变面板示例
• 命名空间要求（Syncfusion.Windows.Forms.Tools）

---

背景样式

📄 阅读： references/background-styling.md

阅读时机： 配置渐变、设置背景颜色或自定义面板外观时

涵盖主题：

• BackgroundColor 属性和 BrushInfo 类
• 背景样式（Solid、Pattern、Gradient、None）
• 渐变样式（Horizontal、Vertical、ForwardDiagonal、BackwardDiagonal、PathRectangle、PathEllipse）
• BackColor 和 ForeColor 属性
• 使用 GradientColors 数组设置多色渐变
• 使用 PatternStyle 设置图案背景
• BackgroundImage 和 BackgroundImageLayout
• 创建复杂的颜色过渡
• 包含代码的完整样式示例

---

边框与圆角设置

📄 阅读： references/border-corner-settings.md

阅读时机： 自定义圆角、调整边框外观或创建圆角面板时

涵盖主题：

• 用于设置圆角的 CornerRadius 属性
• 移除圆角（CornerRadius = 0）
• 用于设置边距的 BorderGap 属性
• 锐角与圆角设计
• 协调圆角与渐变效果
• 不同半径值的完整示例
• 现代与经典设计的最佳实践

---

基元

📄 阅读： references/primitives.md

适合阅读的场景： 添加边框元素、实现折叠功能、在边框中承载控件

涵盖主题：

• 基元概览和 PrimitiveCollection 编辑器
• CollapsePrimitive（使用图像展开/折叠）
• ImagePrimitive（边框中的图像）
• TextPrimitive（边框中的文本标签）
• HostPrimitive（在边框中承载 .NET 控件）
• Alignment 属性（Top、Bottom、Left、Right）
• 用于像素定位的 Position 属性
• 用于设置基元尺寸的 Size 属性
• 包含所有基元类型的完整示例
• 使用基元的登录面板示例

---

折叠和展开动画

📄 阅读： references/collapse-expand-animation.md

适合阅读的场景： 实现动画折叠、配置动画行为

涵盖主题：

• Animated 属性（启用/禁用动画）
• 用于设置计时的 AnimationDelay 属性
• 用于控制速度的 AnimationSpeed 属性
• 与 CollapsePrimitive 集成
• 平滑折叠与即时折叠行为
• 完整动画示例
• 性能注意事项

---

滚动设置和事件

📄 阅读： references/scroll-settings-events.md

适合阅读的场景： 处理可滚动内容、响应事件、自定义事件处理

涵盖主题：

• 用于可滚动面板的 AutoScroll 属性
• 滚动条配置
• GradientPanelExt 专属事件
• 折叠/展开事件处理
• 基元单击事件
• 用于自定义绘制的 Paint 事件
• 完整事件处理程序示例
• 内存管理和清理

---

快速入门

基本渐变面板设置

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

// Create GradientPanelExt
GradientPanelExt gradientPanel = new GradientPanelExt();
gradientPanel.Size = new Size(400, 200);
gradientPanel.Location = new Point(20, 20);

// Set gradient background (horizontal blue gradient)
gradientPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.DarkBlue,
    Color.LightSkyBlue
);

// Rounded corners
gradientPanel.CornerRadius = 10;

// Add child controls
Label label = new Label
{
    Text = "Welcome",
    ForeColor = Color.White,
    BackColor = Color.Transparent,
    Location = new Point(20, 20),
    AutoSize = true
};
gradientPanel.Controls.Add(label);

// Add to form
this.Controls.Add(gradientPanel);

在边框中使用基元

// Add title text primitive at top border
TextPrimitive titlePrimitive = new TextPrimitive
{
    Text = "User Login",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.White,
    TextFont = new Font("Arial", 12, FontStyle.Bold),
    Size = new Size(100, 25),
    BackColor = Color.Transparent
};

// Add button primitives at bottom border
TextPrimitive okButton = new TextPrimitive
{
    Text = "OK",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 100,
    Size = new Size(60, 25),
    BackColor = Color.White,
    TextColor = Color.Black
};

TextPrimitive cancelButton = new TextPrimitive
{
    Text = "Cancel",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 180,
    Size = new Size(60, 25),
    BackColor = Color.White,
    TextColor = Color.Black
};

// Add primitives to panel
gradientPanel.Primitives.AddRange(new Primitive[] { 
    titlePrimitive, 
    okButton, 
    cancelButton 
});

常见模式

模式 1：带渐变和基元的登录面板

// Create login panel
GradientPanelExt loginPanel = new GradientPanelExt
{
    Size = new Size(350, 180),
    Location = new Point(50, 50),
    CornerRadius = 12
};

// Dark gradient background
loginPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Horizontal,
    Color.FromArgb(40, 40, 40),
    Color.FromArgb(80, 80, 80)
);

// Title primitive at top
TextPrimitive title = new TextPrimitive
{
    Text = "Login",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.White,
    TextFont = new Font("Segoe UI", 14, FontStyle.Bold),
    Size = new Size(80, 30),
    BackColor = Color.Transparent
};
loginPanel.Primitives.Add(title);

// Add username and password textboxes inside panel
Label lblUsername = new Label
{
    Text = "Username:",
    Location = new Point(30, 40),
    ForeColor = Color.White,
    BackColor = Color.Transparent,
    AutoSize = true
};

TextBox txtUsername = new TextBox
{
    Location = new Point(110, 38),
    Size = new Size(180, 20)
};

loginPanel.Controls.Add(lblUsername);
loginPanel.Controls.Add(txtUsername);

模式 2：可折叠的仪表板区块

// Create collapsible panel
GradientPanelExt dashboardPanel = new GradientPanelExt
{
    Size = new Size(400, 250),
    Location = new Point(20, 20),
    CornerRadius = 8,
    Animated = true,
    AnimationSpeed = 3
};

// Vertical gradient
dashboardPanel.BackgroundColor = new BrushInfo(
    GradientStyle.Vertical,
    Color.WhiteSmoke,
    Color.LightGray
);

// Section title
TextPrimitive sectionTitle = new TextPrimitive
{
    Text = "Sales Statistics",
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    TextColor = Color.DarkBlue,
    TextFont = new Font("Arial", 12, FontStyle.Bold),
    Size = new Size(150, 25)
};

// Collapse primitive
CollapsePrimitive collapseButton = new CollapsePrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    Position = 350,
    Size = new Size(30, 30),
    BackColor = Color.Transparent
};
// Set images in designer or load from resources

dashboardPanel.Primitives.AddRange(new Primitive[] { 
    sectionTitle, 
    collapseButton 
});

模式 3：带图像和 HostPrimitive 的面板

// Create styled panel
GradientPanelExt styledPanel = new GradientPanelExt
{
    Size = new Size(450, 300),
    CornerRadius = 10
};

// PathEllipse gradient with multiple colors
styledPanel.BackgroundColor = new BrushInfo(
    GradientStyle.PathEllipse,
    new Color[]
    {
        Color.LightBlue,
        Color.LightCyan,
        Color.PaleTurquoise
    }
);

// Image primitive at top-left
ImagePrimitive logo = new ImagePrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Top,
    Position = 10,
    Size = new Size(40, 40)
    // Set Image property from resources
};

// Host a ProgressBar at bottom
ProgressBar progressBar = new ProgressBar
{
    Value = 50,
    Style = ProgressBarStyle.Continuous
};

HostPrimitive progressHost = new HostPrimitive
{
    Alignment = Syncfusion.Windows.Forms.Tools.Alignment.Bottom,
    Position = 100,
    Size = new Size(250, 20),
    HostControl = progressBar,
    BackColor = Color.Transparent
};

styledPanel.Primitives.AddRange(new Primitive[] { 
    logo, 
    progressHost 
});

关键属性

背景属性

• BackgroundColor：使用 BrushInfo 获取/设置背景（样式、颜色、渐变）
• BackgroundColor.Style：画刷样式（Solid、Pattern、Gradient、None）
• BackgroundColor.GradientStyle：渐变方向（Horizontal、Vertical、ForwardDiagonal、BackwardDiagonal、PathRectangle、PathEllipse）
• BackgroundColor.BackColor：渐变起始颜色
• BackgroundColor.ForeColor：渐变结束颜色
• BackgroundColor.PatternStyle：Pattern 画刷样式的图案
• BackgroundColor.GradientColors：多色渐变的数组
• BackgroundImage：面板的背景图像
• BackgroundImageLayout：背景图像的布局样式

边框和圆角属性

• CornerRadius：圆角半径（0 = 直角）
• BorderGap：边框与边距之间的间隔

基元属性

• Primitives：基元集合（通过 PrimitiveCollection 编辑器访问）
• Primitive.Alignment：边框位置（Top、Bottom、Left、Right）
• Primitive.Position：沿边框的像素偏移量
• Primitive.Size：基元的宽度和高度
• Primitive.BackColor：基元的背景颜色

动画属性

• Animated：启用/禁用折叠动画
• AnimationDelay：动画延迟时间，单位为毫秒
• AnimationSpeed：动画速度因子

容器属性（继承自 Panel）

• Controls：面板中承载的子控件集合
• AutoScroll：为溢出内容启用滚动条
• Padding：子控件的内部边距

常见用例

登录/身份验证面板

使用渐变背景、边框中的标题和按钮基元，创建美观的登录表单。

仪表板区块

构建在顶部边框显示区块标题并支持折叠功能的仪表板面板。

设置面板

设计带有类别标题和有序控件组的设置容器。

信息框

创建带有边框图标和丰富内容的样式化信息面板。

向导步骤

实现带有步骤编号或边框图标的向导步骤面板。

分组控件

将相关表单控件组织到视觉上区分明显的渐变面板中。

可折叠侧边栏

使用折叠基元创建可展开的侧边栏面板，以便管理空间。

备注

• GradientPanelExt 派生自 Panel，因此可使用 Panel 的所有标准功能
• Primitives 功能是 GradientPanelExt 独有的，功能非常强大
• 基元位于边框中，而不在主面板区域内
• CornerRadius 默认会创建圆角（设为 0 可使用直角）
• 子控件与普通 Panel 一样添加到 Controls 集合中
• CollapsePrimitive 必须设置折叠和展开图像
• HostPrimitive 可承载任何 .NET 控件，包括自定义控件
• 仅在使用 CollapsePrimitive 时，动画属性才会影响折叠/展开
• BackgroundColor 和 Primitives 可以使用相同或协调的渐变
• 对于常见用法，性能良好；请避免使用过多基元