dataFormatter$

API dataFormatter$ 是全部 Plugin 共用的圖表參數設定，在每一個資料類別的圖表物件上有各自參數格式，主要用來設定資料映射及篩選的規則。
所有的參數皆為可選的，如無使用此 API 則所有參數設定皆為預設值。

語法

設定參數的語法是 chart.dataFormatter$.next(DataFormatter)

範例：

chart.dataFormatter$.next([
  // Params
])

Series

型別：DataFormatterSeriesPartial

欄位：

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedDatumSeries, context: DataFormatterContext<'series'>) => boolean \| null`
sort	排序函式	`((a: ComputedDatumSeries, b: ComputedDatumSeries) => number) \| null`
seriesLabels	Series 標籤	`string[]`
sumSeries	以 Series 分類合併資料	`boolean`
container	多圖表容器布局	`DataFormatterContainer`
separateSeries	以 Series 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`
separateLabel	以 Label 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`

詳細型別

interface ComputedDatumSeries {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  seriesIndex: number
  seriesLabel: string
  seq: number
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.container
名稱說明型別
columnAmount 「欄」的數量 number
rowAmount 「列」的數量 number
columnGap 欄的間距 number | 'auto'
rowGap 列的間距 number | 'auto'
預設值：

名稱	說明	型別
columnAmount	「欄」的數量	`number`
rowAmount	「列」的數量	`number`
columnGap	欄的間距	`number \| 'auto'`
rowGap	列的間距	`number \| 'auto'`

const DEFAULT_DATA_FORMATTER_SERIES: DataFormatterSeries = {
  type: 'series',
  visibleFilter: (datum, context) => true,
  sort: null,
  seriesLabels: [],
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  },
  separateSeries: false,
  separateLabel: false,
  sumSeries: false
}

Grid

型別：DataFormatterGridPartial

欄位：

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedDatumGrid, context: DataFormatterContext<'grid'>) => boolean \| null`
seriesDirection	定義 `data$` 資料的「列」或「欄」為 Series	`boolean`
rowLabels	`data$` 資料「列」的標籤	`boolean`
columnLabels	`data$` 資料「欄」的標籤	`boolean`
valueAxis	資料圖軸（預設為 Y 軸）設定	`DataFormatterValueAxis`
groupAxis	群組圖軸（預設為 X 軸）設定	`DataFormatterGroupAxis`
container	多圖表容器布局	`DataFormatterContainer`
separateSeries	以 Series 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`

詳細型別

interface ComputedDatumGrid {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  gridIndex: number
  seriesIndex: number
  seriesLabel: string
  groupIndex: number
  groupLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.valueAxis

名稱	說明	型別
position	圖軸擺放位置，須注意該欄位設定必須和 `groupAxis` 所設定的 `position` 是垂直的（比如 `groupAxis` 為 `bottom` 時 `valueAxis` 就必須為 `left` 或 `right`	`'top' \| 'bottom' \| 'left' \| 'right'`
scaleDomain	資料的最小值及最大值的範圍設定： [0] => `'min'`: 最小值, `'auto'`: 取最小值，但若大於0則保持為0 [1] => `'max'`: 最大值, `'auto'`: 取最大值，但若小於0則保持為0	`[number \| 'min' \| 'auto', number \| 'max' \| 'auto']`
scaleRange	映射到圖軸的範圍設定（0 ~ 1）	`[number, number]`
label	圖軸標籤	`string`

TIP

圖軸的參數設定是比較複雜的概念，scaleDomain 和 scaleRange 這兩個欄位要互相搭配，也就是「資料」=>「圖軸」映射的設定。

一般情況（預設值） - 資料範圍由 0 ~ 最大值（自動判斷資料的正負值）

{
  scaleDomain: ['auto', 'auto'],
  scaleRange: [0, 0.9]
}

顯示最小到最大值的區域，當只想顯示特定資料範圍的圖表時可以這樣設定

{
  scaleDomain: ['min', 'max'],
  scaleRange: [0.1, 0.9]
}

指定範圍

{
  scaleDomain: [100, 300],
  scaleRange: [0.1, 0.9]
}

dataFormatter.groupAxis

名稱	說明	型別
position	圖軸擺放位置，須注意該欄位設定必須和 `valueAxis` 所設定的 `position` 是垂直的（比如 `groupAxis` 為 `bottom` 時 `valueAxis` 就必須為 `left` 或 `right`	`'top' \| 'bottom' \| 'left' \| 'right'`
scaleDomain	資料的最小值及最大值的範圍設定，以 `data$` 資料中的 Group 資料（預設是「欄」為方向）索引為單位	`[number, number \| 'max']`
scalePadding	圖軸左右兩側的間距，以圖軸刻度為單位	`number`
label	圖軸標籤	`string`

dataFormatter.container
名稱說明型別
columnAmount 「欄」的數量 number
rowAmount 「列」的數量 number
columnGap 欄的間距 number | 'auto'
rowGap 列的間距 number | 'auto'
預設值：

名稱	說明	型別
columnAmount	「欄」的數量	`number`
rowAmount	「列」的數量	`number`
columnGap	欄的間距	`number \| 'auto'`
rowGap	列的間距	`number \| 'auto'`

const DEFAULT_DATA_FORMATTER_GRID: DataFormatterGrid = {
  type: 'grid',
  visibleFilter: (datum, context) => true,
  seriesDirection: 'row',
  rowLabels: [],
  columnLabels: [],
  valueAxis: { 
    position: 'left',
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  groupAxis: {
    position: 'bottom',
    scaleDomain: [0, 'max'],
    scalePadding: 0.5,
    label: ''
  },
  separateSeries: false,
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  }
}

MultiGrid

型別：DataFormatterMultiGridPartial

欄位：

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedDatumGrid, context: DataFormatterContext<'grid'>) => boolean \| null`
gridList	各別 Grid 映射資料的設定，其設定格式和 `Grid` 資料類別的 DataFormatter相同	`Array<DataFormatterGridGrid>`
container	多圖表容器布局	`DataFormatterContainer`
separateGrid	以 Grid 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`

dataFormatter.gridList[]

名稱	說明	型別
seriesDirection	定義 `data$` 資料的「列」或「欄」為 Series	`boolean`
rowLabels	`data$` 資料「列」的標籤	`boolean`
columnLabels	`data$` 資料「欄」的標籤	`boolean`
valueAxis	資料圖軸（預設為 Y 軸）設定	`DataFormatterValueAxis`
groupAxis	群組圖軸（預設為 X 軸）設定	`DataFormatterGroupAxis`
container	多圖表容器布局	`DataFormatterContainer`
separateSeries	以 Series 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`

