当前位置： 首页 > news >正文

@highcharts/react完整技术指南｜新版Highcharts React使用、迁移、SSR、TS 优化全解

news 2026/7/8 14:47:17

一、@highcharts/react 迭代背景与安装

1. 迭代背景

在 React 数据可视化领域，Highcharts 长期依靠highcharts-react-official作为官方适配包，但该包仅对原生 Highcharts 做浅层封装，API 偏命令式，与 React 原生组件化、响应式开发范式偏离。

@highcharts/react是什么？

@highcharts/react是 Highcharts 官方 React 集成包，用来在 React 应用中以组件化方式渲染 Highcharts 图表。

Highsoft 官方推出全新一代官方包@highcharts/react，完全重构底层架构，采用原生 JSX 组件设计，深度适配 React 18.3.1+、TypeScript、Next.js 现代开发体系。新版抛弃旧式配置对象写法，以组件嵌套形式构建图表，支持自动响应状态变更、按需导入打包、图表内渲染原生 React 组件，是替代旧版highcharts-react-official的标准官方方案，迁移成本低、性能与开发体验大幅提升。

中文官方文档介绍地址：https://highcharts.com.cn/integrations/react/https://highcharts.com.cn/integrations/react/

2. 项目安装命令

# npm 安装 npm install @highcharts/react highcharts # yarn 安装 yarn add @highcharts/react highcharts # pnpm 安装 pnpm add @highcharts/react highcharts

3.基础用法

新版推荐使用组件式 API，而不是老的highcharts-react-official。

3.1 一个最小可运行图表示例

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Chart, Title } from '@highcharts/react'; import { LineSeries } from '@highcharts/react/series/Line'; function App() { return ( <Chart> <Title>Monthly Revenue</Title> <LineSeries data={[1, 3, 2, 5, 4]} /> </Chart> ); } createRoot(document.getElementById('container')!).render(<App />);

3.2 轴、提示、图例

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Chart, Title, XAxis, YAxis, Tooltip, Legend } from '@highcharts/react'; import { ColumnSeries } from '@highcharts/react/series/Column'; function App() { return ( <Chart> <Title>Sales</Title> <XAxis categories={['Jan', 'Feb', 'Mar', 'Apr']} /> <YAxis> Revenue </YAxis> <Tooltip shared /> <Legend /> <ColumnSeries name="2026" data={[29, 71, 106, 129]} /> </Chart> ); } createRoot(document.getElementById('container')!).render(<App />);

4. 组件式配置思想

新版@highcharts/react的重点是：

  • 用组件表达 chart 结构
  • 常用配置直接作为 prop
  • 复杂、稀有、事件型配置放到options

4.1 推荐模式

  • Chart：图表根容器
  • Title / Subtitle / Credits
  • XAxis / YAxis
  • Tooltip / Legend
  • 各种Series
  • 模块组件：Accessibility / Exporting / Drilldown / Boost

4.2options默认作为兜底

当某个配置很深、很长、或事件特别多时，可以直接传options。

<Chart options={{ chart: { backgroundColor: '#fff' }, plotOptions: { series: { animation: false } } }} > <Title>Chart</Title> </Chart>

注意：如果同一项在组件和options同时定义，options通常会覆盖前者，所以不要重复定义同一个字段，除非你就是要覆盖。

5. 系列使用方式

新版推荐尽量用专用系列组件，比如：

  • LineSeries
  • ColumnSeries
  • PieSeries
  • ScatterSeries
  • CandlestickSeries
  • MapSeries
  • GanttSeries

5.1 线图

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Chart, Title } from '@highcharts/react'; import { LineSeries } from '@highcharts/react/series/Line'; function App() { return ( <Chart> <Title>Line Demo</Title> <LineSeries data={[1, 2, 3, 4, 5]} /> </Chart> ); } createRoot(document.getElementById('container')!).render(<App />);

