微信小程序集成ECharts图表库:安装、配置与懒加载详解

作者:阿沐时间:2026-10-25 12:25:31浏览:327

本文详解如何在微信小程序中集成官方ECharts组件。涵盖从克隆项目、版本匹配到自定义构建echarts.js以减小体积的安装步骤。深入解析ec-canvas组件在JSON、WXML及WXSS中的配置方法,包括容器样式设置与初始化逻辑。此外,重点介绍了通过lazyLoad属性实现图表延迟加载(懒加载)的技术方案,涵盖组件实例获取、手动初始化及销毁流程,帮助开发者优化小程序性能。

echarts-for-weixin 是由 ECharts 官方维护的开源项目,旨在为微信小程序提供标准化的图表组件。借助该组件,开发者可以在小程序环境中轻松实现各类图表的绘制与展示。

该项目内置了丰富的使用示例,为开发者提供了直观的参考案例,便于快速上手和调试。

安装 ECharts 组件

首先需将项目源码克隆至本地环境。

git clone https://github.com/ecomfe/echarts-for-weixin.git

随后切换至指定版本分支。

git checkout v2.0.0

echarts-for-weixin 当前最新的 Releases 版本为 v2.0.0,其内部集成的 ECharts 核心版本为 5.1.1。具体版本信息可查阅官方 Releases 页面。

项目目录下的 ec-canvas 文件夹即为所需的 ECharts 组件核心包。只需将该文件夹完整复制并粘贴至小程序项目的对应目录中,即可完成基础安装。

在 ec-canvas 目录下存在一个 echarts.js 文件,其默认体积较大。若需优化加载速度,可通过官网提供的自定义构建工具生成精简版 echarts.js。在此过程中,务必确保所选的 ECharts 核心版本与 echarts-for-weixin 的版本严格匹配,例如若使用 v2.0.0,则核心库应对应 5.1.1 版本。

使用 ECharts 组件

假设需要绘制图表的目标页面命名为 echarts,则在小程序项目中需涉及以下四个核心文件:

  • echarts.js
  • echarts.wxml
  • echarts.wxss
  • echarts.json

首先在 echarts.json 文件中声明并引用该组件。

{
  "usingComponents": {
    "ec-canvas": "/activity/components/ec-canvas/ec-canvas"
  }
}

其中 ec-canvas 为组件的名称标识,/activity/components/ec-canvas/ec-canvas 指向小程序项目中实际存放该组件的目录路径。

接着在 echarts.wxml 文件中调用该组件。

<view class="ec-container">
  <ec-canvas canvas-id="echart-pie" ec="{{ec}}"></ec-canvas>
</view>

canvas-id 属性用于指定组件的唯一标识,必须保持唯一性;ec 属性用于绑定组件对象,内部封装了图表绘制所需的数据结构。

ECharts 组件依赖一个容器视图(view)。若需在同一页面展示多个图表,可将它们置于同一个容器内。关键在于,必须在组件初始化(onInit)执行前确保容器已具备明确的宽度和高度;否则,图表可能因无法确定渲染区域而显示为空白。

在 echarts.wxss 文件中定义布局样式类。

.ec-container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;

  width: 100vw;
  height: 100vh;
}

ec-canvas {
  width: 100%;
  height: 100%;
}

.ec-container 是组件容器的样式类,需明确声明其 width 和 height 属性。ec-canvas 是组件本身的样式类,可通过设置宽高或使用绝对定位(absolute/top/bottom/left/right)来精确控制图表的位置与尺寸。

在 echarts.js 文件中创建并绑定 ECharts 组件实例。

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

首先导入 echarts 模块。

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

  var option = {
    backgroundColor: "#ffffff",
    series: [{
      label: {
        normal: {
          fontSize: 14
        }
      },
      type: 'pie',
      center: ['50%', '50%'],
      radius: ['20%', '40%'],
      data: [{
        value: 55,
        name: '北京'
      }, {
        value: 20,
        name: '武汉'
      }, {
        value: 10,
        name: '杭州'
      }, {
        value: 20,
        name: '广州'
      }, {
        value: 38,
        name: '上海'
      }]
    }]
  };
  chart.setOption(option);

  return chart;
}

ECharts 组件初始化是一个通用函数,开发者只需修改该函数内部 option 对象的内容即可定义具体的图表样式与数据。

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

接下来进行 ECharts 组件的初始化并加载图表。

安装 ECharts 组件

图表延迟加载

若希望避免页面渲染时立即加载图表以提升性能,可采用延迟加载策略,即俗称的“懒加载”。

<view class="ec-container">
  <ec-canvas id="lazy-echart-pie" canvas-id="lazy-canvas-pie" ec="{{lazyEc}}"></ec-canvas>
</view>

id 是 ECharts 组件在页面中的唯一标识,canvas-id 则是组件内部 Canvas 画布的唯一标识。

Page({
  data: {
    lazyEc: {
      lazyLoad: true
    }
  }
})

在页面渲染阶段,不直接初始化 ECharts 组件对象,而是通过配置启用懒加载模式。

this.lazyComponent = this.selectComponent('#lazy-echart-pie')

页面渲染完成后,通过组件 ID 获取组件实例(lazyComponent),并将其保存至页面实例(this)中以便后续调用。

this.lazyComponent.init((canvas, width, height, dpr) => {
  const chart = echarts.init(canvas, null, {
    width: width,
    height: height,
    devicePixelRatio: dpr
  });
  canvas.setChart(chart);

  this.lazyChart = chart;

  var option = {
    ...
  };
  chart.setOption(option);

  return chart;
});

当需要展示图表时,利用已获取的组件实例手动调用初始化方法(init)。该方法的具体实现与 initChart 函数一致。为方便后续对图表实例(chart)进行操作,建议将其也保存至页面实例中。

this.lazyChart.dispose();

当图表不再需要时,获取图表实例并调用销毁方法以释放资源。

以上即为微信小程序集成 ECharts 的详细示例与操作指南,更多关于小程序使用 ECharts 的资料,建议关注本站发布的其他相关文章。

作者最新文章