ButtonEx 按钮控件

控件名称

ButtonEx

中文名称

按钮控件

控件优点

ButtonEx 是一个功能丰富的按钮控件，支持多种形状、颜色类型、SVG图标、悬停效果等功能。适用于表单提交、操作触发、导航跳转等场景。

主要特性

多种形状：支持默认、圆形、圆角矩形等多种形状
颜色类型：支持默认、主要、成功、警告、错误、信息等多种颜色类型（使用 Ant Design 功能色）
SVG图标：支持SVG图标显示和旋转
图标位置：支持多种图标位置
悬停效果：支持悬停和按下状态的颜色变化
主题支持：实现 IThemeable 接口，支持亮暗主题自动切换（FollowGlobalTheme 属性）
数据绑定：实现 INotifyPropertyChanged 接口

重要参数说明

基本属性

属性名	类型	默认值	说明
`Text`	string	""	按钮文本
`Shape`	ButtonShape	Default	按钮形状
`CornerRadius`	int	6	圆角半径（Shape=Default时生效）
`Type`	ColorType	Default	颜色类型
`Enabled`	bool	true	是否可用

按钮形状（ButtonShape）

形状值	说明
`Default`	默认圆角矩形
`Circle`	圆形
`Round`	完全圆角矩形

圆角半径（CornerRadius）

属性名	类型	默认值	说明
`CornerRadius`	int	6	圆角半径，仅当Shape=Default时生效。0表示使用自动计算（高度一半或15像素取小值）

颜色类型（ColorType）

类型值	说明	颜色值
`Default`	默认	#018b8d (马尔斯绿)
`Primary`	主要	#1890ff (Ant Design 品牌主色)
`Success`	成功	#52c41a (Ant Design 成功色)
`Warning`	警告	#faad14 (Ant Design 警告色)
`Error`	错误	#f5222d (Ant Design 错误色)
`Info`	信息	#1890ff (Ant Design 链接色)

流行色系（11种）

类型值	说明	颜色值	特性
`BurgundyRed`	勃艮第红	#470125	高贵、优雅、感性
`KleinBlue`	克莱因蓝	#002fa7	希望、自由、理智
`MarsGreen`	马尔斯绿	#018b8d	奢华、神秘、力量
`TitianRed`	提香红	#d34947	典雅、艺术、理智
`HermesOrange`	爱马仕橙	#eb5c20	活力、时尚、温暖
`LimeGreen`	莱姆绿	#6ecc54	生机、自然、平衡
`PrussianBlue`	普鲁士蓝	#0d3a69	绅士、优雅、内敛
`VanDykeBrown`	凡戴克棕	#492d22	权力、深沉、厚重
`ChineseRed`	中国红	#c8161d	热情、福禄、高贵
`TiffanyBlue`	蒂芙尼蓝	#71e2d1	清澈、自由、浪漫
`SchonbrunnerYellow`	申布伦黄	#f9d46c	奢华、阳光、明亮

颜色属性

