「ECharts」交互 API （echarts、echartsInstance）

交互 API

---

> 全局 echarts 对象

全局 echarts 对象是引入 echarts.js 文件之后就可以直接使用的。

> echartsInstance 对象

echartsInstance 对象是通过 echarts.init 方法调用之后得到的。

对于下面这段代码，全局 echarts 对象即为 echarts ，echartsInstance 对象即为创建的实例 mCharts 。

var mCharts = echarts.init(document.querySelector("div"))

交互 API 即为 全局 echarts 对象 和 echartsInstance 对象 中常见方法。

1. 全局 echarts 对象

---

> init

用于初始化 echarts 实例对象、使用主题。

var mCharts = echarts.init(document.querySelector("div"), 'dark')

> registerTheme

用于注册主题，只有注册过的主题，才能在 init 方法中使用。

> registerMap

用于注册地图数据。

$.get('json/map/china.json', (ret) => {
  echarts.registerMap('chinaMap', ret)
  var option = {
    geo: {
      type: 'map',
      map: 'chinaMap',
    },
    series: [
      {
        data: airData,                // 空气质量指数数据
        geoIndex: 0,
        type: 'map'
      },
      {
        data: scatterData,            // 配置散点坐标数据
        type: 'effectScatter',
        coordinateSystem: 'geo',      // 指明散点使用的坐标系统
        rippleEffect: {
          scale: 10                   // 设置涟漪动画缩放比例
        }
      }
    ],
  }
  mCharts.setOption(option)
})

> connect

一个页面中可以有多个独立的图表，每一个图表对应一个 ECharts 实例对象。connect 可以实现多图关联，传入联动目标为 ECharts 实例对象，支持数组。

connect 的应用场景主要为：保存图片的自动拼接、刷新按钮、重置按钮、提示框联动、图例选择、数据范围修改等。

例如，添加如下地图并将其与之前的图表进行拼接，可以这样操作：

var mCharts2 = echarts.init(document.querySelector('#div1'), 'vintage')
$.get('json/map/china.json', function (ret) {
  echarts.registerMap('aa', ret)
  var option2 = {
    geo: {
      type: 'map',
      map: 'aa'
    }
  }
  mCharts2.setOption(option2)
  echarts.connect([mCharts, mCharts2]) // 将柱状图和地图关联起来
})

拼接后进行图片下载，两张图表会被整合在一起进行下载。

2. echartsInstance 对象

---

> setOption

setOption 用于设置或修改图表实例的配置项以及数据。可以对 setOption 方法进行多次调用，进行合并新旧配置项。

> resize

重新计算和绘制图表，一般和 window 对象的 resize 事件结合使用。

// 监听 window 窗口大小变化的事件
window.onresize = function () {
  // 调用 echarts 实例对象的 resize 方法
  mCharts.resize()
}

> on \ off

用于绑定或者解绑事件处理函数。主要用于两类事件：

• 鼠标事件：click、dblclck、mousedown、mousemove、mouseup 等

鼠标事件官网文档说明 > https://echarts.apache.org/zh/api.html#events

    mCharts.on('click', function (arg) {
      console.log(arg)
      console.log('click...')
    }) // 对事件进行监听

• ECharts 事件：legendselectchanged、datazoom、pieselectchanged、mapselectchanged 等

ECharts 事件官网文档说明 > https://echarts.apache.org/zh/api.html#echarts

> dispatchAction

用于模拟用户的行为。具体来说，触发图表行为，例如图例开关 legendToggleSelect，数据区域缩放dataZoom，显示提示框 showTip 等等。

$('#btn1').click(function () {
  // 模拟用户的行为
  mCharts.dispatchAction({
    type: 'highlight',
    seriesIndex: 0, // 系列的索引
    dataIndex: 1 // 数据的索引
  })
  mCharts.dispatchAction({
    type: 'showTip',
    seriesIndex: 0,
    dataIndex: 2
  })
})

> clear

清空当前实例，移除实例中所有的组件和图表，但是可以重新 setOption 来使图表进行显示。

    $('#btn2').click(function () {
      // 清空图表的实例
      mCharts.clear()
    })

    $('#btn3').click(function () {
      // 重新设置 option
      mCharts.setOption(option)
    })

> dispose

销毁实例，销毁后实例无法再被使用。

    $('#btn4').click(function () {
      // 销毁 mCharts
      mCharts.dispose()
    })