syncfusion-winforms-splitbutton

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Split Buttons

SplitButton 实现指南

When to Use This Skill

何时使用本指南

Use this skill when users need to implement Syncfusion SplitButton control in WinForms applications. This control is ideal for:

Button-Dropdown Hybrid: Creating controls that combine a primary button action with a dropdown menu of related options
Command Variations: Providing a default action with alternative variations (e.g., Save with Save As, Send options)
Toggle with Options: Implementing toggle buttons that also provide dropdown menu choices
Dynamic Button Text: Updating button caption based on user selection from dropdown items
Office-Style UI: Building interfaces that match Microsoft Office split button patterns
Custom Rendered Buttons: Creating fully customized button appearances using ISplitButtonRenderer

The SplitButton control provides two button modes (Normal and Toggle), dynamic caption management, built-in Office2016 themes, and extensive customization through custom renderers.

当你需要在WinForms应用中实现Syncfusion SplitButton控件时可以使用本指南。该控件非常适合以下场景：

按钮下拉混合控件：创建兼具主按钮操作功能和相关选项下拉菜单的控件
多命令变体：提供默认操作和可选的替代操作（例如保存功能搭配另存为、发送选项等）
带选项的切换按钮：实现同时支持下拉菜单选择的切换按钮
动态按钮文本：根据用户从下拉项中选择的内容更新按钮标题
Office风格UI：搭建符合Microsoft Office拆分按钮设计规范的界面
自定义渲染按钮：使用ISplitButtonRenderer实现完全自定义的按钮外观

SplitButton控件提供两种按钮模式（普通模式Normal和切换模式Toggle）、动态标题管理能力、内置Office2016主题，还支持通过自定义渲染器实现高度定制。

Component Overview

组件概览

The SplitButton control is a hybrid control that behaves like a button with an integrated dropdown menu. When clicked on the button portion, it executes a primary action. When clicked on the dropdown arrow, it displays a menu of additional options. This pattern is commonly seen in applications like Microsoft Word (Save/Save As) or Outlook (Reply/Reply All).

Key Capabilities:

Two button modes: Normal (standard click) and Toggle (checked/unchecked state)
DropDown items management (Add/Remove items dynamically)
Static or dynamic button captions (set text or use selected dropdown item as caption)
Six built-in visual styles: Office2016White, Office2016Black, Office2016DarkGray, Office2016Colorful, Metro, Default
ISplitButtonRenderer interface for complete button customization
ToolStripProfessionalRenderer for dropdown items appearance customization
DropDownItemClicked event for handling item selection

SplitButton控件是一种混合控件，功能相当于集成了下拉菜单的按钮：点击按钮区域时会执行主操作，点击下拉箭头时会展示更多选项菜单。这种模式常见于Microsoft Word（保存/另存为）、Outlook（回复/全部回复）等应用中。

核心能力：

两种按钮模式：普通模式（标准点击操作）和切换模式（选中/未选中状态）
下拉项管理（可动态添加/移除项）
静态或动态按钮标题（可设置固定文本，也可将选中的下拉项文本作为标题）
6种内置视觉样式：Office2016White、Office2016Black、Office2016DarkGray、Office2016Colorful、Metro、Default
支持ISplitButtonRenderer接口，可对按钮进行完全自定义
支持ToolStripProfessionalRenderer，可自定义下拉项的外观
提供DropDownItemClicked事件，可用于处理选项选择操作

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Read this first for basic setup and implementation:

Assembly references and NuGet package installation
Adding SplitButton through Designer (drag and drop from toolbox)
Adding SplitButton through Code (programmatic creation)
Adding and removing dropdown items using DropDownItems collection
Basic configuration and minimal working examples

📄 阅读： references/getting-started.md

请首先阅读本文 完成基础配置和实现，内容包括：

程序集引用和NuGet包安装
通过设计器添加SplitButton（从工具箱拖拽）
通过代码添加SplitButton（编程创建）
使用DropDownItems集合添加和移除下拉项
基础配置和最小可运行示例

Button Modes and States

按钮模式与状态

📄 Read: references/button-modes.md

Use when users need different button behaviors:

Normal mode for standard button click actions
Toggle mode for checked/unchecked state buttons
ButtonMode property configuration (Normal vs Toggle)
IsButtonChecked property for controlling toggle state
Mode-specific click events and state management

📄 阅读： references/button-modes.md

当你需要实现不同的按钮行为时可阅读本文：

普通模式：用于标准按钮点击操作
切换模式：用于需要选中/未选中状态的按钮
ButtonMode属性配置（普通模式vs切换模式）
IsButtonChecked属性：用于控制切换状态
模式专属的点击事件和状态管理

