微信小程序 ECharts 图表：ec-canvas 接入与性能优化

小程序里画图表这件事，我前后折腾过不少项目。早年用原生 canvas 手撸柱状图，简单场景还行，一旦客户要求堆叠柱、双 Y 轴、缩放拖拽，代码就变成一坨没人敢碰的乱麻。后来转投 ECharts，满心以为把网页端那套 option 原样搬过来就能跑，结果真机一测，白屏、模糊、包体超限轮番上演。这篇东西就按我实际项目的推进顺序，从小程序加 ECharts 的技术选型、组件接入、图表实操，一路讲到真机踩坑和性能优化，中间所有配置尽量给到你能直接抄的程度。不管你是刚接触微信小程序开发的新手，还是做过网页端 ECharts、第一次往小程序里搬的老手，都能在这里找到对得上号的东西。图表这件事说难不难，说简单也真不简单，关键是把几个容易翻车的点提前搞清楚，后面就顺了。

1. 先想明白：小程序容器里跑 ECharts 到底难在哪

1.1 小程序的渲染环境不是浏览器

这是所有问题的根源。网页端的 ECharts 底层依赖 DOM，它要 document 去创建 canvas 节点，要 window 去监听 resize，要 getComputedStyle 去算尺寸，要 addEventListener 去接鼠标事件。小程序这套环境里这些东西统统没有，它用的是自己的渲染层和逻辑层双线程模型，canvas 得靠wx.createCanvasContext或者新版 canvas 2d 接口拿到，事件走的是bindtouchstart这类绑定。你把官方 echarts.js 直接 import 进来，第一步初始化就给你报错，因为里面document.createElement找不到宿主。

那 ECharts 是怎么在小程序里跑起来的？靠的是官方维护的ec-canvas组件。它做的事情本质上是给 ECharts 造了一套"假 DOM"——用wx-canvas.js这个适配层，模拟出 canvas 对象应有的getContext、setAttribute、addEventListener等方法，让 ECharts 以为自己还在浏览器里画图。理解这一点特别重要，因为后面遇到的绝大多数诡异问题，根源都在"这是个模拟环境，不是真浏览器"上。比如 CSS 里给 canvas 写的宽度样式，在旧版 canvas 上根本不生效；比如 tooltip 的浮层定位，在小程序里压根不是 HTML 元素，而是直接画在 canvas 上的。

所以我的第一条经验是：别拿网页端 ECharts 的调试直觉去套小程序。网页上 F12 一看就知道了，小程序里很多问题只能靠打日志、真机预览一点点试出来。心态上先接受这个前提，后面踩坑会淡定很多。

1.2 三种落地方案的取舍

往小程序里塞图表，路子其实不止一条。我把常见的三种方案摆出来对比，你按项目情况挑。

先说我为什么不推荐 WebView 方案。虽然它最省事，网页端怎么写小程序就怎么写，但 web-view 是独立渲染的，和小程序原生页面的通信要靠 postMessage，延迟明显，样式上还有导航栏、滚动等一堆别扭的地方，用户体验割裂感很强。除非你要做的是一个完整独立的可视化大屏页面，不跟小程序其他页面频繁交互，否则别走这条路。

原生 canvas 手绘只适合那些图形极其固定、永远不变的场景，比如一个静态的进度环。一旦需求变成"我想切个数据源"，你就得重写绘图逻辑，维护成本高得吓人。所以绝大多数情况下，ec-canvas是那个正确答案。它把 ECharts 的强大能力和小程序的运行环境连起来，配置语法和网页端几乎一致，网上搜到的 option 写法大部分能直接用。代价就是包体积和性能上要做点优化，但这是可解的，后面细说。

1.3 包体积这条红线得先算清楚

微信小程序主包上限是 2M，整个小程序（主包 + 分包）上限 20M。这个限制卡死了很多人。ECharts 完整版的echarts.min.js压缩后大概 700KB 到 1MB 上下，你在主包塞这么一个东西，再加上图片、字体、业务代码，很容易就顶到 2M 的天花板，上传的时候直接给你报"主包体积超限"。

我见过太多人是先写完了功能，最后卡在体积上传不上去，回头再折腾定制，非常痛苦。正确做法是一开始就把 ECharts 放进分包，或者用按需定制砍掉不用的图表类型。比如你只做折线图和柱状图，就没必要带上桑基图、关系图、树图这些几十 KB 的模块。定制之后，一个项目里只用了折线、柱状、饼图的 echarts 包，往往能压到 300KB 以内，这个差别在 2M 红线下是生死级别的。具体怎么定制，下一章手把手讲。

2. 环境准备：把 ec-canvas 正确装进项目

2.1 获取组件与目录结构规划

先拿组件。官方仓库在 GitHub 上，搜索echarts-for-weixin就能找到，里面最核心的就是ec-canvas这个目录。把它整个拷贝到你小程序项目的根目录下（或者放到你规划好的组件目录里），大致结构是这样：

项目根目录/ ├── ec-canvas/ │ ├── ec-canvas.js │ ├── ec-canvas.json │ ├── ec-canvas.wxml │ ├── ec-canvas.wxss │ ├── echarts.js │ └── wx-canvas.js ├── pages/ │ └── chart/ │ ├── chart.js │ ├── chart.json │ ├── chart.wxml │ └── chart.wxss ── app.json

这里有几个坑我要提前说。第一，ec-canvas这个目录名别随便改，虽然理论上能改，但组件内部有些相对路径引用，改名字容易出幺蛾子，除非你清楚每个文件的引用关系。第二，不同版本的ec-canvas对基础库要求不一样，新版默认走 canvas 2d 接口，要求基础库 2.9.0 以上。如果你的小程序要兼容很老的版本，可以用旧版 canvas，但性能和体验会差一些，这个后面讲。

拷贝完之后，在要用图表的页面page.json里注册组件：

{ "usingComponents": { "ec-canvas": "../../ec-canvas/ec-canvas" } }

注意路径是相对路径，../../的层级要和你实际目录对应上，注册错了编译时会直接报组件找不到。我建议把ec-canvas放在和pages同级的根目录，路径引用最省心。

2.2 按需定制 echarts，把包体积压下来

默认的echarts.js是完整版，直接上很可能撑爆主包。定制流程我走的是官方提供的在线定制工具，思路就是勾选你要用的图表类型和组件，生成一个只包含这些功能的压缩包。

具体操作：打开官方 ECharts 的在线构建页面，找到定制入口，左侧勾选你需要的模块。以最常见的业务场景为例，折线图、柱状图、饼图基本跑不掉，对应的需要勾选line、bar、pie这几个图表类型；坐标轴组件grid、提示框tooltip、图例legend、标题title、数据缩放dataZoom、直角坐标系cartesian都要勾上；如果要画地图，还得勾geo和map。右侧会实时显示预计的体积大小，勾完下载压缩包，里面有个echarts.min.js。

拿到这个文件后，直接把它重命名为echarts.js，覆盖掉ec-canvas目录里原来那个。注意，覆盖前先备份一下原始文件，万一后面发现少了某个功能，还能对照回去重新定制。

提示：定制时宁可多勾一个用得上但暂时没用到的组件，也别漏勾，因为漏了要到运行时才会暴露问题，那时候你看到的往往是一句莫名其妙的报错，排查起来很费劲。

定制完之后，你的 echarts 包大小能砍掉一半甚至更多。我手上一个电商后台的小程序，只用了折线、柱状、饼图加地图，定制后 echarts 包压到了 280KB 左右，主包体积压力一下就缓过来了。

2.3 页面骨架与基础样式

组件注册好，就可以搭页面了。wxml 里加上ec-canvas标签：

<view class="chart-box"> <ec-canvas id="line-chart" canvas-id="line-canvas" ec="{{ ec }}"></ec-canvas> </view>

对应的 wxss 一定要给容器明确的尺寸，这是新手最容易翻车的地方：

.chart-box { width: 100%; height: 500rpx; } ec-canvas { width: 100%; height: 100%; }

为什么强调尺寸？因为 ECharts 初始化时要读取 canvas 的实际宽高，如果容器高度是 0 或者 auto，chart 就会算出一个 0 尺寸，结果是白屏。这个问题在网页端也常见，但在小程序里更隐蔽，因为真机上一看就是空白，你还以为是组件没加载。另外ec-canvas本身也要给 100% 宽高，让它撑满外层容器。我习惯用一个固定高度的 view 包住，高度用 rpx 而不是百分比，因为百分比在一些嵌套布局里会失效。

