syncfusion-wpf-radial-menu

实现 Syncfusion WPF Radial Menu

Syncfusion WPF Radial Menu（SfRadialMenu） 以圆形布局显示分层菜单，在相同空间中展示的菜单项比传统菜单更多。它非常适合上下文菜单、工具调色板和支持触控的界面。

何时使用此技能

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

• 在 WPF 应用程序中实现径向菜单（圆形菜单布局）
• 创建支持分层圆形导航的上下文菜单
• 在中心点周围以圆形布局显示菜单项
• 实现径向模式的逐级深入导航
• 创建采用径向菜单结构的颜色调色板
• 为自助服务终端或平板应用程序构建适合触控的圆形菜单
• 与传统线性菜单相比，在相同空间中显示更多菜单选项

---

组件概述

SfRadialMenu 是一种圆形菜单控件，可将菜单项围绕中心点径向排列。它支持：

• 支持逐级深入的分层导航
• 绑定业务对象集合
• 自定义和默认布局模式
• 自定义中心图标和菜单项图标
• 丰富的外观和样式选项
• 使用 SfRadialColorItem 支持颜色调色板
• 工具提示配置
• 命令绑定和事件处理

命名空间： Syncfusion.Windows.Controls.Navigation
程序集： Syncfusion.SfRadialMenu.WPF

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 命名空间和程序集设置
• 基本 XAML 和代码隐藏实现
• 使用 Show() 和 Close() 方法打开和关闭菜单
• 事件处理：Opened、Closed、Navigating
• 用于设置初始状态的 IsOpen 属性
• 使用 SfSkinManager 支持主题

填充项和数据绑定

📄 阅读： references/populating-items.md

• 将 ItemsSource 绑定到业务对象集合
• 用于显示标题文本的 DisplayMemberPath
• 用于命令绑定的 CommandPath
• 用于自定义项外观的 ItemTemplate
• 用于跟踪导航的 DrillDownItem
• 用于手动旋转的 EnableFreeRotation
• Command 和 CommandParameter 属性
• CloseOnExecute 行为
• CheckMode 选项（None、CheckBox、Radio）
• 用于单选按钮组的 GroupName
• 用于复选框/单选按钮状态的 IsChecked
• SfRadialMenuItem 事件（Click、Checked、UnChecked）

布局配置

📄 阅读： references/layout-types.md

• 默认布局类型（自动分段）
• 通过 VisibleSegmentsCount 设置自定义布局类型
• 用于精确定位项的 SegmentIndex
• 控制分段分布
• 布局类型选择指南

图标和视觉元素

📄 阅读： references/icons.md

• 用于自定义菜单中心的 Center Icon 属性
• 用于设置菜单项图标的 SfRadialMenuItem Icon 属性
• 使用 Image 元素和自定义 UIElements
• 图标大小和拉伸选项

外观和样式

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

• 用于设置菜单大小的 RadiusX 和 RadiusY
• 用于设置内圆大小的 CenterRimRadiusFactor
• 圆环画刷：RimBackground、RimActiveBrush、RimInactiveBrush、RimHoverBrush
• 用于显示/隐藏展开箭头的 IsExpanderVisible
• 用于设置外圆环厚度的 RimRadiusFactor
• 单项自定义：MenuBackgroundColor、MenuMouseOverBackgroundColor
• ShowMouseOverStyle 属性
• 用于导航按钮的 CenterBackButtonForeground
• 分隔符样式：SeparatorBackground、SeparatorWidth
• 描边属性：StrokeThickness、MouseOverRimStrokeThickness
• 用于高级悬停自定义的 MouseOverRimStyle

工具提示

📄 阅读： references/tooltips.md

• 用于设置项工具提示的 ToolTip 属性
• ToolTipPlacement 选项（None、Left、Top、Right、Bottom）
• 相对于菜单定位工具提示

颜色调色板

📄 阅读： references/color-palette.md

• 使用 SfRadialColorItem 选择颜色
• 创建分层颜色调色板
• 使用嵌套颜色项表示颜色变体
• 构建颜色选择器界面

---

快速入门示例

在 XAML 中创建基本径向菜单

