syncfusion-blazor-range-selectors

实现范围选择器

NuGet： Syncfusion.Blazor.Charts + Syncfusion.Blazor.Themes（或单独使用 Syncfusion.Blazor.RangeNavigator 包）
命名空间： Syncfusion.Blazor.Charts

这是一份全面的指南，介绍如何实现 Syncfusion Blazor 范围选择器（RangeNavigator）组件，用于数据范围选择和图表导航。范围选择器让用户能够通过可拖动的滑块，从大型数据集合中选择特定范围，为筛选和浏览时间序列或数值数据提供直观的方式。

何时使用此技能

在以下情况下，请立即使用此技能：

• 在图表中启用带可拖动滑块的范围选择功能
• 按日期范围筛选大型时间序列数据集
• 浏览金融数据或股票价格
• 创建带视觉反馈的图表缩放／平移控件
• 实现基于数据范围的仪表板筛选
• 添加用于快速浏览的周期选择按钮（1M、3M、6M、YTD、1Y、All）
• 使用面积、折线或阶梯折线系列显示数据趋势
• 构建交互式数据探索界面
• 筛选数据以进行下钻分析
• 为 Blazor Server、WebAssembly 或 Web App 创建响应式范围选择控件
• 在多个图表之间启用同步筛选
• 为性能要求较高的场景实现轻量级图表导航
• 为选定的数据范围提供视觉上下文

组件概述

Syncfusion Blazor 范围选择器（SfRangeNavigator）是专为数据范围选择和导航设计的控件。它包含：

• 可拖动滑块：用于选择范围边界的左右滑块
• 可视化系列：以折线、面积或阶梯折线形式呈现数据趋势
• 周期选择器：通过 RangeNavigatorPeriodSelectorSettings、RangeNavigatorPeriods 和 RangeNavigatorPeriod 提供快捷预设按钮
• 值类型：支持 DateTime、Numeric 和 Logarithmic 数据
• 交互式选择：单击标签或拖动滑块以更新范围
• 数据绑定：集成本地和远程数据源
• 自定义：使用 RangeNavigatorBorder、RangeNavigatorMargin、RangeNavigatorStyleSettings、RangeNavigatorThumbSettings 和工具提示设置，提供丰富的样式、主题和格式选项

主要功能：

• 范围选择方式：拖动滑块、点击标签或通过编程设置
• 系列类型：Line（默认）、Area、StepLine
• 值绑定：支持单向和双向绑定
• 集成：可与周期选择器及其他图表配合使用
• 导出：支持导出为 PNG、JPEG、SVG 和 PDF
• 无障碍访问：符合 WCAG 标准，支持键盘导航

文档和导航指南

入门

📄 阅读： references/getting-started.md

从这里开始了解安装、设置和第一个范围选择器。内容包括：

• 安装 Syncfusion.Blazor.RangeNavigator NuGet 包
• 配置 Blazor Server、WebAssembly 和 Web App
• 服务注册和主题配置
• 使用示例数据实现基本的 SfRangeNavigator
• 项目结构和脚本引用
• 常见设置问题的故障排除

核心配置

范围选择和值

📄 阅读： references/range-configuration.md

配置范围选择行为和值绑定：

• 用于设置起始值和结束值的 Value 属性
• 单向和双向绑定模式
• 值类型（DateTime、Numeric、Logarithmic）
• 拖动滑块以选择范围
• 点击标签以快速选择
• 通过编程更新范围并进行验证

系列类型

📄 阅读： references/series-types.md

选择并自定义系列可视化效果：

• 用于显示趋势线的折线系列
• 用于显示填充区域的面积系列
• 用于显示离散数据的阶梯折线系列
• 系列自定义（颜色、宽度、填充）
• 支持多个系列

数据和集成

数据绑定

📄 阅读： references/data-binding.md

为范围选择器配置数据源：

• 本地数据源（List、Array、ExpandoObject）
• 使用 SfDataManager 进行远程数据绑定
• DateTime 数据处理和格式设置
• 数值和对数刻度数据
• 数据刷新和动态更新

时段选择器集成

📄 阅读： references/period-selector-integration.md

添加时段选择器按钮，以便快速导航：

• 预定义时段按钮（1M、3M、6M、YTD、1Y、All）
• 自定义时段配置
• 与范围变化集成
• 时段选择事件处理
• 样式和位置设置

自定义和样式设置

轴自定义

📄 阅读： references/axis-customization.md

自定义轴、网格和标签：

• 网格线配置（主要和次要）
• 刻度自定义（大小、颜色、位置）
• 标签格式设置和旋转
• 间隔类型（Years、Months、Days、Hours、Minutes）
• 对数轴支持
• RTL（从右到左）支持

视觉自定义

📄 阅读： references/visual-customization.md

控制外观、主题和布局：

• 图表尺寸（Width、Height、Margin）
• 主题选择（Material、Bootstrap、Fluent、Tailwind、Fabric、Highcontrast）
• 工具提示配置和模板
• 用于提升性能的轻量级渲染模式
• 自定义样式和配色方案
• 响应式设计模式

高级功能

导出、事件和无障碍功能

📄 阅读： references/export-events-accessibility.md

处理导出和事件，并确保无障碍访问：

• 导出：PNG、JPEG、SVG、PDF 导出功能
• 事件：Changed、Loaded、TooltipRender 事件处理
• 无障碍功能：符合 WCAG 标准、键盘导航、屏幕阅读器、高对比度主题
• ARIA 属性和测试清单

快速入门示例

下面是一个用于时间序列数据筛选并带有事件处理功能的简易范围选择器：

@using Syncfusion.Blazor.Charts

@{
    DateTime[] range = SelectedRange as DateTime[] ?? new DateTime[] { DateTime.Now, DateTime.Now };
}
<h3>Stock Price Range Selector</h3>
<p>Selected Range: @range[0].ToShortDateString() to @range[1].ToShortDateString()</p>

<SfRangeNavigator @bind-Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  LabelFormat="MMM-yy"
                  IntervalType="RangeIntervalType.Months">
        <RangeNavigatorEvents Changed="OnRangeChanged"></RangeNavigatorEvents>
    <RangeNavigatorRangeTooltipSettings Enable="true"></RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@StockData" 
                              XName="Date" 
                              YName="Close" 
                              Type="RangeNavigatorType.Area"
                              Fill="#3F51B5">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@code {
    public class StockInfo
    {
        public DateTime Date { get; set; }
        public double Close { get; set; }
    }
    
    public object SelectedRange = new DateTime[] 
    { 
        new DateTime(2020, 01, 01), 
        new DateTime(2021, 01, 01) 
    };
    
    public List<StockInfo> StockData = new List<StockInfo>
    {
        new StockInfo { Date = new DateTime(2018, 01, 01), Close = 35 },
        new StockInfo { Date = new DateTime(2019, 01, 01), Close = 42 },
        new StockInfo { Date = new DateTime(2020, 01, 01), Close = 48 },
        new StockInfo { Date = new DateTime(2021, 01, 01), Close = 56 },
        new StockInfo { Date = new DateTime(2022, 01, 01), Close = 62 }
    };
    
    private void OnRangeChanged(ChangedEventArgs args)
    {
        // Handle range change event
        Console.WriteLine($"Range changed: {args.Start} to {args.End}");
    }
}

此示例会创建：

• 使用蓝色填充（#3F51B5）显示股价趋势的面积图
• 用于选择范围的可拖动滑块
• 初始选定范围：2020 年 1 月至 2021 年 1 月
• 使用“MMM-yy”格式的月份标签
• 悬停时显示数值的工具提示
• 响应范围变化的事件处理程序
• 使用 @bind-Value 指令进行双向绑定

常见用例

1. 使用时段选择器筛选股价

使用快速时段按钮筛选股票数据：

@using Syncfusion.Blazor.Charts

<SfRangeNavigator @bind-Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  IntervalType="RangeIntervalType.Months"
                  LabelFormat="MMM yy">
    <RangeNavigatorRangeTooltipSettings Enable="true" DisplayMode="TooltipDisplayMode.Always">
    </RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorPeriodSelectorSettings>
        <RangeNavigatorPeriods>
            <RangeNavigatorPeriod Text="1M" Interval="1" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="3M" Interval="3" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="6M" Interval="6" IntervalType="RangeIntervalType.Months"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="YTD"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="1Y" Interval="1" IntervalType="RangeIntervalType.Years"></RangeNavigatorPeriod>
            <RangeNavigatorPeriod Text="All"></RangeNavigatorPeriod>
        </RangeNavigatorPeriods>
    </RangeNavigatorPeriodSelectorSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@StockData" XName="Date" YName="Close" Type="RangeNavigatorType.Area">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@{
    DateTime[] range = SelectedRange as DateTime[] ?? new DateTime[] { DateTime.Now, DateTime.Now };
}
<p>Selected Range: @range[0].ToShortDateString() to @range[1].ToShortDateString()</p>

