Nuxt ECharts: 在 Nuxt 项目中轻松集成 ECharts

[kingyue]

在 Nuxt/Vue 中使用 ECharts 需要许多额外的配置，还要注意在开启 Nuxt SSR 时不引入在服务端无法运行的代码。nuxt-echarts正是为了解决这些痛点而生。只需要一行命令就能完成安装，还提供了同时配置按需引入和 TypeScript 类型的统一设置。

Github →

文档 →

功能

• ⛰ 服务端渲染 (SSR): 使用 Nuxt 服务端组件进行服务端 SVG 渲染

• ♾️ 客户端水合 (Hydration): 按需懒加载完整的 ECharts 或轻量化的客户端运行时

• 🛠️ 可配置: 仅导入必要的 ECharts 功能以缩小打包体积

• 🦾 强类型支持: 根据用户配置自动导入 ECharts 的选项类型

• 🌲 Tree-shaking: 只有使用到的组件才会被构建打包

安装

npx nuxi module add echarts

快速上手

在nuxt.config.ts中配置需要用到的功能（缩小打包体积，避免引入整个 ECharts ）：

export default defineNuxtConfig({
  modules: ['nuxt-echarts'],
  echarts: {
    charts: ['BarChart'],
    components: ['DatasetComponent', 'GridComponent', 'TooltipComponent'],
  },
})

然后就可以在你的项目中使用<VChart>组件了，如果是 TypeScript 项目，你还可以直接使用按照上面的配置自动生成的ECOption类型，为 ECharts 配置提供类型提示：

<script setup lang="ts">
const option = ref<ECOption>({
  dataset: {
    dimensions: ['Product', '2015', '2016', '2017'],
    source: [
      {
        Product: 'Matcha Latte',
        2015: 54,
        2016: 42,
        2017: 23,
      },
    ],
  },
  xAxis: { type: 'category' },
  yAxis: {},
  series: [{ type: 'bar' }],
})
</script>

<template>
  <VChart :option="option" />
</template>

<VChart> 其实就是 @Justineo 大佬的Vue-ECharts，用法完全一样。本项目为 Vue-ECharts 提供了 Nuxt 项目的一键集成，同时还增加了 ECharts 服务端渲染功能。

进阶功能：ECharts SSR

通常即使是开启了 Nuxt 的 SSR ，我们在使用 ECharts 时也仅是在客户端组件挂载后才渲染图表，从服务端发送过来的 HTML 是不含图表的。

ECharts 在 v5.3 和 v5.5 中分别引入了服务端 SVG 渲染功能和客户端轻量运行时（请务必先阅读这个官方文档），让我们能够在前端第一时间显示图表，而且可以在一些无需复杂交互的场景下大幅减少包体积，只在客户端加载一个不到 4KB 的轻量运行时。

nuxt-echarts将各种使用场景封装成了组件，除了常用的<VChart>，还有基于服务端组件的VChartIsland、<VChartServer>和<VChartLight>,分别对应不同的应用场景：

组件	渲染方案	加载量	功能和交互丧失	推荐场景
VChart 同时设置 ssr:true	服务器端 SVG 渲染加客户端 ECharts 延迟加载	大	延迟加载完成前无法交互	首屏加载时间敏感，对完整功能和交互有较高需求，图表加载后最好不立即需要交互
VChartIsland	只在服务器端 SVG 渲染	小	不支持图例切换系列显示，不支持工具提示等对实时性要求高的交互	首屏加载时间敏感，对完整功能和交互要求较低
VChartServer	只在服务器端 SVG 渲染	小	与上面相同，但可以 inject 由祖先组件provide的数据	与上面相同
VChartLight	服务器端 SVG 渲染加客户端轻量级运行时	小	无法实现对实时性要求高的交互	首屏加载时间敏感，对完整功能和交互要求较低，对代码量有严格要求，对交互实时性要求不严格

Examples →

在Nuxt ECharts 文档中探索更多细节吧,欢迎在Issues和Discussions中提出任何问题与建议！

[dragonszy]

战略马克，感觉很需要