syncfusion-react-range-navigator

Syncfusion React Range Navigator

一份全面的指南，介绍如何实现 Syncfusion React Range Navigator 组件——这是一款功能强大的数据可视化控件，支持范围选择，可让用户滚动浏览和导航数据。该组件可轻松与 Chart、Data Grid 等其他控件结合，创建丰富的仪表板。

何时使用此指南

在以下情况下使用此指南：

• 在 React 应用程序中安装和设置 Range Navigator 组件
• 为时间序列或数值数据实现范围选择和导航
• 显示需要导航的财务数据、股票图表或大型数据集
• 配置数值、对数或 DateTime 值类型的数据绑定
• 自定义系列类型（Line、Area、StepLine）
• 添加预定义时间间隔的周期选择器
• 启用不含图表数据的轻量模式
• 自定义导航器外观（滑块、边框、区域）
• 配置范围选择工具提示
• 自定义标签、网格线和刻度线
• 启用无障碍功能或 RTL 支持
• 导出或打印 Range Navigator 图表
• 将 Range Navigator 与其他图表组件集成

组件概述

Range Navigator 是一种数据可视化控件，为大型数据集提供直观的范围选择和导航功能。它以精简视图显示数据，并提供交互式滑块，让用户选择特定范围。该组件尤其适用于：

• 财务数据可视化： 股票价格分析、交易数据、市场趋势
• 时间序列导航： 历史数据探索、日期范围选择
• 大型数据集筛选： 高效浏览大量数据集合
• 仪表板集成： 与 Chart、Grid 和其他组件组合使用

主要功能：

• 支持多种数据源（本地和远程）
• 交互式工具提示和动画
• 适用于移动设备的轻量模式
• 用于自定义时间间隔的周期选择器
• 多种轴和系列类型
• 导出为图像格式（PNG、JPEG、SVG、PDF）

文档与导航指南

API 参考

📄 阅读： references/api.md

• 全面的 API 摘要：属性、方法、事件、样式类和简短的用法示例。包含官方文档链接。

入门

📄 阅读： references/getting-started.md

• 安装和依赖项（@syncfusion/ej2-react-charts package）
• 设置开发环境（Vite/Create React App）
• 添加 CSS 样式表和主题
• 基本的 Range Navigator 实现
• 模块注入（AreaSeries、DateTime、RangeTooltip）
• 添加数据（dataSource、xName、yName）
• 启用工具提示
• 运行第一个应用程序

数据绑定和值类型

📄 阅读： references/data-binding.md

• 数值类型（默认 Double 类型）
• 范围配置（minimum、maximum、interval）
• 数值标签格式（n1、n2、p1、c1、自定义格式）
• 用于数量级数据的对数轴
• 对数范围和基数自定义
• 用于时间序列数据的 DateTime 值类型
• DateTime 间隔类型（Auto、Years、Quarter、Months、Weeks、Days、Hours、Minutes、Seconds）
• DateTime 标签格式
• 完整的格式参考表

系列类型

📄 阅读： references/series-types.md

• Line 系列（默认，LineSeries 模块）
• Area 系列（AreaSeries 模块）
• StepLine 系列（StepLineSeries 模块）
• 各系列类型的模块注入
• 配置和实现示例

自定义

📄 阅读： references/customization.md

• 导航器外观（navigatorStyleSettings）
• 已选和未选区域的颜色
• 滑块自定义（Circle/Rectangle 形状、大小、边框、填充）
• 边框自定义（宽度、颜色）
• 延迟更新以优化性能
• 启用吸附，实现精确选择
• 动画时长控制

周期选择器

📄 阅读： references/period-selector.md

• 配置预设时间周期
• 周期数组（interval、text、intervalType）
• 模块注入（PeriodSelector）
• 定位（Top 或 Bottom）
• 自定义高度
• 禁用范围选择器（仅周期选择器模式）
• 间隔类型（Auto、Years、Quarter、Months、Weeks、Days、Hours、Minutes、Seconds）

轻量模式

📄 阅读： references/lightweight.md

• 不带图表数据的轻量级范围导航器
• 何时使用轻量模式
• 适用于移动设备的实现
• 基本配置

工具提示

📄 阅读： references/tooltip.md

• 启用和禁用工具提示
• 自定义工具提示（fill、opacity、textStyle）
• 工具提示的标签格式
• 日期和时间格式选项
• 完整的格式参考表

标签

📄 阅读： references/labels.md

• 多级标签（为 DateTime 启用 enableGrouping）
• 按间隔分组（Auto、Years、Quarter、Months、Weeks、Days、Hours、Minutes、Seconds）
• 智能标签，避免重叠（labelIntersectAction）
• 标签定位（内部或外部）
• 自定义标签样式（字体、颜色、字族、字重、字号）

网格线和刻度线

📄 阅读： references/grid-and-tick.md

• 自定义网格线（majorGridLines）
• 网格线宽度、颜色和 dashArray
• 自定义刻度线（majorTickLines）
• 刻度线宽度、颜色和 dashArray
• 配置示例

无障碍

📄 阅读： references/accessibility.md

• 支持键盘导航
• 兼容屏幕阅读器
• 符合 WCAG 2.0 标准
• 无障碍功能和最佳实践

从右到左（RTL）支持

📄 阅读： references/rtl.md

• 启用 RTL 模式（enableRtl 属性）
• RTL 布局行为
• 实现示例

导出和打印

📄 阅读： references/export-print.md

• 导出为图像格式（PNG、JPEG、SVG、PDF）
• 打印功能
• 导出/打印方法的用法
• 配置选项

快速入门示例

import * as React from 'react';
import { RangeNavigatorComponent, AreaSeries, DateTime, RangeTooltip, Inject,
  RangenavigatorSeriesCollectionDirective,
  RangenavigatorSeriesDirective } from '@syncfusion/ej2-react-charts';
import * as ReactDOM from "react-dom";

// Register your Syncfusion license key
import { registerLicense } from '@syncfusion/ej2-base';
registerLicense('YOUR_LICENSE_KEY');

function App() {
  const data = [
    { x: new Date(2018, 0, 1), y: 35 },
    { x: new Date(2018, 1, 1), y: 28 },
    { x: new Date(2018, 2, 1), y: 34 },
    { x: new Date(2018, 3, 1), y: 32 },
    { x: new Date(2018, 4, 1), y: 40 },
    { x: new Date(2018, 5, 1), y: 42 },
    { x: new Date(2018, 6, 1), y: 38 }
  ];

  return (
    <RangeNavigatorComponent
      id="rangeNavigator"
      valueType="DateTime"
      value={[new Date(2018, 1, 1), new Date(2018, 4, 1)]}
      tooltip={{ enable: true }}
    >
      <Inject services={[AreaSeries, DateTime, RangeTooltip]} />
      <RangenavigatorSeriesCollectionDirective>
        <RangenavigatorSeriesDirective
          dataSource={data}
          xName="x"
          yName="y"
          type="Area"
        />
      </RangenavigatorSeriesCollectionDirective>
    </RangeNavigatorComponent>
  );
}

export default App;
ReactDOM.render(<App />, document.getElementById("charts"));

常见模式

模式 1：时间序列数据导航

用户需求： 使用日期范围选择来浏览时间序列数据

实现：

import * as React from 'react';
import { RangeNavigatorComponent, AreaSeries, DateTime, RangeTooltip, Inject,
  RangenavigatorSeriesCollectionDirective,
  RangenavigatorSeriesDirective } from '@syncfusion/ej2-react-charts';
import * as ReactDOM from "react-dom";

function App() {
  const data = [
    { x: new Date(2018, 0, 1), y: 35 },
    { x: new Date(2018, 1, 1), y: 28 },
    { x: new Date(2018, 2, 1), y: 34 },
    { x: new Date(2018, 3, 1), y: 32 },
    { x: new Date(2018, 4, 1), y: 40 },
    { x: new Date(2018, 5, 1), y: 42 },
    { x: new Date(2018, 6, 1), y: 38 }
  ];
  return (
    <RangeNavigatorComponent
      valueType="DateTime"
      intervalType="Months"
      labelFormat="MMM"
      value={[new Date(2018, 0, 1), new Date(2018, 6, 1)]}
      tooltip={{ enable: true, displayMode: 'Always' }}>
      <Inject services={[AreaSeries, DateTime, RangeTooltip]} />
      <RangenavigatorSeriesCollectionDirective>
        <RangenavigatorSeriesDirective
          dataSource={data}
          xName="x"
          yName="y"
          type="Area"/>
      </RangenavigatorSeriesCollectionDirective>
    </RangeNavigatorComponent>
  )
}