5.2 多序列

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Chart, Title, XAxis, Legend } from '@highcharts/react'; import { LineSeries } from '@highcharts/react/series/Line'; function App() { return ( <Chart> <Title>Multi Series</Title> <XAxis categories={['Mon', 'Tue', 'Wed', 'Thu', 'Fri']} /> <Legend /> <LineSeries name="A" data={[1, 3, 2, 4, 5]} /> <LineSeries name="B" data={[2, 2, 3, 3, 4]} /> </Chart> ); } createRoot(document.getElementById('container')!).render(<App />);

6. 模块加载

新版 v5 推荐用模块组件，而不是老的highcharts/modules/*方式。

6.1 常见模块

  • Accessibility
  • Exporting
  • Drilldown
  • Boost
  • Data
  • StockTools

示例：无障碍 + 导出

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Chart, Title } from '@highcharts/react'; import { Accessibility } from '@highcharts/react/modules/Accessibility'; import { Exporting } from '@highcharts/react/modules/Exporting'; import { LineSeries } from '@highcharts/react/series/Line'; function App() { return ( <Chart> <Title>Accessible Exportable Chart</Title> <Accessibility /> <Exporting /> <LineSeries data={[1, 2, 3, 4, 5]} /> </Chart> ); } createRoot(document.getElementById('container')!).render(<App />);

6.2 没有 React 模块组件时

如果某个模块没有对应 React 组件，可以使用 Highcharts ESM 入口，例如：

import 'highcharts/es-modules/masters/modules/marker-clusters.src.js';

不要在新版里优先使用旧的 UMD 方式。

7. Stock股票图 / Maps地理图 / Gantt甘特图产品

这三类产品建议使用各自的根组件：

  • StockChart
  • MapsChart
  • GanttChart

7.1 Stock常用于金融股票图表

import React from 'react'; import { createRoot } from 'react-dom/client'; import { StockChart } from '@highcharts/react/Stock'; import { CandlestickSeries } from '@highcharts/react/series/Candlestick'; function App() { return ( <StockChart> <CandlestickSeries data={[ [1704067200000, 100, 110, 95, 107], [1704153600000, 107, 114, 101, 109], [1704240000000, 109, 116, 104, 112] ]} /> </StockChart> ); } createRoot(document.getElementById('container')!).render(<App />);

7.2 Maps用于创建地理相关的交互式地图

import React, { useEffect, useState } from 'react'; import { createRoot } from 'react-dom/client'; import { MapsChart } from '@highcharts/react/Maps'; import { MapSeries } from '@highcharts/react/series/Map'; import { Title } from '@highcharts/react'; function App() { const [topology, setTopology] = useState<any>(null); useEffect(() => { fetch('https://code.highcharts.com/mapdata/custom/world.topo.json') .then((res) => res.json()) .then(setTopology); }, []); if (!topology) return <div>Loading map...</div>; return ( <MapsChart options={{ chart: { map: topology } }}> <Title>World Map</Title> <MapSeries data={[ { 'hc-key': 'us', value: 1 }, { 'hc-key': 'gb', value: 2 } ]} /> </MapsChart> ); } createRoot(document.getElementById('container')!).render(<App />);

7.3 Gantt用时间轴创建任务、资源和事件的甘特图

import React from 'react'; import { createRoot } from 'react-dom/client'; import { GanttChart } from '@highcharts/react/Gantt'; import { GanttSeries } from '@highcharts/react/series/Gantt'; import { Title } from '@highcharts/react'; function App() { return ( <

二、六大核心技术特性

1. 原生响应式设计，自动绑定 React 状态

@highcharts/react 从底层贴合 React 响应式思想，无需手动执行chart.update()更新图表：

  1. 图表数据可直接绑定useState、useReducer；
  2. 完全兼容 Redux、Zustand、Jotai 等主流全局状态管理工具；
  3. 仅对发生变更的数据系列局部重渲染，无多余 DOM 开销，渲染性能更优。

2. TypeScript 原生内置类型，无需额外 @types 包

不同于多数第三方图表库需要单独安装类型声明包，该库完整 TS 类型内置在 npm 包内：

  1. VS Code、WebStorm 等 TS 编辑器提供全量自动补全，图表配置、组件 Props、事件回调均有强类型约束；
  2. 完美支持 TS 严格模式strict: true与现代打包配置moduleResolution: bundler；
  3. 编译阶段拦截配置拼写错误、参数类型错误，大幅减少线上图表报错。

3. 开箱即用 Next.js & SSR 服务端渲染适配

针对 Next.js App Router、Pages Router 做专属兼容，解决图表客户端渲染冲突问题：

  1. 图表组件顶部添加'use client'标记即可转为客户端组件；
  2. 支持服务端组件拉取接口数据，通过 Props 传递给图表组件；
  3. 无需额外 DOM 兼容垫片、无复杂 SSR 配置，开箱即用。

4. 图表内部直接嵌入原生 React 自定义组件

这是新版核心升级亮点，彻底摆脱传统图表dangerouslySetInnerHTML注入 HTML 的方案：

  1. Tooltip 悬浮弹窗、数据标签、点位渲染器内可直接使用项目业务 React 组件；
  2. 渲染真实 React 节点，可复用全局样式、自定义 Hooks；
  3. 规避 HTML 字符串拼接带来的 XSS 安全风险，统一项目开发范式。

5. ES Module 深度导入，支持 Tree-Shaking 打包优化

库提供细分路径导入，适配 Vite、Webpack、Turbopack 等打包工具实现精准按需加载：

  1. 可单独引入折线、柱状、气泡等单一图表组件，不加载全部图表代码；
  2. 打包工具自动剔除未使用模块，显著降低生产环境打包体积；
  3. 轻量化后台、移动端可视化项目可大幅缩减包大小。

6. 全品类图表 JSX 组件全覆盖

Highcharts 全系可视化图表均提供独立 JSX 组件，语义化导入，结构清晰：

  1. 基础图表：折线、柱状、面积、气泡等基础系列组件；
  2. 专业场景图表：金融股票图<StockChart>、地理地图<MapChart>、项目甘特图<GanttChart>；
  3. 配套 Dashboards 大屏组件，一站式搭建数据看板页面。

三、完整实战代码示例（气泡图 / Next.js 示例）

示例 1：基础气泡图（React 原生组件示例）

// @highcharts/react 气泡图基础示例，state自动驱动图表更新 import { useState } from 'react'; import { Chart, BubbleSeries } from '@highcharts/react'; export default function BubbleDemo() { // React状态存储气泡数据，状态变更图表自动刷新 const [series1, setSeries1] = useState([[10, 20, 30], [30, 50, 15]]); const [series2, setSeries2] = useState([[50, 10, 22], [80, 60, 40]]); return ( <Chart title={{ text: '气泡图演示' }}> {/* 两组气泡数据系列 */} <BubbleSeries name="Blue bubbles" data={series1} /> <BubbleSeries name="Purple bubbles" data={series2} /> </Chart> ); }