页面 js 里先准备好ec对象，这个对象决定了图表怎么初始化：

Page({ data: { ec: { onInit: initChart } } });

但这里有个细节，initChart函数得定义在 Page 外面，因为ec.onInit需要在组件创建时被调用，作用域和 Page 的 this 不是一回事。下一章详细讲两种初始化方式的区别。

3. 跑通第一个折线图：初始化与数据更新

3.1 两种初始化方式：onInit 与 lazyLoad

ec-canvas支持两种初始化时机，选哪种取决于你的数据是不是页面一加载就万事俱备。

第一种是onInit，页面渲染时组件立刻初始化并调用你给的函数画图。适合图表数据在打开页面时就已经确定的情况。写法是ec: { onInit: initChart }，其中initChart长这样：

import * as echarts from '../../ec-canvas/echarts'; function initChart(canvas, width, height, dpr) { const chart = echarts.init(canvas, null, { width: width, height: height, devicePixelRatio: dpr }); canvas.setChart(chart); const option = { xAxis: { type: 'category', data: ['周一', '周二', '周三', '周四', '周五'] }, yAxis: { type: 'value' }, series: [{ data: [120, 200, 150, 80, 170], type: 'line', smooth: true }] }; chart.setOption(option); return chart; }

第二种是lazyLoad，先不初始化，等数据从接口回来之后再手动触发。这个方式在实际项目里用得更多，因为数据基本都要请求。写法是ec: { lazyLoad: true }，然后在拿到数据的回调里这样调：

onReady() { this.chartComp = this.selectComponent('#line-chart'); this.chartComp.init((canvas, width, height, dpr) => { const chart = echarts.init(canvas, null, { width: width, height: height, devicePixelRatio: dpr }); chart.setOption(this.buildOption()); this.chart = chart; return chart; }); }

我个人的选择标准很直接：如果数据是同步的，用 onInit；只要涉及网络请求，一律 lazyLoad。因为 onInit 是页面渲染阶段触发的，那时候你的onLoad里发的请求十有八九还没回来，你只能先画个空图，然后还要拿到 chart 实例再 setOption，绕一圈反而麻烦。

注意：不管用哪种方式，echarts.init返回的 chart 实例一定要自己存起来，比如挂到this.chart上。因为后面更新数据、resize、dispose 都要用，丢了实例你就只能重建，浪费性能。

3.2 setOption 的正确姿势与增量更新

拿到 chart 实例后，更新数据就靠setOption。这里有个参数很多人不注意，就是第二个参数notMerge。

// 合并更新，保留原有配置 this.chart.setOption({ series: [{ data: newData }] }); // 全量替换，清掉旧的所有配置 this.chart.setOption(fullOption, true);

默认是合并模式，也就是把新的 option 和旧的深度合并。这在只改数据、不动结构的时候很方便，比如定时刷新折线图的数据点。但有个坑：如果你的 series 数量变了（比如从 2 条线变成 3 条线），合并模式下旧的系列可能残留，图表就变成一坨乱的。这种时候一定要传true做全量替换。我吃过这个亏，切换部门数据时图表上多出来一条已经不该存在的线，查了半天才反应过来是 merge 的锅。

还有一种情况是切换图表类型，比如从折线切到柱状，这种彻底变更配置的场景，也用notMerge: true最稳。代价是每次都会走完整的重绘流程，性能上不如合并，但对于交互触发的切换来说，用户感知不到这点开销。

数据更新的另一个要点是别在onShow里无脑 setOption。页面切走再切回来会触发 onShow，如果你每次都在这里重新 setOption，图表会闪一下。除非你的数据确实需要刷新，否则 onShow 里只做chart.resize()就够了，因为页面尺寸可能变了，需要重新计算。

3.3 尺寸、dpr 与响应式适配

设备像素比 dpr 是个容易被忽略但影响很大的参数。小程序的 canvas 在物理像素和逻辑像素之间有缩放关系，如果你 init 的时候不传devicePixelRatio，在部分高分辨率机型上图表会糊成一片，文字和细线都能看出锯齿。

const dpr = wx.getSystemInfoSync().pixelRatio;

推荐的做法就是 init 时把devicePixelRatio: dpr传进去，ec-canvas 在 onInit 里已经把 dpr 作为第四个参数给你了，直接用即可。

响应式这块，小程序的页面尺寸变化主要发生在横竖屏切换，或者某些特殊容器里。网页端 ECharts 会自动监听 window.resize，小程序里没这回事，得手动调：

// 横竖屏切换时 onResize() { if (this.chart) { this.chart.resize({ width: this.data.canvasWidth, height: this.data.canvasHeight }); } }

如果你用的是百分比布局，图表容器宽度随屏幕变化，那么在某些机型上就得主动 resize 一下。我一般会在onReady后再补一次 resize，确保尺寸稳定。实测在 iPhone 系列上，不补这一下偶尔会出现右侧留白的情况，补了就正常了。

4. 几类高频图表的实操细节

4.1 饼图：labelLine 末端小圆点偏移怎么解

饼图是做后台最常用的图表之一，而labelLine末端的小圆点偏移是很多人问过我的问题。现象是这样的：饼图每个扇区的标签引线末端，本该精准落在一个位置，结果真机上跑偏了，要么和文字重叠，要么飘到了扇区外面。

这个问题根源在于标签和引线的布局算法对空间的计算。ECharts 从 5.x 之后对饼图标签引入了alignTo机制，你可以通过配置来控制对齐方式。我常用的稳定配方是这样：

series: [{ type: 'pie', radius: ['35%', '60%'], label: { alignTo: 'edge', edgeDistance: 10, formatter: '{b}\n{d}%' }, labelLine: { length: 15, length2: 12, smooth: 0.2, minTurnAngle: 90 } }]

alignTo: 'edge'让标签尽量贴到容器边缘对齐，edgeDistance控制离边的距离，这样小圆点的落点就稳定了。labelLine里的length是第一段引线长度，length2是第二段（也就是带小圆点那一截）的长度。真机偏得很厉害的时候，我会把length2适当调小，或者把minTurnAngle设成 90 度限制折角，让引线不要出现太急的弯。

还有一点，如果标签文字特别长，会互相挤压，这时候可以用labelLayout里的hideOverlap: true隐藏重叠的标签，或者干脆把长名称截断，用formatter自己拼一个短名字。别指望 ECharts 自动帮你把长文本排得漂漂亮亮，它做不到，得你手动控制。

提示：饼图标签密集时，把radius设成环形（第一项不为 0），中间留白能让视觉重心更稳，比实心饼图好看不少，也更容易放中心汇总数据。

4.2 中国地图：registerMap 与 geoJSON 加载

地图类的需求主要是区域数据可视化，比如各省销售额分布。要画地图，第一步是把地理数据注册进去，因为 ECharts 本身不携带地理边界数据，得靠 geoJSON。

import * as echarts from '../../ec-canvas/echarts'; import chinaJson from './china.json'; echarts.registerMap('china', chinaJson);

geoJSON 文件可以找公开的地理数据源下载，注意数据要精简，别用那种带几十万个坐标点的超精细版本，那会让包体积爆炸、渲染卡死。一般做省市级别的可视化，用简化的 geoJSON 就够了。

注册完之后配置地理坐标系：

const option = { geo: { map: 'china', roam: true, itemStyle: { areaColor: '#f3f6ff', borderColor: '#c8d3e8' }, emphasis: { itemStyle: { areaColor: '#dbe4ff' } } }, series: [{ type: 'map', geoIndex: 0, data: [ { name: '广东', value: 1200 }, { name: '江苏', value: 900 } ] }] };

这里有个容易踩的点：series的data里name必须和 geoJSON 里的地区名称严格一致，差一个字就渲染不上。比如 geoJSON 里写的是"北京市"，你这里写成"北京"，那就没数据。我一般会先把 geoJSON 里的名称列表打出来对一遍，省得真机上一个个试。

roam: true开启缩放和平移，地图可以拖动放大。在小程序里这个交互是默认支持的，因为 ec-canvas 把触摸事件透传给了 ECharts。不过如果地图嵌在 scroll-view 里，拖动地图会和外层滚动冲突，这个后面踩坑那块讲怎么破。

