BizCharts 使用筆記

一、介紹

---

1、背景

BizCharts 這個其實兩年前就用過一次，最近做 dashboard，涉及數據的可視化展示（即圖表功能），於是又用了回 BizCharts。這次干脆趁熱通讀下官方文檔，遂成此篇。

2、什么是 BizCharts

首先，AntV 是螞蟻金服全新一代數據可視化解決方案。
其次，G2是 AntV 旗下，以數據驅動，具有高度的易用性和擴展性的可視化圖形語法。
再次，Bizcharts是一款基 於antv 的 G2 進行 react 封裝的組件，是以數據為驅動的可視化圖表。

3、優勢/特點

• （在市面上跟其他類似庫相比）跟 react 組件寫法結合的最好
• 是 ant design pro 推薦使用的第三方圖表庫（我司用的即 ant design pro），且 ant design pro 還原生提供了在 BizCharts 基礎上二次封裝的簡化版圖表
• 支持 Canvas 及 SVG 兩種模式的圖表渲染
• 兼容性，支持 Chrome，Safari，IE11+ 瀏覽器

4、文檔

① 官網：
https://bizcharts.net/

② API：
https://bizcharts.net/product/bizcharts/category/7/page/12

③ gallery（demo）：
https://bizcharts.net/product/bizcharts/gallery

建議開發的時候，直接翻閱 gallery（demo）拿來主義再修改即可。因為 BizCharts 的有些編碼設計（尤其是涉及復雜圖表）我覺得並不是很好理解。

gallery 還支持根據 api 篩選 demo，挺好用：

5、安裝

npm install bizcharts --save

以最新的 v3.5.8 為例。

二、圖表構成

---

1、組件構成

在 BizCharts 中，圖表是由各個組件組合而成的。組件有兩種類型：

• 實體組件：在圖表上有對應的圖形、文本顯示。
• 抽象組件：沒有顯示，是一種概念抽象組件。

引用組件的方式：

import {
  G2,
  Chart,
  Geom,
  Axis,
  Tooltip,
  Coord,
  Label,
  Legend,
  View,
  Guide,
  Shape,
  Facet,
  Util
} from "bizcharts";

2、組件的空間構成

下圖所示為常用圖表的各組件的空間構成。

三、組件 - Chart

---

1、data

BizCharts 支持兩種格式的源數據：

