syncfusion-winforms-radial-slider

实现径向滑块（RadialSlider）

一种适用于 Windows Forms 的圆形滑块控件，通过绕径向刻度盘旋转的指针提供直观的数值选择，并支持自定义刻度和主题。

何时使用此技能

在以下情况下使用此技能：

• 圆形数值选择：实现基于刻度盘的数值输入（例如音量旋钮、温度刻度盘）
• 旋转控件：创建带有视觉反馈的旋转控件
• 数值选择器：构建具有最小值和最大值范围的圆形数值选择器
• 刻度标记：在圆形刻度盘周围显示数值刻度
• 视觉指示器：以径向或圆形格式显示数值
• 交互式刻度盘：实现旋钮式控件（仪表、滑块、旋转开关）
• 主题化控件：为圆形滑块应用 Office 2016 视觉主题
• 自定义数值范围：设置带有视觉刻度的特定最小值和最大值范围

组件概览

RadialSlider 是一种高级圆形滑块控件，提供：

• 带旋转指针的圆形／径向数值选择
• 可自定义的最小值和最大值范围
• 刻度盘周围的刻度标记
• 两种滑块样式（带空心圆的 Default 样式、带背景的 Frame 样式）
• 五种 Office 2016 视觉主题，以及默认样式
• 可自定义颜色（背景、圆圈、指针、前景）
• 两种指针类型（直线、点线）
• 用于实时跟踪数值的 ValueChanged 事件
• 用于自定义刻度标签格式的文本格式设置

主要功能：

• MinimumValue 和 MaximumValue 属性，用于配置范围
• Value 属性，用于获取／设置当前选择值
• SliderDivision 属性，用于配置刻度标记
• SliderStyle 枚举（Default、Frame）
• Style 属性，提供 6 种视觉主题
• NeedleType 枚举（StraightLine、DottedLine）
• 颜色自定义（BackgroundColor、InnerCircleColor、OuterCircleColor、SliderNeedleColor）
• 用于跟踪数值变化的 ValueChanged 事件
• 用于自定义文本格式的 DrawText 事件

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 首次设置 RadialSlider、将其添加到窗体、进行基本配置时

涵盖主题：

• 程序集要求和 NuGet 安装
• 基于设计器的设置（从工具箱拖放）
• 以编程方式创建和配置
• 基本尺寸和属性配置
• 滑块样式（Default 与 Frame）
• ShowOuterCircle 属性
• 安装问题排查

数值配置

📄 阅读： references/value-configuration.md

阅读时机： 配置数值范围和刻度、处理数值变化、自定义文本格式时

涵盖主题：

• MinimumValue 和 MaximumValue 属性
• Value 属性（获取／设置当前值）
• 用于刻度标记的 SliderDivision 属性
• ValueChanged 事件处理
• 用于自定义文本格式的 DrawText 事件
• TextType 枚举（Interval、Pointer、Value）
• DrawTextEventArgs 属性（Text、ForeColor、Font）
• 数值跟踪的实用示例

外观自定义

📄 阅读： references/appearance-customization.md

阅读时机： 应用视觉主题、自定义颜色、更改指针外观时

涵盖主题：

• BackgroundColor 属性
• InnerCircleColor 和 OuterCircleColor 属性
• SliderNeedleColor 属性
• ForeColor 属性
• NeedleType 枚举（StraightLine、DottedLine）
• 视觉样式（6 种主题：Default、Office2016Colorful/White/DarkGray/Black）
• 完整的主题设置示例
• 颜色组合最佳实践

快速入门示例

创建一个用于音量控制的基本 RadialSlider：

C#：

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

public partial class VolumeControl : Form
{
    private RadialSlider volumeSlider;
    private Label lblVolume;
    
    public VolumeControl()
    {
        InitializeComponent();
        SetupVolumeControl();
    }
    
