syncfusion-winforms-xptoolbar

实现 Syncfusion WinForms XPToolBar

XPToolBar 控件是一个受 Microsoft Visual Studio 启发的独立工具栏，可便捷访问常用命令和选项。它支持多种项类型、灵活的位置布局、溢出处理和专业主题。

何时使用此技能

在用户需要以下功能时使用此技能：

• 应用程序工具栏： 包含按钮、下拉菜单和组合框的标准工具栏
• Visual Studio 风格的菜单： 受 VS 启发、包含 File、Edit、View 选项的菜单栏
• 快速访问工具栏： 在紧凑工具栏中放置常用命令
• 可停靠工具栏： 可停靠在任意一侧（Top、Bottom、Left、Right）的工具栏
• 多个工具栏层级： 连续堆叠多个工具栏
• 下拉菜单： 带子菜单的 DropDownBarItem 和 ParentBarItem
• 工具栏控件： 工具栏中的 ComboBoxBarItem、TextBoxBarItem、ListBarItem
• 溢出管理： 为无法容纳的项显示省略号按钮
• 主题化工具栏： Office2007、Office2016、Metro 主题
• RTL 应用程序： 从右到左布局的工具栏

组件概览

XPToolBar（Syncfusion.Windows.Forms.Tools.XPMenus.XPToolBar）是一种多功能工具栏控件，支持：

• 8 种 BarItem 类型：
  • BarItem： 独立的菜单／工具栏按钮
  • ParentBarItem： 包含子项的子菜单
  • DropDownBarItem： 下拉列表选择项
  • ComboBoxBarItem： 可编辑组合框
  • ListBarItem： 列表选择控件
  • StaticBarItem： 不可点击的标签／分隔符
  • ToolbarListBarItem： 工具栏列表显示项
  • TextBoxBarItem： 文本输入框
  • Separator： 项目之间的视觉分隔线
• 灵活停靠： 可定位在 Top、Bottom、Left、Right
• 多个工具栏： 添加连续的工具栏层级
• 省略号／溢出按钮： 工具栏过窄时显示隐藏项
• 丰富主题： Office2007、Office2016（Colorful／White／DarkGray／Black）、Metro
• 自定义： 为各项设置文本、颜色、字体、图像和工具提示
• RTL 支持： 适用于国际化应用的从右到左布局
• 本地化： 通过 CultureInfo 支持多语言
• 键盘快捷键： 为 BarItem 指定键盘快捷键

主要命名空间： Syncfusion.Windows.Forms.Tools.XPMenus

程序集： Syncfusion.Tools.Windows.dll（及其依赖项）

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 用户需要安装、配置 XPToolBar，或创建第一个 XPToolBar。

涵盖主题：

• 程序集部署和 NuGet 包安装
• 通过设计器添加 XPToolBar（工具箱、智能标记）
• 通过代码添加 XPToolBar
• 使用 Panel／容器控件定位工具栏
• 使用 BarItem Collection Editor 添加项
• 管理 Bar.Items 集合
• 基本工具栏设置和初始化

BarItem 类型与集合

📄 阅读： references/baritem-types.md

阅读时机： 用户想要添加按钮、下拉菜单、组合框，或了解不同的项类型。

涵盖主题：

• BarItem（独立按钮／菜单项）
• ParentBarItem（包含子项的子菜单）
• DropDownBarItem（下拉选择列表）
• ComboBoxBarItem（可编辑组合框控件）
• ListBarItem（列表选择）
• StaticBarItem（不可点击的标签）
• ToolbarListBarItem（工具栏项列表）
• TextBoxBarItem（工具栏中的文本输入框）
• Separator（视觉分隔线）
• 通过 Items 集合以编程方式添加项
• 项属性（Text、Image、Tooltip、Enabled）

停靠与布局

📄 阅读： references/docking-and-layout.md

阅读时机： 用户需要定位工具栏或添加多个工具栏层级。

涵盖主题：

