微信小程序邂逅Echarts：从入门到避坑全攻略

一、引言

在当今数字化时代，数据可视化对于数据分析和展示至关重要。微信小程序作为一种轻量级应用，在各类场景中广泛应用，而在小程序中实现数据可视化，能让用户更直观地理解数据。Echarts 是一款由百度开源的强大的数据可视化图表库，提供了丰富的图表类型，如折线图、柱状图、饼图、地图等，满足各种数据展示需求。将 Echarts 集成到微信小程序中，能为小程序增添强大的数据可视化能力，提升用户体验。无论是展示业务数据报表、分析用户行为数据，还是呈现各种统计信息，Echarts 在微信小程序中的应用都能发挥重要作用。接下来，本文将详细介绍在微信小程序中使用 Echarts 的具体步骤及一些避坑指南，帮助开发者快速上手并解决可能遇到的问题。

二、Echarts 与微信小程序基础

2.1 Echarts 简介

Echarts 是一个基于 JavaScript 的开源可视化图表库，能够流畅地运行在 PC 和移动设备上。它提供了丰富多样的图表类型，如折线图、柱状图、散点图、饼图、雷达图、地图 、漏斗图等，每种图表类型都有其独特的数据展示方式和适用场景，开发者可以根据具体的数据特点和需求来选择合适的图表类型，以最直观有效的方式呈现数据。

Echarts 不仅图表类型丰富，还具备强大的交互功能，支持数据区域缩放、数据筛选、图例切换、数据提示等交互操作。例如，在折线图中，用户可以通过鼠标滚轮缩放来查看不同时间跨度的数据趋势，或者通过点击图例来显示或隐藏特定的数据系列；在地图图表中，用户点击某个区域可以查看该区域的详细数据信息。这些交互功能使用户能够更深入地探索数据，发现数据背后的规律和价值。

此外，Echarts 拥有丰富的配置选项，开发者可以轻松自定义图表的外观、样式、标签、坐标轴、图例等，以满足各种个性化的展示需求。同时，Echarts 还支持扩展插件和主题切换，进一步增强了其功能和灵活性。在实际应用中，Echarts 广泛应用于数据可视化、商业分析、地理信息系统等领域，帮助企业和开发者更好地理解和展示数据。

2.2 微信小程序开发环境搭建

微信小程序开发需要使用微信开发者工具，这是微信官方提供的一款专门用于开发、调试和发布微信小程序的工具，支持 Windows、Mac 和 Linux 系统。你可以在微信开发者工具的官方网站（https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html ）上下载对应的安装包，然后按照安装向导进行安装。

安装完成后，打开微信开发者工具，使用微信扫码登录。首次登录需要注册小程序账号，在微信公众平台（https://mp.weixin.qq.com/ ）上完成注册流程，并记住你的 AppID，它是小程序的唯一标识。如果只是进行本地开发和测试，也可以选择使用测试号进行开发。

登录成功后，点击 “新建项目”，在弹出的对话框中填写项目的名称、选择项目的目录，并填入之前注册获取的 AppID，然后点击 “确定” 按钮即可创建项目。项目创建成功后，微信开发者工具会自动加载项目，并在编辑器中显示项目的文件结构。此时，你可以在编辑器中编写小程序的代码，在模拟器中查看小程序的运行效果，还可以使用调试工具来调试代码，查找和解决问题。

2.3 Echarts for weixin 介绍

Echarts for weixin 是一个基于 Apache ECharts 的数据可视化库，专门为微信小程序开发设计，它允许开发者在微信小程序中高效地展示各种数据可视化图表。通过引入特制的组件 ec-canvas，Echarts for weixin 成功地在微信小程序内运行 ECharts，使得开发者无需复杂的适配过程，即可呈现丰富的图表效果。

该项目具有诸多优势。首先，它的易用性高，与原生 Echarts 配置方式保持一致，开发者只要熟悉 Echarts，就能快速上手在微信小程序中使用，学习成本低，只需简单的 JSON 配置就能绘制复杂图表。其次，灵活性强，支持多个图表在同一页面并存，轻松实现交互式数据展示，满足各种复杂的业务需求。再者，性能优越，针对微信小程序环境进行了优化，提供了更好的渲染效率和用户体验，即使在移动设备上也能流畅运行。另外，它还具有良好的兼容性，支持微信小程序的基础库版本 >= 1.9.91，覆盖了大量用户群体。并且，Echarts for weixin 会与 Echarts 主线同步，定期更新以修复 bug 和添加新特性，保证开发者能使用到最新、最稳定的功能。