4.3 折线图 x 轴刻度与 tooltip 换行

折线图 x 轴刻度标签太多、互相重叠，是另一个高频问题。解决办法无非几种：旋转、间隔显示、或者换行。

xAxis: { type: 'category', data: dates, axisLabel: { interval: 0, rotate: 45, formatter: (value) => { // 按需截断或换行 return value.length > 6 ? value.slice(0, 6) + '…' : value; } } }

interval: 0表示强制显示所有标签，不自动抽稀；rotate: 45让标签斜着排，给横向空间腾地方。如果你的业务不允许斜排（有些设计规范要求水平），那就用formatter把长标签截断，或者用换行，formatter返回带\n的字符串就行。但换行会让 x 轴区域变高，别忘了给 grid 底部留出空间，否则标签会被裁掉。

tooltip 自动换行也是搜索量很高的点。小程序的 tooltip 是画在 canvas 上的，不像网页是 HTML 浮层，所以没法用 CSS 的 white-space 来换行。要在 formatter 里手动处理：

tooltip: { trigger: 'axis', confine: true, formatter: (params) => { let result = params[0].axisValue + '\n'; params.forEach(item => { result += item.seriesName + '：' + item.value + '\n'; }); return result; } }

关键点是 formatter 返回的字符串里带上\n，canvas 绘制时就会换行。再配合confine: true，让 tooltip 不要超出图表边界，在小屏幕上这一点尤其重要，否则提示框会被截掉一半。

5. 真机踩坑与性能优化实录

5.1 常见报错与排查速查表

下面这张表是我这些年攒下来的高频问题清单，遇到对应现象直接查。

这张表里我想单独说"切页面回来图表消失"这个坑，因为它很典型。你从 A 页面跳到 B 页面再返回 A，canvas 有可能被回收，图表就没了。解决思路是保存 chart 实例，在onShow里判断实例是否还有效，失效了就重新初始化。ec-canvas 的新版对这个场景做了处理，但旧版不一定稳，所以实例管理这件事你最好自己心里有数。

5.2 canvas 层级、滚动穿透与真机差异

小程序的 canvas 在旧版里是原生组件，层级永远最高，会盖住普通 view，z-index 都压不住它。如果你在图表上想放个下拉菜单或者弹层，旧的 canvas 会直接把它盖住。这个问题的解法有两个：一是用cover-view来承载浮层，二是换成新版 canvas 2d，新版 canvas 支持同层渲染，层级问题基本没了。

<!-- 强制使用旧版 canvas（兼容极老基础库时用） --> <ec-canvas id="chart" canvas-id="chart" ec="{{ ec }}" force-use-old-canvas="{{ true }}"></ec-canvas>

新版 canvas 需要基础库 2.9.0，现在绝大多数用户都满足，除非你明确知道有一批老设备要支持，否则优先用新版，性能和层级都更好。

滚动穿透是另一个烦人的点。图表放在scroll-view里，你在地图上拖动想缩放，结果整个页面在滚动。解决思路是给 ec-canvas 的触摸事件做拦截，或者用catchtouchmove阻止事件冒泡。ec-canvas 组件本身提供了disableTouch配置，但它会把图表的所有触摸交互都禁掉，包括拖拽和缩放，所以不能一刀切。我的做法是只在需要交互的图表上开启 roam，不放 scroll-view 里，或者把地图单独放到一个占满屏幕的容器里，避免和外层滚动争抢。

真机差异这件事只能靠多测。iOS 和安卓在 canvas 渲染上确实有细微差别，比如文字基线、抗锯齿效果。我遇到过一次安卓上文字显示不全的问题，最后发现是字号和容器比例的问题，调了一下就好了。经验就是：能在开发者工具里看到的，不一定真机就那样；真机上出现的问题，先在开发者工具里对着日志复现，复现不了就加日志到真机上看。别凭猜测改代码，效率太低。

5.3 大数据量与多图联动的性能处理

数据量大到几千上万个点的时候，折线图会明显卡。这时候有几个优化方向。

第一是数据降采样。ECharts 有内置的sampling配置，对付超长折线很有效：

series: [{ type: 'line', sampling: 'lttb', data: hugeData }]

lttb是一种保形降采样算法，能在大幅减少点数的同时保留曲线走势，视觉效果几乎看不出差别。几千个点降到几百个点，渲染一下就顺畅了。

第二是关掉动画。animation: false在数据频繁刷新的场景下能省不少性能，图表虽然少了一点动效，但流畅度优先级更高。

第三是把重绘频率降下来。如果数据是实时推送的，别每来一条就 setOption 一次，用节流攒一批再更新，比如 500ms 更新一次。这样既保证视觉上的实时感，又不至于把渲染线程压垮。

多图联动是另一个常见需求，比如点击一个图表的某个扇区，另一个图表联动过滤。实现上就是监听第一个图表的点击事件，拿到参数后更新第二个图表的数据：

this.chart.on('click', (params) => { const selected = params.name; this.secondChart.setOption({ series: [{ data: filterBy(selected) }] }); });

注意在小程序里，事件监听要绑在真实的 chart 实例上，别绑在 canvas 元素上，因为事件最终都会被 ec-canvas 转成 ECharts 的事件模型。绑对了之后，联动响应是很跟手的。

6. 多图表页面协作与动态标题设置

6.1 同页面多个图表实例管理

一个页面放好几个图表是很常见的，比如仪表盘页面同时有折线、柱状、饼图。这时候要特别注意两个事：id 唯一和实例分别保存。

每个ec-canvas的id和canvas-id都必须唯一，否则组件会互相串，出现"第二个图表画的是第一个图表的数据"这种诡异现象。我见过有人复制粘贴忘了改 id，调试了一下午。

<ec-canvas id="chart-line" canvas-id="canvas-line" ec="{{ ecLine }}"></ec-canvas> <ec-canvas id="chart-bar" canvas-id="canvas-bar" ec="{{ ecBar }}"></ec-canvas> <ec-canvas id="chart-pie" canvas-id="canvas-pie" ec="{{ ecPie }}"></ec-canvas>

实例也要分别挂到不同变量上：

this.lineChart = null; this.barChart = null; this.pieChart = null;

如果这几个图表用同一份数据的不同维度，可以在接口回来后统一刷新，但每个实例各调各的 setOption。别想着复用一个 chart 实例去画多个图，那是不可能的，一个实例对应一个 canvas。

另外，页面里图表多了要注意初始化时机。用 lazyLoad 的话，数据回来后一口气把几个图都 init 了，可能会有一个短暂的卡顿，因为每个 init 都要创建 canvas 上下文。优化办法是按需初始化，比如用wx.nextTick或者分帧处理，先初始化用户第一眼看到的那个图表。

6.2 结合 wx.setNavigationBarTitle 动态更新标题

页面标题跟着图表状态变，是提升体验的一个小细节。比如切换图表维度时，把标题从"月度销售趋势"改成"季度销售趋势"。小程序里用wx.setNavigationBarTitle就能改：

switchDimension(e) { const dim = e.currentTarget.dataset.dim; const titleMap = { month: '月度销售趋势', quarter: '季度销售趋势', year: '年度销售趋势' }; wx.setNavigationBarTitle({ title: titleMap[dim] }); this.refreshChart(dim); }

这样用户切维度时，标题同步更新，图表标题和页面标题一致，认知负担小。注意wx.setNavigationBarTitle是异步的，不用等回调，直接调就行。如果你用的是自定义导航栏，那这个 API 就不生效了，得自己通过 data 控制自定义导航栏的文字，这个要注意区分。

顺带提一句，图表的title配置和页面导航栏标题最好别重复太多。页面导航栏已经写了"销售分析"，图表里再写一遍"销售分析"，就冗余了。我一般会让图表内部标题承担更具体的说明，比如带时间范围或数据口径，页面标题承担模块定位，各司其职。

图表在小程序里的落地，说到底就是"理解模拟环境 + 用好 ec-canvas + 提前压体积 + 真机多验"这四件事。我见过太多人在第一步就被白屏劝退，其实大部分白屏就是容器没给高度，改一行样式的事。把上面这些配置和坑点过一遍，一个稳定能用的图表页面基本就成型了。剩下那些高级交互和视觉细节，都是在这个基础上慢慢调出来的，先跑起来，比什么都重要。