syncfusion-winui-range-slider

实现 WinUI RangeSlider（SfRangeSlider）

完整指南，介绍如何实现 Syncfusion WinUI RangeSlider 控件——这是一款高度交互式 UI 组件，可通过双滑块、标签、刻度和丰富的自定义选项来选择数值范围。

何时使用此技能

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

• 在 WinUI 应用程序中实现范围选择器或范围选取器
• 允许用户通过双滑块选择数值范围
• 创建价格范围筛选器、日期范围选取器或数值范围选择器
• 添加带标签、刻度和工具提示的交互式滑块
• 自定义轨道、滑块或覆盖层的外观
• 处理范围值更改和验证
• 在 WinUI 应用中使用 SfRangeSlider 控件

WinUI RangeSlider 概览

Syncfusion WinUI RangeSlider（SfRangeSlider）是一款高度交互式 UI 控件，用户可以通过沿轨道移动双滑块，从较大的数据集中选取较小的范围。

主要功能：

• 数值范围选择：在任意范围内选择数值
• 视觉元素：标签、刻度和分隔线，直观显示数值
• 自定义：为轨道、滑块和覆盖层提供丰富的样式选项
• 工具提示：以可自定义的格式显示选定值
• 事件：通过 RangeValueChanged 跟踪范围
• 响应灵敏：滑块交互流畅，并提供视觉反馈

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 创建 WinUI 应用程序
• 安装 Syncfusion.Sliders.WinUI NuGet 包
• 基本 SfRangeSlider 初始化
• 设置 RangeStart 和 RangeEnd 值
• 完整的可运行示例

基本配置

📄 阅读： references/basic-features.md

• 最小值和最大值
• 间隔配置
• 步进频率
• 值更改事件
• 方向（水平／垂直）
• 离散模式与连续模式

标签

📄 阅读： references/labels.md

• 启用标签（ShowLabels）
• 标签数量上限
• 标签偏移和位置
• 自定义标签格式
• 自定义标签模板
• 标签样式

刻度

📄 阅读： references/ticks.md

• 主刻度（ShowTicks）
• 次刻度（MinorTicksPerInterval）
• 刻度长度和偏移
• 刻度位置
• 刻度样式

分隔线

📄 阅读： references/dividers.md

• 启用分隔线（ShowDividers）
• 分隔线尺寸
• 分隔线样式
• 使用场景

轨道自定义

📄 阅读： references/track.md

• 活动轨道样式
• 非活动轨道样式
• 轨道高度和圆角
• 自定义轨道填充

滑块与覆盖层

📄 阅读： references/thumb-and-overlay.md

• 自定义滑块
• 滑块尺寸和图标
• ThumbStyle 属性
• 覆盖层样式
• 自定义滑块模板

工具提示

📄 阅读： references/tooltip.md

• 启用工具提示（ShowTooltip）
• 工具提示格式和位置
• 自定义工具提示模板
• 工具提示样式

高级范围处理

📄 阅读： references/custom-range.md

• RangeValueChanged 和其他事件
• 以编程方式更新值
• 范围验证
• 自定义范围场景

快速入门

1. 安装 NuGet 包

<PackageReference Include="Syncfusion.Sliders.WinUI" Version="Latest" />

2. 添加命名空间

<Page xmlns:slider="using:Syncfusion.UI.Xaml.Sliders">

3. 基本实现

<slider:SfRangeSlider 
    RangeStart="30"
    RangeEnd="70"
    ShowLabels="True"
    ShowTicks="True" />

4. 代码隐藏文件

using Syncfusion.UI.Xaml.Sliders;

SfRangeSlider rangeSlider = new SfRangeSlider();
rangeSlider.Minimum = 0;
rangeSlider.Maximum = 100;
rangeSlider.RangeStart = 30;
rangeSlider.RangeEnd = 70;
rangeSlider.ShowLabels = true;
rangeSlider.ShowTicks = true;
this.Content = rangeSlider;

常见模式

价格范围筛选器

<slider:SfRangeSlider 
    Minimum="0"
    Maximum="1000"
    Interval="100"
    RangeStart="200"
    RangeEnd="800"
    ShowLabels="True"
    ShowTicks="True"
    ShowTooltip="True" />

自定义样式的范围滑块

<slider:SfRangeSlider 
    RangeStart="25"
    RangeEnd="75"
    ShowLabels="True"
    ShowTicks="True"
    ShowDividers="True"
    ActiveTrackHeight="4"
    InactiveTrackHeight="4"
    DividerHeight="4"
    DividerWidth="4"
    ThumbHeight="20"
    ThumbWidth="20" />

值更改跟踪

<slider:SfRangeSlider 
    x:Name="rangeSlider"
    RangeStart="30"
    RangeEnd="70"
    RangeValueChanged="OnRangeChanged" />

private void OnRangeChanged(object sender, RangeValueChangedEventArgs e)
{
    double oldStart = e.RangeStartOldValue;
    double oldEnd = e.RangeEndOldValue;
    double newStart = e.RangeStartNewValue;
    double newEnd = e.RangeEndNewValue;
    
    // Update UI or perform validation
    Debug.WriteLine($"Range: {newStart} - {newEnd}");
}

关键属性

范围配置

• Minimum (double)：最小值（默认值：0）
• Maximum (double)：最大值（默认值：100）
• RangeStart (double)：所选范围的起始值
• RangeEnd (double)：所选范围的结束值
• Interval (double)：标签／刻度的步进间隔
• StepFrequency (double)：数值变化的步长

视觉元素

• ShowLabels (bool)：显示间隔点上的标签
• ShowTicks (bool)：显示主刻度
• ShowDividers (bool)：显示分隔线
• ShowTooltip (bool)：在滑块拇指上显示工具提示

自定义

• ActiveTrackHeight (double)：活动轨道的高度
• InactiveTrackHeight (double)：非活动轨道的高度
• ThumbHeight (double)：滑块拇指的高度
• ThumbWidth (double)：滑块拇指的宽度
• OverlayRadius (double)：滑块拇指覆盖层的半径

行为

• IsInversed (bool)：反转方向
• MinorTicksPerInterval (int)：每个间隔内的次刻度数
• MaximumLabelsCount (int)：每 100 个逻辑像素的最大标签数

常见用例

电商价格筛选

使用 RangeSlider 按价格范围筛选商品，并通过标签和工具提示显示货币值。

日期范围选择器

为日历应用实现月份／年份范围选择，并自定义标签格式。

音频／视频时间轴选择

创建片段选择工具，提供精确的范围控制和视觉反馈。

数据筛选仪表板

让用户按数值范围筛选数据集（年龄、数量、评分等）。

设置和配置

为应用设置提供直观的范围选择器（音量范围、亮度范围等）。

故障排除

范围值未更新：

• 确保 RangeStart 和 RangeEnd 均在 Minimum 和 Maximum 范围内
• 检查双向数据绑定是否配置正确
• 确认已正确连接 RangeValueChanged 事件

标签未显示：

• 设置 ShowLabels="True"
• 配置 Interval 属性以设置标签间距
• 如果使用自动间隔，请检查 MaximumLabelsCount

刻度不可见：

• 设置 ShowTicks="True"
• 确保已定义 Interval
• 根据需要调整 TickOffset

工具提示未显示：

• 设置 ShowTooltip="True"
• 检查 TooltipPlacement 属性
• 确认工具提示模板有效

相关组件

• Slider (SfSlider)：用于选择单个值的单拇指滑块
• DateRangeSlider：用于选择日期范围的专用滑块

资源

• WinUI RangeSlider 文档
• API 参考
• GitHub 示例
• NuGet 包