<Window xmlns:navigation="clr-namespace:Syncfusion.Windows.Controls.Navigation;assembly=Syncfusion.SfRadialMenu.Wpf">
    <Grid>
        <navigation:SfRadialMenu IsOpen="True">
            <navigation:SfRadialMenuItem Header="Bold"/>
            <navigation:SfRadialMenuItem Header="Cut"/>
            <navigation:SfRadialMenuItem Header="Copy"/>
            <navigation:SfRadialMenuItem Header="Paste"/>
        </navigation:SfRadialMenu>
    </Grid>
</Window>

在代码隐藏中创建基本径向菜单

using Syncfusion.Windows.Controls.Navigation;

SfRadialMenu radialMenu = new SfRadialMenu();
radialMenu.IsOpen = true;

radialMenu.Items.Add(new SfRadialMenuItem() { Header = "Bold" });
radialMenu.Items.Add(new SfRadialMenuItem() { Header = "Cut" });
radialMenu.Items.Add(new SfRadialMenuItem() { Header = "Copy" });
radialMenu.Items.Add(new SfRadialMenuItem() { Header = "Paste" });

带子项的分层菜单

<navigation:SfRadialMenu IsOpen="True">
    <navigation:SfRadialMenuItem Header="Format">
        <navigation:SfRadialMenuItem Header="Bold"/>
        <navigation:SfRadialMenuItem Header="Italic"/>
        <navigation:SfRadialMenuItem Header="Underline"/>
    </navigation:SfRadialMenuItem>
    <navigation:SfRadialMenuItem Header="Edit">
        <navigation:SfRadialMenuItem Header="Cut"/>
        <navigation:SfRadialMenuItem Header="Copy"/>
        <navigation:SfRadialMenuItem Header="Paste"/>
    </navigation:SfRadialMenuItem>
    <navigation:SfRadialMenuItem Header="Undo"/>
    <navigation:SfRadialMenuItem Header="Redo"/>
</navigation:SfRadialMenu>

---

常见模式

单击按钮时打开菜单

<Grid>
    <navigation:SfRadialMenu x:Name="radialMenu">
        <navigation:SfRadialMenuItem Header="Bold"/>
        <navigation:SfRadialMenuItem Header="Copy"/>
        <navigation:SfRadialMenuItem Header="Paste"/>
    </navigation:SfRadialMenu>
    
    <Button Content="Open Menu" Click="OpenMenu_Click"/>
</Grid>

private void OpenMenu_Click(object sender, RoutedEventArgs e)
{
    radialMenu.Show();
}

使用业务对象进行数据绑定

// Model
public class EditorCommand
{
    public string Name { get; set; }
    public string IconPath { get; set; }
    public ICommand Command { get; set; }
}

// ViewModel
public class EditorViewModel
{
    public List<EditorCommand> Commands { get; set; }
    
    public EditorViewModel()
    {
        Commands = new List<EditorCommand>
        {
            new EditorCommand { Name = "Bold", IconPath = "bold.png" },
            new EditorCommand { Name = "Copy", IconPath = "copy.png" },
            new EditorCommand { Name = "Paste", IconPath = "paste.png" }
        };
    }
}

<navigation:SfRadialMenu IsOpen="True" 
                         ItemsSource="{Binding Commands}"
                         DisplayMemberPath="Name"
                         CommandPath="Command"/>

使用特定位置进行自定义布局

<navigation:SfRadialMenu IsOpen="True" 
                         LayoutType="Custom" 
                         VisibleSegmentsCount="8">
    <navigation:SfRadialMenuItem Header="Item 1" SegmentIndex="0"/>
    <navigation:SfRadialMenuItem Header="Item 2" SegmentIndex="2"/>
    <navigation:SfRadialMenuItem Header="Item 3" SegmentIndex="4"/>
    <navigation:SfRadialMenuItem Header="Item 4" SegmentIndex="6"/>
</navigation:SfRadialMenu>

使用边缘颜色设置样式

<navigation:SfRadialMenu IsOpen="True"
                         RimBackground="LightBlue"
                         RimActiveBrush="Orange"
                         RimHoverBrush="DarkOrange"
                         CenterRimRadiusFactor="0.3">
    <navigation:SfRadialMenuItem Header="Bold"/>
    <navigation:SfRadialMenuItem Header="Copy"/>
    <navigation:SfRadialMenuItem Header="Paste"/>
</navigation:SfRadialMenu>

带命令和参数的菜单项