示例 2：Next.js App Router SSR 图表示例

// app/bubble/page.tsx 客户端图表组件，必须添加'use client' 'use client'; import { Chart, BubbleSeries } from '@highcharts/react'; // 接收服务端组件传递的图表数据 export default function NextBubbleChart({ chartData }) { return ( <Chart title={{ text: 'Next.js SSR气泡图' }}> <BubbleSeries data={chartData.series1} /> <BubbleSeries data={chartData.series2} /> </Chart> ); }
// app/page.tsx 服务端组件，服务端拉取数据 import NextBubbleChart from './bubble/page'; export default async function Home() { // 服务端请求接口获取图表数据 const res = await fetch('https://xxx/api/chart-data'); const chartData = await res.json(); return ( <main> <h1>Next.js 服务端取数 + 客户端渲染图表</h1> <NextBubbleChart chartData={chartData} /> </main> ); }

四、从 highcharts-react-official 迁移步骤

步骤 1：卸载旧版依赖包

bash运行

npm uninstall highcharts-react-official highcharts

步骤 2：安装新版官方 @highcharts/react

npm install @highcharts/react highcharts

步骤 3：修改组件导入方式

旧版 highcharts-react-official 写法：

import Highcharts from 'highcharts'; import HighchartsReact from 'highcharts-react-official';

