syncfusion-wpf-range-selector

实现范围选择器

实现 Syncfusion® WPF Range Selector（SfDateTimeRangeNavigator）控件的指南，用于按时间范围可视化数据，并通过交互式滚动和导航浏览较长时间段。

何时使用此技能

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

• 浏览大型时序数据集，并进行滚动和缩放
• 从较长时间段中选择特定日期时间范围
• 创建交互式仪表板，并根据范围筛选数据
• 实现图表缩放和时间范围选择
• 显示分层时间标签（年/月、季度/月等）
• 与其他可视化组件结合使用（图表、网格）以探索数据
• 启用数据范围选择，并提供视觉反馈和工具提示

Range Selector 控件适用于用户需要探索和选择大型时序数据中某些部分的场景。它提供直观的滚动条界面，并可智能计算标签。

组件概述

SfDateTimeRangeNavigator 是一种专用控件，可用于浏览按时间范围组织的数据，具备以下关键功能：

核心功能：

• **交互式导航：**滚动和缩放大型数据集
• **双层标签：**分层显示时间（高层级/低层级标签栏）
• **智能标签：**缩放时自动计算标签
• **范围选择：**可调整大小的滚动条，便于精确选择区域
• **内容集成：**嵌入图表、迷你图或任意 UI 元素
• **数据绑定：**支持标准 WPF IEnumerable，并可绑定属性

常见场景：

• 金融数据探索（股票价格、交易量）
• 按日期范围筛选的历史数据分析
• 用于同步视图的仪表板范围控件
• 带有视觉预览的时序数据选择

文档和导航指南

入门

📄 阅读： references/getting-started.md

适用于以下需求：

• 了解视觉结构（高层级/低层级标签栏、内容、滚动条）
• 添加程序集引用并安装包
• 初始化 SfDateTimeRangeNavigator 控件
• 设置 ItemsSource 并绑定日期时间数据
• 在导航器中添加内容（图表、迷你图）
• 在代码隐藏中创建范围导航器
• 为控件应用主题

本参考涵盖从安装到首次成功实现的完整设置流程。

交互和事件

📄 阅读： references/interactivity.md

适用于以下需求：

• 实现缩放和平移功能
• 将 ZoomPosition 和 ZoomFactor 绑定到图表轴
• 获取所选范围中的数据
• 处理 ValueChanged 事件以更新范围
• 自定义滑块外观（左/右滑块）
• 配置滑块的 SymbolTemplate 和 LineStyle
• 自定义高层级和低层级标签栏样式
• 启用延迟更新以提升性能
• 处理 LowerBarLabelsCreated/UpperBarLabelsCreated 事件

本参考涵盖所有交互功能和事件处理。

标签自定义

📄 阅读： references/label-customization.md

适用于以下需求：

• 设置间隔类型（Year、Quarter、Month、Week、Day、Hour）
• 使用 LabelFormatters 自定义标签格式
• 设置选中和未选中标签的样式
• 将标签放置在标签栏内或外
• 控制标签栏的可见性
• 配置 RangePadding（None、Round）
• 自定义网格线和刻度线
• 了解智能标签计算行为

本参考涵盖完整的标签和间隔自定义内容。

工具提示配置

📄 阅读： references/tooltip-support.md

适用于以下需求：

• 在滑块上启用工具提示
• 设置工具提示中的日期时间显示格式
• 自定义左侧和右侧工具提示模板
• 精确显示所选范围的值

本参考涵盖工具提示的显示和自定义。

故障排除

📄 阅读： references/troubleshooting.md

遇到以下问题时：

• 程序集引用问题
• 数据绑定问题或 ItemsSource 错误
• 内容显示不正常
• 缩放绑定未与图表同步
• 大型数据集的性能问题
• 主题应用问题
• 许可证相关错误

此参考文档提供常见问题的解决方案。

快速入门示例

带图表的基本范围导航器

<Window xmlns:syncfusion="clr-namespace:Syncfusion.UI.Xaml.Charts;assembly=Syncfusion.SfChart.WPF">
    <Grid>
        
        <syncfusion:SfChart x:Name="Chart" Margin="10">
            <syncfusion:SfChart.PrimaryAxis>
                <syncfusion:DateTimeAxis 
                    ZoomPosition="{Binding ElementName=RangeNavigator, Path=ZoomPosition, Mode=TwoWay}"
                    ZoomFactor="{Binding ElementName=RangeNavigator, Path=ZoomFactor, Mode=TwoWay}"/>
            </syncfusion:SfChart.PrimaryAxis>
            
            <syncfusion:SfChart.SecondaryAxis>
                <syncfusion:NumericalAxis/>
            </syncfusion:SfChart.SecondaryAxis>
            
            <syncfusion:LineSeries ItemsSource="{Binding Data}" 
                                   XBindingPath="Date" 
                                   YBindingPath="Value"/>
        </syncfusion:SfChart>
        
        
        <syncfusion:SfDateTimeRangeNavigator x:Name="RangeNavigator"
                                             ItemsSource="{Binding Data}"
                                             XBindingPath="Date"
                                             VerticalAlignment="Bottom"
                                             Height="100"
                                             Margin="10">
            <syncfusion:SfDateTimeRangeNavigator.Content>
                <syncfusion:SfLineSparkline ItemsSource="{Binding Data}"
                                            YBindingPath="Value"/>
            </syncfusion:SfDateTimeRangeNavigator.Content>
        </syncfusion:SfDateTimeRangeNavigator>
    </Grid>
