ECharts 自定義 Tooltip 方法大全

ECharts 自定義 Tooltip 大全

ECharts 自定義
Tooltip 大全

ECharts 是一個功能豐富的 JavaScript 圖表庫，提供了各種圖表類型和互動特性。其中，tooltip 是一個重要的元素，它可以在滑鼠懸停於圖表上時顯示相關資訊。本篇文章將介紹如何自定義 ECharts tooltips，特別是如何在 tooltip 中放置圖片，以豐富資料視覺化的效果。

Tooltip 觸發方式

在 ECharts 中，tooltip 可以通過不同的方式進行觸發，例如懸停在圖表上、點擊圖表元素或者其他特定的事件。我們可以根據實際需求選擇合適的觸發方式，以提供更好的使用體驗。

  • 'item' ：數據項目觸發
    主要用於散點圖、圓餅圖等無坐標軸之圖表中使用。
  • 'axis' ：坐標軸觸發
    主要用於柱狀圖、折線圖中。axisPointer.axis 設定指定坐標軸。
  • 'none' ：不觸發

本文範例使用'axis'坐標軸觸發，並指定x坐標軸。

var option = {
 //...其他設定
,tooltip:{
 trigger: 'axis',
 axisPointer: {
    type: "line",
    axis:'x'
 }
},
};

See the Pen Basic Line Chart – Apache ECharts Demo by 葉萱 (@vticdnuj-the-decoder) on CodePen.

利用內建字串模版修改 Tooltip 內容

ECharts 提供了豐富的配置選項，使我們能夠自由定制 tooltip 的內容。我們可以使用 formatter 函式來設定 tooltip 的顯示內容。第一種方法是使用 ECharts 中內建的字串模版，變數有 {a}, {b}，{c}，{d}，{e}，分别表示系列名，數據名，數據值等。 有多個系列數據時，可以通過 {a0}, {a1}等增加索引的方式表示系列的索引。 不同圖表類型的 {a}，{b}，{c}，{d}含義不同，以下是常見圖表類型：

  • 折線圖、柱狀圖、K線圖 : {a}（系列名稱），{b}（類別值），{c}（數值）
  • 散點圖图 : {a}（系列名稱），{b}（數據名稱），{c}（數值數組）
  • 圓餅圖: {a}（系列名稱），{b}（數據項名稱），{c}（數值）, {d}（百分比）
var option = {

 //...其他設定

,tooltip:{

 //...

 formatter: '今天是{b} </br> {a} : {c}'
},
};

See the Pen Basic Line Chart – Apache ECharts Demo-formattedbytemplate by 葉萱 (@vticdnuj-the-decoder) on CodePen.

自定義 Tooltip 內容

接下來介紹第二種自定義 Tooltip 的方法，在 Formatter 函式中，我們可以使用 HTML 和 CSS 來自由設計 tooltip 的外觀和內容，包括放置圖片、設定文字樣式等。

獲取數據集資訊

formatter 會接收 params 的參數，我們可以利用此參數獲取數據集的相關資訊：

{
    componentType: 'series',

    // 數據系列資料類型
    seriesType: string,

    // 數據系列在傳入的 option.series 中的 index
    seriesIndex: number,

    // 數據系列名稱
    seriesName: string,

    // 數據名稱，類別名稱
    name: string,

    // 數據在傳入的 data 數組中的 index
    dataIndex: number,

    // 傳入的原始數據集
    data: Object,

    // 傳入的數據值。在多數據系列下它和 data 相同。在一些系列下是 data 中的分量（如 map、radar 中）
    value: number|Array|Object,
    encode: Object,

    // 维度名稱列表
    dimensionNames: Array<String>,

    // 數據的維度 index，如 0 或 1 或 2 ...
    // 僅在雷達途中使用。
    dimensionIndex: number,

    // 數據圖形的顏色
    color: string,

    // 圓餅圖的百分比
    percent: number

}

建立回調函數

首先我們先利用 formatter 建構基礎的 tooltip 樣式，包含資料時間、資料顏色圖例、資料名稱、資料值，請注意，資料參數的內容結構，會依據圖表類型及傳入資料結構不同而有所差異，下方的例子是以x軸為類別 (Category)的折線圖做為範例，後面還會有以時間軸的折線圖範例讓大家比較參考。

