echarts-for-weixin：Apache ECharts 微信小程序图表接入与使用指南

echarts-for-weixin 是 Apache ECharts 官方团队提供的微信小程序图表库，核心是一个经过 Canvas 适配的 ec-canvas 自定义组件。开发者沿用熟悉的 ECharts option 配置方式，就能在小程序里画出折线、柱状、饼图、关系图等各类可视化图表，无需自己处理小程序 Canvas 与 DOM 的差异。

一、项目官方信息

二、官方图片

ECharts 小程序 Demo 截图（扫码可在微信中体验）：

三、环境要求

• 微信开发者工具 + 已申请的小程序 AppID；
• 小程序基础库：调试时设为 1.9.91 及以上；发布前在 mp.weixin.qq.com「设置」里把最低基础库设为 1.9.91；
• 想使用性能更好的新 Canvas 2d，需基础库 >= 2.9.0（默认开启，不设置 force-use-old-canvas 即生效）。

四、部署/接入步骤

1. 获取项目

下载 ecomfe/echarts-for-weixin 项目。其中 ec-canvas 是官方提供的组件，其余文件是各图表的使用示例（如 pages/bar、pages/line、pages/lazyLoad、pages/multiCharts 等）。

两种接入方式：

• 整包替换：把下载的项目整体替换新建的小程序工程，再把 project.config.json 里的 appid 改成你自己的；按需要删除 pages 下用不到的页面，并同步在 app.json 里移除对应路由。
• 仅拷贝组件：只把 ec-canvas 目录拷进你的工程，参考 pages/bar 的写法接入。

2. 注册 ec-canvas 组件

在页面的 index.json 中注册自定义组件（注意相对路径）：

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

3. 在 wxml 中放置组件

<view class="container">
  <ec-canvas id="mychart-dom-bar" canvas-id="mychart-bar" ec="{{ ec }}"></ec-canvas>
</view>

官方提醒：新建工程 app.wxss 里默认的 .container 样式可能与本 demo 不一致，导致图表区域没有宽高、只显示空白。请参考 demo 的 app.wxss 给容器设置好宽高。

4. 在 js 中初始化图表

index.js 定义 initChart 初始化函数，并用 echarts.init 建图、setOption 配置：

function initChart(canvas, width, height, dpr) {
  const chart = echarts.init(canvas, null, {
    width: width,
    height: height,
    devicePixelRatio: dpr // 像素比
  });
  canvas.setChart(chart);

  var option = {
    xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: [120, 200, 150] }]
  };
  chart.setOption(option);
  return chart;
}

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

对所有 ECharts 图表通用，只需替换 option 即可换图。option 写法见 ECharts 配置项文档；新手可先看「快速上手 ECharts」教程。

5. （可选）精简 echarts.js

仓库自带的 ec-canvas/echarts.js 是含全部组件的完整版。官方建议：调试用未压缩版、发布用压缩版；对包体敏感时，到 ECharts 官网「在线定制」（https://echarts.apache.org/zh/builder.html）只勾选需要的组件、选压缩，下载后重命名为 echarts.js 放回 ec-canvas/ 目录。也可配合小程序分包策略控制主包体积。

五、使用方法

• 折线/柱状图：参考 pages/bar、pages/line，改 option 里的 series 与数据即可。
• 延迟加载图表：先异步请求接口，拿到数据后再初始化，参考 pages/lazyLoad。
• 一个页面多个图表：参考 pages/multiCharts。
• Tooltip：本项目已支持 ECharts Tooltip（需用本项目自带的 ec-canvas/echarts.js），用法同 ECharts，示例见 pages/line/index.js。已知 bug：部分 tooltip 会显示 <br/> 而非换行，可在 formatter 里用 \n 代替。
• 保存为图片：参考 pages/saveCanvas。
• 获取图表实例：echarts.init 的返回值就是实例，可据此在外部调用 setOption、resize 等。
• 切回旧 Canvas：给组件加 force-use-old-canvas="true" 属性。

六、常见问题 FAQ

Q1：图表区域空白，什么都不显示？ 最常见原因是容器没有宽高（.container 样式不对），或基础库版本过低。请参考 demo 的 app.wxss 设置宽高，并把调试基础库调到 1.9.91 以上。

Q2：echarts.js 文件太大，小程序包超限？ 用 ECharts 官网「在线定制」只打包用到的组件、选压缩版，重命名为 echarts.js 替换；并考虑小程序分包。

Q3：Tooltip 为什么显示成 <br/> 而不是换行？ 官方已知 bug。临时规避：在 formatter 里用 \n 作为换行符。

Q4：一个页面要放多个图表怎么做？ 参考 pages/multiCharts 示例：每个图表一个 <ec-canvas>，各自的 onInit 返回独立实例。

Q5：想用数据返回后再画图？ 参考 pages/lazyLoad：在请求拿到数据后，再把初始化函数挂到 ec 上。

Q6：有哪些功能暂不支持？ 官方说明：多个 zlevel 分层暂不支持；另有安卓 transform、iOS 半透明变深/渐变色越界等已知 bug，不影响基本使用。问题可到仓库 issue 反馈。

七、跳转链接

• GitHub 仓库：https://github.com/ecomfe/echarts-for-weixin
• Apache ECharts：https://github.com/apache/echarts
• ECharts 配置项文档：https://echarts.apache.org/zh/option.html
• ECharts 在线定制：https://echarts.apache.org/zh/builder.html
• 快速上手 ECharts：https://echarts.apache.org/handbook/zh/get-started/