syncfusion-winforms-splitbutton

程序集依赖项

必需的程序集：

• Syncfusion.Grid.Base
• Syncfusion.Grid.Windows
• Syncfusion.Shared.Base
• Syncfusion.Shared.Windows
• Syncfusion.Tools.Base
• Syncfusion.Tools.Windows

NuGet 包： Install-Package Syncfusion.Tools.Windows

实现分割按钮

何时使用此技能

当用户需要在 WinForms 应用程序中实现 Syncfusion SplitButton 控件时，请使用此技能。此控件适用于以下场景：

• 按钮与下拉菜单组合： 创建将主要按钮操作与相关选项下拉菜单结合起来的控件
• 命令变体： 提供默认操作及其他变体（例如，保存和另存为、发送选项）
• 带选项的切换按钮： 实现同时提供下拉菜单选项的切换按钮
• 动态按钮文本： 根据用户从下拉菜单项中的选择更新按钮标题
• Office 风格界面： 构建符合 Microsoft Office 分割按钮模式的界面
• 自定义绘制按钮： 使用 ISplitButtonRenderer 完全自定义按钮外观

SplitButton 控件提供两种按钮模式（Normal 和 Toggle）、动态标题管理、内置 Office2016 主题，以及通过自定义绘制器进行广泛自定义的功能。

组件概述

SplitButton 控件是一种混合控件，其行为类似于带有集成下拉菜单的按钮。单击按钮部分时，它会执行主要操作。单击下拉箭头时，它会显示包含其他选项的菜单。这种模式常见于 Microsoft Word（保存/另存为）或 Outlook（答复/全部答复）等应用程序中。

主要功能：

• 两种按钮模式：Normal（标准单击）和 Toggle（选中/未选中状态）
• 下拉菜单项管理（动态添加/移除项目）
• 静态或动态按钮标题（设置文本，或使用选中的下拉菜单项作为标题）
• 六种内置视觉样式：Office2016White、Office2016Black、Office2016DarkGray、Office2016Colorful、Metro、Default
• ISplitButtonRenderer 接口，可全面自定义按钮
• ToolStripProfessionalRenderer，可自定义下拉菜单项外观
• DropDownItemClicked 事件，用于处理项目选择

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

请先阅读此部分，了解基本设置和实现：

• 程序集引用和 NuGet 包安装
• 通过设计器添加 SplitButton（从工具箱拖放）
• 通过代码添加 SplitButton（以编程方式创建）
• 使用 DropDownItems 集合添加和移除下拉菜单项
• 基本配置和最简可用示例

按钮模式和状态

📄 阅读： references/button-modes.md

当用户需要不同的按钮行为时使用：

• Normal 模式，用于标准按钮单击操作
• Toggle 模式，用于选中/未选中状态按钮
• ButtonMode 属性配置（Normal 与 Toggle）
• IsButtonChecked 属性，用于控制切换状态
• 特定于模式的单击事件和状态管理

按钮标题管理

📄 阅读： references/button-caption.md

当用户需要以下操作时使用：

• 使用 Text 属性设置静态按钮文本
• 根据下拉菜单项选择动态更新按钮标题
• 处理 DropDownItemClicked 事件以更新标题
• 将所选项目文本显示为按钮标签

视觉样式和主题

📄 阅读： references/visual-styles.md

当用户需要以下操作时使用：

• 应用内置 Office2016 主题（White、Black、DarkGray、Colorful）
• 使用 Metro 或 Default 视觉样式
• 使按钮外观与应用程序主题相匹配
• 设置 Style 或 ThemeName 属性

高级自定义

📄 阅读： references/advanced-customization.md

适用于用户需要：

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

快速入门示例

下面是一个创建带下拉项的 SplitButton 的最简示例：

设计器方式：

1. 从工具箱将 SplitButton 拖到窗体上
2. 将 Text 属性设为 "Actions"
3. 使用 DropDownItems 属性编辑器添加项
4. 将 Style 属性设为 "Office2016Colorful"

代码方式（C#）：

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)

常见模式

模式 1：根据选中项动态更新标题

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

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

模式 2：切换模式按钮

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

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

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

模式 3：动态添加项

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

// 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);

模式 4：主题按钮

应用 Office2016 主题以匹配应用程序：

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

关键属性

基本属性：

属性	类型	描述	使用场景
Text	string	按钮标题文本	设置静态按钮标签，或根据选中项更新
ButtonMode	ButtonMode	普通或切换模式	选中/未选中状态使用 Toggle，标准点击使用 Normal
IsButtonChecked	bool	切换状态（选中/未选中）	控制或查询切换按钮状态
DropDownItems	ToolStripItemCollection	下拉菜单项集合	添加、移除或管理下拉选项
Style	SplitButtonVisualStyle	外观样式	应用 Office2016White/Black/DarkGray/Colorful、Metro 或 Default
ThemeName	string	用于设置样式的主题名称	应用 Office2019 或自定义主题
Renderer	ISplitButtonRenderer	自定义按钮渲染器	为按钮外观实现自定义绘制
DropDownRenderer	ToolStripRenderer	自定义下拉渲染器	自定义下拉项外观

重要事件：

事件	描述	使用场景
Click	点击按钮部分时触发	处理主要按钮操作
DropDownItemClicked	选择下拉项时触发	更新标题或执行特定于项的操作

常见用例

用例 1：带“另存为”选项的保存按钮

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

• 主按钮保存当前文件
• 下拉菜单提供“另存为”“全部保存”“保存副本”选项
• 阅读 getting-started.md 了解设置
• 阅读 button-caption.md 了解动态文本更新

用例 2：带布局选项的视图切换

创建用于视图模式的切换按钮，并提供多种布局：

• 使用切换模式控制视图的开/关状态
• 下拉项提供布局选项（网格、列表、详细信息）
• 阅读 button-modes.md 了解切换配置
• 阅读 getting-started.md 了解项管理

用例 3：主题工具栏按钮

构建与 Office 2016/2019 主题相匹配的 SplitButton：

• 应用 Office2016Colorful 或 Office2019Colorful 主题
• 与应用程序的整体设计风格保持一致
• 阅读 visual-styles.md 了解主题应用

用例 4：自定义品牌按钮

创建带有公司品牌标识的完全自定义 SplitButton：

• 自定义颜色、边框和箭头图标
• 自定义下拉外观
• 阅读 advanced-customization.md 了解 ISplitButtonRenderer 实现

决策指南

在以下情况下选择 SplitButton：

• 用户需要一个主要操作及其相关备选项
• 按钮标题应根据所选项而变化
• 需要同时具备切换行为和下拉选项
• 需要 Office 风格的 UI 模式

在以下情况下考虑其他方案：

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

平台说明： 此技能适用于 Windows Forms 版 Syncfusion Essential Studio。其他平台请参考：

• WPF： 使用 Syncfusion WPF SplitButton（实现方式不同）
• ASP.NET： 使用 Syncfusion ASP.NET SplitButton 控件
• Blazor/MAUI/React： 参阅特定平台的 split button 文档