export default App;
ReactDOM.render(<App />, document.getElementById("charts"));

模式 2：带周期选择器的金融数据

用户需求： 使用预设时间周期（1M、3M、6M、YTD、1Y）浏览股票图表

实现：

import * as React from 'react';
import {
  RangeNavigatorComponent,
  AreaSeries,
  DateTime,
  RangeTooltip,
  PeriodSelector,
  Inject,
  RangenavigatorSeriesCollectionDirective,
  RangenavigatorSeriesDirective,
} from '@syncfusion/ej2-react-charts';
import * as ReactDOM from 'react-dom';

function App() {
  const data = [
    { x: new Date(2018, 0, 1), y: 35 },
    { x: new Date(2018, 1, 1), y: 28 },
    { x: new Date(2018, 2, 1), y: 34 },
    { x: new Date(2018, 3, 1), y: 32 },
    { x: new Date(2018, 4, 1), y: 40 },
    { x: new Date(2018, 5, 1), y: 42 },
    { x: new Date(2018, 6, 1), y: 38 }
  ];
  return (
    <RangeNavigatorComponent
      valueType="DateTime"
      value={[new Date(2023, 0, 1), new Date(2023, 11, 31)]}
      periodSelectorSettings={{
        periods: [
          { intervalType: 'Months', interval: 1, text: '1M' },
          { intervalType: 'Months', interval: 3, text: '3M' },
          { intervalType: 'Months', interval: 6, text: '6M' },
          { intervalType: 'Years', interval: 1, text: '1Y' },
          { text: 'YTD' },
        ],
        position: 'Top',
      }}
    >
      <Inject
        services={[
          AreaSeries,
          DateTime,
          RangeTooltip,
          PeriodSelector,
        ]}
      />
      <RangenavigatorSeriesCollectionDirective>
        <RangenavigatorSeriesDirective
          dataSource={data}
          xName="x"
          yName="y"
          type="Area"
        />
      </RangenavigatorSeriesCollectionDirective>
    </RangeNavigatorComponent>
  );
}

export default App;
ReactDOM.render(<App />, document.getElementById('charts'));

模式 3：自定义样式和外观

用户需求： 自定义导航器颜色、滑块和边框

实现：

<RangeNavigatorComponent
  navigatorStyleSettings={{
    selectedRegionColor: 'rgba(33, 150, 243, 0.3)',
    unselectedRegionColor: 'transparent',
    thumb: {
      type: 'Circle',
      fill: '#2196F3',
      border: { width: 2, color: '#ffffff' },
      height: 20,
      width: 20
    }
  }}
  navigatorBorder={{ width: 2, color: '#2196F3' }}
>
  {/* Series configuration */}
</RangeNavigatorComponent>

模式 4：适用于移动设备的轻量模式

用户需求： 为移动设备提供不带图表数据的简单范围选择器

实现：

<RangeNavigatorComponent
  valueType="DateTime"
  value={[new Date(2018, 0, 1), new Date(2018, 6, 1)]}
  intervalType="Months"
>
  <Inject services={[DateTime]} />
  {/* No series - lightweight mode */}
</RangeNavigatorComponent>

模式 5：大范围数据的对数刻度

用户需求： 处理数值跨越多个数量级的数据

实现：

import { RangeNavigatorComponent, LineSeries, Logarithmic, Inject,
  RangenavigatorSeriesCollectionDirective,
  RangenavigatorSeriesDirective } from '@syncfusion/ej2-react-charts';
import * as ReactDOM from "react-dom";

<RangeNavigatorComponent
  valueType="Logarithmic"
  logBase={10}
  minimum={100}
  maximum={100000}
  interval={1}
>
  <Inject services={[LineSeries, Logarithmic]} />
  <RangenavigatorSeriesCollectionDirective>
    <RangenavigatorSeriesDirective
      dataSource={logData}
      xName="x"
      yName="y"
      type="Line"
    />
  </RangenavigatorSeriesCollectionDirective>
</RangeNavigatorComponent>

关键属性

核心配置

• valueType：'Double' | 'DateTime' | 'Logarithmic' - 轴值类型（默认值：'Double'）
• value：number[] | Date[] - 初始选定范围 [start, end]
• minimum：number | Date - 轴的最小值
• maximum：number | Date - 轴的最大值
• interval：number - 轴间隔
• intervalType：DateTime 的间隔类型（'Auto' | 'Years' | 'Quarter' | 'Months' | 'Weeks' | 'Days' | 'Hours' | 'Minutes' | 'Seconds'）

系列配置

• series：包含 dataSource、xName、yName、type 的系列对象数组
• dataSource：系列的数据数组
• xName：x 轴值的字段名称
• yName：y 轴值的字段名称
• type：'Line' | 'Area' | 'StepLine' - 系列渲染类型

外观

• navigatorStyleSettings：自定义选中/未选中区域和滑块
• navigatorBorder：边框宽度和颜色
• theme：'Material' | 'Bootstrap' | 'Fabric' | 'Fluent' | 'Tailwind'

功能

• tooltip：工具提示配置（启用、填充、透明度、textStyle、labelFormat）
• periodSelectorSettings：时间段选择器配置（时间段、位置、高度）
• enableDeferredUpdate：拖动完成后触发更改事件（默认值：false）
• allowSnapping：将滑块吸附到最近的间隔（默认值：false）
• enableGrouping：为 DateTime 启用多级标签（默认值：false）
• groupBy：多级标签的分组间隔类型
• labelPosition：'Outside' | 'Inside' - 标签位置
• enableRtl：启用从右到左的渲染

事件

• changed：范围选择更改时触发
• load：渲染前触发
• loaded：渲染后触发
• tooltipRender：工具提示渲染前触发

常见用例

用例 1：带范围导航的股票图表

实现一个带范围选择功能的金融股票图表，以分析价格随时间变化的趋势。使用 DateTime 轴、Area 系列和时间段选择器，以便快速选择时间范围。

用例 2：仪表板数据筛选

将 Range Navigator 与 Data Grid 集成，根据日期或数值范围筛选大型数据集。使用 changed 事件更新网格数据源。

用例 3：历史数据分析

通过提供直观的范围选择功能，并使用工具提示显示精确值，分析历史销售、天气或分析数据。

用例 4：适用于移动设备的导航

在无需渲染图表的移动应用中使用轻量模式，提供简单的范围选择界面。

用例 5：多数量级数据可视化

使用对数刻度显示跨越多个数量级（10^-6 至 10^6）的科学或金融数据。

模块注入要求

Range Navigator 的特定功能需要注入模块：

import { Inject } from '@syncfusion/ej2-react-charts';

// For Area series
import { AreaSeries } from '@syncfusion/ej2-react-charts';
<Inject services={[AreaSeries]} />

// For DateTime axis
import { DateTime } from '@syncfusion/ej2-react-charts';
<Inject services={[DateTime]} />

// For tooltips
import { RangeTooltip } from '@syncfusion/ej2-react-charts';
<Inject services={[RangeTooltip]} />

// For period selector
import { PeriodSelector } from '@syncfusion/ej2-react-charts';
<Inject services={[PeriodSelector]} />

// For logarithmic scale
import { Logarithmic } from '@syncfusion/ej2-react-charts';
<Inject services={[Logarithmic]} />

// For line series
import { LineSeries } from '@syncfusion/ej2-react-charts';
<Inject services={[LineSeries]} />

// For step line series
import { StepLineSeries } from '@syncfusion/ej2-react-charts';
<Inject services={[StepLineSeries]} />

请根据所用功能，在单个 Inject 组件中始终注入所有必需模块。