Button Caption Management

按钮标题管理

📄 Read: references/button-caption.md

Use when users need to:

Set static button text using Text property
Update button caption dynamically from dropdown item selection
Handle DropDownItemClicked event to update caption
Display selected item text as button label

📄 阅读： references/button-caption.md

当你需要实现以下需求时可阅读本文：

使用Text属性设置静态按钮文本
根据选中的下拉项动态更新按钮标题
处理DropDownItemClicked事件更新标题
将选中项的文本展示为按钮标签

Visual Styles and Theming

视觉样式与主题

📄 Read: references/visual-styles.md

Use when users want to:

Apply built-in Office2016 themes (White, Black, DarkGray, Colorful)
Use Metro or Default visual styles
Match button appearance to application theme
Set Style or ThemeName properties

📄 阅读： references/visual-styles.md

当你需要实现以下需求时可阅读本文：

应用内置的Office2016主题（白色、黑色、深灰、多彩）
使用Metro或Default视觉样式
让按钮外观和应用主题匹配
设置Style或ThemeName属性

Advanced Customization

高级自定义

📄 Read: references/advanced-customization.md

Use when users require:

Custom button rendering using ISplitButtonRenderer interface
Custom border, text, or arrow drawing (DrawBorder, DrawText, DrawArrow methods)
Dropdown items appearance customization using DropDownRenderer
Custom ToolStripProfessionalRenderer implementation
Override methods: OnRenderItemText, OnRenderImageMargin, OnRenderItemImage, OnRenderToolStripBackground, OnRenderToolStripBorder

📄 阅读： references/advanced-customization.md

当你需要实现以下需求时可阅读本文：

使用ISplitButtonRenderer接口自定义按钮渲染
自定义边框、文本或箭头绘制（DrawBorder、DrawText、DrawArrow方法）
使用DropDownRenderer自定义下拉项外观
自定义ToolStripProfessionalRenderer实现
重写方法：OnRenderItemText、OnRenderImageMargin、OnRenderItemImage、OnRenderToolStripBackground、OnRenderToolStripBorder

Quick Start Example

快速开始示例

Here's a minimal example showing how to create a SplitButton with dropdown items:

Designer Approach:

Drag SplitButton from toolbox to form
Set
```
Text
```
property to "Actions"
Use
```
DropDownItems
```
property editor to add items
Set
```
Style
```
property to "Office2016Colorful"