新版 JSX 组件化写法：

import { Chart, BubbleSeries, LineSeries, Title } from '@highcharts/react';

步骤 4：重构图表渲染逻辑

  1. 移除旧版完整options配置对象，改用嵌套 JSX 组件拆分图表标题、坐标轴、数据系列；
  2. 删除手动chart.update()更新逻辑，直接绑定 useState 状态驱动数据刷新；
  3. 如需自定义弹窗、标签，替换 HTML 字符串渲染为原生 React 组件；
  4. Next.js 项目图表组件添加'use client'标识适配 SSR。

五、@highcharts/react FAQ 问答

Q1：@highcharts/react 和 highcharts-react-official 是什么关系？

A：@highcharts/react是 Highsoft 官方全新的官方组件化 React 集成包，完全替代旧版highcharts-react-official。新版采用原生 JSX 组件架构，渲染速度更快、API 更简洁，整体迁移仅需修改依赖与导入语句，成本极低。

Q2：@highcharts/react 版本兼容要求是什么？

A：最低依赖 React 18.3.1 及以上版本，不支持 React17 及更早版本，搭配对应版本 Highcharts 核心库即可正常运行。当前确认的文档基线是：

  • Highcharts：v12.2+
  • React：v18.0+
  • ReactDOM：v18.0+
  • Node.js：v14.0+（主要用于构建/安装环境）

Q3：使用该库是否需要单独安装 TypeScript 类型包？

A：不需要。完整 TypeScript 声明内置在 npm 包中，安装后直接获得全量类型提示，无需额外安装@types/highcharts-react类包。

Q4：@highcharts/react 是否支持 Next.js 与 SSR 服务端渲染？

A：完全支持。只需在图表组件文件顶部添加'use client'标记，数据可在服务端组件请求后通过 props 传递，无需额外兼容配置。

Q5：@highcharts/react 是什么？

A：@highcharts/react是 Highcharts 官方 React 集成包，用来在 React 应用中以组件化方式渲染 Highcharts 图表。

Q6：如何实现打包体积优化，减少图表代码冗余？

A：使用 ES Module 深度导入，例如import { LineSeries } from '@highcharts/react/series/Line'，仅引入项目使用的图表类型，配合 Vite/Webpack 实现 Tree-Shaking 剔除无用代码。

六、Highcharts 全系列配套产品生态

@highcharts/react 并非独立图表工具，配套完整可视化产品线，覆盖金融、地理、项目管理、数据大屏等全业务场景：

  1. Highcharts Stock：金融时序图表，内置 K 线、分时、各类技术指标，适配股票、理财数据展示；
  2. Highcharts Maps：地理可视化图表，支持区域热力图、航线分布图、省市分层地图；
  3. Highcharts Gantt：项目管理甘特图，可视化任务排期、资源分配、工期节点；
  4. Highcharts Grid：网页交互式表格，提供了一种在网页中进行查看、编辑与拓展功能的表格处理方式。
  5. Highcharts Dashboards：预制大屏仪表盘组件，快速搭建企业数据中台、可视化大屏；
  6. Export Server：图表导出服务，支持用户一键下载 PDF、PNG、JPG、SVG 矢量图片；

七、适用场景与总结