属性名	类型	默认值	说明
`ShellColor`	Color	240, 240, 240	外壳颜色
`ButtonColor`	Color	1, 139, 141 (#018b8d)	按钮颜色（Type=Default时生效，默认马尔斯绿）
`BorderColor`	Color	1, 139, 141 (#018b8d)	边框颜色（Type=Default时生效，默认马尔斯绿）
`HoverColor`	Color	26, 164, 166	悬停颜色（Type=Default时自动基于ButtonColor变亮）
`PressedColor`	Color	0, 111, 113	按下颜色（Type=Default时自动基于ButtonColor变暗）
`PressedBorderColor`	Color	0, 111, 113	按下边框颜色

图标属性

属性名	类型	默认值	说明
`IconSvgName`	string	"windows"	SVG图标名称
`IconSvgColor`	Color?	null	图标颜色（null自动跟随按钮文字颜色）
`IconSvgRotation`	float	0	图标旋转角度
`IconPosition`	IconPosition	Left	图标位置
`IconSize`	int	0	图标大小（0自动）
`IconGap`	float	0.2f	图标与文本间距比例

图标颜色自动跟随规则

当 IconSvgColor 为 null 时，图标颜色会自动跟随文本颜色：

按钮类型	图标颜色
`Primary` / `Success` / `Warning` / `Error` / `Info`	白色
深色背景流行色（除蒂芙尼蓝、申布伦黄外）	白色
浅色背景流行色（蒂芙尼蓝、申布伦黄）	黑色
`Default`	根据背景色亮度自动计算（深色背景用白色，浅色背景用黑色）

图标位置（IconPosition）

位置值	说明
`Left`	左侧
`Right`	右侧
`Top`	顶部
`Bottom`	底部

显示样式（DisplayStyle）

样式值	说明
`Default`	图片+文本（默认）
`ImageOnly`	仅图片
`TextOnly`	仅文本

幽灵按钮

属性名	类型	默认值	说明
`Ghost`	bool	false	幽灵按钮，背景透明只显示边框

箭头

属性名	类型	默认值	说明
`ShowArrow`	bool	false	显示箭头
`IsLink`	bool	false	箭头链接样式（右箭头）

自动大小

属性名	类型	默认值	说明
`AutoSize`	bool	false	自动调整大小
`AutoSizeMode`	AutoSizeMode	None	自动大小模式

AutoSizeMode 枚举

值	说明
`None`	禁用自动大小
`Auto`	宽度和高度都自动调整
`Width`	仅宽度自动调整
`Height`	仅高度自动调整

Toggle 切换功能

属性名	类型	默认值	说明
`AutoToggle`	bool	false	点击时自动改变选中状态
`Toggle`	bool	false	选中状态
`ToggleIconSvgName`	string?	null	切换图标SVG名称
`ToggleIconSvgNameHover`	string?	null	切换悬停图标SVG名称
`IconToggleAnimation`	int	200	图标切换动画时长（毫秒）
`ToggleFore`	Color?	null	切换文字颜色
`ToggleForeHover`	Color?	null	切换悬停文字颜色
`ToggleForeActive`	Color?	null	切换激活文字颜色
`ToggleType`	ButtonToggleType	None	切换类型
`ToggleBack`	Color?	null	切换背景颜色
`ToggleBackExtend`	string?	null	切换背景渐变色
`ToggleBackHover`	Color?	null	切换悬停背景颜色
`ToggleBackActive`	Color?	null	切换激活背景颜色

ButtonToggleType 枚举（可选）

注意：只要设置了 ToggleIconSvgName 或 ToggleBack/ToggleBackActive，切换功能就会自动生效，ToggleType 属性主要用于向后兼容。

值	说明
`None`	无切换
`Icon`	仅图标切换
`Background`	背景色切换
`IconAndBackground`	图标+背景切换

其他属性

属性名	类型	默认值	说明
`Gap`	int	0	按键体与外壳间隙

主题属性

属性名	类型	默认值	说明
`FollowGlobalTheme`	bool	true	是否跟随全局主题（亮暗模式切换）
`IsDark`	bool	false	只读，当前是否为暗色模式

主题说明：ButtonEx 实现 IThemeable 接口，构造时自动注册到 ThemeManager。当 FollowGlobalTheme = true 时，主题切换会自动保存用户原始颜色并在暗色模式下调整背景色/文字色。用户手动设置的颜色（ButtonColor、BorderColor 等）会被标记，主题切换时不会覆盖用户自定义颜色。

重要事件

事件名	说明
`Click`	点击时触发
`PropertyChanged`	属性值改变时触发
`ToggleChanged`	Toggle 状态改变时触发（参数 bool 表示新状态）

使用示例

基本使用

// 创建按钮
ButtonEx button = new ButtonEx();
button.Text = "点击我";
button.Size = new Size(120, 40);
this.Controls.Add(button);

// 点击事件
button.Click += (sender, e) =>
{
    MessageBox.Show("按钮被点击！");
};

不同形状

// 默认形状
button1.Shape = ButtonShape.Default;

// 圆形按钮
button2.Shape = ButtonShape.Circle;
button2.Size = new Size(60, 60);

// 完全圆角矩形
button3.Shape = ButtonShape.Round;

自定义圆角半径

// 设置圆角半径为10像素
button1.CornerRadius = 10;

// 设置圆角半径为0（直角矩形，使用自动计算）
button2.CornerRadius = 0;

颜色类型（Ant Design 功能色）

// 默认类型 - #018b8d（马尔斯绿）
button1.Type = ColorType.Default;

// 主要类型 - #1890ff
button2.Type = ColorType.Primary;

// 成功类型 - #52c41a
button3.Type = ColorType.Success;

// 警告类型 - #faad14
button4.Type = ColorType.Warning;

// 错误类型 - #f5222d
button5.Type = ColorType.Error;

// 信息类型 - #1890ff
button6.Type = ColorType.Info;

流行色系（11种）

// 勃艮第红 - #470125
button.Type = ColorType.BurgundyRed;

// 克莱因蓝 - #002fa7
button.Type = ColorType.KleinBlue;

// 马尔斯绿 - #018b8d
button.Type = ColorType.MarsGreen;

// 提香红 - #d34947
button.Type = ColorType.TitianRed;

// 爱马仕橙 - #eb5c20
button.Type = ColorType.HermesOrange;

// 莱姆绿 - #6ecc54
button.Type = ColorType.LimeGreen;

// 普鲁士蓝 - #0d3a69
button.Type = ColorType.PrussianBlue;

// 凡戴克棕 - #492d22
button.Type = ColorType.VanDykeBrown;

// 中国红 - #c8161d
button.Type = ColorType.ChineseRed;

// 蒂芙尼蓝 - #71e2d1（浅色背景，使用黑色文字）
button.Type = ColorType.TiffanyBlue;

// 申布伦黄 - #f9d46c（浅色背景，使用黑色文字）
button.Type = ColorType.SchonbrunnerYellow;

图标按钮

// 带图标的按钮
button.IconSvgName = "search";
button.IconPosition = IconPosition.Left;
button.IconSize = 20;

// 仅图标按钮
button.DisplayStyle = ButtonDisplayStyle.ImageOnly;
button.IconSvgName = "home";
button.Size = new Size(40, 40);

// 旋转图标
button.IconSvgRotation = 45f;

图标颜色自动跟随

// 不设置 IconSvgColor（保持null）时，图标颜色会自动跟随按钮类型：

// Primary/Success/Warning/Error/Info 类型 → 图标为白色
button.Type = ColorType.Primary;
button.IconSvgName = "play";  // 图标显示为白色

button.Type = ColorType.Warning;
button.IconSvgName = "warning";  // 图标显示为白色

// Default 类型 → 图标使用 ForeColor（默认黑色）
button.Type = ColorType.Default;
button.IconSvgName = "setting";  // 图标显示为 ForeColor 颜色

// 如需自定义图标颜色，可显式设置 IconSvgColor：
button.Type = ColorType.Primary;
button.IconSvgName = "star";
button.IconSvgColor = Color.Yellow;  // 强制显示黄色图标

自定义颜色（Type=Default时生效）

// 设置颜色
button.Type = ColorType.Default;
button.ShellColor = Color.LightGray;
button.ButtonColor = Color.White;
button.BorderColor = Color.Gray;
button.HoverColor = Color.LightBlue;
button.PressedColor = Color.Blue;

图标位置

// 图标在左侧（默认）
button.IconPosition = IconPosition.Left;

// 图标在右侧
button.IconPosition = IconPosition.Right;

// 图标在顶部
button.IconPosition = IconPosition.Top;

// 图标在底部
button.IconPosition = IconPosition.Bottom;

数据绑定

// 属性改变事件
button.PropertyChanged += (sender, e) =>
{
    Console.WriteLine($"属性 {e.PropertyName} 已更改");
};

幽灵按钮（Ghost）

// 幽灵按钮 - 背景透明，显示边框
button.Ghost = true;
button.Type = ColorType.Primary;

// 幽灵链接样式 - 带下划线
button.Ghost = true;
button.IsLink = true;

箭头按钮

// 下拉箭头按钮
button.ShowArrow = true;

// 链接箭头按钮（右箭头）
button.ShowArrow = true;
button.IsLink = true;

自动大小

// 启用自动大小
button.AutoSize = true;
button.AutoSizeMode = AutoSizeMode.Auto;  // 宽高都自动

// 仅宽度自动
button.AutoSize = true;
button.AutoSizeMode = AutoSizeMode.Width;

Toggle 切换按钮

// 自动切换按钮
button.AutoToggle = true;
button.ToggleChanged += (sender, isToggled) =>
{
    Console.WriteLine($"切换状态: {isToggled}");
};

// 图标切换（设置 ToggleIconSvgName 即可自动切换图标）
button.AutoToggle = true;
button.IconSvgName = "heart-o";      // 未选中图标
button.ToggleIconSvgName = "heart";  // 选中图标

// 背景色切换（设置 ToggleBack 或 ToggleBackActive）
button.AutoToggle = true;
button.ToggleBackActive = Color.Red;  // 选中时的背景色

// 图标+背景同时切换
button.AutoToggle = true;
button.IconSvgName = "star-o";
button.ToggleIconSvgName = "star";
button.ToggleBackActive = Color.Yellow;

显示样式

// 仅文本
button.DisplayStyle = ButtonDisplayStyle.TextOnly;

// 仅图标
button.DisplayStyle = ButtonDisplayStyle.ImageOnly;

// 图文（默认）
button.DisplayStyle = ButtonDisplayStyle.Default;

注意事项

形状选择：不同形状需要调整控件尺寸以保证显示效果
颜色类型：Type 属性会覆盖 ButtonColor、HoverColor、PressedColor 设置
图标大小：IconSize 为 0 时会自动计算合适大小（按钮高度的70%）
显示样式：DisplayStyle 为 ImageOnly 时只显示图标，TextOnly 时只显示文本
Ant Design 颜色：Primary、Success、Warning、Error、Info 类型使用 AntDesignColors 类中定义的颜色值
圆角半径：CornerRadius 仅在 Shape=Default 时生效，设置为0时使用自动计算（高度一半或15像素取小值）
禁用状态：Enabled 为 false 时按钮不可点击，鼠标悬停显示禁用样式（Cursor.No）

版本更新

2026-08-08

新增：实现 IThemeable 接口，支持 FollowGlobalTheme 属性（默认 true），自动跟随全局亮暗主题切换
新增：构造函数自动注册到 ThemeManager，Dispose 时自动注销
新增：用户手动设置颜色时自动标记（_isButtonColorSetByUser 等），主题切换不覆盖用户自定义颜色
新增：多框架兼容支持（net8.0-windows 和 net48）
优化：暗色模式下自动调整背景色和文字色，确保可读性

2025-05-28

新增：11种流行色系（勃艮第红、克莱因蓝、马尔斯绿、提香红、爱马仕橙、莱姆绿、普鲁士蓝、凡戴克棕、中国红、蒂芙尼蓝、申布伦黄）
修复：默认类型（Type=Default）背景色改为马尔斯绿（#018b8d）
修复：图标颜色自动跟随文本颜色，确保与背景色形成对比
修复：Type=Default 时悬停和按下状态颜色基于背景色动态计算（变亮/变暗15%）
修复：Type=Default 时文本颜色根据背景色亮度自动计算对比色
修复：主题切换时不再重置用户自定义的颜色设置

2025-05-02

新增：CornerRadius 属性，支持自定义圆角半径（默认值为6）