syncfusion-winforms-button

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms SfButton

实现Syncfusion Windows Forms SfButton

Welcome to the comprehensive guide for implementing and customizing the Syncfusion Windows Forms SfButton control. SfButton is an advanced button control that provides rich text, image support, extensive customization options, and professional theming capabilities.

欢迎阅读这份关于实现和自定义Syncfusion Windows Forms SfButton控件的完整指南。SfButton是一款高级按钮控件，支持富文本、图片，提供丰富的自定义选项和专业的主题能力。

When to Use This Skill

何时使用本指南

Use this skill whenever you need to:

Create interactive buttons in Windows Forms applications
Display text and images together on buttons
Customize button appearance for different states (hover, pressed, focused, disabled)
Implement rich text formatting in buttons
Apply themes and styling to buttons
Handle button click events and user interactions
Create icon-only or image-only buttons
Show tooltips on button hover
Set Accept or Cancel buttons for forms
Implement animated GIF images in buttons

当你需要完成以下操作时可使用本指南：

在Windows Forms应用中创建可交互按钮
在按钮上同时展示文本和图片
针对不同状态（悬浮、按下、聚焦、禁用）自定义按钮外观
在按钮中实现富文本格式化
为按钮应用主题和样式
处理按钮点击事件和用户交互
创建仅含图标或仅含图片的按钮
按钮悬浮时显示提示信息
为表单设置确认或取消按钮
在按钮中实现动图GIF展示

Component Overview

组件概述

SfButton is an advanced button control superior to the standard Windows Forms Button. Key capabilities include:

Rich Content: Display text, images, rich text, and animated GIFs
State-Based Customization: Customize appearance for hover, pressed, focused, and disabled states
Professional Theming: Built-in Office 2016 themes (Colorful, White, DarkGray, Black)
Text Control: Support for text wrapping, trimming with ellipsis, and rich text formatting
Auto-Sizing: Automatic button resizing based on content
Flexible Positioning: Control image and text alignment, positioning, and spacing
Event Support: Full support for click events, focus handling, and user interactions
Background Customization: Solid colors, gradients, and background images

SfButton是一款优于标准Windows Forms Button的高级按钮控件，核心功能包括：

丰富内容：支持展示文本、图片、富文本和动图GIF
基于状态的自定义：可针对悬浮、按下、聚焦、禁用状态自定义外观
专业主题：内置Office 2016主题（多彩、白色、深灰、黑色）
文本控制：支持文本换行、省略号裁剪和富文本格式化
自动调整大小：根据内容自动调整按钮尺寸
灵活定位：可控制图片和文本的对齐方式、位置和间距
事件支持：全面支持点击事件、焦点处理和用户交互
背景自定义：支持纯色、渐变和背景图片

Documentation Navigation Guide

文档导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Start here to learn:

Assembly dependencies and NuGet installation
Adding SfButton to forms (designer and code)
Basic button setup with text and properties
Handling click events
First working example

📄 阅读： references/getting-started.md

从这里开始你可以学习：

程序集依赖和NuGet安装方法
向表单中添加SfButton（设计器和代码两种方式）
带文本和基础属性的按钮基础设置
处理点击事件
第一个可运行的示例

Button Types & Content

按钮类型与内容

📄 Read: references/button-types-and-content.md

Learn how to create different button styles:

Text and image buttons
Image-only and icon-only buttons
Text and image positioning using TextImageRelation
Image size customization
Rich text support and formatting
Text wrapping and ellipsis trimming
Content alignment (text and image)
Auto-sizing buttons

📄 阅读： references/button-types-and-content.md

学习如何创建不同的按钮样式：

文本和图片按钮
仅图片和仅图标按钮
使用TextImageRelation设置文本和图片的位置关系
图片尺寸自定义
富文本支持和格式化
文本换行和省略号裁剪
内容对齐（文本和图片）
自动调整大小按钮

Appearance & Styling

外观与样式

📄 Read: references/appearance-and-styling.md

Master button styling and customization:

Solid color backgrounds
Gradient brush backgrounds
Background images with layouts
Customizing appearance by button state
Back color and fore color in all states
Image changes in hover, pressed, focused, disabled states
Border customization per state
Focus rectangle visibility
Rounded rectangle button implementation
Animated GIF images

📄 阅读： references/appearance-and-styling.md

掌握按钮样式和自定义方法：