TIP

gridList[] 中的欄位格式和 Grid 資料類別的 DataFormatter 完全相同，所以細部的欄位說明就不再重覆。
當 gridList[] 陣列數量和 data$ 內 Grid 資料（陣列）數量不一致的時候，會以 gridList[0] （如無設定就是以預設值）為主。

dataFormatter.container
名稱說明型別
columnAmount 「欄」的數量 number
rowAmount 「列」的數量 number
columnGap 欄的間距 number | 'auto'
rowGap 列的間距 number | 'auto'
預設值：

名稱	說明	型別
columnAmount	「欄」的數量	`number`
rowAmount	「列」的數量	`number`
columnGap	欄的間距	`number \| 'auto'`
rowGap	列的間距	`number \| 'auto'`

const DEFAULT_DATA_FORMATTER_MULTI_GRID: DataFormatterMultiGrid = {
  type: 'multiGrid',
  visibleFilter: (datum, context) => true,
  gridList: [
    {
      seriesDirection: 'row',
      rowLabels: [],
      columnLabels: [],
      valueAxis: { 
        position: 'left',
        scaleDomain: ['auto', 'auto'],
        scaleRange: [0, 0.9],
        label: '',
      },
      groupAxis: {
        position: 'bottom',
        scaleDomain: [0, 'max'],
        scalePadding: 0.5,
        label: ''
      },
      separateSeries: false,
    },
  ],
  separateGrid: false,
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  }
}

MultiValue