1. 适配项目场景

  1. React 18+、Next.js App Router/Pages Router 前后端分离后台、数据看板；
  2. 使用 TypeScript 严格模式的大型中台、金融、政务、医疗可视化系统；
  3. 需要自定义 Tooltip、数据标签，内嵌业务 React 组件的复杂可视化页面；
  4. 追求打包体积轻量化、需要 Tree-Shaking 优化的移动端、轻量化前端项目；
  5. 金融、项目管理、地理统计类专业图表需求业务系统。

2. 核心优势总结

  1. 原生贴合 React 响应式机制，无需命令式手动更新图表；
  2. TypeScript 类型内置，开箱即用强类型开发体验；
  3. Next.js SSR 零配置兼容，适配现代前端服务端渲染方案；
  4. 支持图表内渲染原生 React 组件，消除 XSS 风险，开发统一；
  5. 细分模块导入，Tree-Shaking 优化打包体积；
  6. 全品类图表 + 完整商用配套生态，覆盖绝大多数可视化需求。

3. 整体总结

@highcharts/react 是当前 React 生态下 Highcharts 官方最优可视化解决方案，彻底解决旧版封装带来的开发割裂问题，兼顾开发效率、渲染性能、打包体积与类型安全。对于有复杂图表、数据大屏开发需求的 React 开发者，选择新版@highcharts/react可大幅降低图表开发、维护与迁移成本。

http://www.jsqmd.com/news/1148323/

相关文章：

  • 从复位向量到内核入口：U-Boot SPL 到 Kernel 启动全链路逐阶段剖析
  • 多级缓存架构落地：从 L1 内存到 L3 磁盘的 RAG 检索缓存分层设计
  • 电气设备配电箱开关保护器件插座检测数据集VOC+YOLO格式4135张10类别有增强
  • 企业级CAD字体管理架构优化：3大性能提升策略实战指南
  • Python Playwright关键字驱动测试框架：从脚本到工程化实战
  • Python 数据管线调度引擎：DAG 编排代替 Cron 硬编码
  • 第十章：Gradle Wrapper
  • 中国车牌生成器：高效自动化车牌数据生成技术实现指南
  • 研究生论文降AI全流程：从初稿到盲审通过4.8元工具组合完整操作指南
  • Next.js DApp 国际化路由：多语言链上术语库与动态内容切换
  • PyTorch混合精度训练完整配置：从AMP初始化到梯度缩放故障排查
  • “轴承制造的精度革命，不只靠一台机床，而是一整套从车削到磨削的‘精密闭环’。”
  • 终极清理指南：如何用MyComputerManager彻底删除Windows此电脑中的顽固图标
  • Zotero SciHub插件技术深度解析：学术文献自动获取的高效方案
  • Layerdivider：三步实现智能图像分层的终极解决方案
  • 3分钟解锁B站缓存视频：m4s转MP4完整指南
  • 终极指南：如何通过defender-control实现Windows Defender永久禁用与精细控制
  • 原来专业高铁标识有这么多门道，到底哪家好？
  • 相机成像模型 EMVA1288 解析：从辐射亮度 L 到像素灰度值的 4 个关键参数
  • Poppins字体终极指南：如何用免费几何字体解决多语言设计难题？
  • PowerToys：重新定义Windows生产力的瑞士军刀
  • TPD2015FN智能功率开关在工业负载控制中的应用
  • Starlight：基于 Astro 的文档网站框架，8.7K Star
  • 音乐文件被平台锁定了怎么办？这款免费工具让你真正拥有音乐
  • 高效判断回文链表的3种解法
  • BPF安全监控：能力、配置与策略实践
  • 模型推理成本可视化：从Token消耗到预算告警的监控体系
  • 2026年选F1级耐火桥架，专业公司保障安全无忧
  • 数字 IC 求职加分项：10 节课吃透大厂必考 Verilog 全考点
  • 【SkyWalking从入门到精通】第19篇：用SkyWalking提取关键路径：找到拖慢全军的瓶颈链路