简介：面向.NET桌面开发者的WinForm与ECharts集成示例，核心解决桌面应用中动态数据可视化及前后端交互问题。项目演示通过WebBrowser控件加载HTML，借助InvokeScript将C#侧的新数据推送到ECharts并执行setOption，同时监听ECharts点击等事件回传WinForm，实现网页图表与桌面客户端的双向通信，并在C#与JavaScript之间建立了清晰的数据通道。适合有C#基础、想快速掌握内嵌HTML图表交互的开发者学习与复用。压缩包共39个文件，以7个cs源码、4个js脚本、2个html图表页、2个resx资源及sln工程文件为主，另有pdb调试信息、exe可执行程序、docx说明文档和settings配置文件，便于查阅运行，整体仅1.28MB。已有724人学习下载。通过该完整案例可梳理从创建HTML、挂载WebBrowser到数据更新与事件回调的流程；工程目录结构清晰，并附带说明文档与配置，方便对照修改、二次集成到实际业务中，实现前后端代码分离，降低维护成本。
1. WinForm 与内嵌 ECharts：让数据动起来的组合拳
工控项目和后台管理系统的开发里，经常出现一种尴尬：生产过程数据已经实时进到 C# 后台了，但界面还是黑压压的表格。用 WinForm 自带 Chart 画个静态折线还行，一旦要实现动态刷新、点击下钻、大屏看板，开发量就翻着倍涨。而 ECharts 恰好解决图表表现力的问题，它跑在浏览器里，WinForm 只需要提供一个宿主容器，数据通过内置对象传给前端 JS，再把图表点击事件回传给 C#，两端就这样直接对话。这个资源包就是一个完整的 WinForm + ECharts 交互 Demo，折线图、柱状图、饼图都能实时联动。适合用 C# 做桌面端、想把数据可视化做得像 Web 端一样灵活、又不想额外起 Web 服务的开发者。下面会把交互机制、具体写法、翻车点和封装技巧都过一遍。
2. 选型与原理：为什么桌面端也敢用 ECharts，交互桥是怎么搭起来的
2.1 ECharts 凭什么比原生 Chart 更值得嵌
WinForm 自带 Chart 控件不是不能用，但遇到两类项目就很痛苦：一是数据点成千上万、而且持续追加，原生控件刷新经常抖动、CPU 拉高；二是界面要做得像大屏看板，带渐变色、数据缩放、点击下钻，原生控件一样样画过去工程量非常大。ECharts 是纯 Canvas 渲染，折线图、柱状图、饼图、仪表盘随手一套就能出效果，渐变背景、区域着色、x 轴刻度控制都有现成 API。更重要的是它有完整的事件体系，点击、悬停、缩放都能触发 JS 回调，这正好是 WinForm 原生控件不擅长的地方。
在实际开发里，我最看中的是「配置项驱动」。ECharts 的 setOption 传入一个 JSON 对象，图表就按里面的配置重绘。这意味着 C# 端只需要把数据组装成 JSON，通过 InvokeScript 塞进去，前端代码几乎不用改。数据结构变了就改 JSON 结构，界面想动就改 option 里的 series、color 字段，C# 和 JS 的耦合被压到最低。
2.2 WebBrowser 还是 WebView2：先把宿主内核选清楚
WinForm 里能用宿主控件，一个是老牌的 WebBrowser，一个是微软后来的 WebView2。WebBrowser 基于 IE 内核，.NET 里直接拖就能用，发布时不需要额外运行时，但默认兼容模式对 ES6 支持不理想，新版 ECharts 在这个壳里容易白屏。WebView2 基于 Chromium 内核，需要机器上有 WebView2 Runtime，发布包多一个依赖，但 JS 和 Canvas 表现和 Chrome 一致，调试工具也对齐 Chromium。这个资源包的示例以 WebBrowser 为主，因为老一批 WinForm 项目根本装不了 WebView2，照 WebBrowser 的写法上手最直接。
如果项目从零开始、允许安装依赖，我会建议直接选 WebView2：ECharts 换版本不用迁就浏览器，跨线程调用也更稳定。如果目标机器是 XP、Win7 这种老环境，或者公司禁止额外运行时，那还是 WebBrowser 稳当。同一套 HTML 和 ECharts 配置在两个宿主上基本通用，差的只是加载和调用 API，后面会给出两侧写法。
2.3 ObjectForScripting 双向通信：本质是对象穿过 COM 边界
C# 和页面 JS 的交互不靠 HTTP，而是靠浏览器控件的脚本桥接。WebBrowser 提供了ObjectForScripting，把一个标记了 ComVisible 的类实例暴露给页面，页面里通过window.external就能调用这个类的方法。反过来，C# 通过Document.InvokeScript调用页面里定义的 JS 函数，参数用 object 数组传，返回值可以是字符串或基础类型。
这个桥有个关键限制：能跨边的只能是基础类型。C# 传对象给 JS，需要先序列化成 JSON 字符串；JS 回调给 C#，也必须把数据拼成字符串或数字，不能直接把 JS 对象丢过来。资源包里所有交互都遵循这个契约，所以不会出现卡死或者参数丢失。
一个典型的桥接类长这样：
[ComVisible(true)] public class Bridge { private readonly Form1 _form; public Bridge(Form1 form) { _form = form; } public void onChartClick(string json) { _form.HandleChartClick(json); } }类上必须加[ComVisible(true)]，否则运行时直接报“无法使对象可用于脚本”。window.external.onChartClick(...)就是调用到这个方法。JS 端每次只传字符串，C# 端拿到再反序列化成自己的模型，两边各管各的数据结构，这套模式我用了两年没出过问题。
3. 把 ECharts 页面塞进 WinForm：三步搭出可交互图表的壳子
3.1 准备 HTML 模板与 ECharts 资源：文件路径是第一个全局变量
拿到资源包后，先把里面的 html 目录完整拷进 vs 项目的根目录，目录里通常有 index.html 和 echarts.min.js。右键这两个文件，在属性里把“复制到输出目录”改成“始终复制”。这样生成后它们会出现在 bin\Debug 下面，发布时也会跟着走。路径上建议用英文目录，中文路径在旧版 IE 内核里偶尔会解析出问题。
我的习惯是在程序里用Application.StartupPath拼绝对路径，而不是依赖当前工作目录：
var pagePath = Path.Combine(Application.StartupPath, "html", "index.html"); webBrowser1.Navigate(pagePath);这里用 StartupPath 的原因是桌面程序一旦被快捷方式启动，当前工作目录可能不在 exe 所在目录，用相对路径就容易摸不到文件。这一步看着小，但后面避坑章节里的白屏问题，八成都是从这里开始的。
3.2 index.html 里的 ECharts 初始化与页面回调
资源包里的 index.html 核心逻辑是：初始化 ECharts、向 C# 暴露一个updateData函数、绑定图表点击事件。一个精简可用的模板是这样：
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <title>ChartPage</title> <script src="echarts.min.js"></script> <style> html, body, #main { width: 100%; height: 100%; margin: 0; } </style> </head> <body> <div id="main"></div> <script> var chart = echarts.init(document.getElementById('main')); function updateData(jsonStr) { var data = JSON.parse(jsonStr); chart.setOption({ xAxis: { type: 'category', data: data.categories }, yAxis: { type: 'value' }, series: [{ type: data.chartType || 'line', data: data.values }] }); } chart.on('click', function (params) { if (window.external && window.external.onChartClick) { window.external.onChartClick(JSON.stringify({ name: params.name, value: params.value, seriesName: params.seriesName })); } }); </script> </body> </html>meta X-UA-Compatible那行是给 WebBrowser 用的，强制它切到 Edge 模式渲染，ES6 解析和 Canvas 性能都会好一点。chart.init必须在页面宽度确定之后执行，所以初始化放在 body 底部，并且把容器 #main 撑满整个页面。
updateData是整个项目的前端入口，C# 只要调用这个函数，就能把运行时数据灌进图表。chart.on('click')是页面侧的事件出口，图表里每一次点击，最终都变成对 C# 方法的调用。这一进一出，双向通路就算建成了。
3.3 在 Form 里加载页面并注册交互桥
在 WinForm 设计器里拖一个 WebBrowser 控件，Dock 设为 Fill。然后在窗体的构造函数里注册交互桥，在 Load 事件里导航到页面：
public partial class Form1 : Form { public Form1() { InitializeComponent(); webBrowser1.ObjectForScripting = new Bridge(this); webBrowser1.DocumentCompleted += WebBrowser1_DocumentCompleted; } private void Form1_Load(object sender, EventArgs e) { var pagePath = Path.Combine(Application.StartupPath, "html", "index.html"); webBrowser1.Navigate(pagePath); } private void WebBrowser1_DocumentCompleted(object sender, WebBrowserDocumentCompletedEventArgs e) { if (e.Url != webBrowser1.Document?.Url) return; PushData(ChartModel.DemoData()); } }这里ObjectForScripting必须在Navigate之前赋值，赋值的是窗体自身关联的 Bridge 实例，Bridge 里再持有窗体引用。DocumentCompleted事件会触发多次，子框架加载也会触发一次，所以需要用e.Url == Document.Url判断一下，等真正的主页面加载完再推送数据。
e.Url != webBrowser1.Document?.Url这种写法在 Document 为空时会有小坑，实际项目里也可以直接判断e.Url.AbsolutePath.EndsWith("index.html")。目的是同一个：只处理最外层页面。
3.4 用 InvokeScript 把 C# 数据推给 ECharts
页面里的updateData等着 JSON 字符串进来，C# 端要把数据模型序列化后推送过去。我一般定义一个简单的 DTO：
public class ChartModel { public List<string> categories { get; set; } public List<double> values { get; set; } public string chartType { get; set; } }序列化和推送的过程：
private void PushData(ChartModel data) { if (webBrowser1.Document == null) return; string json = JsonConvert.SerializeObject(data); webBrowser1.Document.InvokeScript("updateData", new object[] { json }); }这里用 Newtonsoft.Json 序列化，字段名和 JS 里读取的键保持一致，都用小写开头。InvokeScript的第一个参数是页面里的函数名，第二个参数是传给该函数的实参数组。函数名大小写要完全一致，JS 里叫updateData，这边就不能写UpdateData。
如果项目不想引入第三方序列化库，也可以直接用 JavaScriptSerializer 或System.Text.Json，但要注意字段名策略，默认可能是首字母大写，需要在 JS 端做适配。资源包里统一用 Newtonsoft.Json，序列化和反序列化都不用手拼字符串，改动最省事。
4. 让数据动起来：定时刷新、JSON 序列化与事件回传
4.1 定时器驱动实时折线图：别用 while + Sleep
很多人第一次做动态图，第一反应是在后台线程里 while(true) 发数据，结果界面卡死。WinForm 里的标准做法是用System.Windows.Forms.Timer，它跑在 UI 线程上，每个 Tick 事件里直接更新图表，不需要跨线程调度：
private Timer _timer; private int _index = 0; private Random _random = new Random(); private void StartTimer() { _timer = new Timer { Interval = 1000 }; _timer.Tick += (s, e) => { _index++; var data = new ChartModel { categories = new List<string> { DateTime.Now.ToString("HH:mm:ss") }, values = new List<double> { _random.Next(20, 80) }, chartType = "line" }; PushData(data); }; _timer.Start(); }如果只把最新一点数据传过去，图表会覆盖旧的。最常见的效果是滚动折线图，也就是保留最近 N 个点。这里有两种思路：一是 C# 端保存完整历史集合，每次把最近 N 条全部序列化传过去；二是前端拿到新点后自己 push，再配合 dataZoom 只显示尾部窗口。项目简单就用第一种，逻辑都在 C# 端，好调试。
当时间点越来越多，x 轴刻度会挤成一团。ECharts 里可以用axisLabel.interval控制显示密度，或者用 dataZoom 控制可视范围：
xAxis: { type: 'category', data: data.categories, axisLabel: { interval: Math.floor(data.categories.length / 6), rotate: 30 } }interval 按总数据量除一个合适的值，让横轴始终保持五六个刻度，不再糊在一起。这个在资源包的折线图里已经配好，自己接数据时改一下除数就行。
4.2 图表点击回传：从 params 对象到 C# 命令
图表交互不只是“看”，经常要做点击下钻或者点击展示详情。前面 HTML 里已经绑定过chart.on('click')，关键是回传内容。ECharts 的 click 回调收到一个 params 对象，它包含 name、value、seriesName 等字段。COM 桥只能传基础类型，所以 JS 里先JSON.stringify再调用 C#：
chart.on('click', function (params) { if (window.external && window.external.onChartClick) { window.external.onChartClick(JSON.stringify({ name: params.name, value: params.value, seriesName: params.seriesName })); } });C# 端 Bridge 里对应方法拿到字符串后，再用 Newtonsoft.Json 反序列化成一个点击模型：
public void onChartClick(string json) { var model = JsonConvert.DeserializeObject<ChartClickModel>(json); MessageBox.Show($"你点击了 {model.name}，数值是 {model.value}"); }注意方法名大小写和 JS 里完全一致。COM 边界不支持重载，Bridge 类里每个方法名都要唯一。如果业务复杂，可以在 C# 端根据 SeriesName 分发到不同命令，比如“温度”走实时详情，“产量”走趋势报表。这样页面侧只是透传，真正的业务判断都在 C# 层，逻辑不容易混乱。
4.3 setOption 的 notMerge 和 appendData：动态更新的两种姿势
ECharts 的 setOption 默认是“合并”模式：如果新旧 option 里都有 series，会按 index 合并而不是覆盖。这在第一次加载时很友好，但动态刷新时会造成旧序列残留、新序列数量对不上。如果每次数据都是完全替换的完整快照，我建议直接强制替换：
chart.setOption(newOption, true);第二个参数notMerge = true意味着整体替换，旧的 series、坐标轴配置都会被清掉重新构建。代价是每次刷新图表状态都重新计算，数据点特别多时会有卡顿风险。
另一种更轻量的方式是appendData，它专门用于大数据量滚动场景。初始化时需要给 series 设置large: true，然后后端每隔一段时间只追加这一段数据：
chart.appendData({ seriesIndex: 0, data: [[newTime, newValue]] });这种方式不会每次都重绘整个图，遇到每秒几十个点的监控数据依然流畅。但 appendData 要求数据格式必须是二维数组，而且 xAxis 需要用 time 或 value 类型，和类目轴不太兼容。所以小数据量快照用 notMerge 彻底替换，大数据量流式场景用 appendData 增量追加，不要混着用。
5. 避坑与排查：内嵌 ECharts 最常见的六个翻车现场
5.1 页面白屏，但 HTML 单独打开没问题
现象：WinForm 里运行后整个区域一片空白，把 html 文件用 Chrome 打开却是正常的。
原因：第一是 echarts.min.js 或 index.html 没有复制到输出目录，程序运行时在 Application.StartupPath 下面根本找不到这些文件；第二是 WebBrowser 默认兼容模式停留在 IE7，新版 ECharts 的 ES6 语法把它直接卡死，页面解析失败。
解决：把 html 和 js 文件的“复制到输出目录”改为“始终复制”。然后在 HTML 的 head 里加上<meta http-equiv="X-UA-Compatible" content="IE=edge" />，强制内核走 Edge 模式。如果加了还白屏，用 WebBrowser 的Document.Title或DocumentText打个日志看看页面的真实报错，基本上路径问题会在这一步暴露。
5.2 window.external 为空，点击事件没反应
现象：图表正常显示，但单击图表 C# 端没有收到任何消息，甚至 JS 里调用 window.external 直接报错。
原因：ObjectForScripting没有赋值，或者赋值给了没有[ComVisible(true)]标记的类，也可能是 Bridge 类不是 public。还有一部分人是在DocumentCompleted之后再赋值，这时页面脚本已经初始化完毕，window.external 不会重新绑定。
解决：在构造函数里、Navigate 之前完成这样三件事——把 Bridge 类改成 public，加上[ComVisible(true)]，然后webBrowser1.ObjectForScripting = new Bridge(this);。赋值之后不要轻易换实例。JS 端调用前多做一层判断，if (window.external && window.external.onChartClick)，就算 C# 侧没注册，前端也不至于报异常中断流程。
5.3 数据越刷越多，旧图不消失
现象：每次定时刷新后，折线图里能看到上一次的数据曲线还压在下面，新旧混在一起。
原因：setOption 默认是 merge 合并，不是整体替换。当新数据比旧数据少，或 series 结构不完全一致，旧的 series 或坐标轴配置会被保留，视觉上就是两条线叠在一起。
解决：后端更新使用chart.setOption(option, true)，强制 notMerge。如果想整个图从头来，也可以先chart.clear()再 setOption，但要记住 clear 会把之前绑定的事件监听一并清掉，需要重新绑定 click。而 notMerge 只替换数据和配置，事件监听还在，更适合动态刷新场景。
5.4 窗体一拉大，图表不变形也不自适应
现象：窗体最大化之后，图表仍然保持原来的尺寸，四周留白或出现滚动条。
原因：ECharts 初始化时会按容器当前尺寸创建 Canvas，之后容器尺寸变了，Canvas 并不会自动跟着变。WinForm 里 WebBrowser 控件的页面 window resize 事件有时延迟，导致 chart.resize() 没有被触发。
解决：在 HTML 里监听 window.resize，重新调用 chart.resize()：
window.addEventListener('resize', function () { chart.resize(); });如果发现 WebBrowser 缩放在部分系统上不触发 resize，可以加一个兜底，在窗体 Resize 事件结束里通过 InvokeScript 调用一个同名 JS 函数。注意 debounce，鼠标拖拽时 resize 会连续触发多次，js 里可以做个延时处理，避免每帧都在重绘 Canvas。
5.5 后台线程更新数据，界面卡死或报跨线程错误
现象：用 Task 或 Thread 每 100ms 产数据，然后直接调用 InvokeScript，WinForm 界面卡住，或者抛出“调用线程无法访问此控件”的异常。
原因：WebBrowser 控件属于 UI 线程，通过 Document.InvokeScript 操作它必须回到 UI 线程。一旦在后台线程直接操作，轻则等待卡死，重则抛跨线程异常。
解决：把数据推送给 UI 的代码包到 BeginInvoke 里：
Task.Run(() => { var json = BuildNewDataJson(); webBrowser1.BeginInvoke((Action)(() => webBrowser1.Document.InvokeScript("updateData", new object[] { json }))); });用 BeginInvoke 而不是 Invoke，是为了避免后台线程阻塞等待 UI 线程处理，防止数据更新过快时积压造成界面卡顿。数据频率不高的话，直接用System.Windows.Forms.Timer最省事，它本身就跑在 UI 线程，不用跨线程调度。
5.6 发布后图表没了，F5 运行却正常
现象：开发目录里按 F5 一切正常，但把 exe 和依赖拷贝到别的机器运行，页面区域变成空白。
原因：html 和 echarts.min.js 如果没有设置“始终复制”，发布时不会进入输出目录。即便设置了复制，有些部署方式会把 exe 拷走，html 目录没有跟着拷贝，程序自然找不到页面。
解决：先检查发布目录下是否存在 html 文件夹和 index.html。防呆的做法是在 Form 加载时检查路径，文件缺失就弹一个明显提示，避免用户对着白屏猜。更稳妥的是把 html 和 js 作为嵌入资源编译进程序集，运行时解压到临时目录再 Navigate，这样只有一个 exe，不会丢文件。需要注意NavigateToString会使 ObjectForScripting 的桥接不稳定，尽量不要用，解压到临时目录这种方案最保险。
6. 进阶：把整套图表封装成 UserControl 与主题复用
用 WebBrowser 嵌 ECharts 最爽的，是业务代码和前端代码可以彻底分层。但如果不做封装，每次新建窗口都要拖控件、写 DocumentCompleted、写 InvokeScript，复制粘贴多了也容易出错。我一般会把这套逻辑封装成一个ChartHost用户控件，对外只暴露一两个方法。
封装思路是这样的：
public partial class ChartHost : UserControl { public ChartHost() { InitializeComponent(); webBrowser1.ObjectForScripting = new HostBridge(this); webBrowser1.DocumentCompleted += (s, e) => { if (e.Url == webBrowser1.Document?.Url && DocumentReady != null) { DocumentReady(this, EventArgs.Empty); } }; } public event EventHandler DocumentReady; public void ShowData(string json) { if (webBrowser1.Document != null) { webBrowser1.Document.InvokeScript("updateData", new object[] { json }); } } public void ApplyTheme(string themeJson) { if (webBrowser1.Document != null) { webBrowser1.Document.InvokeScript("applyTheme", new object[] { themeJson }); } } }桥接类依然要做 ComVisible，但可以做成内部私有，对外只暴露 ShowData 和 ApplyTheme。业务层不再关心 Document、Navigator，只要序列化好 JSON 往里丢就行。这也让后续换 WebView2 时，只需要动 ChartHost 内部，业务窗体代码几乎不用改。
主题这块我也建议从 C# 控制。可以定义一个 theme.json，里面写背景色、系列颜色、字体样式，HTML 初始化时先读取全局变量再创建图表：
{ "backgroundColor": "#0f1a2a", "color": ["#3dd68c", "#f7b731", "#fc5c65"], "fontSize": 14 }JS 端在 init 前把主题配置合并进 option：
chart.setOption({ backgroundColor: chartTheme.backgroundColor, color: chartTheme.color, textStyle: { fontSize: chartTheme.fontSize } });这样一来，界面美化完全可以靠改配置文件完成，不需要重新编译 exe。现场交付时，我经常直接改 JSON 里的配色和上下轨参数，图表样式跟着变，客户还以为我临时写了套新界面。
从第一次踩白屏坑到现在，我每次接手 WinForm 图表需求都强制自己走一遍这套流程：先定宿主内核，再搭 HTML 模板，再封装 UserControl，最后把数据和主题接上。把这四步固定住，项目再多也只是往里填图表配置，不会再被浏览器兼容问题拖住。希望帮到你。
本文还有配套的精品资源，点击获取
