Back to Details

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:
  1. Drag SplitButton from toolbox to form
  2. Set 
    Text
    property to "Actions"
  3. Use 
    DropDownItems
    property editor to add items
  4. 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):
vb
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的最小示例：
设计器实现方式：
  1. 从工具箱拖拽SplitButton到窗体
  2. 将
    Text
    属性设置为"Actions"
  3. 使用
    DropDownItems
    属性编辑器添加选项
  4. 将
    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）：
vb
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:
PropertyTypeDescriptionWhen to Use
Text
stringButton caption textSet static button label or update from selected item
ButtonMode
ButtonModeNormal or Toggle modeToggle for checked/unchecked state, Normal for standard click
IsButtonChecked
boolToggle state (checked/unchecked)Control or query toggle button state
DropDownItems
ToolStripItemCollectionCollection of dropdown menu itemsAdd, remove, or manage dropdown options
Style
SplitButtonVisualStyleVisual appearance styleApply Office2016White/Black/DarkGray/Colorful, Metro, or Default
ThemeName
stringTheme name for stylingApply Office2019 or custom themes
Renderer
ISplitButtonRendererCustom button rendererImplement custom drawing for button appearance
DropDownRenderer
ToolStripRendererCustom dropdown rendererCustomize dropdown items appearance
Important Events:
EventDescriptionWhen to Use
Click
Fired when button portion is clickedHandle primary button action
DropDownItemClicked
Fired when dropdown item is selectedUpdate caption or perform item-specific action
基础属性：
PropertyTypeDescriptionWhen 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自定义下拉渲染器自定义下拉项外观时使用
重要事件：
EventDescriptionWhen 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文档