• 停靠位置（Top、Bottom、Left、Right）
• Dock 属性配置
• 多个连续工具栏
• 添加工具栏层级
• 容器要求（Panel、GroupBox 等）
• 工具栏定位策略
• 适用于不同场景的布局最佳实践

Chevron 和溢出

📄 阅读： references/chevron-and-overflow.md

阅读时机： 用户遇到溢出问题，或想管理隐藏的工具栏项。

涵盖主题：

• Chevron/溢出按钮功能
• 查看无法容纳在工具栏宽度内的项
• 溢出行为和触发条件
• 配置 Chevron 外观
• 用户与溢出菜单的交互
• 管理适用于不同窗口大小的工具栏项

外观自定义

📄 阅读： references/appearance-customization.md

阅读时机： 用户想自定义颜色、字体、图像或工具提示。

涵盖主题：

• 文本自定义（Text 属性）
• 背景色（BackColor 属性）
• 前景色（ForeColor 属性）
• 为每个项或工具栏配置字体
• 为 BarItems 指定图像
• 工具提示配置（每个项的 ToolTip 属性）
• 调整尺寸和间距
• 自定义每个项的外观

主题与样式

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

阅读时机： 用户需要 Office 主题、RTL 支持或本地化。

涵盖主题：

• 视觉样式：Office2007（Blue、Silver、Black）
• Office2016 主题（Colorful、White、DarkGray、Black）
• Metro 主题
• Style 属性配置
• 支持阿拉伯语/希伯来语的 RTL（从右向左）
• 使用 CultureInfo 进行本地化
• 键盘快捷键（Ctrl+X、Alt+F 等）
• 触发 BarItems 执行自定义操作

---

快速入门示例

带菜单项的基本工具栏

using Syncfusion.Windows.Forms.Tools.XPMenus;
using System.Windows.Forms;

// Create panel to host toolbar
Panel panel1 = new Panel();
panel1.Dock = DockStyle.Top;
panel1.Height = 50;

// Create XPToolBar
XPToolBar xpToolBar1 = new XPToolBar();

// Create menu items
BarItem fileItem = new BarItem();
fileItem.Text = "File";

ParentBarItem editItem = new ParentBarItem();
editItem.Text = "Edit";

// Add submenu items to Edit
BarItem cutItem = new BarItem { Text = "Cut" };
BarItem copyItem = new BarItem { Text = "Copy" };
BarItem pasteItem = new BarItem { Text = "Paste" };
editItem.Items.AddRange(new BarItem[] { cutItem, copyItem, pasteItem });

DropDownBarItem viewItem = new DropDownBarItem();
viewItem.Text = "View";

// Add items to toolbar
xpToolBar1.Bar.Items.AddRange(new BarItem[] { 
    fileItem, 
    editItem, 
    viewItem 
});

// Add toolbar to panel
panel1.Controls.Add(xpToolBar1);

// Add panel to form
this.Controls.Add(panel1);

使用 Office2016 主题的工具栏

// Apply Office2016 Colorful theme
xpToolBar1.Style = VisualStyle.Office2016Colorful;

---

常见模式

带子菜单项的文件菜单

// Create File menu with submenu
ParentBarItem fileMenu = new ParentBarItem();
fileMenu.Text = "File";

// Add submenu items
BarItem newItem = new BarItem { Text = "New", Image = Properties.Resources.New };
BarItem openItem = new BarItem { Text = "Open", Image = Properties.Resources.Open };
BarItem saveItem = new BarItem { Text = "Save", Image = Properties.Resources.Save };
BarItem separator = new BarItem { BarItemType = BarItemType.Separator };
BarItem exitItem = new BarItem { Text = "Exit" };

fileMenu.Items.AddRange(new BarItem[] { 
    newItem, 
    openItem, 
    saveItem, 
    separator, 
    exitItem 
});