@code {
    public object SelectedRange = new DateTime[] 
    { 
        new DateTime(2022, 01, 01), 
        new DateTime(2023, 01, 01) 
    };
    
    public List<StockInfo> StockData = GetStockData();
    
    private static List<StockInfo> GetStockData()
    {
        // Sample data generation
        var data = new List<StockInfo>();
        var startDate = new DateTime(2020, 01, 01);
        var random = new Random();
        
        for (int i = 0; i < 100; i++)
        {
            data.Add(new StockInfo 
            { 
                Date = startDate.AddDays(i * 10), 
                Close = 100 + random.Next(-20, 20) 
            });
        }
        
        return data;
    }

    public class StockInfo
    {
        public DateTime Date { get; set; }
        public double Close { get; set; }
    }
}

2. 使用基于范围的筛选的仪表板

将图表数据与范围选择器同步：

@using Syncfusion.Blazor.Charts

<div class="dashboard-container">
    <h3>Sales Dashboard</h3>
    <SfRangeNavigator Value="@SelectedRange"
                      ValueType="RangeValueType.DateTime"
                      Height="140px">

        <RangeNavigatorEvents Changed="OnRangeChanged" />

        <RangeNavigatorSeriesCollection>
            <RangeNavigatorSeries DataSource="@SalesDetails"
                                  XName="Date"
                                  YName="Revenue"
                                  Type="RangeNavigatorType.Area" />
        </RangeNavigatorSeriesCollection>

    </SfRangeNavigator>
    <SfChart Height="300px">
        <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime"
                           Minimum="@SelectedRange[0]"
                           Maximum="@SelectedRange[1]" />

        <ChartSeriesCollection>
            <ChartSeries DataSource="@FilteredData"
                         XName="Date"
                         YName="Revenue"
                         Type="ChartSeriesType.Column" />
        </ChartSeriesCollection>
    </SfChart>
</div>

@code {
    public DateTime[] SelectedRange =
    {
        new DateTime(2023, 01, 01),
        new DateTime(2023, 06, 30)
    };

    public List<SalesData> SalesDetails = new();
    public List<SalesData> FilteredData = new();

    protected override void OnInitialized()
    {
        SalesDetails = GetSalesData();
        ApplyFilter();
    }

    private void OnRangeChanged(ChangedEventArgs args)
    {
        if (args.Start is DateTime start && args.End is DateTime end)
        {
            SelectedRange = new[] { start, end };
            ApplyFilter();
        }
    }

    private void ApplyFilter()
    {
        FilteredData = SalesDetails
            .Where(d => d.Date >= SelectedRange[0] && d.Date <= SelectedRange[1])
            .ToList();
    }

    private List<SalesData> GetSalesData()
    {
        var data = new List<SalesData>();
        var random = new Random();
        var start = new DateTime(2023, 01, 01);
        decimal revenue = 15000;

        for (int i = 0; i < 180; i++)
        {
            revenue += random.Next(-1500, 2000);

            data.Add(new SalesData
            {
                Date = start.AddDays(i),
                Revenue = Math.Max(revenue, 5000)
            });
        }

        return data;
    }

    public class SalesData
    {
        public DateTime Date { get; set; }
        public decimal Revenue { get; set; }
    }
}

3. 用于提升性能的轻量级模式

针对大型数据集进行优化：

@using Syncfusion.Blazor.Charts

<SfRangeNavigator Value="@SelectedRange" 
                  ValueType="RangeValueType.DateTime"
                  EnableGrouping="true"
                  GroupBy="RangeIntervalType.Months"
                  AllowSnapping="true">
    <RangeNavigatorRangeTooltipSettings Enable="true"></RangeNavigatorRangeTooltipSettings>
    <RangeNavigatorSeriesCollection>
        <RangeNavigatorSeries DataSource="@LargeDataset" 
                              XName="Timestamp" 
                              YName="Value"
                              Type="RangeNavigatorType.Line">
        </RangeNavigatorSeries>
    </RangeNavigatorSeriesCollection>
</SfRangeNavigator>

@code {
    public DateTime[] SelectedRange;
    public List<DataPoint> LargeDataset = GenerateLargeDataset(10000);

    public class DataPoint
    {
        public DateTime Timestamp { get; set; }
        public double Value { get; set; }
    }
    
    private static List<DataPoint> GenerateLargeDataset(int count)
    {
        // Generate large dataset efficiently
        return Enumerable.Range(0, count)
            .Select(i => new DataPoint 
            { 
                Timestamp = DateTime.Now.AddHours(-count + i), 
                Value = Math.Sin(i * 0.1) * 100 
            })
            .ToList();
    }
}

关键属性参考

基本属性

属性	类型	描述	默认值
Value	DateTime[] / double[]	选定范围 [start, end]	null
ValueType	RangeValueType	数据类型（DateTime、Double、Logarithmic）	Double
DataSource	object	系列的数据集合	null
IntervalType	RangeIntervalType	轴间隔（Auto、Years、Months、Days 等）	Auto
LabelFormat	string	标签显示格式	null
Width	string	组件宽度	"100%"
Height	string	组件高度	"80px"
Theme	Theme	视觉主题（Material、Bootstrap5、Fluent、Tailwind、Fabric、HighContrast）	Material
Interval	int	轴间隔值	1
LogBase	double	对数轴的底数	10
Orientation	Orientation	水平或垂直	Horizontal

