syncfusion-wpf-range-slider

实现 Syncfusion WPF Range Slider

Syncfusion WPF Range Slider（SfRangeSlider）是一种多功能控件，允许用户在指定的最小值和最大值范围内选择一个值或一段数值范围。它支持双滑块选择、刻度线、标签、工具提示、自定义、触摸/手势支持以及多种方向选项。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 在 WPF 应用程序中实现范围滑块控件
• 允许用户通过双滑块选择数值范围
• 创建带刻度线和吸附行为的滑块
• 显示滑块的数值标签或自定义标签
• 显示带格式化数值的工具提示
• 自定义滑块外观（滑块、轨道、刻度线）
• 使用验证处理范围选择（ThumbInterval）
• 支持基于触摸和手势的交互
• 实现垂直或反向滑块
• 响应范围值变化并执行

组件概览

SfRangeSlider 提供：

• 单滑块或双滑块选择 - 选择单个值，或使用两个滑块选择一个数值范围
• 刻度线 - 支持吸附行为的主刻度和次刻度
• 自定义标签 - 支持数值标签和自定义标签
• 工具提示 - 可自定义的工具提示，用于显示当前值
• 方向 - 支持水平或垂直布局，并可反转方向
• 触摸和手势 - 全面支持触摸，以及键盘/鼠标手势
• 自定义 - 可全面控制所有视觉元素的样式
• 事件 - 范围变化通知和标签自定义挂钩

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 包安装和设置
• 基本范围滑块实现
• 设置最小值和最大值
• 初始范围配置
• 主题和 CSS 集成

范围选择功能

📄 阅读： references/range-selection.md

• RangeStart 和 RangeEnd 属性
• 用于双滑块模式的 ShowRange 属性
• 用于拖动整个范围的 AllowRangeDrag
• 用于设置滑块最小间距的 ThumbInterval
• 单滑块与双滑块选择模式
• 范围值数据绑定

刻度线和吸附行为

📄 阅读： references/ticks-and-snapping.md

• TickFrequency 和 MinorTickFrequency
• TickPlacement 选项（TopLeft、BottomRight、None）
• SnapsTo 行为（Ticks、StepFrequency、None）
• 用于设置增量值的 StepFrequency
• 刻度线的可视化和自定义
• 吸附行为示例

标签和数值显示

📄 阅读： references/labels.md

• ShowValueLabels 和 ShowCustomLabels
• LabelPlacement 选项
• LabelOrientation（水平/垂直）
• 用于设置数值位置的 ValuePlacement
• CustomLabels 集合
• 用于动态自定义的 LabelLoaded 事件
• 标签格式化示例

工具提示和数值显示

📄 阅读： references/tooltips.md

• ThumbToolTipPlacement（TopLeft、BottomRight、None）
• 用于设置小数位数的 ThumbToolTipPrecision
• 用于格式化数值的 ToolTipFormat
• ToolTipDisplayMode（Always、OnFocus）
• 用于自定义外观的 ToolTipStyle
• 高级工具提示自定义

中间值

📄 阅读： references/intermediate-values.md

• IntermediateValue 属性
• IntermediateRangeStart 和 IntermediateRangeEnd
• 中间指示器的使用场景
• 可视化示例

自定义和样式设置

📄 阅读： references/customization.md

• ThumbStyle 自定义
• ActiveTrackStyle 和 InactiveTrackStyle
• 刻度线样式（描边、长度、粗细）
• 次刻度自定义
• 完整的视觉样式示例
• 主题集成

方向与朝向

📄 阅读： references/orientation-and-direction.md

• Orientation 属性（Horizontal、Vertical）
• IsDirectionReversed 属性
• 视觉行为差异
• 布局注意事项
• RTL 支持

手势与交互

📄 阅读： references/gestures-and-interaction.md

• MoveToPoint，用于轻触／单击导航
• 触控支持能力
• 键盘手势（方向键、Page Up／Page Down、Home／End）
• 鼠标手势
• 无障碍功能

事件与事件处理程序

📄 阅读： references/events.md

• RangeChanged 事件
• RangeStartChanged 事件
• RangeEndChanged 事件
• LabelLoaded 事件
• 事件处理程序示例（XAML 和 C#）

快速入门示例

基本范围滑块

<Window x:Class="RangeSliderDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:editors="clr-namespace:Syncfusion.Windows.Controls.Input;assembly=Syncfusion.SfInput.Wpf">
    
    <Grid>
        
        <editors:SfRangeSlider
            Width="400"
            Minimum="0"
            Maximum="100"
            RangeStart="20"
            RangeEnd="80"
            ShowRange="True"
            TickPlacement="BottomRight"
            TickFrequency="10"
            ShowValueLabels="True" />
    </Grid>
</Window>

using Syncfusion.Windows.Controls.Input;
using System.Windows;

namespace RangeSliderDemo
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();

            // Create range slider programmatically
            SfRangeSlider rangeSlider = new SfRangeSlider()
            {
                Width = 400,
                Minimum = 0,
                Maximum = 100,
                RangeStart = 20,
                RangeEnd = 80,
                ShowRange = true,
                TickPlacement = TickPlacement.BottomRight,
                TickFrequency = 10,
                ShowValueLabels = true
            };

            // Add to container
            this.Content = rangeSlider;
        }
    }
}

常见模式

模式 1：价格范围筛选器

<editors:SfRangeSlider
    Width="350"
    Minimum="0"
    Maximum="1000"
    RangeStart="100"
    RangeEnd="500"
    ShowRange="True"
    TickFrequency="100"
    TickPlacement="BottomRight"
    ShowValueLabels="True"
    ToolTipFormat="C0"
    ThumbToolTipPlacement="TopLeft"
    SnapsTo="Ticks"
    RangeChanged="PriceRangeSlider_RangeChanged" />

模式 2：带微调功能的音量控制

<editors:SfRangeSlider
    Width="300"
    Minimum="0"
    Maximum="100"
    Value="50"
    TickFrequency="10"
    MinorTickFrequency="2"
    TickPlacement="BottomRight"
    SnapsTo="StepFrequency"
    StepFrequency="5"
    ShowValueLabels="True"
    ThumbToolTipPlacement="TopLeft"
    ToolTipFormat="N0" />

模式 3：日期范围选择器

<editors:SfRangeSlider
    Width="450"
    Minimum="0"
    Maximum="11"
    RangeStart="2"
    RangeEnd="8"
    ShowRange="True"
    ShowCustomLabels="True"
    TickFrequency="1"
    TickPlacement="BottomRight"
    SnapsTo="Ticks">
    <editors:SfRangeSlider.CustomLabels>
        <editors:LabelItem Content="Jan" Position="0"/>
        <editors:LabelItem Content="Feb" Position="1"/>
        <editors:LabelItem Content="Mar" Position="2"/>
        <editors:LabelItem Content="Apr" Position="3"/>
        <editors:LabelItem Content="May" Position="4"/>
        <editors:LabelItem Content="Jun" Position="5"/>
        <editors:LabelItem Content="Jul" Position="6"/>
        <editors:LabelItem Content="Aug" Position="7"/>
        <editors:LabelItem Content="Sep" Position="8"/>
        <editors:LabelItem Content="Oct" Position="9"/>
        <editors:LabelItem Content="Nov" Position="10"/>
        <editors:LabelItem Content="Dec" Position="11"/>
    </editors:SfRangeSlider.CustomLabels>
</editors:SfRangeSlider>

模式 4：垂直温度滑块

<editors:SfRangeSlider
    Height="300"
    Minimum="-10"
    Maximum="50"
    Value="22"
    Orientation="Vertical"
    TickFrequency="10"
    TickPlacement="TopLeft"
    ShowValueLabels="True"
    ThumbToolTipPlacement="TopLeft"
    ToolTipFormat="N0"
    IsDirectionReversed="False" />

模式 5：自定义颜色的样式化范围滑块

<Window.Resources>
    
    <Style x:Key="CustomThumbStyle" TargetType="Thumb">
        <Setter Property="Width" Value="20"/>
        <Setter Property="Height" Value="20"/>
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="Thumb">
                    <Ellipse Fill="#FF4CAF50" 
                             Stroke="#FF2E7D32" 
                             StrokeThickness="2"/>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</Window.Resources>

<editors:SfRangeSlider
    Width="400"
    Minimum="0"
    Maximum="100"
    RangeStart="30"
    RangeEnd="70"
    ShowRange="True"
    ThumbStyle="{StaticResource CustomThumbStyle}"
    ActiveTickStroke="#FF4CAF50"
    TickStroke="#FFBDBDBD"
    TickPlacement="BottomRight"
    TickFrequency="10" />

关键属性

范围与数值