// Handle click events
newItem.Click += (s, e) => CreateNewDocument();
openItem.Click += (s, e) => OpenDocument();
saveItem.Click += (s, e) => SaveDocument();
exitItem.Click += (s, e) => Application.Exit();

xpToolBar1.Bar.Items.Add(fileMenu);

适用场景： 包含文件操作的标准应用菜单。

带 ComboBox 和 TextBox 的工具栏

// Font selector combo box
ComboBoxBarItem fontCombo = new ComboBoxBarItem();
fontCombo.Text = "Font:";
fontCombo.ChoiceList.AddRange(new string[] { "Arial", "Calibri", "Times New Roman" });
fontCombo.SelectedIndex = 0;

// Font size text box
TextBoxBarItem fontSizeTextBox = new TextBoxBarItem();
fontSizeTextBox.Text = "Size:";
fontSizeTextBox.TextBoxValue = "12";
fontSizeTextBox.MinimumSize = new Size(50, 20);

// Add to toolbar
xpToolBar1.Bar.Items.AddRange(new BarItem[] { 
    fontCombo, 
    fontSizeTextBox 
});

// Handle changes
fontCombo.SelectedIndexChanged += (s, e) => {
    string selectedFont = fontCombo.ChoiceList[fontCombo.SelectedIndex];
    ApplyFont(selectedFont);
};

适用场景： 文本编辑器或格式工具栏。

停靠的工具栏（顶部）

// Create toolbar with top docking
XPToolBar toolbar = new XPToolBar();
toolbar.Dock = DockStyle.Top;

// Add items
toolbar.Bar.Items.AddRange(new BarItem[] { 
    new BarItem { Text = "Home" },
    new BarItem { Text = "Insert" },
    new BarItem { Text = "View" }
});

// Add directly to form (no panel needed for simple top dock)
this.Controls.Add(toolbar);

适用场景： 简单的顶部停靠工具栏，无复杂布局。

多个工具栏层级

// First toolbar level (Menu bar)
Panel menuPanel = new Panel { Dock = DockStyle.Top, Height = 30 };
XPToolBar menuToolbar = new XPToolBar();
menuToolbar.Bar.Items.AddRange(new BarItem[] { 
    new ParentBarItem { Text = "File" },
    new ParentBarItem { Text = "Edit" },
    new ParentBarItem { Text = "View" }
});
menuPanel.Controls.Add(menuToolbar);

// Second toolbar level (Quick access)
Panel quickPanel = new Panel { Dock = DockStyle.Top, Height = 40 };
XPToolBar quickToolbar = new XPToolBar();
quickToolbar.Bar.Items.AddRange(new BarItem[] { 
    new BarItem { Text = "New", Image = Properties.Resources.New },
    new BarItem { Text = "Save", Image = Properties.Resources.Save },
    new BarItem { Text = "Undo", Image = Properties.Resources.Undo }
});
quickPanel.Controls.Add(quickToolbar);

// Add to form (order matters - add quick toolbar first for correct stacking)
this.Controls.Add(quickPanel);
this.Controls.Add(menuPanel);

适用场景： 包含菜单栏和快速访问工具栏的复杂应用。

---

关键属性

核心属性

属性	类型	描述	适用场景
Bar.Items	BarItemCollection	工具栏项集合	添加/管理工具栏按钮和控件
Dock	DockStyle	停靠位置	定位工具栏（Top/Bottom/Left/Right）
Style	VisualStyle	视觉主题样式	应用 Office2007/2016/Metro 主题

BarItem 属性

属性	类型	描述	适用场景
Text	string	项文本/标题	设置按钮或菜单标签
Image	Image	项图标	为项添加视觉图标
ToolTip	string	工具提示文本	提供悬停信息
Enabled	bool	启用/禁用项	控制项的交互性
Visible	bool	显示/隐藏项	切换项的可见性

BarItem 类型摘要