Code Approach (C#):

csharp

using Syncfusion.Windows.Forms.Tools;

// Create SplitButton
SplitButton splitButton = new SplitButton();
splitButton.Text = "Save";
splitButton.Size = new Size(120, 40);
splitButton.Location = new Point(20, 20);
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful;

// Add dropdown items
ToolStripMenuItem saveItem = new ToolStripMenuItem("Save");
ToolStripMenuItem saveAsItem = new ToolStripMenuItem("Save As...");
ToolStripMenuItem saveAllItem = new ToolStripMenuItem("Save All");

splitButton.DropDownItems.Add(saveItem);
splitButton.DropDownItems.Add(saveAsItem);
splitButton.DropDownItems.Add(saveAllItem);

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

Code Approach (VB.NET):

Imports Syncfusion.Windows.Forms.Tools

' Create SplitButton
Dim splitButton As New SplitButton()
splitButton.Text = "Save"
splitButton.Size = New Size(120, 40)
splitButton.Location = New Point(20, 20)
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful

' Add dropdown items
Dim saveItem As New ToolStripMenuItem("Save")
Dim saveAsItem As New ToolStripMenuItem("Save As...")
Dim saveAllItem As New ToolStripMenuItem("Save All")

splitButton.DropDownItems.Add(saveItem)
splitButton.DropDownItems.Add(saveAsItem)
splitButton.DropDownItems.Add(saveAllItem)

' Add to form
Me.Controls.Add(splitButton)

以下是创建带下选项的SplitButton的最小示例：

设计器实现方式：

从工具箱拖拽SplitButton到窗体
将
```
Text
```
属性设置为"Actions"
使用
```
DropDownItems
```
属性编辑器添加选项
将
```
Style
```
属性设置为"Office2016Colorful"

代码实现方式（C#）：

csharp

using Syncfusion.Windows.Forms.Tools;

// Create SplitButton
SplitButton splitButton = new SplitButton();
splitButton.Text = "Save";
splitButton.Size = new Size(120, 40);
splitButton.Location = new Point(20, 20);
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful;

// Add dropdown items
ToolStripMenuItem saveItem = new ToolStripMenuItem("Save");
ToolStripMenuItem saveAsItem = new ToolStripMenuItem("Save As...");
ToolStripMenuItem saveAllItem = new ToolStripMenuItem("Save All");

splitButton.DropDownItems.Add(saveItem);
splitButton.DropDownItems.Add(saveAsItem);
splitButton.DropDownItems.Add(saveAllItem);

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

代码实现方式（VB.NET）：

Imports Syncfusion.Windows.Forms.Tools

' Create SplitButton
Dim splitButton As New SplitButton()
splitButton.Text = "Save"
splitButton.Size = New Size(120, 40)
splitButton.Location = New Point(20, 20)
splitButton.Style = SplitButtonVisualStyle.Office2016Colorful

' Add dropdown items
Dim saveItem As New ToolStripMenuItem("Save")
Dim saveAsItem As New ToolStripMenuItem("Save As...")
Dim saveAllItem As New ToolStripMenuItem("Save All")

splitButton.DropDownItems.Add(saveItem)
splitButton.DropDownItems.Add(saveAsItem)
splitButton.DropDownItems.Add(saveAllItem)

' Add to form
Me.Controls.Add(splitButton)

Common Patterns

常用模式

Pattern 1: Dynamic Caption from Selected Item

模式1：根据选中项动态设置标题

Update button text when user selects a dropdown item:

csharp

private void splitButton1_DropDownItemClicked(object sender, ToolStripItemClickedEventArgs e)
{
    // Set button caption to selected item text
    splitButton1.Text = e.ClickedItem.Text;
}

当用户选中下拉项时更新按钮文本：

csharp

private void splitButton1_DropDownItemClicked(object sender, ToolStripItemClickedEventArgs e)
{
    // Set button caption to selected item text
    splitButton1.Text = e.ClickedItem.Text;
}

Pattern 2: Toggle Mode Button

模式2：切换模式按钮

Create a toggle button with dropdown options:

csharp

splitButton1.ButtonMode = ButtonMode.Toggle;
splitButton1.IsButtonChecked = false; // Initially unchecked

// Check if button is toggled
if (splitButton1.IsButtonChecked)
{
    // Perform checked state action
}

创建带下拉选项的切换按钮：

csharp

splitButton1.ButtonMode = ButtonMode.Toggle;
splitButton1.IsButtonChecked = false; // Initially unchecked

// Check if button is toggled
if (splitButton1.IsButtonChecked)
{
    // Perform checked state action
}

Pattern 3: Adding Items Dynamically

模式3：动态添加选项

Add or remove dropdown items at runtime:

csharp

// Add new item
ToolStripMenuItem newItem = new ToolStripMenuItem("New Option");
splitButton1.DropDownItems.Add(newItem);

// Remove specific item
splitButton1.DropDownItems.Remove(existingItem);

// Remove by index
splitButton1.DropDownItems.RemoveAt(0);

运行时添加或移除下拉项：

csharp

// Add new item
ToolStripMenuItem newItem = new ToolStripMenuItem("New Option");
splitButton1.DropDownItems.Add(newItem);

// Remove specific item
splitButton1.DropDownItems.Remove(existingItem);

// Remove by index
splitButton1.DropDownItems.RemoveAt(0);

Pattern 4: Themed Button

模式4：主题化按钮

Apply Office2016 theme to match application:

csharp

// Set visual style
splitButton1.Style = SplitButtonVisualStyle.Office2016Colorful;

// Or use ThemeName property
splitButton1.ThemeName = "Office2019Colorful";

应用Office2016主题匹配应用风格：

csharp

// Set visual style
splitButton1.Style = SplitButtonVisualStyle.Office2016Colorful;

// Or use ThemeName property
splitButton1.ThemeName = "Office2019Colorful";

Key Properties

核心属性

Essential Properties:

Property	Type	Description	When to Use
`Text`	string	Button caption text	Set static button label or update from selected item
`ButtonMode`	ButtonMode	Normal or Toggle mode	Toggle for checked/unchecked state, Normal for standard click
`IsButtonChecked`	bool	Toggle state (checked/unchecked)	Control or query toggle button state
`DropDownItems`	ToolStripItemCollection	Collection of dropdown menu items	Add, remove, or manage dropdown options
`Style`	SplitButtonVisualStyle	Visual appearance style	Apply Office2016White/Black/DarkGray/Colorful, Metro, or Default
`ThemeName`	string	Theme name for styling	Apply Office2019 or custom themes
`Renderer`	ISplitButtonRenderer	Custom button renderer	Implement custom drawing for button appearance
`DropDownRenderer`	ToolStripRenderer	Custom dropdown renderer	Customize dropdown items appearance

Important Events:

Event	Description	When to Use
`Click`	Fired when button portion is clicked	Handle primary button action
`DropDownItemClicked`	Fired when dropdown item is selected	Update caption or perform item-specific action

基础属性：

Property	Type	Description	When to Use
`Text`	string	按钮标题文本	设置静态按钮标签，或根据选中项更新时使用
`ButtonMode`	ButtonMode	普通或切换模式	需要选中/未选中状态时用切换模式，标准点击操作用普通模式
`IsButtonChecked`	bool	切换状态（选中/未选中）	控制或查询切换按钮状态时使用
`DropDownItems`	ToolStripItemCollection	下拉菜单项集合	添加、移除或管理下拉选项时使用
`Style`	SplitButtonVisualStyle	视觉外观样式	应用Office2016White/Black/DarkGray/Colorful、Metro或Default样式时使用
`ThemeName`	string	样式主题名称	应用Office2019或自定义主题时使用
`Renderer`	ISplitButtonRenderer	自定义按钮渲染器	实现自定义按钮外观绘制时使用
`DropDownRenderer`	ToolStripRenderer	自定义下拉渲染器	自定义下拉项外观时使用

重要事件：

Event	Description	When to Use
`Click`	点击按钮区域时触发	处理主按钮操作时使用
`DropDownItemClicked`	选中下拉项时触发	更新标题或执行对应项操作时使用

Common Use Cases

常见使用场景

Use Case 1: Save Button with Save As Option

场景1：带另存为选项的保存按钮

Implement a split button like Microsoft Word's Save button:

Primary button saves current file
Dropdown provides "Save As", "Save All", "Save Copy" options
Read getting-started.md for setup
Read button-caption.md for dynamic text updates

实现类似Microsoft Word保存按钮的拆分按钮：

主按钮保存当前文件
下拉菜单提供"另存为"、"全部保存"、"保存副本"选项
阅读getting-started.md完成配置
阅读button-caption.md实现动态文本更新

Use Case 2: View Toggle with Layout Options

场景2：带布局选项的视图切换按钮

Create a toggle button for view modes with layout variations:

Toggle mode for on/off view state
Dropdown items for layout options (Grid, List, Details)
Read button-modes.md for toggle configuration
Read getting-started.md for item management

创建支持多种布局的视图模式切换按钮：

切换模式用于控制视图开启/关闭状态
下拉项提供布局选项（Grid、List、Details）
阅读button-modes.md完成切换模式配置
阅读getting-started.md学习选项管理

Use Case 3: Themed Toolbar Button

场景3：主题化工具栏按钮

Build split buttons matching Office 2016/2019 theme:

Apply Office2016Colorful or Office2019Colorful theme
Match application's overall design language
Read visual-styles.md for theme application

打造适配Office 2016/2019主题的拆分按钮：

应用Office2016Colorful或Office2019Colorful主题
匹配应用整体设计语言
阅读visual-styles.md学习主题应用方法

Use Case 4: Custom Branded Button

场景4：自定义品牌风格按钮

Create fully customized split button with company branding:

Custom colors, borders, and arrow icon
Custom dropdown appearance
Read advanced-customization.md for ISplitButtonRenderer implementation

打造符合企业品牌风格的完全自定义拆分按钮：

自定义颜色、边框和箭头图标
自定义下拉菜单外观
阅读advanced-customization.md学习ISplitButtonRenderer实现方法

Decision Guide

选型指南

Choose SplitButton when:

Users need a primary action with related alternatives
Button caption should change based on selection
Toggle behavior is needed alongside dropdown options
Office-style UI patterns are desired

Consider alternatives when:

Only dropdown menu is needed → Use ComboBox or DropDownButton
Simple button without menu → Use standard Button control
Multiple independent actions → Use separate Button controls or ButtonAdv

Platform Note: This skill covers Syncfusion Essential Studio for Windows Forms. For other platforms:

WPF: Use Syncfusion WPF SplitButton (different implementation)
ASP.NET: Use Syncfusion ASP.NET SplitButton controls
Blazor/MAUI/React: Refer to platform-specific split button documentation

适合使用SplitButton的场景：

需要主操作搭配相关替代操作
按钮标题需要根据选中内容变化
需要切换行为同时支持下拉选项
需要实现Office风格的UI模式

建议选择其他组件的场景：

仅需要下拉菜单 → 使用ComboBox或DropDownButton
不需要菜单的简单按钮 → 使用标准Button控件
多个独立操作 → 使用单独的Button控件或ButtonAdv

平台说明： 本指南适用于Syncfusion Essential Studio for Windows Forms，其他平台请参考对应文档：

WPF: 使用Syncfusion WPF SplitButton（实现方式不同）
ASP.NET: 使用Syncfusion ASP.NET SplitButton控件
Blazor/MAUI/React: 参考对应平台的SplitButton文档