• JSON 數組
• DataView 對象 (由 DataSet 創建，下面會專門介紹）

2、width/height + forceFit + padding

① height、width

height、width 未指定時，默認為 500px。

注：只是 Canvas 的寬高，如果<Chart />內還包含其他標簽元素，譬如加上了標題（<h3 />），或者沒有數據觸發了placeholder屬性（下面會介紹），則不算在內。

② forceFit

圖表的寬度自適應開關（不能自適應高度），默認為 false，設置為 true 時表示自動取 dom（實例容器）的寬度。

注：當 forceFit: true 時，width 不生效。

② padding

有時候坐標軸、圖例等繪圖區域外的組件顯示不全時，可以通過調整圖表各個方向的 padding 來調整最終效果，或者直接用 auto（推薦），它會自動計算邊框（僅考慮 axis 和 legend ）

<Chart padding="auto" />
<Chart padding={[ 20, 30, 20, 30]} />
<Chart padding={20} />
<Chart padding={{ top: 20, right: 30, bottom: 20, left: 30 }} />
<Chart padding={[20, 'auto', 30, 'auto']} />
<Chart padding={['20%', '30%']} />

3、選擇 Canvas 還是 SVG ？

默認使用 Canvas 渲染，可以改用 SVG 版本、

如何選擇：如果單就圖表庫的視角來看，選擇 Canvas 和 SVG 各有千秋。小畫布、大數據量的場景適合用 Canvas，譬如熱力圖、大數據量的散點圖等。如果畫布非常大，有縮放、平移等高頻的交互，或者移動端對內存占用量非常敏感等場景，可以使用 SVG 的方案。

4、scale

度量 Scale，是數據空間到圖形空間的轉換橋梁，負責原始數據到 [0, 1] 區間數值的相互轉換工作，從原始數據到 [0, 1] 區間的轉換我們稱之為歸一化操作。

更多資料，可看：https://bizcharts.net/product/bizcharts/category/7/page/35

const scale = {
  'sales': {
    type: 'identity' | 'linear' | 'cat' | 'time' | 'timeCat' | 'log' | 'pow', // 指定數據類型
    alias: string, // 數據字段的別名，會影響到軸的標題內容
    formatter: () => {}, // 格式化文本內容，會影響到軸的label格式
    range: array, // 輸出數據的范圍，默認[0, 1]，格式為 [min, max]，min 和 max 均為 0 至 1 范圍的數據。
    tickCount: number, // 設置坐標軸上刻度點的個數
    ticks: array, // 用於指定坐標軸上刻度點的文本信息，當用戶設置了 ticks 就會按照 ticks 的個數和文本來顯示
    sync: boolean // 當 chart 存在不同數據源的 view 時，用於統一相同數據屬性的值域范圍
  }
};

常用的：

• formatter：formatter: (item) => {return item + "%"}, // 格式化 label 文本內容
• alias：修改 lable 的 title

注：通過 Chart 的 scale ，可以直接對 Chart 下的子組件，如 Axis、Label 進行配置（當然也可以單獨在 Axis、Label 上設置）。

5、placeholder

沒有數據，即 data 屬性傳了 null or []，應該顯示什么？

默認值: <div style={{ position: 'relative', top: '48%', textAlign: 'center' }}>暫無數據</div>

6、theme

默認 "default" ，可開啟 "dark" 樣式。

此功能可以作用於全局或者作用在單獨的 Chart 上。

四、組件 - Coord

---

1、介紹

BizCharts 將坐標系抽象為 Coord 組件，並且包含兩種：

• 笛卡爾坐標系（又名直角坐標系）（rect）【默認】
• 極坐標系（polar、theta、helix）

注：目前所有的坐標系均是 2 維的。

可通過 type 屬性改變坐標系類型。

五、組件 - Axis

---

1、介紹

坐標軸由如下五部分組成：

• 標題 title
• 文本 label
• 坐標軸線 line
• 刻度線 tickLine
• 網格 grid

2、使用

// 只顯示其中一條坐標軸
<Chart width={600} height={400} data={data}>
  <Axis name="sold" />
  <Axis name="genre" visible={false} />
  <Geom type="interval" position="genre*sold" color="genre" />
</Chart>

1、name 屬性必填
2、如果不用<Axis/>組件，默認不顯示坐標軸，但一旦使用，所有的坐標軸都會顯示，這時如若需要隱藏某一個坐標軸，務必將visible參數置為false。

3、更多設置

Axis 的很多屬性，在<Chart /> 中的 scale 中也可以設置。大致分為三類：

• 1、只能在 Axis 中設置
• 2、只能在<Chart /> 中的 scale 設置：坐標軸設置別名
• 3、兩者都能設置：刻度線（tickLine）等

六、組件 - Geom

---

1、介紹

Geom 為幾何標記對象，決定創建圖表的類型。

BizCharts 生成的圖表的類型，是由幾何標記（Geom 的 type 屬性）和坐標系（Coord）共同決定的。

2、幾何標記類型：type

例如：

• point：點，用於點圖的構建。
• line：線，點按照 x 軸連接成一條線，構成線圖。

還可以自定義 shape。

3、數據映射相關的屬性

包含：position, color, shape, size, opacity。

① position

位置屬性的映射，用於確定由數據中的哪幾個字段來確定數據在平面坐標系的位置。通俗地解釋，即確定 x 軸和 y 軸的數據字段。

寫法：

<Geom position="x*y" />
<Geom position={['x', 'y']} />

② color

將數據值映射到圖形的顏色上的方法。

'field'，field 為數據字段名，內部會使用主題中的默認顏色進行數據值到顏色值的映射；
//代碼示例
<Geom color='cut'/>


['field', colors]，將數據值映射至指定的顏色值 colors（可以是字符串也可以是數組），此時用於通常映射分類數據；
//代碼示例
<Geom color={['city', ['#ff0000', '#00ff00']]}/>


['field', 'color1-color2-colorN')]，指定顏色的漸變路徑，用於映射連續的數據；
//代碼示例
<Geom color={['price', '#ff0000-#00ff00']}/>