• BarItem - 标准按钮／菜单项
• ParentBarItem - 带有子菜单项的菜单（使用 .Items 集合）
• DropDownBarItem - 下拉列表（使用 .ChoiceList）
• ComboBoxBarItem - 可编辑组合框（使用 .Items 和 .SelectedIndex）
• ListBarItem - 列表选择控件
• StaticBarItem - 不可点击的标签
• TextBoxBarItem - 文本输入（使用 .TextBoxValue）
• ToolbarListBarItem - 工具栏项列表
• Separator - 视觉分隔线（设置 BarItemType = BarItemType.Separator）

---

常见用例

1. 应用程序菜单栏

场景： 包含“文件”“编辑”“视图”“帮助”的标准菜单栏。

• 为每个顶级菜单使用 ParentBarItem
• 向每个 ParentBarItem 添加子菜单 BarItem
• 在各组菜单项之间添加分隔线
• 为操作处理 Click 事件
• 阅读：baritem-types.md

2. 文本编辑器工具栏

场景： 包含字体、字号、粗体和斜体选项的格式工具栏。

• 使用 ComboBoxBarItem 选择字体
• 使用 TextBoxBarItem 设置字号
• 使用带图像的 BarItem 实现粗体／斜体／下划线
• 使用图像提升视觉辨识度
• 阅读：baritem-types.md、appearance-customization.md

3. 类似 Ribbon 的快速访问工具栏

场景： 位于主要内容上方的快速访问工具栏。

• 在顶部停靠常用命令工具栏
• 使用不带文字的图像（仅图标按钮）
• 为每个项启用工具提示
• 应用 Office2016 主题，呈现现代外观
• 阅读：docking-and-layout.md、themes-and-styling.md

4. 多级工具栏系统

场景： 菜单栏 + 快速访问工具栏 + 格式工具栏。

• 创建多个 Panel 容器
• 在每个面板中添加一个 XPToolBar
• 按适当的停靠顺序堆叠面板
• 为所有工具栏应用一致的主题
• 阅读：docking-and-layout.md

5. 本地化工具栏

场景： 面向阿拉伯语／希伯来语国际化应用程序的工具栏。

• 启用 RTL 支持
• 使用 CultureInfo 进行本地化
• 从资源中加载本地化字符串
• 使用不同语言进行测试
• 阅读：themes-and-styling.md

6. 动态工具栏

场景： 根据上下文在运行时添加／移除工具栏项。

• 使用 Bar.Items.Add/Remove 方法
• 使用 Visible 属性显示／隐藏项
• 使用 Enabled 属性启用／禁用项
• 更改后刷新工具栏布局
• 阅读：baritem-types.md

---

事件

常见的 BarItem 事件：

• Click - 单击项时触发
• SelectedIndexChanged - ComboBoxBarItem/DropDownBarItem 的选择发生更改时触发

barItem1.Click += (sender, e) => {
    // Handle button click
    MessageBox.Show("Item clicked!");
};

comboBoxBarItem1.SelectedIndexChanged += (sender, e) => {
    string selected = comboBoxBarItem1.ChoiceList[comboBoxBarItem1.SelectedIndex];
    // Handle selection change
};

---

最佳实践

1. 容器用法： 始终将 XPToolBar 放在 Panel 或容器中，以确保正确定位
2. 主题一致性： 使工具栏 Style 与应用程序主题相匹配
3. 图像质量： 为 BarItem 图像使用高质量图标（16x16 或 24x24）
4. 工具提示： 始终为仅图标按钮提供工具提示
5. 溢出管理： 合理控制工具栏项数量，以尽量减少溢出
6. 事件处理： 为所有可交互的 BarItem 订阅 Click 事件
7. 分隔线： 使用分隔线对相关项进行视觉分组
8. 键盘快捷键： 为常用命令分配快捷键
9. 动态更新： 使用 Enabled/Visible 属性，而不是移除项
10. 停靠顺序： 堆叠多个工具栏时，按相反顺序添加面板

---

另请参阅

• Syncfusion XPToolBar 文档
• XPToolBar API 参考
• BarItem API 参考