mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-10-15 05:19:17 +00:00
461 lines
13 KiB
Markdown
461 lines
13 KiB
Markdown
---
|
||
title: uni-echarts
|
||
iframe: true
|
||
iframeFormatter: subEcharts/echarts/index
|
||
---
|
||
# Echarts
|
||
|
||
在移动端跨平台开发中，数据可视化是一个常见需求。而 ECharts 作为百度开源的强大图表库，在 Web 端有着广泛的应用，我们在技术栈选择的时候往往倾向于选择这种应用广泛，解决方案完善的库。
|
||
|
||
但在 uni-app 中直接使用 ECharts 会遇到各种兼容性问题，特别是在小程序端。幸运的是，有很多库可以帮助我们在 `uni-app` 中使用 `Echarts`，例如 `uni-echarts`、`lime-echart` 等插件，为我们提供了相应的解决方案。
|
||
|
||
本章节中，我们将会在 wot-starter 中，探索 uni-app 接入 `Echarts` 的方案，并针对小程序，对其超级庞大的体积进行优化。
|
||
|
||
## 为什么选择 uni-echarts？
|
||
|
||
[uni-echarts](https://github.com/xiaohe0601/uni-echarts) 是一个适用于 uni-app 的 Apache ECharts 组件（仅支持Vue 3），具有以下优势：
|
||
|
||
- 🚀 **快速上手**：与 [Vue ECharts](https://github.com/ecomfe/vue-echarts) 近乎一致的使用体验
|
||
- 📱 **多端兼容**：支持 H5、小程序、APP 等多个平台
|
||
- 📦 **支持 easycom**：无需手动导入，开箱即用
|
||
- ☕ **TypeScript 支持**：完整的类型定义
|
||
- 🍳 **免费商用**：基于 MIT 许可协议
|
||
|
||
基于以上，选择使用 `uni-echarts` 作为我们的图表库，当然也可以选择 [lime-echart](https://ext.dcloud.net.cn/plugin?id=4899) 。
|
||
|
||
## 安装和配置
|
||
|
||
### 1. 安装依赖
|
||
|
||
首先安装必要的依赖包：
|
||
|
||
```bash
|
||
pnpm add echarts uni-echarts
|
||
# 或者
|
||
npm install echarts uni-echarts
|
||
```
|
||
|
||
在我们的项目中，`package.json` 已经包含了这些依赖：
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"echarts": "^6.0.0",
|
||
"uni-echarts": "^1.1.2"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. Vite 配置
|
||
|
||
在 `vite.config.ts` 中添加必要的配置：
|
||
|
||
```typescript
|
||
import { defineConfig } from 'vite'
|
||
import Uni from '@dcloudio/vite-plugin-uni'
|
||
import UniHelperComponents from '@uni-helper/vite-plugin-uni-components'
|
||
import { UniEchartsResolver } from 'uni-echarts/resolver'
|
||
|
||
export default defineConfig({
|
||
optimizeDeps: {
|
||
exclude:['@wot-ui/ui', 'uni-echarts'] : [],
|
||
},
|
||
plugins: [
|
||
// 组件自动导入
|
||
UniHelperComponents({
|
||
resolvers: [UniEchartsResolver()],
|
||
dts: 'src/components.d.ts',
|
||
}),
|
||
Uni(),
|
||
],
|
||
})
|
||
```
|
||
|
||
这样配置后，`uni-echarts` 组件就可以在项目中自动导入使用了，更多信息参见 [Uni ECharts 快速开始](https://uni-echarts.xiaohe.ink/guide/getting-started)。
|
||
|
||
## 基础使用示例
|
||
|
||
### 创建一个柱状图组件
|
||
|
||
让我们以项目中的 `BarChart.vue` 为例，看看如何创建一个基础的柱状图：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { BarChart } from 'echarts/charts'
|
||
import { DatasetComponent, GridComponent, LegendComponent, TooltipComponent } from 'echarts/components'
|
||
import * as echarts from 'echarts/core'
|
||
import { CanvasRenderer } from 'echarts/renderers'
|
||
import { provideEcharts } from 'uni-echarts/shared'
|
||
|
||
// 🚨 重要：由于 npm 插件编译机制问题，需要手动提供 echarts 实例
|
||
provideEcharts(echarts)
|
||
|
||
// 注册需要的组件
|
||
echarts.use([
|
||
GridComponent,
|
||
LegendComponent,
|
||
TooltipComponent,
|
||
DatasetComponent,
|
||
BarChart,
|
||
CanvasRenderer,
|
||
])
|
||
|
||
// 图表配置
|
||
const option = ref({
|
||
tooltip: {
|
||
trigger: 'axis',
|
||
axisPointer: {
|
||
type: 'shadow',
|
||
},
|
||
},
|
||
legend: {
|
||
data: ['销售额', '利润'],
|
||
top: 30,
|
||
},
|
||
grid: {
|
||
left: '3%',
|
||
right: '4%',
|
||
bottom: '3%',
|
||
containLabel: true,
|
||
},
|
||
xAxis: {
|
||
type: 'category',
|
||
data: ['1月', '2月', '3月', '4月', '5月', '6月'],
|
||
},
|
||
yAxis: {
|
||
type: 'value',
|
||
},
|
||
series: [
|
||
{
|
||
name: '销售额',
|
||
type: 'bar',
|
||
data: [120, 200, 150, 80, 70, 110],
|
||
itemStyle: {
|
||
color: '#5470c6',
|
||
},
|
||
},
|
||
{
|
||
name: '利润',
|
||
type: 'bar',
|
||
data: [20, 40, 30, 15, 12, 22],
|
||
itemStyle: {
|
||
color: '#91cc75',
|
||
},
|
||
},
|
||
],
|
||
})
|
||
</script>
|
||
|
||
<template>
|
||
<uni-echarts custom-class="h-300px" :option="option" />
|
||
</template>
|
||
```
|
||
|
||
### 关键要点说明
|
||
|
||
1. **provideEcharts(echarts)**：这是使用 uni-echarts 的关键步骤，必须在每个组件中调用
|
||
2. **按需导入**：只导入需要的图表类型和组件，减小打包体积
|
||
3. **echarts.use()**：注册导入的组件
|
||
4. **uni-echarts 组件**：使用 `<uni-echarts>` 标签渲染图表
|
||
|
||
## 更多图表类型
|
||
更多图表类型见 [Echarts](https://echarts.apache.org/examples/zh/index.html) 和 [Uni ECharts](https://uni-echarts.xiaohe.ink/examples/basic)，当然你也可以使用 AI 工具帮助你编写想要的图表配置，它非常善于处理这个事情。
|
||
|
||
|
||
## 高级功能：分包优化与异步加载
|
||
|
||
引入 `Echarts` 后，体积暴增 800KB ，怎么办？
|
||
|
||
有办法，我们曾在 [Vue3 uni-app 主包 2 MB 危机？1 个插件 10 分钟瘦身](https://mp.weixin.qq.com/s/nnmu91kclQHnE-1TAn11Tg) 一文中介绍过 `@uni-ku/bundle-optimizer`，它是解决微信小程序超包的利器，我们现在使用它的分包优化和分包异步化能力，来优化引入 `Echarts` 后暴增的小程序体积。
|
||
|
||
这是我们的项目结构，在 `subEcharts` 分包中实现 `Echarts` 相关组件，在 `subAsyncEcharts` 分包中演示分包异步化效果：
|
||
|
||
```text
|
||
src/
|
||
├── pages/ # 主包页面
|
||
├── subEcharts/ # ECharts 组件分包
|
||
│ └── echarts/
|
||
│ └── components/
|
||
├── subAsyncEcharts/ # 异步 ECharts 演示分包
|
||
│ └── asyncEcharts/
|
||
└── subPages/ # 其他功能分包
|
||
```
|
||
|
||
### 安装和配置
|
||
|
||
#### 1. 安装依赖
|
||
|
||
```bash
|
||
pnpm add -D @uni-ku/bundle-optimizer
|
||
# 或者
|
||
npm install -D @uni-ku/bundle-optimizer
|
||
```
|
||
|
||
在我们的项目中，`package.json` 已经包含了这个依赖：
|
||
|
||
```json
|
||
{
|
||
"devDependencies": {
|
||
"@uni-ku/bundle-optimizer": "1.3.15-beta.2"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. Vite 配置
|
||
|
||
在 `vite.config.ts` 中配置插件：
|
||
|
||
```typescript
|
||
import { defineConfig } from 'vite'
|
||
import Uni from '@dcloudio/vite-plugin-uni'
|
||
import Optimization from '@uni-ku/bundle-optimizer'
|
||
|
||
export default defineConfig({
|
||
plugins: [
|
||
Uni(),
|
||
// 分包优化插件
|
||
Optimization({
|
||
logger: true, // 开启日志输出
|
||
}),
|
||
],
|
||
})
|
||
```
|
||
|
||
#### 3. 小程序分包配置
|
||
|
||
在 `manifest.json` 中开启分包优化：
|
||
|
||
```json
|
||
{
|
||
"mp-weixin": {
|
||
"optimization": {
|
||
"subPackages": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
如果你使用了 `@uni-helper/vite-plugin-uni-manifest` 插件，那么需要在 `manifest.config.ts` 中开启分包优化：
|
||
```ts
|
||
export default defineManifestConfig({
|
||
'mp-weixin': {
|
||
optimization: {
|
||
subPackages: true,
|
||
},
|
||
},
|
||
})
|
||
```
|
||
配置完成后，重新构建，我们会发现主包少了 200+KB ，还剩 500KB 在主包中，可以期待 `@uni-ku/bundle-optimizer` 未来可以传送组件到分包中，到时会把大部分构建产物都打包进入分包中。
|
||
> 这里配合 lime-echart 的话，应该可以将 echarts.min.js 完全放入分包，各位可以自行探索。
|
||
|
||
### 跨分包异步组件引用
|
||
|
||
在我们的项目中，`subAsyncEcharts` 分包可以异步引用 `subEcharts` 分包中的组件：
|
||
|
||
```vue
|
||
<!-- src/subAsyncEcharts/asyncEcharts/index.vue -->
|
||
<script setup lang="ts">
|
||
// 跨分包异步导入组件
|
||
import BarChart from '@/subEcharts/echarts/components/BarChart.vue?async'
|
||
import DonutChart from '@/subEcharts/echarts/components/DonutChart.vue?async'
|
||
import FunnelChart from '@/subEcharts/echarts/components/FunnelChart.vue?async'
|
||
import GaugeChart from '@/subEcharts/echarts/components/GaugeChart.vue?async'
|
||
import LineChart from '@/subEcharts/echarts/components/LineChart.vue?async'
|
||
import LiquidFillChart from '@/subEcharts/echarts/components/LiquidFillChart.vue?async'
|
||
import MiniLineChart from '@/subEcharts/echarts/components/MiniLineChart.vue?async'
|
||
import PieChart from '@/subEcharts/echarts/components/PieChart.vue?async'
|
||
import RadarChart from '@/subEcharts/echarts/components/RadarChart.vue?async'
|
||
import ScatterChart from '@/subEcharts/echarts/components/ScatterChart.vue?async'
|
||
import StackedBarChart from '@/subEcharts/echarts/components/StackedBarChart.vue?async'
|
||
</script>
|
||
```
|
||
|
||
|
||
更多信息参见 [@uni-ku/bundle-optimizer](https://github.com/uni-ku/bundle-optimizer)。
|
||
|
||
## 注意事项和最佳实践
|
||
|
||
### 1. 使用 npm 方式安装必须调用 provideEcharts
|
||
|
||
在每个使用 ECharts 的组件中，都必须调用 `provideEcharts(echarts)`：
|
||
|
||
```javascript
|
||
import * as echarts from 'echarts/core'
|
||
import { provideEcharts } from 'uni-echarts/shared'
|
||
|
||
// 🚨 这一行是必须的
|
||
provideEcharts(echarts)
|
||
```
|
||
|
||
### 2. 按需导入组件
|
||
|
||
为了减小打包体积，建议按需导入需要的图表类型和组件：
|
||
|
||
```javascript
|
||
// 只导入需要的图表类型
|
||
import { BarChart, LineChart, PieChart } from 'echarts/charts'
|
||
// 只导入需要的组件
|
||
import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components'
|
||
// 导入渲染器
|
||
import { CanvasRenderer } from 'echarts/renderers'
|
||
```
|
||
|
||
### 3. 设置图表尺寸
|
||
|
||
使用 `custom-class` 属性设置图表容器的尺寸：
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 使用 UnoCSS/Tailwind 类名 -->
|
||
<uni-echarts custom-class="h-300px w-full" :option="option" />
|
||
|
||
<!-- 或者使用自定义 CSS 类 -->
|
||
<uni-echarts custom-class="chart-container" :option="option" />
|
||
</template>
|
||
|
||
<style>
|
||
.chart-container {
|
||
width: 100%;
|
||
height: 300px;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### 4. 响应式数据更新
|
||
|
||
当需要动态更新图表数据时，直接修改 `option` 对象即可：
|
||
|
||
```javascript
|
||
const option = ref({
|
||
// 初始配置
|
||
})
|
||
|
||
// 更新数据
|
||
function updateData() {
|
||
option.value.series[0].data = [/* 新数据 */]
|
||
}
|
||
```
|
||
|
||
### 5. 主题定制
|
||
|
||
可以通过 `provideEchartsTheme` 来设置自定义主题：
|
||
|
||
```javascript
|
||
import { provideEcharts, provideEchartsTheme } from 'uni-echarts/shared'
|
||
import * as echarts from 'echarts/core'
|
||
|
||
provideEcharts(echarts)
|
||
|
||
// 设置自定义主题
|
||
provideEchartsTheme({
|
||
color: ['#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de'],
|
||
backgroundColor: 'transparent',
|
||
// 更多主题配置...
|
||
})
|
||
```
|
||
|
||
## 卸载步骤
|
||
|
||
如果你不再需要在项目中使用 ECharts，可以按照以下步骤完全卸载相关依赖和配置：
|
||
|
||
### 1. 卸载依赖包
|
||
|
||
首先卸载 ECharts 相关的依赖包：
|
||
|
||
```bash
|
||
pnpm remove echarts uni-echarts
|
||
```
|
||
|
||
### 2. 清理 Vite 配置
|
||
|
||
在 `vite.config.ts` 中移除 ECharts 相关的配置：
|
||
|
||
```typescript
|
||
import { defineConfig } from 'vite'
|
||
import Uni from '@dcloudio/vite-plugin-uni'
|
||
import UniHelperManifest from '@uni-helper/vite-plugin-uni-manifest'
|
||
import UniHelperPages from '@uni-helper/vite-plugin-uni-pages'
|
||
import UniHelperLayouts from '@uni-helper/vite-plugin-uni-layouts'
|
||
import UniHelperComponents from '@uni-helper/vite-plugin-uni-components'
|
||
import AutoImport from 'unplugin-auto-import/vite'
|
||
import { WotResolver } from '@uni-helper/vite-plugin-uni-components/resolvers'
|
||
import { UniEchartsResolver } from 'uni-echarts/resolver' // [!code --]
|
||
import UniKuRoot from '@uni-ku/root'
|
||
|
||
export default async () => {
|
||
const UnoCSS = (await import('unocss/vite')).default
|
||
|
||
return defineConfig({
|
||
optimizeDeps: {
|
||
exclude: ['@wot-ui/ui', 'uni-echarts'] : [], // [!code --]
|
||
exclude: ['@wot-ui/ui',] : [], // [!code ++]
|
||
},
|
||
plugins: [
|
||
UniHelperManifest(),
|
||
UniHelperPages({
|
||
dts: 'src/uni-pages.d.ts',
|
||
subPackages: [
|
||
'src/subPages',
|
||
],
|
||
exclude: ['**/components/**/*.*'],
|
||
}),
|
||
UniHelperLayouts(),
|
||
UniHelperComponents({
|
||
resolvers: [WotResolver(), UniEchartsResolver()], // [!code --]
|
||
resolvers: [WotResolver()], // [!code ++]
|
||
dts: 'src/components.d.ts',
|
||
dirs: ['src/components', 'src/business'],
|
||
directoryAsNamespace: true,
|
||
}),
|
||
UniKuRoot(),
|
||
Uni(),
|
||
// https://github.com/uni-ku/bundle-optimizer
|
||
Optimization({
|
||
logger: true,
|
||
}),
|
||
AutoImport({
|
||
imports: ['vue', '@vueuse/core', 'pinia', 'uni-app', {
|
||
from: '@wot-ui/router',
|
||
imports: ['createRouter', 'useRouter', 'useRoute'],
|
||
}, {
|
||
from: '@wot-ui/ui',
|
||
imports: ['useToast', 'useMessage', 'useNotify', 'CommonUtil'],
|
||
}, {
|
||
from: 'alova/client',
|
||
imports: ['usePagination', 'useRequest'],
|
||
}],
|
||
dts: 'src/auto-imports.d.ts',
|
||
dirs: ['src/composables', 'src/store', 'src/utils', 'src/api'],
|
||
vueTemplate: true,
|
||
}),
|
||
UnoCSS(),
|
||
],
|
||
})
|
||
}
|
||
```
|
||
|
||
### 3. 删除相关文件和目录
|
||
|
||
删除项目中与 ECharts 相关的文件和目录：
|
||
|
||
```bash
|
||
# 删除 ECharts 组件分包目录
|
||
rm -rf src/subEcharts/
|
||
|
||
# 删除异步 ECharts 演示分包目录
|
||
rm -rf src/subAsyncEcharts/
|
||
|
||
```
|
||
|
||
完成以上步骤后，你的项目就完全移除了 ECharts 相关的依赖和配置，项目体积也会相应减小。
|
||
|
||
## 总结
|
||
|
||
我们在 `wot-starter` 中 使用 `uni-echarts` 结合 `@uni-ku/bundle-optimizer` 为 `uni-app` 开发者提供了一个完整的高性能 ECharts 解决方案。通过合理的配置和规范的使用方式，我们可以在各个平台上实现丰富的数据可视化效果，同时保证应用的性能和用户体验。
|
||
|
||
## 参考资源
|
||
|
||
- [uni-echarts 官方文档](https://uni-echarts.xiaohe.ink)
|
||
- [@uni-ku/bundle-optimizer](https://github.com/uni-ku/bundle-optimizer)
|
||
- [ECharts 官方文档](https://echarts.apache.org/zh/index.html)
|
||
- [lime-echart](https://ext.dcloud.net.cn/plugin?id=4899)
|