• Minimum - 滑块的最小值（默认值：0）
• Maximum - 滑块的最大值（默认值：100）
• RangeStart - 所选范围的起始值
• RangeEnd - 所选范围的结束值
• ShowRange - 启用双滑块模式以选择范围
• AllowRangeDrag - 允许拖动整个选定范围
• ThumbInterval - 滑块之间的最小间距

刻度

• TickFrequency - 主刻度之间的间隔
• MinorTickFrequency - 次刻度之间的间隔
• TickPlacement - 刻度位置（TopLeft、BottomRight、None）
• SnapsTo - 吸附行为（Ticks、StepFrequency、None）
• StepFrequency - 吸附时的增量值

标签

• ShowValueLabels - 显示数值标签
• ShowCustomLabels - 显示自定义标签
• CustomLabels - 自定义标签项集合
• LabelPlacement - 标签位置
• LabelOrientation - 标签文本方向
• ValuePlacement - 数值显示位置

工具提示

• ThumbToolTipPlacement - 工具提示位置（TopLeft、BottomRight、None）
• ThumbToolTipPrecision - 工具提示中的小数位数
• ToolTipFormat - 工具提示数值的格式字符串
• ToolTipDisplayMode - 工具提示的显示时机（Always、OnFocus）
• ToolTipStyle - 工具提示的自定义样式

布局

• Orientation - 水平或垂直
• IsDirectionReversed - 反转数值方向

交互

• MoveToPoint - 将滑块移动到单击／轻触的位置

样式

• ThumbStyle - 滑块控件的自定义样式
• ActiveTrackStyle - 活动轨道区域的样式
• InactiveTrackStyle - 非活动轨道区域的样式
• ActiveTickStroke - 活动刻度的颜色
• TickStroke - 刻度的颜色

事件

RangeChanged

当 RangeStart 或 RangeEnd 值发生变化时触发。提供起始值和结束值的新旧值。

RangeStartChanged

当 RangeStart 值发生变化时触发。提供起始值的新旧值。

RangeEndChanged

当 RangeEnd 值发生变化时触发。提供结束值的新旧值。

LabelLoaded

创建滑块标签时触发。可用于动态自定义标签内容。

常见用例

1. 价格范围筛选器 - 电商产品筛选，可选择最低和最高价格
2. 日期范围选择 - 使用自定义标签选择日历或时间线范围
3. 音量／亮度控件 - 媒体播放器或系统设置
4. 温度控件 - 使用垂直滑块的 HVAC 或科学应用
5. 数据筛选 - 分析仪表板中的数据范围选择
6. 年龄范围筛选器 - 人口统计或用户档案筛选
7. 缩放级别控件 - 地图或图像缩放，可精确调整增量
8. 预算分配 - 带范围限制的金融应用
9. 时间范围选择 - 日程安排或时间线应用
10. 测量范围 - 科学或工业应用

最佳实践

1. 设置合适的 TickFrequency - 使刻度间隔与数据粒度相匹配
2. 对离散值使用 SnapsTo - 启用吸附功能，让离散数据的操作体验更好
3. 合理设置工具提示格式 - 使用 ToolTipFormat 匹配数据类型（货币、百分比等）
4. 考虑 ThumbInterval - 设置拇指之间的最小间距，以避免无效范围
5. 对非数值数据使用 CustomLabels - 为类别或日期范围提供更好的操作体验
6. 处理 RangeChanged 事件 - 更新相关 UI 或验证范围选择
7. 选择合适的方向 - 垂直滑块适用于高度、温度和音量
8. 保持样式一致 - 使拇指和轨道颜色与应用主题相匹配
9. 提供视觉反馈 - 使用 ShowRange 和工具提示显示当前选择
10. 考虑无障碍性 - 确保支持键盘导航和屏幕阅读器

相关组件

• SfDateTimeRangeNavigator - 用于结合图表选择日期／时间范围
• SfSlider - 单值滑块（无需双拇指时使用）
• NumericUpDown - 用于精确数值输入
• DatePicker - 用于选择日期，无需选择范围

安装

# Install via NuGet Package Manager
Install-Package Syncfusion.SfInput.WPF

# Or via .NET CLI
dotnet add package Syncfusion.SfInput.WPF

在 XAML 中添加 XML 命名空间：

xmlns:editors="clr-namespace:Syncfusion.Windows.Controls.Input;assembly=Syncfusion.SfInput.Wpf"

更多资源

• Syncfusion WPF 范围滑块文档
• API 参考
• 许可证信息