虽然 Echarts for weixin 基于 Echarts，但两者也存在一些区别。在运行环境上，Echarts 主要运行在 Web 浏览器中，而 Echarts for weixin 则是专门为微信小程序环境定制。在使用方式上，Echarts for weixin 通过微信小程序的组件化机制，使用 ec-canvas 组件来引入和使用 Echarts，与在 Web 中直接引入 Echarts 库的方式有所不同。 不过，它们的核心功能和配置项基本相同，都提供了丰富的图表类型和强大的交互功能，开发者可以根据项目的具体需求选择合适的版本。

三、微信小程序中使用 Echarts 详细步骤

3.1 下载 Echarts

你可以从 Echarts for weixin 的 GitHub 仓库（https://github.com/ecomfe/echarts-for-weixin ）下载所需文件。下载并解压后，你会得到一个包含多个文件和文件夹的目录。其中，ec-canvas文件夹是关键部分，它包含了在微信小程序中使用 Echarts 所需的核心组件和相关脚本。ec-canvas.js负责组件的逻辑处理，ec-canvas.wxml用于定义组件的结构，ec-canvas.wxss用于设置组件的样式，而echarts.js则是 Echarts 的核心库文件，包含了各种图表的绘制和交互逻辑。这个文件夹为在小程序中集成 Echarts 提供了基础支持，后续的引入和配置操作都将围绕它展开。

3.2 引入 Echarts 到小程序项目

将下载解压后的ec-canvas文件夹复制到小程序的项目根目录下（你也可以将其放置在components文件夹中，这取决于你的项目结构和组织习惯，只要确保后续引用路径正确即可）。

接下来，在需要使用 Echarts 的页面的.json文件中进行配置，以告诉小程序该页面要使用ec-canvas组件。假设ec-canvas文件夹位于项目根目录，配置代码如下：

{

"usingComponents": {

"ec-canvas": "../../ec-canvas/ec-canvas"

}

}

这里的路径../../ec-canvas/ec-canvas需要根据ec-canvas文件夹的实际位置进行准确设置。如果放置在components文件夹中，路径可能变为../../components/ec-canvas/ec-canvas。路径的准确性直接影响到组件能否被正确引入和使用，如果路径错误，小程序在编译时将无法找到该组件，从而导致页面报错或图表无法显示 。

3.3 在.wxml 文件中创建 Echarts 容器

在页面的.wxml文件中，使用ec-canvas组件来创建图表的容器。示例代码如下：

<view class="echarts-container">

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

</view>

在这段代码中：

• id属性为ec-canvas组件指定了一个唯一的标识符mychart-dom-bar，这在后续通过 JavaScript 获取和操作该组件时会用到，比如在初始化图表、更新图表数据等操作中。

• canvas-id属性指定了画布的 IDmychart-bar，Echarts 会基于这个画布来绘制图表，它是 Echarts 绘制图表的实际载体。

• ec属性绑定了一个名为ec的对象，这个对象在页面的.js文件中定义，用于配置和初始化 Echarts 图表，它包含了图表的初始化函数、数据等重要信息 。

同时，为了让图表能够正确显示，还需要在.wxss文件中为ec-canvas组件及其父容器设置合适的宽度和高度。例如：

.echarts-container {

width: 100%;

height: 400px; /* 根据需求调整高度 */

}

ec-canvas {

width: 100%;

height: 100%;

}

如果不设置宽度和高度，ec-canvas组件及其内部的图表可能无法正常显示，因为默认情况下它们的尺寸可能为 0。

3.4 在.js 文件中初始化和配置 Echarts

    1、引入 echarts 库：在页面的.js文件中，首先需要引入 Echarts 库。假设ec-canvas文件夹位于项目根目录，引入代码如下：

import * as echarts from '../../ec-canvas/echarts';

     2、编写 initChart 函数：这个函数用于初始化图表并设置其基本配置。代码示例如下：

function initChart(canvas, width, height, dpr) {

const chart = echarts.init(canvas, null, {

width: width,

height: height,

devicePixelRatio: dpr // 像素比，用于处理高清屏显示

});

// 设置图表的基本配置项

var option = {

color: ['#3398DB'], // 图表颜色

tooltip: {

trigger: 'axis',

axisPointer: {

type:'shadow'

}

},

legend: {

data: ['数据']

},

xAxis: {

type: 'category',

data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']

},

yAxis: {

type: 'value'

},

series: [{

name: '数据',

type: 'bar',

data: [120, 200, 150, 80, 70, 110, 130]

}]

};

chart.setOption(option);

return chart;

}

在这个函数中：

• canvas参数是 Echarts 用于绘制图表的画布对象。

• width和height分别表示画布的宽度和高度，用于确定图表的尺寸大小。