    private void SetupVolumeControl()
    {
        // Create radial slider
        volumeSlider = new RadialSlider
        {
            Location = new System.Drawing.Point(50, 50),
            Size = new System.Drawing.Size(250, 250),
            MinimumValue = 0,
            MaximumValue = 100,
            Value = 50,
            SliderDivision = 10,
            SliderStyle = SliderStyles.Frame
        };
        
        // Create label for volume display
        lblVolume = new Label
        {
            Location = new System.Drawing.Point(50, 310),
            Size = new System.Drawing.Size(250, 30),
            Text = "Volume: 50",
            TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        };
        
        // Handle value changes
        volumeSlider.ValueChanged += VolumeSlider_ValueChanged;
        
        // Add to form
        this.Controls.Add(volumeSlider);
        this.Controls.Add(lblVolume);
    }
    
    private void VolumeSlider_ValueChanged(object sender, RadialSlider.ValueChangedEventArgs e)
    {
        lblVolume.Text = $"Volume: {volumeSlider.Value}";
    }
}

常见模式

模式 1：使用自定义文本的温度控件

C#：

private RadialSlider tempSlider;

private void SetupTemperatureControl()
{
    tempSlider = new RadialSlider
    {
        MinimumValue = 0,
        MaximumValue = 100,
        Value = 25,
        SliderDivision = 10,
        Style = RadialSliderStyle.Office2016Colorful
    };
    
    // Custom text formatting with degree symbol
    tempSlider.DrawText += TempSlider_DrawText;
    
    this.Controls.Add(tempSlider);
}

private void TempSlider_DrawText(object sender, RadialSlider.DrawTextEventArgs e)
{
    // Add degree Celsius symbol
    e.Text += "°C";
    
    // Color code by temperature range
    int temp = int.Parse(e.Text.Replace("°C", ""));
    
    if (temp <= 33)
    {
        e.ForeColor = System.Drawing.Color.Blue; // Cold
    }
    else if (temp > 33 && temp <= 66)
    {
       e.ForeColor = System.Drawing.Color.Orange; // Warm
    }
    else
    {
        e.ForeColor = System.Drawing.Color.Red; // Hot
    }
}

主要属性

属性	类型	默认值	用途
MinimumValue	int	0	滑块范围的起始值
MaximumValue	int	10	滑块范围的结束值
Value	int	0	当前选定值
SliderDivision	int	10	分隔标记的数量
SliderStyle	SliderStyles	Default	视觉样式（Default、Frame）
Style	RadialSliderStyle	Default	主题（Default、Office2016*）
BackgroundColor	Color	系统默认值	背景颜色
InnerCircleColor	Color	系统默认值	内圆颜色
OuterCircleColor	Color	系统默认值	外圆颜色
SliderNeedleColor	Color	系统默认值	指针颜色
ForeColor	Color	系统默认值	文本颜色
NeedleType	SliderNeedleType	StraightLine	指针外观
ShowOuterCircle	bool	true	显示/隐藏外圆

常见用例

音量/音频控制

使用 RadialSlider 创建音量旋钮、音频级别控件或媒体播放器控件，通过圆形旋钮实现直观控制。

温度设置

为恒温器、气候控制或天气应用实现温度选择器，并使用颜色区分范围。

速度控制

为电机、风扇或动画创建速度选择器，并通过分隔标记提供视觉反馈。

亮度/不透明度调整

为显示器、图像编辑器或灯光控制构建亮度控件，并使用基于百分比的范围。

计时器/时长选择

实现倒计时器或时长选择器，并在圆形表盘上标示分钟/秒的分隔。

仪表显示

创建用户可以调整的交互式仪表（燃油表、压力表、进度指示器）。

设置面板

用于适合以可视化方式呈现的数值设置（缩放级别、质量设置、强度控件）。

数据可视化

实现交互式数据选择器，适用于更偏好圆形呈现而非线性滑块的场景。

其他资源

• Syncfusion RadialSlider API 参考
• 控件依赖项
• 程序集：Syncfusion.Tools.Windows
• 命名空间：Syncfusion.Windows.Forms.Tools