</Window>

ViewModel

public class DataViewModel : INotifyPropertyChanged
{
    public ObservableCollection<DataPoint> Data { get; set; }
    
    public DataViewModel()
    {
        Data = new ObservableCollection<DataPoint>();
        DateTime startDate = DateTime.Today.AddYears(-1);
        
        for (int i = 0; i < 365; i++)
        {
            Data.Add(new DataPoint 
            { 
                Date = startDate.AddDays(i), 
                Value = 50 + (i % 30) 
            });
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
}

public class DataPoint
{
    public DateTime Date { get; set; }
    public double Value { get; set; }
}

常见模式

模式 1：图表与范围导航器同步

将导航器的缩放属性绑定到图表轴，以实现同步导航：

<syncfusion:SfChart>
    <syncfusion:SfChart.PrimaryAxis>
        <syncfusion:DateTimeAxis 
            ZoomPosition="{Binding ElementName=RangeNavigator, Path=ZoomPosition, Mode=TwoWay}"
            ZoomFactor="{Binding ElementName=RangeNavigator, Path=ZoomFactor, Mode=TwoWay}"/>
    </syncfusion:SfChart.PrimaryAxis>
</syncfusion:SfChart>

<syncfusion:SfDateTimeRangeNavigator x:Name="RangeNavigator"
                                     ItemsSource="{Binding Data}"
                                     XBindingPath="Date"/>

模式 2：获取选中的数据

访问所选范围内的数据：

private void OnRangeChanged(object sender, EventArgs e)
{
    var navigator = sender as SfDateTimeRangeNavigator;
    var selectedData = navigator.SelectedData;
    
    // Process selected data
    ProcessDataInRange(selectedData);
}

模式 3：自定义间隔配置

为标签栏设置特定的间隔类型：

<syncfusion:SfDateTimeRangeNavigator ItemsSource="{Binding Data}" 
                                     XBindingPath="Date">
    <syncfusion:SfDateTimeRangeNavigator.Intervals>
        <syncfusion:Interval IntervalType="Year"/>
        <syncfusion:Interval IntervalType="Month"/>
    </syncfusion:SfDateTimeRangeNavigator.Intervals>
</syncfusion:SfDateTimeRangeNavigator>

模式 4：通过延迟更新提升性能

为大型数据集启用延迟更新：

<syncfusion:SfDateTimeRangeNavigator EnableDeferredUpdate="True"
                                     DeferredUpdateDelay="500"
                                     ItemsSource="{Binding LargeDataset}"
                                     XBindingPath="Date"/>

关键属性

数据绑定

• ItemsSource - 数据集合（必须实现 IEnumerable）
• XBindingPath - 日期时间值的属性名称
• Content - 导航器内部显示的 UI 元素（图表、迷你图等）

范围和缩放

• ZoomPosition - 当前缩放位置（0.0 到 1.0）
• ZoomFactor - 当前缩放级别（0.0 到 1.0）
• Minimum - 导航器的起始范围
• Maximum - 导航器的结束范围
• ViewRangeStart - 所选范围的起始值（只读）
• ViewRangeEnd - 所选范围的结束值（只读）
• SelectedData - 所选范围内的数据集合（只读）

间隔和标签

• Intervals - 标签栏的间隔配置集合
• HigherLevelBarStyle - 上方标签栏的样式
• LowerLevelBarStyle - 下方标签栏的样式
• RangePadding - 填充类型（None、Round）

交互性

• EnableDeferredUpdate - 滚动/平移期间延迟更新
• DeferredUpdateDelay - 延迟更新的毫秒数
• ShowGridLines - 显示/隐藏内容中的网格线
• ShowToolTip - 启用/禁用滑块上的工具提示
• ToolTipLabelFormat - 工具提示的日期时间格式

自定义

• LeftThumbStyle - 左侧滑块的样式
• RightThumbStyle - 右侧滑块的样式
• LeftToolTipTemplate - 左侧工具提示的模板
• RightToolTipTemplate - 右侧工具提示的模板

常见使用场景

财务仪表板

显示股票价格图表，并支持选择范围，以便详细分析特定时间段。用户可以浏览多年的数据，并缩放到特定的交易日。

系统监控

监控一段时间内的系统指标，并可选择和分析异常发生时的特定时间范围。

销售分析

浏览多年的销售数据，并通过分层时间标签查看不同时间尺度下的模式，涵盖年份、季度和月份。

天气数据可视化

浏览历史天气数据，并可选择特定日期范围进行比较和分析。

IoT 传感器数据

浏览较长时间段内的传感器读数，并选择特定时间窗口进行详细调查。

与其他控件集成

范围选择器可与以下控件无缝协作：

• SfChart - 同步缩放和平移
• SfLineSparkline - 在内容区域轻量预览数据
• DataGrid - 根据所选范围筛选网格数据
• 自定义可视化 - 任何 UI 元素都可以嵌入为内容

性能注意事项

为大型数据集获得最佳性能：

• 启用 EnableDeferredUpdate，降低更新频率
• 在内容区域使用 SfLineSparkline 替代完整图表，实现轻量渲染
• 对超大型数据集考虑使用数据虚拟化
• 根据数据量设置合适的 DeferredUpdateDelay

相关技能

• 实现图表 - 查看图表实现的详细信息
• 父级库： 实现 Syncfusion WPF 组件

---

后续步骤： 根据当前的实现需求，导航到上面的相应参考文件。