Skip to content
/ uni-echarts Public

🪀 适用于uni-app的Apache ECharts组件（仅支持Vue 3）

License

MIT license
13 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

xiaohe0601/uni-echarts

BranchesTags

Repository files navigation

logo

uni-echarts

🪀 适用于uni-app的Apache ECharts组件（仅支持Vue 3）

github stars npm version npm downloads JSDocs License

xiaohe0601 / github@xiaohe0601 / gitee@xiaohe0601

🎉 特性

  • 🚀 快速上手，与 vue-echarts 近乎一致的使用体验

  • 📱 多端兼容，支持H5、小程序、APP

  • 📦 支持 easycom

  • ☕ 支持 TypeScript

  • 🍳 支持免费商用

🚁 安装

uni-echarts 提供了 npm 和 uni-modules 两种使用方式，任选其一即可

版本要求

{
  "echarts": ">=5.3.0",
  "vue": ">=3.3.0"
}

npm 方式

# pnpm
pnpm add echarts uni-echarts

# yarn
yarn add echarts uni-echarts

# npm
npm install echarts uni-echarts

uni-modules 方式

  1. 使用 npm 安装 echarts

    # pnpm
pnpm add echarts

# yarn
yarn add echarts

# npm
npm install echarts

  2. 前往uni-app插件市场下载 uni-echarts

🛹 使用

简单示例

npm 方式

<template>
  <uni-echarts custom-class="chart" :option="option"></uni-echarts>
</template>

