data$

API data$ 是繪製圖表的必要 API 之一，用來加入繪製圖表所需的數據資料。

6 種資料格式的圖表物件在建立資料的語法都是相同的，但其中各個資料格式皆不同，說明篇幅會較長，所以以下將依類別各別介紹，讀者也可依自行需求查閱。

TIP

本章節的範例 JSON 資料可以直接複製貼上至 Playground 頁面當中，直接在上面修改資料可即時呈現繪圖出來的結果。

語法

建立資料的語法是 chart.data$.next(Data)

範例：

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

Series

  • 型別：(DataSeriesDatum | DataSeriesValue)[][] | (DataSeriesDatum | DataSeriesValue)[]
詳細型別
type DataSeriesValue = number | null

interface DataSeriesDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}
  • 說明：

Series 的格式是二維陣列的資料，第二維的陣列資料我們會稱之為「序列資料」 (Series Data)。

以下面範例來說就是有兩組序列資料：

[ 
  [ 65, 70, 50, 12, 50 ],
  [ 35, 40, 15, 65 ]
]

有一種情況是「序列資料」中只會有一筆資料，這種情況可以不寫成陣列 (number[]) 可以直接用 number 來取代，比如原本是這樣格式的資料：

[ 
  [55],
  [80],
  [50],
  [11],
  [150]
]

他可以等同於這個寫法，這是一個方便的簡易寫法，但在 OrbCharts 的繪圖意義上我們還是會說這裡有五組序列資料（會繪圖出五種顏色的圖形）。

[ 55, 80, 50, 11, 150 ]

兩種格式是可以混合在一起寫的：

[ 
  35,
  [ 65, 70, 50, 12, 50 ],
  [ 35, 40, 15, 65 ]
]

每一個個別資料的格式除了是 number 外，也可以是一個 {} 物件，主要是兩個用途：

  • label 用來標註資料的標籤，可用來顯示在特定的 Plugin 上
  • data 可塞入更多自訂義的資料，用於 event$ 事件取出相關資料。
[
  [
    {
      label: '台北',
      value: 50000
    },
    {
      label: '台中',
      value: 40000
    },
    {
      label: '高雄',
      value: 30000
    }
  ]
]

Grid

  • 型別：(DataGridDatum | DataGridValue)[][]
詳細型別
type DataGridValue = number | null

interface DataGridDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}
  • 說明：

Grid 的資料是二維陣列的資料：

[
  [ 55, 80, 50, 11 ],
  [ 35, 40, 15, 65 ]
]

Grid 資料格式中有「欄」和「列」的概念，我們把資料排列成一個矩陣形狀，可轉換成下面的假想格式，這組資料中，我們可以說他有兩列、四欄：

     欄1  欄2   欄3  欄4
列1 | 55 | 80 | 50 | 11 
列2 | 35 | 40 | 15 | 65

在預設的設定當中，「列」也等同於「序列資料」(series)，「欄」的資料也稱之為「群組資料」 (group)；了解這個概念並不是必要的，但是在一些進階的使用上時，其他的 API 比如 chartParams$、dataFormatter$ 能夠對於資料上進一步操作時會使用到。

TIP

在其他的 API 對 series 和 group 操作的範例：

  1. chartParams$ 的 highlightTarget 可以設定 Highlight 的對象為 series、或 group 等
  2. dataFormatter$ 中 seriesDirection 可以設定「列」或者「欄」為 series，則另一個就會是 group，主要目的是透過 seriesDirection 的設定可以控制繪圖映射規則的轉置。

Grid 格式有一個規則，就是每一欄以及每一列的陣列資料長度必須保持一致，如果是有無資料（呈現在繪圖上也是如此）的情況需要補上 null 值：

[
  [ 55, 80, 50, 11 ],
  [ 35, 40, 15, null ]
]

每一個個別資料的格式除了是 number 外，也可以是一個 {} 物件，主要是兩個用途：

  • label 用來標註資料的標籤，可用來顯示在特定的 Plugin 上
  • data 可塞入更多自訂義的資料，用於 event$ 事件取出相關資料。
[
  [
    {
      label: '進口-Q1',
      value: 55
    },
    {
      label: '進口-Q2',
      value: 80
    },
    {
      label: '進口-Q3',
      value: 50
    },
    {
      label: '進口-Q4',
      value: 11
    }
  ],
  [
    {
      label: '出口-Q1',
      value: 35
    },
    {
      label: '出口-Q2',
      value: 40
    },
    {
      label: '出口-Q3',
      value: 15
    },
    {
      label: '出口-Q4',
      value: 65
    }
  ],
]

MultiGrid

  • 型別：DataGrid[]
詳細型別
type DataGrid = (DataGridDatum | DataGridValue)[][]

type DataGridValue = number | null

interface DataGridDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}
  • 說明：

MultiGrid 和 Gird 的差別在於 MultiGrid 有多組的 Grid 資料，從資料結構上來看，也可以說是在 Gird 結構上多加一層的陣列結構：

[
  // 第一組 Grid 資料
  [
    [ 55, 80, 50, 11, 150 ],
    [ 35, 40, 15, 65, 120 ]
  ],
  // 第二組 Grid 資料
  [
    [ 65, 70, 90, 110, 80 ],
    [ 25, 40, 25, 75, 90 ]
  ]
]

其他的規則和 Grid 相同，請參考前面章節說明。

MultiValue

  • 型別：(DataMultiValueDatum | DataMultiValueValue[])[]
詳細型別
type DataMultiValueValue = number

interface DataMultiValueDatum {
  id?: string
  label?: string
  data?: any
  categoryLabel?: string
  value: number[]
}
  • 說明：