['field', callback)]，使用回調函數進行顏色值的自定義；可以使用多個字段使用*號連接 注意： color 屬性的回調函數一般返回的單個顏色，因為 G2 中所有的 shape 僅支持單個顏色 color 屬性的回調函數也可以返回數組，數組中有多個顏色，但是這時候需要 shape 支持多顏色的解析，詳細情況查看 自定義shape。
//代碼示例
<Geom
  color={['cut', (cut)=>{
    //some code
      if(cut < 1000)
        return '#00ff00';
      else
        return '#ff0000';
    }]}
/>


color('#ffffff')， 直接指定顏色常量，不進行數據映射。
//代碼示例
<Geom color='#ffffff'/>


color('l(0) 0:#ffffff 0.5:#7ec2f3 1:#1890ff')，支持線性漸變和放射漸變，具體參見漸變色

③ shape、size、opacity 同 color 的寫法，略

4、更多屬性

• 顯示輔助信息的屬性：style, tooltip
• 額外的控制屬性：adjust, select, setSelect, active, hide

七、組件 - Label

---

1、介紹

2、使用

① 在每個幾何標記 Geom 內使用 Label 組件。

② 一旦使用 <Label/> 組件，那么所有的圖例都會顯示，如若需要隱藏某一個圖例，將那一個的 visible 參數配置為 false。

③ content 指定 label 上顯示的文本內容。

<Label content="常量字符串" />
// 使用數據
<Label content="sales*date"/>
// 使用回調函數
<Label content={["sales*date", (sales, date)=>{
    return ${data}:${sales};
  }]}
/>

八、組件 - Legend

---

1、介紹

圖例分為兩種：

• 分類圖例
• 連續圖例

2、怎么才能有 Legend

① 只有當 <Geom /> 組件上有 shape、color、size 中任意一個屬性時，並且將 <Legend /> 組件的 name 屬性跟這個屬性的字段關聯上，才會正常顯示 Legend。

② 一旦使用 <Legend /> 組件，那么所有的圖例都會顯示，如若需要隱藏某一個圖例，將那一個 visible 參數配置為 false。

3、自定義圖例

把 custom 設為 ture，表示不使用默認生成的圖例，允許用戶自定義圖例，包括具體的圖例項以及 click、hover 交互。

如果不是特別需要，建議別輕易的開啟 custom，這會讓你多寫很多代碼。

例如：

<Legend
  custom={true}
  items={[
    { value: 'waiting', fill: '#3182bd', marker: 'shape' },
    { value: 'call', fill: '#99d8c9', marker: 'shape' },
    { value: 'people', fill: '#fdae6b', marker: 'shape' },
  ]}
  onHover={ev => {console.log(ev)}} // 自定義 hover 事件
  onClick={ev => {console.log(ev)}} // 自定義 click 事件
/>

更詳細的例子，可參考 柱線混合圖 的例子（https://bizcharts.net/product/bizcharts/demo/8）

九、組件 - Tooltip

---

1、介紹

BizCharts 默認不展示。

2、crosshairs - 輔助線