<navigation:SfRadialMenu IsOpen="True">
    <navigation:SfRadialMenuItem Header="Bold"
                                 Command="{Binding BoldCommand}"
                                 CommandParameter="Bold"
                                 CloseOnExecute="True"/>
    <navigation:SfRadialMenuItem Header="Copy"
                                 Command="{Binding CopyCommand}"
                                 CommandParameter="Copy"
                                 CloseOnExecute="True"/>
</navigation:SfRadialMenu>

---

主要属性和事件

SfRadialMenu 属性

属性	类型	描述
IsOpen	bool	获取或设置径向菜单是否已打开
ItemsSource	IEnumerable	用于数据绑定的业务对象集合
DisplayMemberPath	string	菜单项标题的属性路径
CommandPath	string	菜单项命令的属性路径
LayoutType	LayoutType	默认或自定义布局模式
VisibleSegmentsCount	int	自定义布局中的分段数
EnableFreeRotation	bool	允许手动旋转菜单
RadiusX	double	菜单的水平半径
RadiusY	double	菜单的垂直半径
RimBackground	Brush	外缘背景颜色
RimActiveBrush	Brush	活动展开器的外缘颜色
RimHoverBrush	Brush	悬停状态下的外缘颜色
CenterRimRadiusFactor	double	内圆大小（0.0 至 1.0）

SfRadialMenuItem 属性

属性	类型	描述
Header	object	菜单项中显示的内容
Icon	UIElement	菜单项的自定义图标
Command	ICommand	单击时执行的命令
CommandParameter	object	传递给命令的参数
SegmentIndex	int	自定义布局模式中的位置
CloseOnExecute	bool	单击菜单项后关闭菜单
CheckMode	CheckMode	None、CheckBox 或 Radio 行为
IsChecked	bool	CheckBox/Radio 的选中状态
GroupName	string	单选按钮组名称
ToolTip	string	工具提示文本
ToolTipPlacement	Placement	工具提示位置
MenuBackgroundColor	Brush	菜单项背景颜色

事件

事件	描述
Opened	径向菜单打开时触发
Closed	径向菜单关闭时触发
Navigating	导航到子项时触发（可取消）
Click (MenuItem)	单击菜单项时触发
Checked (MenuItem)	选中 CheckBox/Radio 菜单项时触发
UnChecked (MenuItem)	取消选中 CheckBox 菜单项时触发

---

常见用例

1. 文本编辑器的上下文菜单

创建一个包含格式选项（粗体、斜体、下划线、字号、颜色）的径向菜单，并在右键单击时显示。

2. 图形编辑器工具栏

以圆形布局实现工具选择器，提供绘图工具（钢笔、画笔、橡皮擦、形状）。

3. 径向布局的颜色选择器

使用 SfRadialColorItem 构建颜色调色板，第一层显示原色，第二层显示色调。

4. 支持触控的自助服务终端导航

为自助服务终端应用设计便于触控的导航菜单，利用圆形布局提升可访问性。

5. 带子命令的命令面板

创建分层命令菜单，其中顶层菜单项代表类别，子项则是具体命令。

6. 快捷操作菜单

实现一个浮动操作按钮，单击后打开包含常用操作（编辑、删除、分享、更多）的径向菜单。

---

实现指南

当用户想要实现径向菜单时：

1. 从基础开始 → 引导他们阅读 getting-started.md，了解设置和基本实现
2. 对于数据绑定 → 引导他们查看 populating-items.md，了解 ItemsSource、模板和命令
3. 对于精确的布局控制 → 向他们介绍 layout-types.md，了解 Custom 布局和 SegmentIndex
4. 对于视觉自定义 → 指引他们查看 icons.md 和 appearance-and-styling.md
5. 对于颜色选择 UI → 引导他们查看 color-palette.md，了解 SfRadialColorItem 的用法
6. 对于工具提示 → 请他们参考 tooltips.md，了解工具提示配置

始终考虑：

• 空间限制：径向菜单能在有限空间内展示更多项目
• 触控与鼠标：触控界面应使用更大的半径
• 层级深度：为保证易用性，将菜单层级控制在 2-3 层
• 项目数量：每层的理想范围为 4-8 个项目
• 视觉反馈：使用 RimHoverBrush 和 MenuMouseOverBackgroundColor 提供清晰的悬停状态