<script setup>
import { PieChart } from "echarts/charts";
import { DatasetComponent, LegendComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import UniEcharts from "uni-echarts";
import { provideEcharts, provideEchartsTheme } from "uni-echarts/shared";
import { ref } from "vue";

// 由于目前 uni-app 对于 npm 插件的编译机制问题
// 小程序端的 npm 插件内部无法正确获取到业务侧的 echarts
// 所以需要手动将 echarts 提供给插件用于构建图表
provideEcharts(echarts); // 🚨 注意：npm 方式需要添加这一行代码

// 此处仅用于演示通过 provide 修改图表 theme 的方式，不是必需
provideEchartsTheme("dark");

echarts.use([
  LegendComponent,
  TooltipComponent,
  DatasetComponent,
  PieChart,
  CanvasRenderer
]);

const option = ref({
  legend: {
    top: 10,
    left: "center"
  },
  tooltip: {
    trigger: "item",
    textStyle: {
      // #ifdef MP-WEIXIN
      // 临时解决微信小程序 tooltip 文字阴影问题
      textShadowBlur: 1
      // #endif
    }
  },
  series: [
    {
      type: "pie",
      radius: ["30%", "52%"],
      label: {
        show: false,
        position: "center"
      },
      itemStyle: {
        borderWidth: 2,
        borderColor: "#ffffff",
        borderRadius: 10
      },
      emphasis: {
        label: {
          show: true,
          fontSize: 20
        }
      }
    }
  ],
  dataset: {
    dimensions: ["来源", "数量"],
    source: [
      ["Search Engine", 1048],
      ["Direct", 735],
      ["Email", 580],
      ["Union Ads", 484],
      ["Video Ads", 300]
    ]
  }
});
</script>

<style scoped>
.chart {
  height: 300px;
}
</style>

uni-modules 方式

uni-echarts 支持 easycom 规范，当使用 uni-modules 方式时无需导入即可直接使用组件

<template>
  <uni-echarts custom-class="chart" :option="option"></uni-echarts>
</template>

<script setup>
import { PieChart } from "echarts/charts";
import { DatasetComponent, LegendComponent, TooltipComponent } from "echarts/components";
import { use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { ref } from "vue";
// 🚨 注意导入路径与 npm 方式的区别
import { provideEchartsTheme } from "@/uni_modules/xiaohe-echarts";

// 此处仅用于演示通过 provide 修改图表 theme 的方式，不是必需
provideEchartsTheme("dark");

use([
  LegendComponent,
  TooltipComponent,
  DatasetComponent,
  PieChart,
  CanvasRenderer
]);

const option = ref({
  legend: {
    top: 10,
    left: "center"
  },
  tooltip: {
    trigger: "item",
    textStyle: {
      // #ifdef MP-WEIXIN
      // 临时解决微信小程序 tooltip 文字阴影问题
      textShadowBlur: 1
      // #endif
    }
  },
  series: [
    {
      type: "pie",
      radius: ["30%", "52%"],
      label: {
        show: false,
        position: "center"
      },
      itemStyle: {
        borderWidth: 2,
        borderColor: "#ffffff",
        borderRadius: 10
      },
      emphasis: {
        label: {
          show: true,
          fontSize: 20
        }
      }
    }
  ],
  dataset: {
    dimensions: ["来源", "数量"],
    source: [
      ["Search Engine", 1048],
      ["Direct", 735],
      ["Email", 580],
      ["Union Ads", 484],
      ["Video Ads", 300]
    ]
  }
});
</script>

<style scoped>
.chart {
  height: 300px;
}
</style>

Important

由于小程序对于代码体积的要求非常严苛，所以我们鼓励手动从 echarts 中引入组件和图表，以减小打包体积。vue-echarts 团队构建了一个导入代码生成器，你只需要把 option 的代码粘贴进去，就可以得到精确的导入代码。

试一试 →

但如果你实在需要全量引入 echarts 从而无需手动引入模块，只需要在代码中添加：

import "echarts";

属性

参数 说明 类型 可选值 默认值
custom-class 自定义 class any - -
custom-style 自定义 style StyleValue - -
option echarts option object - -
option-key provide option key string - -
theme echarts theme string / object - -
init-options echarts init opts object - -
update-options echarts setOption opts object - -
group echarts group string - -
manual-update 是否手动更新 option boolean - false
WEB autoresize 是否自动 resize（仅WEB端支持） AutoResize - false
loading 是否显示加载动画效果 boolean - false
loading-options echarts showLoading opts string - -
canvas-type canvas type string 2d / legacy 2d
disable-scroll 触摸时是否禁用滚动 boolean - false
support-hover PC 端是否支持 hover 行为 boolean - false
init-delay 初始化延迟时间（单位：ms） number - 30

相关类型定义

type AutoResize = boolean | {
  throttle?: number;
  onResize?: () => void;
};

事件

可以使用 Vue 的 v-on 指令绑定事件

<template>
  <uni-echarts
    :option="option"
    @click="handleClick"
    @finished.once="handleFinished"
    @zr:click="handleZrClick"
    @native:tap="handleNativeTap"></uni-echarts>
</template>

Note

仅支持 .once 修饰符（并且小程序端不支持），因为其它修饰符都与 DOM 事件机制强耦合。

uni-echarts 支持如下事件：

  • highlight →

  • downplay →

  • selectchanged →

  • legendselectchanged →

  • legendselected →

  • legendunselected →

  • legendselectall →

  • legendinverseselect →

  • legendscroll →

  • datazoom →

  • datarangeselected →

  • timelinechanged →

  • timelineplaychanged →

  • restore →

  • dataviewchanged →

  • magictypechanged →

  • geoselectchanged →

  • geoselected →

  • geounselected →

  • axisareaselected →

  • brush →

  • brushEnd →

  • brushselected →

  • globalcursortaken →

  • rendered →

  • finished →

  • 鼠标事件

  • ZRender 事件

    • zr:click
    • zr:mousedown
    • zr:mouseup
    • zr:mousewheel
    • zr:dblclick
    • zr:contextmenu

请参考支持的事件列表。前往 →

原生 DOM 事件

由于 uni-echarts 默认将事件绑定到 echarts 实例，因此在使用原生 DOM 事件时需要做一些特殊处理，你需要在事件名称前加上 native: 前缀来绑定原生 DOM 事件。

<template>
  <!-- 注意，uni-app 中的原生 DOM 点击事件应该使用 tap 而不是 click -->
  <uni-echarts @native:tap="handleNativeTap"></uni-echarts>
</template>

Provide / Inject

🚧 Web 端使用 npm 方式使用组件时暂不支持该用法

uni-echarts 为 option、 theme、init-options、update-options 和 loading-options 提供并导出了 provide 相关的 API，从而可以通过上下文的方式进行配置选项。

例如，可以通过如下方式来使用 provide API 为 theme 提供上下文配置：

import { provideEchartsTheme } from "uni-echarts/shared";

// 支持 字面量、ref、getter 等类型的值，组件内部通过 `toValue` 解析
provideEchartsTheme("dark");

另外，option 与其他选项略有不同，可以通过 option-key 选择控制某一个图表

<template>
  <!-- 注意，option-key 不是响应式，不支持动态修改 -->
  <uni-echarts option-key="chart1"></uni-echarts>

  <uni-echarts option-key="chart2"></uni-echarts>

  <uni-echarts></uni-echarts>
</template>

<script setup>
import { provideEchartsOption } from "uni-echarts/shared";
import { ref } from "vue";

const option = ref({
  // ...
});

// 此时，option 仅会影响 option-key 相同的图表
provideEchartsOption("chart1", option);
</script>

方法

  • setOption →

  • getWidth →

  • getHeight →

  • getDom →

  • getOption →

  • resize →

  • dispatchAction →

  • convertToPixel →

  • convertFromPixel →

  • containPixel →

  • showLoading →

  • hideLoading →

  • getDataURL →

  • getConnectedDataURL →

  • clear →

  • dispose →

  • toTempFilePath → （无需传 canvasId 或 canvas 参数）

可以通过 ref 调用以上方法，例如：

<template>
  <uni-echarts ref="chartEl"></uni-echarts>
</template>

<script lang="ts" setup>
import type { UniEchartsInst } from "uni-echarts/shared";
import { ref } from "vue";

const chartEl = ref<UniEchartsInst | null>(null);

function download() {
  if (chartEl.value == null) {
    return;
  }

  chartEl.value.toTempFilePath();
}
</script>

静态方法

静态方法请直接通过 echarts 本身 进行调用

🍬 感谢

🐶 讨论交流

🏆 开源协议

🚓 声明

The Apache Software Foundation Apache ECharts, ECharts, Apache, the Apache feather, and the Apache ECharts project logo are either registered trademarks or trademarks of the Apache Software Foundation.

About

🪀 适用于uni-app的Apache ECharts组件（仅支持Vue 3）

Resources

Readme

License

MIT license
Activity

Stars

13 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 7

v0.0.7 Latest
Feb 8, 2025
+ 6 releases

Packages

No packages published

Languages