var option = {
  xAxis: {
    type: 'category',
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {
    type: 'value'
  },
 series: [
    {
      name:'降雨量',
      data: [150, 230, 224, 218, 135, 147, 260],
      type: 'line'
    }
  ]

 //...其他設定

 ,tooltip:{  
 formatter : function (params) {
      let tooltip_box = `<div class="tooltipbox">`
      params.forEach(d=>{
     tooltip_box +=
     `<div class="tooltipbox_item">`
     + `<p class="tooltipbox_category"> ${d.name} </p>`
     + `<span style="height: 15px;width: 15px;background-color: ${d.color};border-radius: 50%;display: inline-block;"></span>`
     + `  ${d.seriesName} : ${d.data}</div>`
     +`<img width='200' src='http://blog.yyhapp.com/wp-content/uploads/2023/06/rain.jpg'/>`;

      })
     tooltip_box += `</div>`;
    return tooltip_box;
    }
  },
};
  1. 先建立一個 <div class="tooltipbox"> 來當tooltip的外框。
  2. 使用 forEach 迴圈遍歷 params 陣列中的每個系列。
  3. 將每個系列的名稱 d.name、系列名稱 d.seriesName 和數據 d.data 加入到 tooltip_box 字串中，並利用 <span> 及 數據顏色 d.color 來建立代表數據的圓形圖例、。
  4. 在資訊後方插入一張水庫水位的圖片，示意降雨量的多寡，並設定了圖片的寬度為 200 像素。
  5. 最後，將構建完成的 tooltip_box 字串返回，作為 tooltips 的內容。

See the Pen Basic Line Chart Formatted tooltip with img- Apache ECharts Demo by 葉萱 (@vticdnuj-the-decoder) on CodePen.

以時間軸的折線圖為範例，這次數據集的格式與上述範例不同，數據及的第一個值為時間(TimeStamp)、第二個值為數值：

// 數據集格式
let data=[[1685569320000,463],[1685569380000,473].....];

var option = {
  xAxis: {
    type: 'time',
  },
  yAxis: {
    type: 'value',
  },
series: [
    {
      name: 'Fake Data',
      type: 'line',
      data: data
    }
  ],
  
   // ... 其他設定

  tooltip: {
  formatter:function (params) {
      let tooltip_box = `<div class="tooltipbox">`
      params.forEach(d=>{
        // 時間格式化
        var dat=new Date(d.data[0])
	var formattime =
            dat.getUTCFullYear() + "/" +
            ("0" + (dat.getUTCMonth()+1)).slice(-2) + "/" +
            ("0" + dat.getUTCDate()).slice(-2) + " " +
            ("0" + dat.getUTCHours()).slice(-2) + ":" +
            ("0" + dat.getUTCMinutes()).slice(-2) + ":" +
            ("0" + dat.getUTCSeconds()).slice(-2);

         tooltip_box +=
         `<div class="tooltipbox_item">`
         + `<p style="margin-block-start:5px;margin-block-end:5px;">現在是 ${formattime} </p>`
         + `<span style="height: 15px;width: 15px;background-color: ${d.color};border-radius: 50%;display: inline-block;"></span>`
         + `  ${d.seriesName} : ${d.data[1]}</div>`;     
      })
     tooltip_box += `</div>`;
     return tooltip_box;
    },     
}
}
  1. 定義了一個 data 陣列，包含了一系列的數據點。每個數據點是一個陣列，第一個元素是時間戳記（TimeStamp），第二個元素是數據值。
  2. 將每個系列的時間戳記 d.data[0] 轉換成指定日期時間格式。這裡使用了 Date 物件的方法來進行轉換，並將結果儲存在 formattime 變數中。
  3. 將格式化後的時間 formattime、點的顏色 d.color、系列名稱 d.seriesName 和數據值 d.data[1] 加入到 tooltip_box 字串中，並使用 HTML 標籤來樣式化顯示。
  4. 最後，將構建完成的 tooltip_box 字串返回，作為 tooltips 的內容。

See the Pen Area Chart with Time Axis_Formatted Tooltip – Apache ECharts Demo by 葉萱 (@vticdnuj-the-decoder) on CodePen.

樣式

ECharts 提供了我們 extraCssText 來設定附加到浮層上的 css 樣式，如下方我們示範將 Tooltip 改成深色系主題：

var option = {
    tooltip:{

    // ... 其他設定
     extraCssText:'background-color:black; color:white'
   }
 
};

我們也可以利用 css 檔，單獨設定我們自定義出來的tooltip樣式，以下示範將數據類別改成以粗體顯示：

.tooltipbox_category{
  font-weight:bold;
  margin-block-start:5px;
  margin-block-end:5px;
}

See the Pen Basic Line Chart Formatted tooltip with img- Apache ECharts Demo by 葉萱 (@vticdnuj-the-decoder) on CodePen.

完整程式碼如下：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
	<meta charset="utf-8">
	<title>Basic Line Chart - Apache ECharts Demo</title>
</head>
<body>
	<style>
	* {
	 margin: 0;
	 padding: 0;
	}
	#chart-container {
	 position: relative;
	 height: 100vh;
	 overflow: hidden;
	}
	.tooltipbox_category{
	 font-weight:bold;
	 margin-block-start:5px;
	 margin-block-end:5px;
	}
	</style>
	<div id="chart-container"></div>
	<script src="https://fastly.jsdelivr.net/npm/echarts@5/dist/echarts.min.js">
	</script> 
	<script>
	 var dom = document.getElementById('chart-container');
	var myChart = echarts.init(dom, null, {
	 renderer: 'canvas',
	 useDirtyRect: false
	});
	var app = {};

	var option;

	option = {
	 xAxis: {
	   type: 'category',
	   data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
	 },
	 yAxis: {
	   type: 'value'
	 },
	 tooltip:{
	   trigger:'axis',
	    axisPointer: {
	     type: "line",
	     axis:'x'
	   },
	   formatter: function (params) {
	     let tooltip_box = `<div class="tooltipbox">`
	     params.forEach(d=>{
	    tooltip_box +=
	    `<div class="tooltipbox_item">`
	    + `<p class="tooltipbox_category"> ${d.name} <\/p>`
	    + `<span style="height: 15px;width: 15px;background-color: ${d.color};border-radius: 50%;display: inline-block;"><\/span>`
	    + `  ${d.seriesName} : ${d.data}<\/div>`
	    +`<img width='200' src='http://blog.yyhapp.com/wp-content/uploads/2023/06/rain.jpg'/>`;

	     })
	    tooltip_box += `<\/div>`;
	   return tooltip_box;
	   },
	    extraCssText:'background-color:black; color:white'

	 },
	 series: [
	   {
	     name:'降雨量',
	     data: [150, 230, 224, 218, 135, 147, 260],
	     type: 'line'
	   }
	 ]
	};

	if (option && typeof option === 'object') {
	 myChart.setOption(option);
	}

	window.addEventListener('resize', myChart.resize);
	 
	</script>
</body>
</html>

參考資料

ECharts 配置項手冊
ECharts 範例集

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *