
uni-echarts
工具适用于 uni-app 的 Apache ECharts 组件(仅支持 Vue 3),提供与 vue-echarts 近乎一致的开发体验,支持 Web、小程序、APP 多端运行,内置 easycom 自动注册、TypeScript 类型支持、在线代码生成器
echartschartvisualizationvue3uni-appcanvastypescriptdata-viz
详细文档
资源概述#
uni-echarts 是 xiaohe0601 开发的 uni-app Vue3 Apache ECharts 组件封装。它让开发者能在 uni-app 项目中以近乎 vue-echarts 的方式使用 ECharts 数据可视化,一份代码运行在 Web、各家小程序和 APP 端。
核心特性#
- Vue 3 Composition API:响应式 option 绑定,自动更新图表
- 多端兼容:Web、微信/支付宝/百度/抖音/QQ 小程序、APP 全覆盖
- easycom 支持:配置后自动注册组件,无需手动 import
- TypeScript 原生:完整类型定义,开发体验友好
- API 对齐 vue-echarts:迁移成本极低,熟悉 vue-echarts 的开发者零学习成本
- 代码生成器:提供在线代码生成器,一键生成图表配置
- 在线演示:在线 Playground 可实时预览各种图表类型
项目数据#
| 指标 | 数值 |
|---|---|
| GitHub Stars | 172⭐ |
| Forks | 10 |
| npm 版本数 | 43(latest: 2.5.2) |
| npm 最后修改 | 2026-05-26 |
| 最后推送 | 2026-08-04 |
| 许可证 | MIT |
| 创建年份 | 2023 |
设计规范#
组件 API 设计#
uni-echarts 的组件接口与 vue-echarts 高度一致:
<template>
<uni-echarts :option="option" @click="onClick" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
// easycom 已自动注册,无需 import
const option = ref({
xAxis: {
type: 'category',
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
},
yAxis: { type: 'value' },
series: [{
data: [150, 230, 224, 218, 135, 147, 260],
type: 'line'
}]
})
const onClick = (params: any) => {
console.log('点击了', params.name, params.value)
}
</script>
支持的图表类型#
通过按需引入 echarts 模块,uni-echarts 支持所有 ECharts 图表类型:
| 分类 | 图表 |
|---|---|
| 基础图表 | 柱状图(bar)、折线图(line)、饼图(pie)、散点图(scatter) |
| 专业图表 | 雷达图(radar)、箱线图(boxplot)、蜡烛图(candlestick)、热力图(heatmap) |
| 高级图表 | 关系图(graph)、树图(tree)、旭日图(sunburst)、桑基图(sankey)、漏斗图(funnel) |
| 地图 | 地图(map)、系列地图(series.map) |
| 3D 图表 | 需引入 echarts-gl 扩展 |
按需引入(减小包体积)#
// main.ts 或入口文件
import * as echarts from 'echarts/core'
import { BarChart, LineChart, PieChart } from 'echarts/charts'
import {
TitleComponent, TooltipComponent, GridComponent, LegendComponent
} from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'
echarts.use([
BarChart, LineChart, PieChart,
TitleComponent, TooltipComponent, GridComponent, LegendComponent,
CanvasRenderer
])
平台兼容性#
| 平台 | 支持 | 说明 |
|---|---|---|
| 微信小程序 | ✅ | Canvas 2D |
| 支付宝小程序 | ✅ | Canvas 2D |
| 百度小程序 | ✅ | Canvas 2D |
| 抖音小程序 | ✅ | Canvas 2D |
| QQ 小程序 | ✅ | Canvas 2D |
| H5 / Web | ✅ | Canvas / SVG |
| APP | ✅ | Canvas |
| 鸿蒙 | ⚠️ | 理论兼容(uni-app 支持),未官方测试 |
审核规范#
不适用(开源工具库,非平台类资源)
开发指南#
安装#
# npm
npm install uni-echarts echarts
# pnpm
pnpm add uni-echarts echarts
# DCloud 插件市场导入
# https://ext.dcloud.net.cn/plugin?id=15250
配置 easycom#
在 pages.json 中配置自动注册:
{
"easycom": {
"custom": {
"uni-echarts": "uni-echarts/components/uni-echarts/uni-echarts.vue"
}
}
}
完整示例#
<template>
<view class="chart-container">
<uni-echarts
ref="chartRef"
:option="option"
:loading="loading"
@click="onChartClick"
@finished="onChartFinished"
/>
<button @click="updateData">刷新数据</button>
<button @click="exportImage">导出图片</button>
</view>
</template>
<script setup lang="ts">
import { ref, shallowRef } from 'vue'
const chartRef = ref()
const loading = ref(false)
// 使用 shallowRef 包装 echarts option(性能优化)
const option = shallowRef({
title: { text: '销售数据', left: 'center' },
tooltip: { trigger: 'axis' },
legend: { data: ['销售额', '利润'], bottom: 0 },
xAxis: {
type: 'category',
data: ['1月', '2月', '3月', '4月', '5月', '6月']
},
yAxis: { type: 'value', name: '万元' },
series: [
{
name: '销售额',
type: 'bar',
data: [120, 200, 150, 80, 70, 110],
itemStyle: { color: '#5470c6' }
},
{
name: '利润',
type: 'line',
data: [60, 95, 75, 40, 35, 55],
itemStyle: { color: '#91cc75' }
}
]
})
const updateData = () => {
loading.value = true
setTimeout(() => {
option.value = {
...option.value,
series: option.value.series.map(s => ({
...s,
data: s.data.map(() => Math.round(Math.random() * 200 + 50))
}))
}
loading.value = false
}, 500)
}
const exportImage = () => {
const instance = chartRef.value?.getEchartsInstance()
if (instance) {
const url = instance.getDataURL({
type: 'png',
pixelRatio: 2,
backgroundColor: '#fff'
})
console.log('图片 URL:', url)
// uni.saveImageToPhotosAlbum({ filePath: url })
}
}
const onChartClick = (params: any) => {
console.log('点击:', params.componentType, params.name, params.value)
}
const onChartFinished = () => {
console.log('图表渲染完成')
}
</script>
<style scoped>
.chart-container {
width: 100%;
height: 300px;
}
</style>
常见陷阱#
- 包体积过大:echarts 全量引入会导致小程序包体超限(>2MB),必须按需引入图表模块
- option 使用 shallowRef:echarts option 对象较大时,使用
shallowRef而非ref避免不必要的深度响应式开销 - Canvas 层级问题:小程序中 Canvas 组件层级最高,覆盖弹窗/导航时需使用
cover-view/cover-image - renderToDataURL:导出图片在小程序端需要适配平台 API,不能直接使用浏览器
toDataURL - Skyline 渲染引擎:微信小程序开启 Skyline 后需确认 Canvas 组件兼容性
生态资源#
ECharts 生态#
| 项目 | 说明 | Stars |
|---|---|---|
| Apache ECharts | 底层可视化库 | 61000+⭐ |
| vue-echarts | Vue3 ECharts 组件(Web 端) | 9500+⭐ |
| echarts-for-weixin | 微信原生小程序 ECharts 适配 | 7501⭐ |
对比参考#
| 方案 | 框架 | 多端 | Vue3 | 维护状态 | 文档 |
|---|---|---|---|---|---|
| uni-echarts | uni-app Vue3 | ✅ 全端 | ✅ | 🟢 活跃 | ⭐⭐⭐⭐ |
| echarts-for-weixin | 微信原生 | ❌ 仅微信 | ❌ | ⚠️ 停更(2024-06) | ⭐⭐⭐ |
| lime-echart | uni-app | ✅ | ✅ | 🟡 个人维护 | ⭐⭐ |
版本更新#
- v2.5.2(2026-05):TypeScript 类型修复,优化小程序端 Canvas 渲染性能
- v2.5.0(2026-03):重大更新,对齐 vue-echarts 7.x API,支持
provide/injectECharts 实例 - v2.4.0(2025-12):新增在线代码生成器,支持 DCloud 插件市场导入
- v2.3.0(2025-09):优化按需引入体验,支持 echarts/core tree-shaking
- v2.0.0(2025-06):Vue 3 Composition API 重写,放弃 Vue 2 支持