系列配置

属性	类型	描述	默认值
Type	RangeNavigatorType	系列类型（Line、Area、StepLine）	Line
XName	string	X 轴数据字段名称	null
YName	string	Y 轴数据字段名称	null
Fill	string	系列填充颜色	null
Width	double	系列线条宽度	1
Opacity	double	系列不透明度（0-1）	1
Name	string	系列名称/标签	null

视觉属性

属性	类型	描述	默认值
EnableGrouping	bool	启用数据分组	false
AllowSnapping	bool	将滑块吸附到数据点	false
EnableRtl	bool	支持从右到左的布局	false
TabIndex	int	键盘导航的 Tab 索引	0

周期选择器

属性	类型	描述
RangeNavigatorPeriodSelectorSettings	Component	周期选择器配置（Enabled、Height、Position）
RangeNavigatorPeriods	Collection	周期按钮集合容器
RangeNavigatorPeriod	Item	单个周期选择器按钮（Text、Interval、IntervalType、Selected）

工具提示配置

属性	类型	描述	默认值
RangeNavigatorRangeTooltipSettings.Enable	bool	启用/禁用工具提示	true
RangeNavigatorRangeTooltipSettings.DisplayMode	TooltipDisplayMode	显示模式（OnDemand、Always）	OnDemand
RangeNavigatorRangeTooltipSettings.Format	string	工具提示内容格式模板	null

轴自定义

属性	类型	描述
RangeNavigatorMargin	Component	边距（Left、Right、Top、Bottom）
RangeNavigatorBorder	Component	边框（Color、Width、DashArray）
RangeNavigatorMajorGridLines	Component	网格线（Width、Color、DashArray）
RangeNavigatorMajorTickLines	Component	刻度线（Width、Color、Height）
RangeNavigatorLabelStyle	Component	标签样式（Color、FontFamily、Size、FontWeight）

滑块配置

属性	类型	描述	默认值
RangeNavigatorThumbSettings.Type	ThumbType	滑块形状（Circle、Rectangle）	Circle
RangeNavigatorThumbSettings.Fill	string	滑块填充颜色	"#f3f3f3"
RangeNavigatorThumbSettings.Size	double	滑块大小（像素）	15

事件参考

处理 Range Navigator 交互的关键事件：

事件	事件参数	描述
Changed	ChangedEventArgs	范围选择发生变化时触发（start、end、value）
Loaded	RangeLoadedEventArgs	组件完全加载后触发
Resizing	RangeResizeEventArgs	拖动滑块时触发
Resized	RangeResizeEventArgs	滑块拖动完成后触发
Rendering	RangeSelectorRenderEventArgs	选择器渲染前触发
TooltipRender	RangeTooltipRenderEventArgs	工具提示渲染前触发
LabelRender	RangeLabelRenderEventArgs	标签渲染时触发

事件处理程序示例：

private void OnRangeChanged(ChangedEventArgs args)
{
    var startValue = args.Start;  // DateTime or double
    var endValue = args.End;      // DateTime or double
    var selectedData = args.SelectedData;  // Filtered data
    StateHasChanged();
}

方法参考

用于编程控制的关键方法：

方法	返回类型	描述
ExportAsync(ExportType, string)	Task	导出为 PNG、JPEG、SVG 或 PDF
Print()	Task	打印 Range Navigator
Refresh()	Task	刷新/重绘组件
GetVisibleRangeModel()	VisibleRangeModel	获取当前可见范围

实现工作流

实现范围选择器时，请按以下顺序操作：

1. 从 入门指南 开始，了解安装和基本设置
2. 根据 范围配置 配置范围值，设置选择行为
3. 使用 系列类型 选择系列类型，设置可视化效果
4. 根据 数据绑定 设置数据绑定，以匹配你的数据结构 — 使用远程数据时，优先选择可信的内部 API 或模拟数据；请参阅 数据绑定 - 安全注意事项
5. 添加周期选择器（可选），参阅 周期选择器集成
6. 使用 坐标轴自定义 自定义坐标轴，确保标签恰当
7. 根据 视觉自定义 应用视觉样式
8. 使用 导出、事件和无障碍功能 添加导出功能和事件
9. 查看 API 参考，了解包含所有类、属性和枚举的完整 API 文档

如有疑问或遇到问题，请参阅各参考文件中的故障排除部分，或查看 导出、事件和无障碍功能，了解事件处理模式和无障碍要求。