繪製圖表

在前一章節中我們透過圖表類別建立了圖表物件，這個圖表物件為方便閱讀我們後續將統一使用 chart 來代表這個物件，圖表物件上可以進行繪圖以及互動，接下來將針對物件上常用的 API進行解說。

必要使用的 API

要繪製圖表最基本必須使用的兩個 API 是 plugins$ 和 data$：

  • plugins$：OrbCharts 中的「Plugin」，指的就是一個用來繪製 SVG 圖形元素的物件，一個圖表會由一個或多個 Plugin 組合起來。6 種圖表物件可以使用的「Plugin」必須使用相同的資料格式，比如說 Pie 和 PieLabels 同屬於 Series，那他就不能在 GridChart 圖表類別建立的圖表物件中使用，只能使用在 SeriesChart 建立的圖表物件中使用。

  • data$：OrbCharts 中的「Data」顧名思義就是圖表所要呈現的資料，6 種圖表物件都有相對應的「Data」格式。

簡易的範例：

<div id="#chart"></div>

import { SeriesChart, Pie, PRESET_PIE_BASIC } from 'orbcharts'

const element = document.querySelector('#chart')

// 透過圖表類別建立的 chart 物件
const chart = new SeriesChart(element, {
  preset: PRESET_PIE_BASIC
})

// plugin$
chart.plugins$.next([new Pie()])

// data$
chart.data$.next([
  [80,120,45],
  [50,30,15,28],
  [55,13,38,10,5]
])

TIP

透過 Playground 頁面可以簡單的依照圖表類別選取相對應的 Plugin

特性與注意事項

OrbCharts 所有產生資料的 API 都有以下特性：

(1) 所有 API 新建立的資料都會合併計算、並觸發繪圖函式

(2) 所有 API 傳入參數都是「可選的」，沒有建立資料或欄位都會以預設值補上

特性1 - 所有 API 新建立的資料都會合併計算、並觸發繪圖函式

Orbcharts 中有需多不同的 API，在輸入資料或參數之後都會觸發繪圖函式：

chart.chartParams$.next(
  // ...
)
plugin.params$.next(
  // ...
)
chart.plugins$.next([plugin])
chart.data$.next(
  // ...
)
chart.dataFormatter(
  // ...
)

這些資料都是以 RxJS 的資料流形式傳遞，在 OrbCharts 內部會先被搜集起來合併計算，才會傳給繪圖函式，所以基本上 OrbCharts 會盡量避免重覆計算的問題發生，並且只會執行一次渲染 SVG 元素的動作。

要執行第二次渲染的條件，是要傳入資料的事件本身就是一個非同步的行為時才會發生：

chart.chartParams$.next(
  // ...
)
plugin.params$.next(
  // ...
)
chart.plugins$.next([plugin])
chart.data$.next(
  // ...
)
// 非同步
setTimeout(() => {
  chart.dataFormatter(
    // ...
  )
}, 1000)

以這個範例來說 setTimeout 就是一個非同步的事件，所以會在第0秒的時候執行一次渲染圖表，在第1秒的時候執行第二次渲染。

特性2- 所有 API 傳入參數都是「可選的」，沒有建立資料或欄位都會以預設值補上

所有傳入資料的 API 都是可選的，可以在有多層物件欄位的情況下每一層的欄位也都是可選的。

比如說，假設 API chartParams 的預設值為（非真實資料，已簡化過方便說明）：

{
  padding: {
    top: 60,
    right: 60,
    bottom: 60,
    left: 60
  },
  fontSize: '0.875rem'
}

當我進行這個輸入資料的操作時：

chart.chartParams$.next({
  padding: {
    bottom: 100
  }
})

最終資料合併的結果會把欠缺的欄位以預設值補上：

{
  padding: {
    top: 60,
    right: 60,
    bottom: 100,
    left: 60
  },
  fontSize: '0.875rem'
}

所有的輸入資料的 API 都是這個規則在處理的。