• dpr是设备像素比，在高清屏设备上，设置合适的dpr可以保证图表的清晰度，避免出现模糊的情况。

• 使用echarts.init方法初始化图表，并传入画布、主题（这里设置为null，表示使用默认主题）以及包含宽度、高度和像素比的配置对象。

• 通过chart.setOption方法设置图表的各种配置项，包括颜色、提示框（tooltip）、图例（legend）、坐标轴（xAxis 和 yAxis）以及系列数据（series）等。这些配置项决定了图表的外观、交互和数据展示方式。

     3、在 Page 的 data 中定义 ec 对象：在Page的data中定义ec对象，并将onInit指向initChart函数，代码如下：

Page({

data: {

ec: {

onInit: initChart

}

}

});

这样，当页面加载时，小程序会根据ec对象中的配置，调用initChart函数来初始化 Echarts 图表 。

3.5 动态数据绑定与更新

在实际应用中，数据往往是动态变化的，需要从接口获取数据并更新到 Echarts 图表中。以下是实现动态数据绑定与更新的步骤：

   1、通过接口获取动态数据：使用微信小程序的wx.request方法来发送 HTTP 请求获取数据。例如：

wx.request({

url: 'https://example.com/api/data', // 接口地址

success: (res) => {

// res.data为接口返回的数据

const newData = res.data;

// 这里对数据进行处理和更新图表的操作

}

});

     2、更新 Echarts 图表：在获取到数据后，需要更新图表的数据。可以通过setTimeout来模拟接口请求的延迟，在回调函数中更新图表数据。假设initChart函数中的series.data是需要更新的数据，示例代码如下：

Page({

data: {

ec: {

onInit: initChart,

lazyLoad: true // 开启懒加载

}

},

onLoad: function() {

// 模拟接口请求

setTimeout(() => {

const newData = [150, 220, 180, 90, 80, 130, 150]; // 新的数据

const ecComponent = this.selectComponent('#mychart-dom-bar');

ecComponent.init((canvas, width, height, dpr) => {

const chart = echarts.init(canvas, null, {

width: width,

height: height,

devicePixelRatio: dpr

});

const option = {

// 配置项...

series: [{

name: '数据',

type: 'bar',

data: newData // 更新数据

}]

};

chart.setOption(option);

return chart;

});

}, 1000); // 模拟延迟1秒

}

});

在这个示例中，通过selectComponent获取到ec-canvas组件，然后调用init方法重新初始化图表，并在init的回调函数中设置新的数据和配置项，从而实现图表数据的更新 。这样，当从接口获取到新数据时，就可以按照类似的方式更新图表，以展示最新的数据。

四、避坑指南

4.1 版本兼容性问题

在使用 Echarts for weixin 时，务必注意版本兼容性。下载的 Echarts 版本要与小程序基础库版本相匹配，否则可能出现各种兼容性问题，如图表无法正常渲染、交互功能异常等。例如，某些旧版本的 Echarts 可能不支持新版本小程序基础库的某些特性，而新版本的 Echarts 可能需要较高版本的小程序基础库才能正常运行。

同时，在定制echarts.min.js文件时，要确保其版本与ec-canvas组件中使用的echarts.js版本一致。如果版本不一致，可能会导致引入的图表库无法正常工作，出现报错信息，如 “找不到某个函数或变量” 等，使得图表无法正确显示和交互。在更新 Echarts 版本或小程序基础库版本时，要全面测试图表的各项功能，及时发现并解决兼容性问题。

4.2 文件大小与性能优化

微信小程序对文件大小有严格限制，整个小程序所有分包大小不能超过 20M，单个分包 / 主包大小不能超过 2M 。而 Echarts 库本身文件较大，如果直接使用未定制的echarts.js，可能会使小程序的包体积过大，影响加载速度和性能。因此，定制echarts.min.js文件，只包含项目中实际需要的图表类型和功能，能有效减小文件体积，提升小程序的加载和运行效率。

在优化图表渲染性能方面，合理设置canvas尺寸非常重要。如果canvas尺寸过大，会增加渲染的计算量和内存消耗，导致图表加载缓慢甚至卡顿。应根据实际显示需求，精确设置canvas的宽度和高度，避免不必要的尺寸浪费。同时，要避免在图表中添加过多不必要的元素，如过多的图例、标签、装饰线等，这些元素都会增加渲染的复杂度和时间，影响图表的展示性能。对于复杂的图表，可以考虑采用懒加载、数据分页等技术，减少初始加载的数据量和渲染压力，提高用户体验。

4.3 图表显示异常问题

1、canvas 无法渲染：有时会遇到canvas无法渲染的情况，图表区域显示空白。这通常是由于ec-canvas组件没有正确设置宽高导致的。解决方法是在ec-canvas外面包裹一层view等元素，并为其和ec-canvas组件都指定明确的宽度和高度，确保canvas有足够的空间进行绘制。例如：

<view class="echarts-wrapper">

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

</view>


.echarts-wrapper {

width: 100%;

height: 300px;

}

ec-canvas {

width: 100%;

height: 100%;

}

2、 图表模糊问题：在高清屏设备上，图表可能会出现模糊的情况。这是因为设备像素比（devicePixelRatio）的原因。devicePixelRatio表示物理像素与逻辑像素的比例，在初始化 Echarts 图表时，需要正确设置devicePixelRatio参数，以确保图表在不同屏幕上都能清晰显示。例如：

function initChart(canvas, width, height, dpr) {

const chart = echarts.init(canvas, null, {

width: width,

height: height,

devicePixelRatio: dpr

});

// 其他配置...

return chart;

}

3、 echarts 图滑动消失：当在小程序页面中滑动图表时，可能会出现图表消失的情况，特别是在使用tooltip提示框时。这通常是因为tooltip的触发方式和交互逻辑与小程序的滑动事件产生了冲突。解决办法是在tooltip属性中添加triggerOn: 'click'，使提示框只能在点击时出现，而不是在鼠标移动或触摸滑动时触发，从而避免图表消失的问题。例如：

var option = {

// 其他配置...

tooltip: {

trigger: 'axis',

triggerOn: 'click',

axisPointer: {

type:'shadow'

}

}

};

4.4 事件与交互问题

在小程序中为 Echarts 图表绑定事件（如点击、触摸等）和实现交互（如缩放、拖拽）时，可能会遇到一些问题。例如，事件绑定不生效，点击图表没有触发相应的回调函数；或者交互效果异常，缩放、拖拽操作不流畅、不准确等。

这可能是由于小程序的事件机制与 Echarts 的事件处理存在差异，或者在绑定事件和实现交互逻辑时代码存在错误。在绑定事件时，要确保事件名称和回调函数的定义正确，并且在合适的生命周期中进行绑定。例如，在页面加载完成后（onReady生命周期）绑定点击事件：

Page({

onReady: function() {

const ecComponent = this.selectComponent('#mychart-dom-bar');

ecComponent.init((canvas, width, height, dpr) => {

const chart = echarts.init(canvas, null, {

width: width,

height: height,

devicePixelRatio: dpr

});

// 绑定点击事件

chart.on('click', function(params) {

console.log('点击图表：', params);

// 处理点击事件的逻辑

});

// 其他配置...

return chart;

});

}

});

对于交互效果异常的问题，要检查交互功能的配置是否正确，如缩放、拖拽的相关参数设置。同时，要注意性能优化，避免在交互过程中进行过多复杂的计算，以免影响交互的流畅性。

4.5 层级问题

当 Echarts 图表与小程序的其他组件（如弹出层、模态框等）同时存在时，可能会出现层级冲突的问题。这是因为 Echarts 是使用canvas绘制图表，而小程序中原生的canvas组件层级是最高的，会覆盖在其他组件之上。当弹出层等组件需要显示在图表上方时，就会被图表遮挡，无法正常展示。

为了解决这个问题，可以使用cover-view等覆盖层组件。cover-view是小程序提供的特殊组件，它可以覆盖在canvas之上，并且支持在其中使用text、button等组件。将需要显示在图表上方的内容放在cover-view组件中，就可以实现层级的控制。例如：

<view class="container">

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

<cover-view class="popup" wx:if="{{showPopup}}">

<cover-view class="popup-content">

<text>这是弹出层内容</text>

<cover-view bindtap="closePopup">关闭</cover-view>

</cover-view>

</cover-view>

</view>


.popup {

position: fixed;

top: 50%;

left: 50%;

transform: translate(-50%, -50%);

background-color: rgba(0, 0, 0, 0.8);

color: white;

padding: 20px;

border-radius: 10px;

}

.popup-content {

text-align: center;

}

在上述代码中，cover-view组件包裹了弹出层的内容，使其能够显示在 Echarts 图表的上方。同时，要注意cover-view组件的样式设置和事件绑定，确保其正常工作。

五、总结

在微信小程序中使用 Echarts，为开发者提供了强大的数据可视化能力，能够将复杂的数据以直观、生动的图表形式展示给用户。通过本文介绍的详细步骤，从下载 Echarts、引入到小程序项目、创建图表容器，到初始化和配置 Echarts，以及实现动态数据绑定与更新，希望本文对你有所帮助！