纯色背景
渐变画笔背景
带布局的背景图片
按按钮状态自定义外观
所有状态下的背景色和前景色设置
悬浮、按下、聚焦、禁用状态下的图片切换
按状态自定义边框
聚焦矩形可见性设置
圆角按钮实现
动图GIF支持

Events & Interactions

事件与交互

📄 Read: references/events-and-interactions.md

Implement button interactions:

Click event handling
Setting Accept buttons for forms (ENTER key)
Setting Cancel buttons for forms (ESC key)
Tooltip support with SfToolTip
Focus and keyboard handling

📄 阅读： references/events-and-interactions.md

实现按钮交互功能：

点击事件处理
为表单设置确认按钮（ENTER键触发）
为表单设置取消按钮（ESC键触发）
搭配SfToolTip实现提示框支持
焦点和键盘处理

Quick Start Example

快速入门示例

Here's a minimal example to get started with SfButton:

csharp

using Syncfusion.WinForms.Buttons;
using System.Windows.Forms;

public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();
        
        // Create and configure SfButton
        SfButton sfButton1 = new SfButton();
        sfButton1.Text = "Click Me";
        sfButton1.Font = new System.Drawing.Font("Segoe UI", 10F);
        sfButton1.Location = new System.Drawing.Point(50, 50);
        sfButton1.Size = new System.Drawing.Size(120, 40);
        
        // Add click event
        sfButton1.Click += SfButton1_Click;
        
        // Add to form
        this.Controls.Add(sfButton1);
    }
    
    private void SfButton1_Click(object sender, System.EventArgs e)
    {
        MessageBox.Show("Button clicked!");
    }
}

以下是SfButton的最小可运行示例：

csharp

using Syncfusion.WinForms.Buttons;
using System.Windows.Forms;

public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();
        
        // Create and configure SfButton
        SfButton sfButton1 = new SfButton();
        sfButton1.Text = "Click Me";
        sfButton1.Font = new System.Drawing.Font("Segoe UI", 10F);
        sfButton1.Location = new System.Drawing.Point(50, 50);
        sfButton1.Size = new System.Drawing.Size(120, 40);
        
        // Add click event
        sfButton1.Click += SfButton1_Click;
        
        // Add to form
        this.Controls.Add(sfButton1);
    }
    
    private void SfButton1_Click(object sender, System.EventArgs e)
    {
        MessageBox.Show("Button clicked!");
    }
}

Common Patterns

常用模式

Pattern 1: Button with Image and Text

模式1：带图片和文本的按钮

csharp

sfButton1.Text = "Save";
sfButton1.Image = Image.FromFile(@"save-icon.png");
sfButton1.TextImageRelation = TextImageRelation.ImageBeforeText;
sfButton1.ImageSize = new Size(20, 20);

csharp

sfButton1.Text = "Save";
sfButton1.Image = Image.FromFile(@"save-icon.png");
sfButton1.TextImageRelation = TextImageRelation.ImageBeforeText;
sfButton1.ImageSize = new Size(20, 20);

Pattern 2: Icon-Only Button

模式2：仅图标按钮

csharp

sfButton1.Text = "";  // Empty text
sfButton1.Image = Image.FromFile(@"icon.png");
sfButton1.ImageSize = new Size(24, 24);
sfButton1.Style.BackColor = Color.White;
sfButton1.Style.Border = null;

csharp

sfButton1.Text = "";  // Empty text
sfButton1.Image = Image.FromFile(@"icon.png");
sfButton1.ImageSize = new Size(24, 24);
sfButton1.Style.BackColor = Color.White;
sfButton1.Style.Border = null;

Pattern 3: Button with State-Based Colors

模式3：带状态色的按钮

csharp

sfButton1.Style.BackColor = Color.LightBlue;
sfButton1.Style.ForeColor = Color.Black;
sfButton1.Style.HoverBackColor = Color.Blue;
sfButton1.Style.HoverForeColor = Color.White;
sfButton1.Style.PressedBackColor = Color.DarkBlue;
sfButton1.Style.PressedForeColor = Color.White;

csharp

sfButton1.Style.BackColor = Color.LightBlue;
sfButton1.Style.ForeColor = Color.Black;
sfButton1.Style.HoverBackColor = Color.Blue;
sfButton1.Style.HoverForeColor = Color.White;
sfButton1.Style.PressedBackColor = Color.DarkBlue;
sfButton1.Style.PressedForeColor = Color.White;

Pattern 4: Auto-Sizing Button

模式4：自动调整大小按钮

csharp