型別：DataFormatterMultiValuePartial

欄位：

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedDatumMultiValue, context: DataFormatterContext<'multiValue'>) => boolean \| null`
categoryLabels	Category 標籤	`string[]`
xAxis	X 圖軸設定	`DataFormatterAxis`
yAxis	Y 圖軸設定	`DataFormatterAxis`
container	多圖表容器布局	`DataFormatterContainer`
separateCategory	以 Category 分類分開顯示（以 `container` 欄位設定的布局擺放）	`boolean`

詳細型別

interface ComputedDatumMultiValue {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  datumIndex: number
  value: number[]
  color: string
  categoryIndex: number
  categoryLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.xAxis 及 dataFormatter.yAxis

名稱	說明	型別
scaleDomain	資料的最小值及最大值的範圍設定： [0] => `'min'`: 最小值, `'auto'`: 取最小值，但若大於0則保持為0 [1] => `'max'`: 最大值, `'auto'`: 取最大值，但若小於0則保持為0	`[number \| 'min' \| 'auto', number \| 'max' \| 'auto']`
scaleRange	映射到圖軸的範圍設定（0 ~ 1）	`[number, number]`
label	圖軸標籤	`string`

TIP

圖軸的參數設定是比較複雜的概念，scaleDomain 和 scaleRange 這兩個欄位要互相搭配，也就是「資料」=>「圖軸」映射的設定。

一般情況（預設值） - 資料範圍由 0 ~ 最大值（自動判斷資料的正負值）

{
  scaleDomain: ['auto', 'auto'],
  scaleRange: [0, 0.9]
}

顯示最小到最大值的區域，當只想顯示特定資料範圍的圖表時可以這樣設定

{
  scaleDomain: ['min', 'max'],
  scaleRange: [0.1, 0.9]
}

指定範圍

{
  scaleDomain: [100, 300],
  scaleRange: [0.1, 0.9]
}

dataFormatter.container
名稱說明型別
columnAmount 「欄」的數量 number
rowAmount 「列」的數量 number
columnGap 欄的間距 number | 'auto'
rowGap 列的間距 number | 'auto'
預設值：

名稱	說明	型別
columnAmount	「欄」的數量	`number`
rowAmount	「列」的數量	`number`
columnGap	欄的間距	`number \| 'auto'`
rowGap	列的間距	`number \| 'auto'`

const DEFAULT_DATA_FORMATTER_MULTI_VALUE: DataFormatterMultiValue = {
  type: 'multiValue',
  visibleFilter: (datum, context) => true,
  categoryLabels: [],
  xAxis: {
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  yAxis: {
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  },
  separateCategory: false
}

Relationship

型別：DataFormatterRelationshipPartial
欄位：
名稱說明型別
visibleFilter 資料篩選函式 (datum: ComputedNode, context: DataFormatterContext<'relationship'>) => boolean | null
categoryLabels Category 標籤 string[]

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedNode, context: DataFormatterContext<'relationship'>) => boolean \| null`
categoryLabels	Category 標籤	`string[]`

詳細型別

interface ComputedNode {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  categoryIndex: number
  categoryLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

預設值：

const DEFAULT_DATA_FORMATTER_RELATIONSHIP: DataFormatterRelationship = {
  type: 'relationship',
  visibleFilter: (datum, context) => true,
  categoryLabels: []
}

Tree

型別：DataFormatterTreePartial
欄位：
名稱說明型別
visibleFilter 資料篩選函式 (datum: ComputedDataTree, context: DataFormatterContext<'tree'>) => boolean | null
categoryLabels Category 標籤 string[]

名稱	說明	型別
visibleFilter	資料篩選函式	`(datum: ComputedDataTree, context: DataFormatterContext<'tree'>) => boolean \| null`
categoryLabels	Category 標籤	`string[]`

詳細型別

interface ComputedDataTree {
  level: number
  seq: number
  children?: ComputedDataTree[]
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

預設值：

const DEFAULT_DATA_FORMATTER_TREE: DataFormatterTree = {
  type: 'tree',
  visibleFilter: (datum, context) => true,
  categoryLabels: []
}