MultiValue 最大的特色就是每一筆資料都是一組固定長度的陣列資料資料，而這個陣列長度為多少是依照所使用的 Plugin 設定來決定（比如 ScatterBubbles 的設計是 [x座標, y座標, value] - 長度為 3）。

例如：

[
  [ 25, 30, 15 ],
  [ 55, 60, 40 ],
  [ 45, 55, 30 ],
  [ 75, 35, 30 ],
  [ 65, 25, 5 ],
]

每一個個別資料的格式除了是 number 外，也可以是一個 {} 物件，主要用途：

  • label 用來標註資料的標籤，可用來顯示在特定的 Plugin 上
  • categoryLabel 用來標籤類別資料，可對應顏色以及圖例文字
  • data 可塞入更多自訂義的資料，用於 event$ 事件取出相關資料。

範例：

[
  [ 10, 25, 5 ],
  [ 5, 10, 5 ],
  [ 30, 45, 20 ],
  [ 35, 40, 25 ],
  [ 25, 30, 15 ],
  [ 55, 60, 40 ],
  {
    value: [
      45,
      55,
      30
    ],
    categoryLabel: "category1"
  },
  {
    value: [
      75,
      35,
      30
    ],
    categoryLabel: "category2"
  },
  {
    value: [
      65,
      25,
      5
    ],
    categoryLabel: "category2"
  },
  [ 50, 65, 35 ],
  [ 20, 30, 15 ],
  [ 15, 25, 10 ],
  [ 70, 80, 60 ],
  [ 60, 70, 50 ],
  [ 55, 65, 45 ],
  [ 25, 35, 20 ]
]

Relationship

  • 型別：DataRelationshipObj | DataRelationshipList
詳細型別
interface DataRelationshipObj {
  nodes: Node[]
  edges: Edge[]
}

// 陣列資料
type DataRelationshipList = [
  Node[],
  Edge[]
]

interface Node extends DatumBase {
  id: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

interface Edge extends DatumBase {
  id: string
  start: string
  end: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}
  • 說明：

有兩種資料結構可以通用，第一種是「物件結構」、第二種是「陣列結構」，一般情況下建議直接使用「物件結構」即可：

// 物件結構
{
  nodes: Node[]
  edges: Edge[]
}
// 陣列結構
[
  Node[],
  Edge[]
]

Node 必要欄位：

  • id 識別資料用，必須為唯一值

Edge 必要欄位：

  • id 識別資料用，必須為唯一值
  • start 連接線起始 Node 的 id
  • end 連接線結束 Node 的 id

Node 及 Edge 內的可選欄位：

  • label 用來標註資料的標籤，可用來顯示在特定的 Plugin 上
  • categoryLabel 用來標籤類別資料，可對應顏色以及圖例文字
  • data 可塞入更多自訂義的資料，用於 event$ 事件取出相關資料。
  • value 標註數量資料，可在特定的 Plugin 上呈現出來

範例：

{
  nodes: [
    {
      id: "id0",
      label: "label0",
      value: 19800000,
      categoryLabel: "category1"
    },
    {
      id: "id3",
      label: "label1",
      value: 5114269,
      categoryLabel: "category1"
    },
    {
      id: "id4",
      label: "label2",
      value: 1093200,
      categoryLabel: "category1"
    },
    {
      id: "id5",
      label: "label3",
      value: 32007217,
      categoryLabel: "category1"
    }
  ],
  edges: [
    {
      id: "id14",
      label: "label8",
      categoryLabel: "category2",
      start: "id5",
      end: "id0",
      value: 100
    },
    {
      id: "id15",
      label: "",
      categoryLabel: "category2",
      start: "id5",
      end: "id3",
      value: 100
    },
    {
      id: "id16",
      label: "",
      categoryLabel: "category2",
      start: "id5",
      end: "id4",
      value: 50
    }
  ]
}

Tree

  • 型別：DataTreeObj | DataTreeDatum[]
詳細型別
// 樹狀結構
interface DataTreeObj {
  id: string
  children?: DataTreeObj[]
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

// 陣列資料
interface DataTreeDatum {
  id: string
  parent?: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}
  • 說明：

有兩種資料結構可以通用，第一種是「物件結構」、第二種是「陣列結構」，一般情況下建議直接使用「物件結構」即可。

以「物件結構」（樹狀結構）為例，其特性是資料中會有一個起始資料稱之為「根節點」，每一個「根節點」會對應到多個「子節點」

「物件結構」範例：

{
  id: 'root',
  value: 10,
  categoryLabel: '根節點',
  children: [
    {
      id: 'child1',
      value: 5,
      categoryLabel: '子節點1',
    },
    {
      id: 'child2',
      value: 30,
      categoryLabel: '子節點2',
      children: [
        {
          id: 'child3',
          value: 20,
          categoryLabel: '子節點3'
        }
      ]
    }
  ]
}

「陣列結構」和前者主要差異在於子節點中用 parent 欄位對應唯一的父節點，雖然說兩種資料結構都通用（「陣列結構」經過轉換之後也可計算出相同的樹狀結構資料），但這種寫法可能產生的問題在於除錯不易，難以從資料上判斷是否能夠計算出合法的樹狀資料結構。

以下「陣列結構」範例是和前者一樣的資料、可以繪製出完全一樣的圖形：

[
  {
    id: 'root',
    value: 10,
    categoryLabel: '根節點'
  },
  {
    id: 'child1',
    value: 5,
    categoryLabel: '子節點1',
    parent: 'root'
  },
  {
    id: 'child2',
    value: 30,
    categoryLabel: '子節點2',
    parent: 'root'
  },
  {
    id: 'child3',
    value: 20,
    categoryLabel: '子節點3',
    parent: 'child2'
  }
]

欄位說明：

  • id 為識別資料用，必須為唯一值

  • value, categoryLabel, children, parent 這幾個欄位都是可選的