sfButton1.Text = "Variable Length Content";
sfButton1.AutoSize = true;  // Auto-adjust to content
sfButton1.Font = new Font("Segoe UI", 11F);

csharp

sfButton1.Text = "Variable Length Content";
sfButton1.AutoSize = true;  // Auto-adjust to content
sfButton1.Font = new Font("Segoe UI", 11F);

Pattern 5: Themed Button

模式5：带主题的按钮

csharp

// In Program.cs Main():
SfSkinManager.LoadAssembly(typeof(Office2016Theme).Assembly);

// In form:
sfButton1.ThemeName = "Office2016Colorful";

csharp

// In Program.cs Main():
SfSkinManager.LoadAssembly(typeof(Office2016Theme).Assembly);

// In form:
sfButton1.ThemeName = "Office2016Colorful";

Key Properties at a Glance

核心属性速览

Property	Type	Purpose
`Text`	string	Button display text
`Image`	Image	Button image/icon
`ImageSize`	Size	Dimensions of displayed image
`TextImageRelation`	TextImageRelation	Position of image relative to text
`TextAlign`	ContentAlignment	Text alignment within button
`ImageAlign`	ContentAlignment	Image alignment within button
`AutoSize`	bool	Auto-fit button to content
`AllowWrapText`	bool	Enable text wrapping
`AutoEllipsis`	bool	Show ellipsis for trimmed text
`AllowRichText`	bool	Enable rich text formatting
`BackgroundImage`	Image	Background fill image
`FocusRectangleVisible`	bool	Show focus indicator rectangle
`ThemeName`	string	Apply built-in theme
`Style`	ButtonVisualStyle	Access appearance customization

属性	类型	用途
`Text`	string	按钮展示文本
`Image`	Image	按钮图片/图标
`ImageSize`	Size	展示图片的尺寸
`TextImageRelation`	TextImageRelation	图片相对于文本的位置
`TextAlign`	ContentAlignment	按钮内文本对齐方式
`ImageAlign`	ContentAlignment	按钮内图片对齐方式
`AutoSize`	bool	按钮自适应内容大小
`AllowWrapText`	bool	启用文本换行
`AutoEllipsis`	bool	文本裁剪时显示省略号
`AllowRichText`	bool	启用富文本格式化
`BackgroundImage`	Image	背景填充图片
`FocusRectangleVisible`	bool	显示聚焦指示矩形
`ThemeName`	string	应用内置主题
`Style`	ButtonVisualStyle	访问外观自定义配置

Common Use Cases

常见使用场景

Save/Submit Button: Text with icon, colored background, hover effects
Icon Toolbar: Image-only buttons arranged in rows
Themed Dialog Buttons: Accept/Cancel with consistent theming
Rich Text Buttons: Formatted text with custom colors
Dynamic Buttons: Buttons that change appearance based on state
Form Control Buttons: Accept button (ENTER), Cancel button (ESC)
Multi-Content Buttons: Text above/below image with custom alignment

保存/提交按钮：带图标文本、彩色背景、悬浮效果
图标工具栏：排列成行的仅图片按钮
带主题的对话框按钮：样式统一的确认/取消按钮
富文本按钮：带自定义颜色的格式化文本按钮
动态按钮：根据状态切换外观的按钮
表单控制按钮：确认按钮（ENTER）、取消按钮（ESC）
多内容按钮：文本在图片上方/下方，支持自定义对齐

Next Steps

后续步骤

✅ Review the Getting Started guide to set up your first SfButton
✅ Choose a button style from Button Types & Content that matches your UI
✅ Apply styling from Appearance & Styling for professional look
✅ Implement interactions from Events & Interactions

✅ 阅读入门指南创建你的第一个SfButton
✅ 从按钮类型与内容中选择符合你UI需求的按钮样式
✅ 参考外观与样式部分应用样式打造专业外观
✅ 参考事件与交互部分实现交互功能

Assembly Dependencies

程序集依赖

Required assemblies for SfButton:

```
Syncfusion.Core.WinForms
```
(Main assembly containing SfButton)
```
Syncfusion.Shared.Base
```
(Shared base library)
```
Syncfusion.Office2016Theme.WinForms
```
(for themes)

See Getting Started reference for detailed NuGet installation instructions.

SfButton所需的程序集：

```
Syncfusion.Core.WinForms
```
（包含SfButton的核心程序集）
```
Syncfusion.Shared.Base
```
（共享基础库）
```
Syncfusion.Office2016Theme.WinForms
```
（主题支持）

查看入门指南参考文档获取详细的NuGet安装说明。