D3(Data-Driven Documents)是一套以資料驅動 DOM 的可視化函式庫。它所有的 API 都掛在 d3 命名空間之下,並採用語意化版本命名。隨時可以透過 d3.version 查詢當前版本。
由於 API 數量龐大,本文按照模組整理,幫助你快速定位需要的能力。
一、核心 d3
選擇集(Selections)
選擇集是 D3 一切操作的起點,概念上類似 jQuery 的選取結果,但多了「資料綁定」這個關鍵能力。
- d3.select / d3.selectAll:從文件中選取單一或多個元素。
- selection.attr:設定或取得屬性。
- selection.classed:新增或移除 CSS class。
- selection.style:設定或移除樣式,優先級高於 attr。
- selection.property:操作原生 DOM property。
- selection.text / selection.html:設定或取得文字內容/HTML 內容。
- selection.append / selection.insert:在選取元素之後/之前插入新節點。
- selection.remove:從文件中刪除選取元素。
- selection.data:為一群元素綁定資料,並計算資料與元素之間的關聯(data join)。
- selection.enter / selection.exit:enter 回傳「資料有、元素沒有」的佔位集合,exit 回傳「元素有、資料沒有」的多餘集合。這兩者搭配 data 是 D3 最需理解的部分。
- selection.datum:為單一元素綁定資料,不進行 join 運算。
- selection.filter / selection.sort:依綁定資料過濾或排序。
- selection.order:重排文件中的元素順序以符合選擇集。
- selection.on:新增或移除事件監聽器。
- selection.transition:啟動過渡效果,回傳 Transition 物件,可理解為動畫。
- selection.interrupt:立即停止進行中的動畫。
- selection.each / selection.call:為每個元素執行函式/以選擇集為 this 執行函式。
- selection.empty / selection.node / selection.size:判斷是否為空、取第一個元素、取元素數量。
- selection.select / selection.selectAll:從選取元素的子元素建立新選擇集。
- d3.selection:選擇集的原型,可透過
d3.selection.prototype 擴充功能。
- d3.event:取得當前互動的使用者事件。
- d3.mouse / d3.touches:取得滑鼠或觸控點相對於某元素的座標。
過渡效果(Transitions)
動畫是 D3 的強項,而緩衝函式(ease)則讓動態更自然。
- d3.transition:開始一段動畫過渡。
- transition.delay / transition.duration:設定延遲與持續時間(毫秒)。
- transition.ease:指定緩衝函式,例如 elastic 可模擬彈性物體的運動。
- transition.attr / transition.attrTween:平滑過渡到新的屬性值;attrTween 可自訂起始值甚至整個過渡函式。
- transition.style / transition.styleTween:樣式的平滑過渡版本。
- transition.text:在過渡開始時設定文字。
- transition.tween:讓任意屬性(不限 attr 或 style)過渡到新值。
- transition.select / selectAll / filter:對子元素或篩選後的元素進行過渡。
- transition.transition:銜接下一段過渡,形成序列動畫。
- transition.remove:過渡結束後移除元素。
- transition.each / transition.call:不指定觸發類型時立即執行;指定 'start' 或 'end' 則在過渡起訖時執行。
- d3.timer / d3.timer.flush:自訂動畫計時,內部以 requestAnimationFrame 實作,比 setTimeout 更有效率;flush 可立即執行未延遲的計時,用於處理閃屏問題。
插值函式(Interpolators)
插值函式是介於兩個數值之間的計算函式,輸入參數落在 [0, 1] 區間。
- d3.interpolate:依輸入型別(數字、字串、顏色)自動選擇合適的插值方式。
- d3.interpolateNumber / interpolateRound:數字插值;Round 版本會四捨五入取整。
- d3.interpolateString:字串插值,會解析字串中的數字並對其插值。
- d3.interpolateRgb / Hsl / Lab / Hcl:在不同色彩空間之間插值。
- d3.interpolateArray:
d3.interpolateArray([0, 1], [1, 10, 100])(0.5) 回傳 [0.5, 5.5, 100]。
- d3.interpolateObject:物件插值,行為與 Array 版本類似。
- d3.interpolateTransform:在兩個 2D 仿射轉換之間插值。
- d3.interpolateZoom:在兩點之間平滑縮放平移。
- d3.interpolators:註冊自訂插值函式。
陣列與資料操作
- 統計類:d3.min、d3.max、d3.extent(取範圍)、d3.sum、d3.mean、d3.median、d3.quantile(分位數)。
- 排序與搜尋:d3.ascending、d3.descending、d3.bisect(二分插入位置)、d3.bisector(自訂二分函式)。
- 結構變換:d3.shuffle(隨機排列)、d3.permute(依指定順序排列)、d3.zip(多陣列合併)、d3.transpose(矩陣轉置)、d3.pairs(相鄰元素配對)、d3.merge(合併多陣列)、d3.range(產生數列)。
- 物件操作:d3.keys、d3.values、d3.entries 分別取出物件的 key 陣列、value 陣列與 key-value 陣列。
- d3.nest:把扁平陣列組織成階層結構。搭配 nest.key(增加層級)、nest.sortKeys、nest.sortValues、nest.rollup(改寫葉節點值)、nest.map(輸出物件)與 nest.entries(輸出 key-value 陣列)使用。
- d3.map:把 JS 物件轉為 hash,避開原型鏈造成的干擾。方法包含 has、get、set、remove、keys、values、entries、forEach。
- d3.set:把陣列轉為 set,自動去重。方法包含 has、add、remove、values、forEach。
其他核心模組
- Math:d3.random.normal(常態分布)、d3.random.logNormal(對數常態分布)、d3.random.irwinHall、d3.transform(SVG transform 字串轉標準 2D 矩陣)。
- 載入外部資源:d3.xhr 搭配 xhr.header、xhr.mimeType、xhr.response、xhr.get、xhr.post、xhr.send、xhr.abort、xhr.on;另有 d3.text、d3.json、d3.html、d3.xml、d3.csv、d3.tsv 等語法糖。
- 字串格式化:d3.format(數字轉指定格式字串)、d3.formatPrefix(自動判定量級,如 K、M、G)、d3.requote(正則表達式轉義)、d3.round(指定位數取整,回傳 number 而非字串)。
- CSV / TSV:d3.csv.parse、parseRows、format、formatRows;d3.tsv 提供對應方法;d3.dsv 可自訂分隔符與 MIME type。
- 顏色:d3.rgb、d3.hsl、d3.lab、d3.hcl 四種色彩物件,各自支援 brighter(提高亮度)、darker(降低亮度)、toString 以及跨空間轉換。
- 命名空間:d3.ns.prefix、d3.ns.qualify。
- 內部方法:d3.functor(把值轉為回傳該值的函式)、d3.rebind(借用其他物件的方法)、d3.dispatch 搭配 dispatch.on 與 dispatch.type(自訂事件)。
二、d3.scale:尺度變換
尺度變換負責把「資料空間」映射到「像素空間」,是繪製圖表的核心抽象。
定量變換(Quantitative)
這類變換的定義域是連續區間。共通方法包括 domain(定義域)、range(值域)、invert(反變換)、rangeRound(值域取整)、interpolate、clamp(是否鎖定在值域內)、nice(把定義域擴展成更整齊的數字)、ticks(取出代表性刻度值)、tickFormat(刻度格式化)與 copy。
- d3.scale.linear:線性變換,最常用。
- d3.scale.sqrt:平方根變換。
- d3.scale.pow:指數變換,搭配
pow.exponent 設定冪次。
- d3.scale.log:對數變換。
- d3.scale.quantize:定義域為數值區間,值域為離散值,會自動均分區間。搭配
quantize.invertExtent 可反查某離散值對應的範圍。
- d3.scale.threshold:與 quantize 的差別在於——它讓你自行指定各區間的邊界值,而非自動均分。
- d3.scale.quantile:以中位數切分區間(quantize 則以算術平均切分),另有
quantile.quantiles 可取得分隔值。
- d3.scale.identity:定義域與值域相同的特殊線性變換,主要供 D3 內部的 axis 與 brush 模組使用。
序數變換(Ordinal)
與定量變換最大的不同:序數變換的輸入定義域是離散的。
- d3.scale.ordinal:不在定義域中的輸入值會自動被加入定義域。
- ordinal.rangePoints:用幾個離散點切分連續區間,適合散佈圖。
- ordinal.rangeBands / rangeRoundBands:用幾段離散區間切分連續區間,適合長條圖;Round 版本邊界與寬度會取整。
- ordinal.rangeBand / rangeExtent:取得區間寬度與輸出域的最小最大值。
- d3.scale.category10 / category20 / category20b / category20c:預設的定性配色方案。
三、d3.svg:SVG 圖形與元件
Shapes(形狀生成器)
- d3.svg.line:線段生成器,用於折線圖。可設定 line.x、line.y、line.interpolate(插值模式)、line.tension(曲線張力)、line.defined(判斷某點是否有值)。
- d3.svg.line.radial:輻射線生成器,用於雷達圖,以 line.radius 與 line.angle 取代 x/y。
- d3.svg.area:區域生成器,用於面積圖。除 x/y 外,另有 x0/x1、y0/y1 分別指定基線與背線。
- d3.svg.area.radial:極座標版區域生成器,搭配 radius、innerRadius、outerRadius、angle、startAngle、endAngle 使用。
- d3.svg.arc:弧生成器,用於圓餅圖與環圈圖。搭配 innerRadius、outerRadius、startAngle、endAngle;
arc.centroid 可算出弧的重心,常用來放標籤。
- d3.svg.symbol:符號生成器,用於散佈圖。搭配 symbol.type 與 symbol.size(單位為平方像素),可用型別見 d3.svg.symbolTypes。
- d3.svg.chord:弦生成器,用二次貝茲曲線連接兩段弧,用於弦圖。
- d3.svg.diagonal / diagonal.radial:斜線生成器,用於節點連接圖,可透過 projection 自訂點的變換。
座標軸(Axes)
d3.svg.axis 建立座標軸生成器,再於頁面中呼叫 axis 完成渲染。可設定項目包括:
- axis.scale:綁定的尺度變換,決定數值與像素位置的轉換規則。
- axis.orient:刻度方向(top、bottom、left、right)。
- axis.ticks / tickValues:控制刻度的產生方式,或指定特定刻度值。
- axis.tickSize / innerTickSize / outerTickSize:刻度線長度。
- axis.tickPadding:刻度與文字之間的距離。
- axis.tickFormat:刻度文字格式。
Controls
d3.svg.brush 讓使用者以點擊拖曳框選二維區域,常用於縮放與區間篩選。搭配 brush.x、brush.y、brush.extent、brush.clear、brush.empty 使用;brush.on 可監聽 brushstart、brush、brushend 三種事件,brush.event 則用於程式設定 extent 後主動觸發。
四、d3.time:時間處理
- 格式化:d3.time.format 建立本地時間轉換器(format 轉字串、format.parse 轉回 date 物件);d3.time.format.utc 用於 UTC;d3.time.format.iso 用於 ISO 8601。
- 時間尺度:d3.time.scale 定義域為數值、值域為時間,常用於時間座標軸。方法與 linear 幾乎一致。
- 時間間隔:d3.time.interval 搭配 range、floor(下捨入)、round、ceil(上捨入)、offset、utc 使用。
- 各級單位:day/hour/minute/month/second 與各國星期(sunday 至 saturday)皆提供對應函式,回傳該單位的起始時間;複數形式(如 days、hours)等同
.range;另有 dayOfYear 與各星期對應的 *OfYear 可計算一年中的天數或週數。
- 別名:d3.time.week 等同 sunday,weeks 等同 sunday.range,weekOfYear 等同 sundayOfYear。
- d3.time.year / years:以年為單位的起始時間與序列。
五、d3.layout:預built 圖表布局
- Bundle:d3.layout.bundle 套用 Holten 的分層捆綁演算法處理連線。
- Chord(弦圖):d3.layout.chord 搭配 matrix、padding、sortGroups、sortSubgroups、sortChords,並輸出 chords 與 groups。
- Cluster(集群):d3.layout.cluster 搭配 sort、children、nodes、links、separation、size、nodeSize。
- Force(力導向):以物理模擬決定節點位置。可調參數包含 linkDistance、linkStrength、friction(摩擦)、charge(電荷,決定排斥或吸引)、gravity(引力)、theta;控制方法有 start、resume、stop、alpha(冷卻係數)、tick(推進一步)、drag;另有 on 可監聽 start/step/end。
- Hierarchy(階層):d3.layout.hierarchy 是所有階層布局的基礎,提供 sort、children、nodes、links、value、revalue。
- Histogram(直方圖):d3.layout.histogram 搭配 value、range、bins、frequency(決定 Y 軸是次數還是百分比)。
- Pack(層包):以遞迴圓環呈現多層結構,可設定 size、radius、padding、value。
- Partition(分區):把樹遞迴切分成區塊,可設定 size 與 value。
- Pie(圓餅):d3.layout.pie 把原始資料轉為適合圓餅/環圈圖的結構,可設定 value、sort、startAngle、endAngle。
- Stack(堆疊):計算每一層的基線,適合堆疊面積圖與長條圖。可設定 values、order、offset、x、y、out。
- Tree(樹):d3.layout.tree 把節點整齊排列,可設定 separation、size、nodeSize。
- Treemap(矩陣樹):以矩形面積表現數值大小,可設定 value、size、padding、round、sticky(更新資料時保有平滑動畫)、mode(切換布局演算法)。
六、d3.geo:地理資料
- Paths:d3.geo.path 建立地理路徑生成器,搭配 projection(投影)、context(渲染上下文)、pointRadius、area、centroid、bounds。
- graticule(座標網):d3.geo.graticule 產生經緯網,可設定 lines、outline、extent、majorExtent、minorExtent、step、majorStep、minorStep、precision。
- circle:d3.geo.circle 以多邊形模擬圓形,可設定 origin、angle、precision。
- 測量:d3.geo.area、bounds、centroid、distance(大圓距離)、interpolate(沿大圓插值)、length、rotation(搭配 invert 做反旋轉)。
- 投影:d3.geo.projection 由原始投影建立標準投影,可設定 rotate、center、translate、scale、clipAngle、clipExtent、precision、stream。內建投影包含 albers(含 albersUsa)、azimuthalEqualArea、azimuthalEquidistant、conicConformal、conicEquidistant、conicEqualArea、equirectangular、gnomonic、mercator、orthographic、stereographic,並各有對應的 .raw 版本。
- Streams:d3.geo.stream 把 GeoJSON 轉為 geometry stream,搭配 point、lineStart/lineEnd、polygonStart/polygonEnd、sphere 等事件;d3.geo.clipExtent 可裁切到指定矩形。
七、d3.geom:幾何運算
- Voronoi:d3.geom.voronoi 計算 Voronoi 鑲嵌,可設定 x、y、clipExtent,並用 links(Delaunay 網格)或 triangles(三角分割)輸出。
- Quadtree:d3.geom.quadtree 為點集建立四叉樹,搭配 add 與 visit。
- Polygon:d3.geom.polygon 搭配 area、centroid、clip。
- Hull:d3.geom.hull 計算凸包,可設定 x、y 座標存取器。
八、d3.behavior:互動行為
- Drag:d3.behavior.drag 搭配 origin 與 on。
- Zoom:d3.behavior.zoom 建立縮放行為。可讀寫 scale、translate,並可透過 scaleExtent 限制縮放範圍、center 指定滾輪縮放焦點、size 設定視口尺寸、x/y 綁定尺度變換;
zoom.on 監聽 scale 或 translate 的變化,zoom.event 在程式改動後主動派發事件。
學習建議
D3 的 API 看似浩瀚,但真正的核心只有三件事:選擇集、資料綁定(data / enter / exit)、尺度變換。把這三者吃透,其餘的 shape、layout、geo 都只是把資料轉成 SVG 路徑的工具函式而已。
另外提醒:本文對應的是 D3 v3 時代的 API 結構。D3 v4 之後做了大幅重構,模組被拆分為 d3-selection、d3-scale、d3-shape 等獨立套件,部分命名也調整了(例如 d3.svg.line 改為 d3.line、nest 移入 d3-collection)。查文件時請先確認版本,以免照著舊教學寫出跑不動的程式碼。