<Tooltip crosshairs={{
  //rect: 矩形框,x: 水平輔助線,y: 垂直輔助線,cross: 十字輔助線。
  type: 'rect' || 'x' || 'y' || 'cross',
  style: {
   // 圖形樣式
   fill: {string}, // 填充的顏色
   stroke: {string}, // 邊框的顏色
   strokeOpacity: {number}, // 邊框顏色的透明度，數值為 0 - 1 范圍
   fillOpacity: {number}, // 填充的顏色透明度，數值為 0 - 1 范圍
   lineWidth: {number}, // 邊框的粗細
   lineDash: {number} | {array} // 線的虛線樣式
}}/>

如下圖，右邊的默認的，左邊是 type='cross'。

3、格式化顯示內容

有幾種方法：

• 通過 <Geom /> 上的 tooltip 屬性的回調函數來配置。
• 通過 <Tooltip /> 上的 itemTpl 來格式化顯示內容。
• 特別復雜的場景可以通過 <Chart> 上的 onTooltipChange 事件來格式化 <Tooltip /> 顯示內容。

十、組件 - Guide

---

用於繪制圖表的輔助元素。

十一、組件 - Facet

---

分面組件，將一份數據按照某個維度分隔成若干子集，然后創建一個圖表的矩陣，將每一個數據子集繪制到圖形矩陣的窗格中，所有子圖采用相同的圖表類型，並進行了一定的設計，使得它們之間方便進行比較。

十二、組件 - View

---

視圖，由 Chart 生成和管理，擁有自己獨立的數據源、坐標系和圖層，用於異構數據的可視化以及圖表組合。

一個 Chart 由一個或者多個視圖 View 組成。因此 view 上的 api 同 chart 基本相同。

可參考 多層餅圖 的例子（https://bizcharts.net/product/bizcharts/demo/124）

十三、DataSet

---

1、介紹

DataSet 主要完成了以下功能：

① Connector + Transform

• 源數據的解析，將 CSV, DSV, GeoJSON 轉成標准的JSON，查看 Connector

• 加工數據，包括 filter, map, fold(補數據) 等操作，查看 Transform

• 統計函數，匯總統計、百分比、封箱 等統計函數，查看 Transform

• 特殊數據處理，包括 地理數據、矩形樹圖、桑基圖、文字雲 的數據處理，查看 Transform

Transform 基於的 lodash 的封裝。

② state 狀態量

使用 DataSet 的狀態量可以很容易的實現圖表的聯動。

類似 react 里的 state 概念。
這邊就牽扯一個問題，就是數據的狀態更新到底是托管在 react 的 state 里，還是托管在 DataSet 的 state 里 ？后者的好處是，可以跟 Connector + Transform 的功能融為一套數據處理流，一改則改，很方便維護。

2、安裝

npm install @antv/data-set --save

3、使用

方法一：不用 DataSet 的 state，直接創建 DataView，傳入 <Chart />

import { View } from '@antv/data-set'; 
const data = [
  {
    item: '事例一',
    count: 40,
  },
  {
    item: '事例二',
    count: 21,
  },
  {
    item: '事例三',
    count: 17,
  },
  {
    item: '事例四',
    count: 13,
  },
  {
    item: '事例五',
    count: 9,
  },
];
const dv = new View();
dv.source(data).transform({
  type: 'percent',
  field: 'count',
  dimension: 'item',
  as: 'percent',
});

上面的例子，即 基礎環圖（餅圖）。

我們可以后台先構造一個簡單的數據類型：

{
    item: '事例一',
    count: 40,
},

因為不用 DataSet 的 state，我們就直接創建 DataView 。

再通過 DataView 里的 Transform，改造數據為：

item: "事例一"
count: 40
percent: 0.4

最后塞給 <Chart />。

方法二：使用 DataSet 的 state，實現圖表的聯動

import DataSet from '@antv/data-set'; 

// step1：創建 dataset （指定 state）
const ds = new DataSet({
  state: {
    year: '2010'
  }
});

// step2：創建 DataView
const dv = ds.createView().source(data);

// step3：使用 transform 改造數據
dv.transform({
  type: 'filter',
  callback(row) {
    return row.year === ds.state.year; //（取 state）
  }
});

// step4：引用 DataView
<chart data={dv}>...</chart>

// step5：更新 state
ds.setState('year', '2012');

十四、圖表（組件）事件 - Event

---

Chart組件上提供了各種事件支持，以響應用戶的操作，方便用戶擴展交互。開發者可以監聽這些事件，然后通過回調函數做相應的處理，比如跳轉到一個地址，或者彈出對話框，或者做數據下鑽等等。

事件用法如下：

<Chart
    eventType={eventCallback}
>
 ...
</Chart>

具體介紹，略。