syncfusion-winforms-radial-menu

在 Syncfusion WinForms 中实现 RadialMenu

本技能指导你实现 Syncfusion WinForms RadialMenu 控件——一种圆形分层上下文菜单，包含颜色调色板、字体选择器和数值滑块等专用元素。

何时使用此技能

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

• 实现具有分层结构的圆形上下文菜单
• 为平板电脑／触控应用创建适合触控的径向导航
• 添加 RadialColorPalette，在径向布局中选择颜色
• 实现 RadialFontListBox，选择字体系列
• 添加 RadialMenuSlider，输入数值（最小值／最大值范围）
• 应用 Office 2016 主题（Colorful、White、DarkGray、Black）
• 创建带复选框和单选按钮的自定义上下文菜单
• 使用 SuperAccelerator（Alt+key）启用键盘快捷键
• 在圆形布局中实现子菜单层级
• 自定义视觉外观（颜色、边缘、弧形、显示样式）
• 使用现代径向菜单替代标准上下文菜单

RadialMenu 非常适合启用了触控的应用、图形编辑器，以及需要在圆形布局中快速访问上下文命令的应用。

组件概述

RadialMenu 是一种圆形分层菜单控件，可在径向布局中显示命令。它是一种现代化的上下文菜单，包含专用输入元素。主要功能：

• 分层结构：支持子菜单的菜单项（逐级深入导航）
• RadialMenuItem：标准菜单项，支持复选框／单选按钮模式
• RadialColorPalette：集成到径向菜单中的颜色选择器
• RadialFontListBox：径向布局中的字体系列选择器
• RadialMenuSlider：用于数值范围的滑块
• Office 2016 主题：5 种专业的内置视觉样式
• 可自定义样式：颜色、边缘厚度、弧形间距、显示模式
• 键盘支持：通过 SuperAccelerator 使用 Alt+key 快捷键
• 触控优化：圆形布局中的大型触控目标
• 工具提示：悬停时显示菜单项工具提示

与标准 ContextMenu 的主要区别： RadialMenu 提供了适合触控的圆形布局，包含专用元素（颜色调色板、字体列表、滑块）和现代化的 Office 2016 主题。

文档与导航指南

入门与基本设置

📄 阅读： references/getting-started.md

当用户需要以下内容时，请阅读此参考文档：

• 程序集依赖项和 NuGet 包安装
• 命名空间：Syncfusion.Windows.Forms.Tools
• 通过设计器或代码创建 RadialMenu
• 将其添加到窗体并使其可见
• 向 Items 集合添加基本菜单项
• 了解控件层级
• 完整的最小可运行示例

菜单项与分层结构

📄 阅读： references/menu-items-and-structure.md

当用户需要以下内容时，请阅读此参考文档：

• 创建 RadialMenuItem 实例
• 带子菜单项的分层菜单
• CheckMode 属性（None、CheckBox、RadioButton）
• 用于单选按钮分组的 GroupName
• 构建嵌套菜单结构
• Click 事件处理
• 示例：复选框项、单选按钮组、子菜单

特殊元素（颜色调色板、字体列表、滑块）

📄 阅读： references/special-elements.md

当用户需要以下内容时，请阅读此参考文档：

• 使用 RadialColorPalette 选择颜色
• 使用 RadialFontListBox 选择字体系列
• 使用 RadialMenuSlider 输入数值
• 配置 MinimumValue 和 MaximumValue
• 处理颜色／字体／数值选择事件
• 与主菜单项集成
• 每种元素类型的完整示例

样式和外观自定义

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

当用户需要以下内容时，请阅读此参考资料：

• 钻取区域颜色（OuterArcColor、OuterArcHighLightedColor）
• 外环自定义（RimBackground、OuterRimThickness）
• 圆弧间隙配置（OuterArcGap）
• DisplayStyle（Text、Image、TextAboveImage、ImageAboveText）
• 图像大小自定义（MenuItemImageSize、ImageSize）
• 中心图标配置（Icon 属性）
• 自定义样式示例

主题和视觉样式

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

当用户需要以下内容时，请阅读此参考资料：

• Style 属性概览
• Office 2016 主题（Colorful、White、DarkGray、Black）
• 默认主题
• 主题比较和选择指南
• 在运行时应用主题
• 主题最佳实践

高级功能和配置

📄 阅读： references/advanced-features.md

当用户需要以下内容时，请阅读此参考资料：

• WedgeCount 属性（切片数量配置）
• MenuVisibility 属性，用于初始显示
• PersistPreviousState，用于状态恢复
• ImageList 配置（ImageListAdv）
• 使用 UseIndexBasedOrder 排列项目
• 使用 SuperAccelerator 支持键盘操作
• 加速键配置（Alt+key）
• ShowTooltip 属性和工具提示自定义
• 高级配置示例

快速入门示例

以下是创建包含菜单项的 RadialMenu 的最小示例：

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

public class RadialMenuExample : Form
{
    private RadialMenu radialMenu1;
    
    public RadialMenuExample()
    {
        // Create RadialMenu
        radialMenu1 = new RadialMenu();
        radialMenu1.Visible = true;
        radialMenu1.Style = RadialMenuStyle.Office2016Colorful;
        
        // Create menu items
        RadialMenuItem editItem = new RadialMenuItem();
        editItem.Text = "Edit";
        
        RadialMenuItem cutItem = new RadialMenuItem();
        cutItem.Text = "Cut";
        
        RadialMenuItem copyItem = new RadialMenuItem();
        copyItem.Text = "Copy";
        
        RadialMenuItem pasteItem = new RadialMenuItem();
        pasteItem.Text = "Paste";
        
        // Add items to menu
        radialMenu1.Items.Add(editItem);
        radialMenu1.Items.Add(cutItem);
        radialMenu1.Items.Add(copyItem);
        radialMenu1.Items.Add(pasteItem);
        
        // Add menu to form
        this.Controls.Add(radialMenu1);
        
        this.Text = "RadialMenu Example";
        this.Size = new Size(500, 400);
    }
}

**结果：**一个包含 4 个项目（Edit、Cut、Copy、Paste）的圆形菜单，采用 Office 2016 Colorful 主题。

常见模式

带子菜单的上下文菜单

**模式：**创建带有分层子菜单的径向上下文菜单。

// Create main RadialMenu
RadialMenu contextMenu = new RadialMenu();
contextMenu.Visible = true;
contextMenu.Style = RadialMenuStyle.Office2016Colorful;

// Create main menu item with submenu
RadialMenuItem formatItem = new RadialMenuItem();
formatItem.Text = "Format";

// Create submenu items
RadialMenuItem boldItem = new RadialMenuItem();
boldItem.Text = "Bold";
boldItem.Click += (s, e) => ApplyBoldFormatting();

RadialMenuItem italicItem = new RadialMenuItem();
italicItem.Text = "Italic";
italicItem.Click += (s, e) => ApplyItalicFormatting();

// Add submenu items to parent
formatItem.Items.Add(boldItem);
formatItem.Items.Add(italicItem);

// Add to main menu
contextMenu.Items.Add(formatItem);
this.Controls.Add(contextMenu);

**适用场景：**用户需要分层菜单导航，并可逐层进入子菜单。

颜色选择器菜单

**模式：**为径向菜单添加颜色选择功能。

// Create RadialMenu
RadialMenu menu = new RadialMenu();
menu.Visible = true;
menu.Style = RadialMenuStyle.Office2016Colorful;

// Create RadialColorPalette
RadialColorPalette colorPalette = new RadialColorPalette();
colorPalette.Text = "Color";
colorPalette.ColorSelected += (s, e) => 
{
    // Handle color selection
    Color selectedColor = e.Color;
    ApplyColor(selectedColor);
};

// Add color palette to menu
menu.Items.Add(colorPalette);
this.Controls.Add(menu);

**适用场景：**用户需要在径向菜单中集成颜色选择功能（用于图形应用、文本编辑器）。

带滑块的格式工具栏菜单

**模式：**组合字体选择器、颜色选择器和字号滑块。

// Create RadialMenu
RadialMenu formatMenu = new RadialMenu();
formatMenu.Visible = true;
formatMenu.Style = RadialMenuStyle.Office2016White;
formatMenu.WedgeCount = 3; // Reserve space for 3 items

// Font list
RadialFontListBox fontList = new RadialFontListBox();
fontList.Text = "Font";
fontList.SelectedFontChanged += (s, e) => 
{
    ApplyFont(fontList.SelectedFont);
};

// Color palette
RadialColorPalette colorPalette = new RadialColorPalette();
colorPalette.Text = "Color";

// Size slider
RadialMenuSlider sizeSlider = new RadialMenuSlider();
sizeSlider.Text = "Size";
sizeSlider.MinimumValue = 8;
sizeSlider.MaximumValue = 72;
sizeSlider.SliderValueChanged += (s, e) => 
{
    ApplyFontSize((int)sizeSlider.SliderValue);
};

// Add all elements
formatMenu.Items.Add(fontList);
formatMenu.Items.Add(colorPalette);
formatMenu.Items.Add(sizeSlider);

this.Controls.Add(formatMenu);

**适用场景：**用户需要在紧凑的径向菜单中使用全面的格式设置控件。

关键属性

核心属性

属性	类型	描述	使用场景
Visible	bool	显示/隐藏 RadialMenu	控制可见性
Style	RadialMenuStyle	视觉主题	应用 Office 2016 主题
Items	Collection	菜单项集合	添加 RadialMenuItem、调色板等
WedgeCount	int	可见菜单切片的最大数量	为项目预留空间
MenuVisibility	bool	加载时显示菜单	初始显示菜单

样式属性

属性	类型	描述	使用场景
OuterArcColor	Color	钻取区域颜色（常态）	自定义圆弧外观
OuterArcHighLightedColor	Color	钻取区域颜色（悬停）	自定义悬停效果
RimBackground	Color	外环颜色	自定义外环外观
OuterRimThickness	int	外环厚度（像素）	调整外环大小
OuterArcGap	int	外环与圆弧之间的间隙	调整间距
DisplayStyle	DisplayStyle	文本/图像布局	控制项目外观
MenuItemImageSize	Size	所有项目的图像大小	设置统一的图像大小
Icon	Image	中心图标	添加自定义中心图标

高级属性

属性	类型	描述	使用场景
PersistPreviousState	bool	恢复上一个菜单状态	保持导航状态
ImageList	ImageListAdv	图像集合	提供自定义图像
UseIndexBasedOrder	bool	基于索引的项目排序	控制项目位置
ShowToolTip	bool	启用工具提示	显示项目说明

RadialMenuItem 属性

属性	类型	描述	使用场景
Text	string	菜单项文本	显示项目标签
ImageIndex	int	ImageList 中的图像索引	添加项目图标
CheckMode	CheckMode	None/CheckBox/RadioButton	启用勾选行为
GroupName	string	单选按钮组	对单选按钮分组
Items	Collection	子菜单项	创建分层菜单

常见使用场景

图形和图像编辑器

用于编辑工具的径向上下文菜单：

• 用于填充/描边颜色的调色板
• 用于文本工具的字体选择器
• 用于画笔/钢笔大小的尺寸滑块
• 编辑命令（剪切、复制、粘贴）

支持触控的应用程序

针对触控优化的圆形菜单：

• 径向布局中的大型触控目标
• 快速访问常用命令
• 通过逐层深入进行子菜单导航
• 适用于平板电脑/触控笔的界面

文本编辑器和文字处理器

格式设置上下文菜单：

• 字体系列选择
• 文本颜色选择器
• 字号滑块
• 样式切换（粗体、斜体、下划线）

CAD 和设计应用程序

设计工具上下文菜单：

• 对象操作命令
• 图层控件
• 捕捉选项
• 视图控件

实现检查清单

实现 RadialMenu 时，请确保：

• ✅ 引用必需程序集（Syncfusion.Tools.Windows.dll 等）
• ✅ 包含命名空间（Syncfusion.Windows.Forms.Tools）
• ✅ 创建并配置 RadialMenu 实例
• ✅ 将 Visible 属性设为 true（或按需切换）
• ✅ 设置 Style 属性以应用主题（推荐 Office2016Colorful）
• ✅ 将菜单项添加到 Items 集合
• ✅ 为菜单项添加 Click 事件处理程序
• ✅ 使用多个项目时配置 WedgeCount
• ✅ 使用自定义图标时配置 ImageList
• ✅ 使用鼠标和触控进行测试（如适用）

故障排除速查

问题： RadialMenu 不可见

• 设置 Visible = true
• 确保菜单已添加到窗体的 Controls
• 检查 Location 属性是否位于窗体边界内
• 确认窗体已获得焦点

问题： 菜单项未显示

• 检查 Items 集合是否已填充
• 确认 WedgeCount >= 项目数
• 确保已为项目设置 Text 或 ImageIndex
• 检查 DisplayStyle 属性

问题： 子菜单导航不起作用

• 将项目添加到父项的 Items 集合（而非菜单的 Items）
• 确保子项已设置 Text 属性
• 检查层级结构是否正确

问题： 图像未显示

• 配置 ImageList 属性
• 为菜单项设置 ImageIndex
• 确认 ImageListAdv 中存在这些图像
• 检查 DisplayStyle 是否包含图像

问题： 键盘快捷键不起作用

• 添加 SuperAccelerator 组件
• 使用 SetAccelerator 方法设置每个项目
• 确保窗体已获得焦点
• 按 Alt 键激活

问题： 调色板/字体列表未显示

• 创建 RadialColorPalette 或 RadialFontListBox 实例
• 将其添加到菜单的 Items 集合（而非 RadialMenuItem）
• 检查是否已设置 Text 属性
• 使用自定义图标时，确认 ImageIndex 设置正确

总结

RadialMenu 提供圆形分层菜单功能，包括：

• 圆形布局：针对触控优化的径向菜单结构
• 专用元素：调色板、字体列表、数值滑块
• Office 2016 主题：5 种专业视觉样式
• 分层导航：支持逐层深入的子菜单
• 可自定义样式：颜色、边框、弧形、显示模式
• 键盘支持：通过 SuperAccelerator 使用 Alt+键快捷键

在需要适用于触控的圆形上下文菜单、专用输入元素（颜色/字体/滑块）或现代主题菜单时，请使用 RadialMenu，为 WinForms 应用程序创建直观且易于访问的导航。