常见问题

列举了一些常见问题和解决方案。

不支持的功能清单

受限于 uni-app 的 API，以下功能尚不支持：

• SVG 渲染器
• toolbox.feature.saveAsImage
• series-map
• echarts-gl
• series-heatmap 暂不支持 echarts 6.1，请使用 6.0 及以下版本

Could not resolve "zrender/xxx"

使用 PNPM 安装 echarts 时，需要启用 shamefullyHoist 选项提升依赖， 否则会导致 echarts 无法正确解析 zrender 相关依赖。

# .npmrc

shamefully-hoist=true

或者：

# pnpm-workspace.yaml

shamefullyHoist: true

Yarn v2 等其他依赖管理工具请自行参考其官方文档配置。

小程序端 class / style 无效

在小程序端 Uni ECharts 通过 virtualHost 将自定义节点设置成 虚拟化组件节点， 使其更加接近 Vue 组件的表现。但是这将导致组件的 class / style 属性失效，所以组件提供了 custom-class / custom-style 属性来弥补这一缺陷。

• 可以在 manifest.json 的 mp-weixin / mp-alipay 字段下添加 mergeVirtualHostAttributes 配置， 用于合并小程序组件虚拟节点外层属性，这样就可以正常使用 class / style 等属性。

  // manifest.json
  
  {
    "mp-weixin": {
      // ...
      "mergeVirtualHostAttributes": true
    },
    "mp-alipay": {
      // ...
      "mergeVirtualHostAttributes": true
    }
  }

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

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

• 如果不启用 mergeVirtualHostAttributes 则需要将相关样式转移到一个单独不带 scoped 标识的 style 块中，使 Uni ECharts 可以共享样式。

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

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

• 也可以直接使用 custom-style 设置样式。

  <template>
    <uni-echarts custom-style="height: 300px" :option="option"></uni-echarts>
  
    <uni-echarts :custom-style="{ height: '300px' }" :option="option"></uni-echarts>
  </template>

• 在自定义组件中如果需要覆盖 Uni ECharts 的内部样式，需要添加 styleIsolation: "shared" 选项。

  <script setup>
  defineOptions({
    options: {
      styleIsolation: "shared"
    }
  });
  </script>

  Options API 示例

  <script>
  import { defineComponent } from "vue";
  
  export default defineComponent({
    options: {
      styleIsolation: "shared"
    }
  });
  </script>

小程序端 tooltip 文字阴影问题

具体原因未知，猜测可能是微信 canvas 的问题，可以通过设置 textShadowBlur 临时解决，示例如下：

const option = ref({
  tooltip: {
    trigger: "item",
    textStyle: {
      // #ifdef MP-WEIXIN
      textShadowBlur: 1
      // #endif
    }
  }
});

注意

目前 textShadowBlur 设置为 0 无效，所以退而求其次设置为了 1。

微信开发者工具 canvas 不跟随页面滚动或者层级过高

这是微信开发者工具的 BUG，真机不受影响，可以忽略。

部分小程序平台不支持 option 包含诸如 formatter 的函数字段

这是部分小程序平台原生的限制，他们通过 JSON 序列化参数所以导致函数字段丢失，可以通过以下方案解决：

• 启用 manual-update 并使用 setOption 手动设置 option

• 使用 provideEchartsOption 设置 option，参考 依赖注入

在弹窗组件内使用时无法正常展示

一般弹窗组件都会添加入场动画，导致 Uni ECharts 刚渲染时无法正常获取到画布大小，所以需要将 Uni ECharts 的渲染时机延迟到弹窗动画完成后。

下面以 Wot UI 的 Popup 弹出层 为例：

<template>
  <wd-popup
    v-model="visible"
    @after-enter="render = true"
    @after-leave="render = false"
  >
    <uni-echarts v-if="render" :option="option"></uni-echarts>
  </wd-popup>
</template>

const visible = ref(false);
const render = ref(false);

以上示例仅展示关键代码，详细可以参考 弹窗内使用 部分的代码示例。