DIV CSS 佈局教程網

D3.js API 中文導覽:從選擇集到地理投影的完整地圖
編輯:關於JavaScript     

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)。查文件時請先確認版本,以免照著舊教學寫出跑不動的程式碼。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved