JavaScript視覺化圖表庫D3.js API中文參考

D3 庫所提供的所有 API 都在 d3 命名空間下。 d3 函式庫使用語意版本命名法（semantic versioning）。你可以用 d3.version 查看目前的版本資訊。

d3 (核心部分)

選擇集

d3.select - 從目前文件中選擇一系列元素。
d3.selectAll - 從目前文件中選擇多項元素。
selection.attr - 設定或取得指定屬性。
selection.classed - 新增或刪除選取元素的 CSS 類別（CSS class）。
selection.style - 設定或刪除 CSS 屬性。 style優先權高於attr。
selection.property - 設定或取得原生的屬性值（raw property）。
selection.text - 設定或取得選定元素的標籤體文字內容。
selection.html - 設定或取得選定元素的 HTML 內容（類似 innerHTML ）
selection.append - 建立並新增元素到選定元素後。
selection.insert - 建立並新增元素到選定元素前。
selection.remove - 從目前文件物件中刪除選取的元素。
selection.data - 設定或取得一組元素的綁定資料（get or set data for a group of elements, while computing a relational join.）
selection.enter - 傳回缺失元素的佔位物件（placeholder），指向綁定的資料中比選定元素集多出的一部分元素。
selection.exit - 傳回多餘元素的元素集，即選擇元素中比綁定資料多出的一部分。 (關於data, enter, exit原理的範例1, 範例2, 範例3)
selection.datum - 設定或取得單獨元素的數據，不進行關聯。（get or set data for individual elements, without computing a join.）
selection.filter - 根據綁定的資料過濾選擇集。
selection.sort - 根據綁定的資料對所選的元素進行排序。
selection.order - 將文件中的元素重新排序以符合選擇集。
selection.on - 新增或刪除事件監聽器。
selection.transition - 啟動一個過渡效果（返回 Transition 物件），可以理解為動畫。
selection.interrupt - 立即停止所有正在進行的動畫動作。
selection.each - 為每個選取的元素集呼叫指定的函數。
selection.call - 為目前選取的元素集呼叫指定的函數。
selection.empty - 測試選擇集是否為空。
selection.node - 傳回選擇集中的第一個元素。
selection.size - 傳回選擇集中的元素個數。
selection.select - 選擇所選的元素中的第一個子元素組成新的選擇集。
selection.selectAll - 選擇所選的元素中的多個子元素組成新的選擇集。
d3.selection - 選擇集物件原型（可透過 d3.selection.prototype 為選擇集增強功能）。
d3.event - 取得目前互動的使用者事件。
d3.mouse - 取得滑鼠的相對某元素的座標。
d3.touches - 取得相對某元素的觸控點座標。

過渡效果

d3.transition - 開始一個動畫轉場。簡單教學
transition.delay - 指定每個元素過渡的延遲時間（單位：毫秒ms）。
transition.duration - 指定每個元素過渡的持續時間（單位：毫秒ms）。
transition.ease - 指定過渡的緩衝函數。
transition.attr - 平滑過渡到新的attr屬性值（起始屬性值為目前屬性）。
transition.attrTween - 在不同attr屬性值之間平滑過渡（起始屬性值可在過渡函數中設定,甚至整個過渡函數都可以自訂）。
transition.style - 平滑過渡到新的style屬性值。
transition.styleTween - 在不同style屬性值之間平滑過渡。
transition.text - 在過渡開始時設定文字內容。
transition.tween - 使某個屬性過渡到一個新的屬性值，該屬性可以是非attr或非style屬性，例如text。
transition.select - 選擇每個目前元素的某個子元素進行過渡。
transition.selectAll - 選擇每個目前元素的多個子元素進行過渡。
transition.filter - 透過資料篩選出目前元素中的部分元素進行過渡。
transition.transition - 目前過渡結束後開始新的過渡。
transition.remove - 過渡結束後移除目前元素。
transition.empty - 如果過渡為空就回傳true。如果目前元素中沒有非null元素，則此過渡為空。
transition.node - 返回過渡中的第一個元素。
transition.size - 傳回過渡中目前元素的數量。
transition.each - 遍歷每個元素執行操作。不指定觸發類型時，立即執行操作。當指定觸發類型為'start'或'end'時,會在過渡開始或結束時執行操作。
transition.call - 以當前過渡為this執行某個函數。
d3.ease - 客製化過渡的緩衝函數。
ease - 緩衝函數。緩衝函數可讓動畫效果更自然，例如elastic緩衝函數可用以模擬彈性物體的運動。是一種插值函數的特例。
d3.timer - 開始一個客製化的動畫計時。功能類似setTimeout，但內部用requestAnimationFrame實現，更有效率。
d3.timer.flush - 立刻執行目前沒有延遲的計時。可用於處理閃屏問題。
d3.interpolate - 產生一個插值函數，在兩個參數間內插。差值函數的類型會根據輸入參數的類型（數字、字串、顏色等）而自動選擇。
interpolate - 插值函數。輸入參數在[0, 1]之間。
d3.interpolateNumber - 在兩個數字間內插。
d3.interpolateRound - 在兩個數字間內插值，傳回值會四捨五入取整。
d3.interpolateString - 在兩個字串間內插。解析字串中的數字，對應的數字會插值。
d3.interpolateRgb - 在兩個RGB顏色間內插。
d3.interpolateHsl - 在兩個HSL顏色間內插。
d3.interpolateLab - 在兩個L*a*b*顏色間內插。
d3.interpolateHcl - 在兩個HCL顏色間插值。
d3.interpolateArray - 在兩個數列間內插。 d3.interpolateArray( [0, 1], [1, 10, 100] )(0.5); // returns [0.5, 5.5, 100]
d3.interpolateObject - 在兩個object間插值。 d3.interpolateArray( {x: 0, y: 1}, {x: 1, y: 10, z: 100} )(0.5); // returns {x: 0.5, y: 5.5, z: 100}
d3.interpolateTransform - 在兩個2D仿射變換間內插。
d3.interpolateZoom - 在兩個點之間平滑地縮放平移。範例
d3.interpolators - 新增一個自訂的插值函數.

資料操作(Working with Arrays)

d3.ascending - 升序排序函數.
d3.descending - 降序排序函數.
d3.min - 取得陣列中的最小值.
d3.max - 取得陣列中的最大值.
d3.extent - 取得陣列的範圍(最小值和最大值).
d3.sum - 取得數組中數字總和.
d3.mean -取得陣列中數字的算術平均值.
d3.median - 取得陣列中數字的中位數 (相當於 0.5-quantile的值).
d3.quantile - 取得排好序的陣列的一個分位數(quantile).
d3.bisect - 以二分法取得某個數在排好序的陣列中的插入位置(同d3.bisectRight).
d3.bisectRight - 取得某個數在排好序的陣列中的插入位置(相等的值歸入右邊).
d3.bisectLeft - 取得某個數在排好序的陣列中的插入位置(相等的值歸入左邊).
d3.bisector - 自訂一個二分函數.
d3.shuffle - 洗牌，隨機排列數組中的元素.
d3.permute - 以指定順序排列數組中的元素.
d3.zip - 將多個數組合成一個數組的數組，新數組的第i個元素是原來各個數組中第i個元素組成的數組.
d3.transpose - 矩陣轉置，透過d3.zip實作.
d3.pairs - 傳回臨近元素對的數組，d3.pairs([1, 2, 3, 4]); // returns [ [1, 2], [2, 3] , [3, 4] ].
d3.keys - 傳回關聯陣列(雜湊表、json、object物件)的key組成的陣列.
d3.values - 傳回關聯陣列的value組成的陣列.
d3.entries - 傳回關聯陣列的key-value實體所組成的陣列, d3.entries({ foo: 42 }); // returns [{key: "foo", value: 42 }].
d3.merge - 將多個陣列連成一個，類似於原生方法concat. d3.merge([ [1], [2, 3] ]); // returns [1, 2, 3].
d3.range - 取得數列. d3.range([start, ]stop[, step])
d3.nest - 取得nest對象，將陣列組織成層級結構.範例：http://bl.ocks.org/phoebebright/raw/3176159/
nest.key - 為nest層級結構增加一個層級.
nest.sortKeys - 將目前的nest層級結構依key排序.
nest.sortValues - 將葉nest層級依value排序.
nest.rollup - 設定修改葉節點值的函數.
nest.map - 執行nest操作, 傳回一個關聯數組(json).
nest.entries - 執行nest運算, 傳回一個key-value陣列. 如果nest.map回傳的結果類似{ foo: 42 }, 則nest.entries回傳的結果類似[{ key: "foo", 值: 42}].
d3.map - 將javascript的object轉換為hash,屏蔽了object的原型鏈功能導致的與hash不一致的問題。
map.has - map有某個key就回傳true.
map.get - 傳回map某個key對應的value.
map.set - 設定map中某個key對應的value.
map.remove - 刪除map中的某個key.
map.keys - 傳回map中所有key組成的陣列.
map.values - 傳回map中所有value組成的陣列.
map.entries - 傳回map中所有entry（key-value鍵值對）組成的陣列.類似{ foo: 42 }轉換成[{key: "foo", value: 42 }]
map.forEach - 對map中每一個entry執行某個函數.
d3.set - 將javascript的array轉化為set,屏蔽了array的object原型鏈功能導致的與set不一致的問題。 set中的value是array中每個值轉換成字串的結果。 set中的value是去重過的。
set.has - 回傳set中是否含有某個value.
set.add - 增加某個value.
set.remove - 刪除某個value.
set.values - 傳回set中的值組成的陣列.set中的value是去重過的.
set.forEach - 對set中每一個value執行某個函數.

Math

d3.random.normal - 利用常態分佈產生隨機數.
d3.random.logNormal - 利用對數常態分佈產生一個隨機數.
d3.random.irwinHall - 利用Irwin–Hall分佈（簡單可行且容易編程的常態分佈實作方法）產生隨機數.
d3.transform - 將svg的tranform格式轉換為標準的2D轉換矩陣字串格式.

載入外部資源(Loading External Resources)

d3.xhr - 啟動XMLHttpRequest請求取得資源。
xhr.header - 設定 request header。
xhr.mimeType - 設定 Accept request header，並重寫 response MIME type。
xhr.response - 設定response回傳值轉換函數。如 function(request) { return JSON.parse(request.responseText); }
xhr.get - 啟動GET請求。
xhr.post - 發起POST請求。
xhr.send - 以指定的方法和資料啟動請求。
xhr.abort - 終止目前請求。
xhr.on - 為請求添加”beforesend”, “progress”, “load” 或 “error” 等事件監聽器。
d3.text - 請求一個text檔。
d3.json - 請求一個JSON。
d3.html - 請求一個html文字片段。
d3.xml - 請求一個XML文字片段。
d3.csv - 請求一個CSV(comma-separated values, 逗號分隔值)檔案。
d3.tsv - 請求一個TSV(tab-separated values, tab分隔值)檔案。

字串格式化(String Formatting)

d3.format - 將數字轉換成指定格式的字串。轉換的格式非常豐富，且非常聰明。
d3.formatPrefix - 以指定的值和精確度獲得一個[SI prefix]物件。這個函數可用來自動判斷資料的量級，如K(千)，M(百萬)等等。範例: var prefix = d3.formatPrefix(1.21e9); console.log(prefix.symbol); // “G”; console.log(prefix.scale(1.21e9)); // 1.21
d3.requote - 將字串轉義成可在正規表示式中使用的格式。如 d3.requote(‘$'); // return “$”
d3.round - 設定某個數字以小數點後多少位元取整。與toFixed()類似，但回傳格式為number。如 d3.round(1.23); // return 1; d3.round(1.23, 1); // return 1.2; d3.round(1.25, 1); // return 1.3

CSV 格式化 (d3.csv)

d3.csv - 取得一個CSV (comma-separated values, 冒號分隔值)檔案。
d3.csv.parse - 將CSV檔案字串轉換成object的陣列，object的key由第一行決定。如： [{"Year": "1997", "Length": "2.34"}, {"Year": "2000", "Length": "2.38"}]
d3.csv.parseRows - 將CSV檔案字串轉換成陣列的陣列。如： [ ["Year", "Length"],["1997", "2.34"],["2000", "2.38"] ]
d3.csv.format - 將object的陣列轉換成CSV檔案字串，是d3.csv.parse的逆操作。
d3.csv.formatRows - 將陣列的陣列轉換成CSV檔案字串，是d3.csv.parseRows的逆操作。
d3.tsv - 取得一個TSV (tab-separated values, tab分隔值)檔案。
d3.tsv.parse - 類似d3.csv.parse。
d3.tsv.parseRows - 類似d3.csv.parseRows。
d3.tsv.format - 類似d3.csv.format。
d3.tsv.formatRows - 類似d3.csv.formatRows。
d3.dsv - 建立一個類似d3.csv的檔案處理對象，可以自訂分隔符號和mime type。如：var dsv = d3.dsv(“|”, “text/plain”);

顏色

d3.rgb - 指定一種顏色，建立一個RGB顏色物件。支援多種顏色格式的輸入。
rgb.brighter - 增強顏色的亮度，變化幅度由參數決定。
rgb.darker - 減弱顏色的亮度，變化幅度由參數決定。
rgb.hsl - 將RGB顏色物件轉換成HSL顏色物件。
rgb.toString - RGB顏色轉換為字串格式。
d3.hsl - 建立一個HSL顏色物件。支援多種顏色格式的輸入。
hsl.brighter - 增強顏色的亮度，變化幅度由參數決定。
hsl.darker - 減弱顏色的亮度，變化幅度由參數決定。
hsl.rgb - 將HSL顏色物件轉換成RGB顏色物件。
hsl.toString - HSL顏色轉換為字串格式。
d3.lab - 建立一個Lab顏色物件。支援多種顏色格式的輸入。
lab.brighter - 增強顏色的亮度，變化幅度由參數決定。
lab.darker - 減弱顏色的亮度，變化幅度由參數決定。
lab.rgb - 將Lab顏色物件轉換成RGB顏色物件。
lab.toString - Lab顏色轉換為字串格式。
d3.hcl - 建立一個HCL顏色物件。支援多種顏色格式的輸入。
hcl.brighter - 增強顏色的亮度，變化幅度由參數決定。
hcl.darker - 減弱顏色的亮度，變化幅度由參數決定。
hcl.rgb - 將HCL顏色物件轉換成RGB顏色物件。
hcl.toString - HCL顏色轉換為字串格式。

命名空間

d3.ns.prefix - 取得或擴充已知的XML命名空間。
d3.ns.qualify - 驗證命名空間前綴是否存在, 如”xlink:href”中xlink是已知的命名空間。

內部方法（Internals）

d3.functor - 函數化。將非函數變數轉換為只傳回該變數值的函數。輸入函數，則傳回原函數；輸入值，則傳回函數，函數只傳回原值。
d3.rebind - 將一個物件的方法綁定到另一個物件上。
d3.dispatch - 建立一個客製化的事件。
dispatch.on - 新增或移除一個事件監聽器。對一個事件可新增多個監聽器。
dispatch.type - 觸發事件。其中‘type'為要觸發的事件的名稱。

d3.scale(Scales)

定量變換(Quantitative)

d3.scale.linear - 建立一個線性定量變換。（建議參考原始碼以深入理解各種變換。）
linear - 輸入一個定義域的值，傳回一個值域的值。
linear.invert - 反變換，輸入值域值回傳定義域值。
linear.domain - get或set定義域。
linear.range - get或set值域。
linear.rangeRound - 設定值域，並對結果取整。
linear.interpolate - get或set變換的插值函數，如將預設的線性內插函數替換成取整的線性內插函數d3_interpolateRound。
linear.clamp - 設定值域是否閉合，預設不閉合。當值域閉合時，如果內插結果在值域之外，會取值域的邊界值。如值域為[1, 2],內插函數的計算結果為3，若不閉合，最終結果為3；若閉合，最終結果為2。
linear.nice - 擴展定義域範圍使定義域更規整。如[0.20147987687960267, 0.996679553296417] 變成 [0.2, 1]。
linear.ticks - 從定義域中取出代表性的值。通常用於座標軸刻度的選取。
linear.tickFormat - 取得格式轉換函數，通常用於座標軸刻度的格式轉換。如：var x = d3.scale.linear().domain([-1, 1]); console.log(x.ticks(5).map(x.tickFormat(5, “ %”))); / / ["-100%", "-50%", " 0%", " 50%", " 100%"]
linear.copy - 從現有的變換複製出一個變換。
d3.scale.sqrt - 建立一個求平方根的定量轉換。
d3.scale.pow - 建立一個指數變換。（可參考linear對應函數的註解）
pow - 輸入一個定義域的值，傳回一個值域的值。
pow.invert - 反變換，輸入值域值回傳定義域值。
pow.domain - get或set定義域。
pow.range - get或set值域。
pow.rangeRound - 設定值域，並對結果取整。
pow.interpolate - get或set變換的插值函數。
pow.clamp - 設定值域是否閉合，預設不閉合。
pow.nice - 擴展定義域範圍使定義域更規整。
pow.ticks - 從定義域中取出有代表性的值。通常用於座標軸刻度的選取。
pow.tickFormat - 取得格式轉換函數，通常用於座標軸刻度的格式轉換。
pow.exponent - get或set指數的冪次方。預設為1次方。
pow.copy - 從已有的變換複製出一個變換。
d3.scale.log - 建立一個對數轉換。（可參考linear對應函數的註解）
log - 輸入一個定義域的值，傳回一個值域的值。
log.invert - 反變換，輸入值域值回傳定義域值。
log.domain - get或set定義域。
log.range - get或set值域。
log.rangeRound - 設定值域，並對結果取整。
log.interpolate - get或set變換的插值函數。
log.clamp - 設定值域是否閉合，預設不閉合。
log.nice - 擴充定義域範圍使定義域更規整。
log.ticks - 從定義域中取出有代表性的值。通常用於座標軸刻度的選取。
log.tickFormat - 取得格式轉換函數，通常用於座標軸刻度的格式轉換。
log.copy - 從已有的變換複製出一個變換。
d3.scale.quantize - 建立一個quantize線性變換,定義域為一個數值區間，值域為幾個離散值。
quantize - 輸入數值，傳回離散值。如： var q = d3.scale.quantize().domain([0, 1]).range(['a', 'b', 'c']); //q(0.3) === 'a ', q(0.4) === 'b', q(0.6) === 'b', q(0.7) ==='c;
quantize.invertExtent - 傳回得到某個離散值的值域範圍。 // q.invertExtent(‘a') 的結果是 [0, 0.3333333333333333]
quantize.domain - get或set變換的定義域。
quantize.range - get或set變換的值域。
quantize.copy - 從現有的變換複製出一個變換。
d3.scale.threshold - 建立一個threshold(閾值)線性變換。定義域為分隔值數值序列，值域為離散值。它與quantize的差異是quantize指定的值域為一個區間，然後均分這個區間為多個小區間，以對應各離散值。 threshold則指定各小區間的邊界分隔值。例: var t = d3.scale.threshold().domain([0, 1]).range(['a', 'b', 'c']); t(-1) === 'a' ; t(0) === 'b'; t(0.5) === 'b'; t(1) === 'c'; t(1000) === 'c'; t.invertExtent(' a'); //returns [undefined, 0] t.invertExtent('b'); //returns [0, 1] t.invertExtent('c'); //returns [1, undefined]
threshold - 輸入數值，傳回離散值。
threshold.invertExtent - 輸入離散值，傳回數值。
threshold.domain - get或set變換的定義域。
threshold.range - get或set變換的值域。
threshold.copy - 從已有的變換複製出一個變換。
d3.scale.quantile - 建構一個quantile線性變換。使用方法與quantize完全類似，差異在於quantile根據中位數來分隔區間，quantize根據算數平均值來分隔區間。 example
quantile - 輸入數值，傳回離散值。
quantile.invertExtent - 輸入離散值，傳回數值。
quantile.domain - get或set變換的定義域。
quantile.range - get或set變換的值域。
quantile.quantiles - 得到quantile變換的分隔值。示例： var q = d3.scale.quantile().domain([0, 1]).range(['a', 'b', 'c']); q.quantiles() returns [0.33333333333333326, 0.6666666666666665]
quantile.copy - 從已有的變換複製出一個變換。
d3.scale.identity - 建構一個identity線性變換。特殊的linear線性變換，此變換定義域和值域相同，只在一些d3內部的axis或brush模組中用到。
identity - identity線性變換函數。傳回輸入值。
identity.invert - 和identity函數相同，傳回輸入值。
identity.domain - get或set變換的定義域。
identity.range - get或set變換的值域。
identity.ticks - 從定義域中取出有代表性的值。通常用於座標軸刻度的選取。
identity.tickFormat - 取得格式轉換函數，通常用於座標軸刻度的格式轉換。
identity.copy - 從現有的變換複製出一個變換。

序數轉換（Ordinal）

d3.scale.ordinal - 建構一個ordinal變換物件。 ordinal變換的輸入定義域和輸出值域都是離散的。而quantitative變換的輸入定義域是連續的，這是兩者最大的不同。
ordinal - 輸入一個離散值，回傳一個離散值。不在目前定義域中的輸入值會自動加入定義域。
ordinal.domain - get或set變換的定義域。
ordinal.range - get或set變換的值域。
ordinal.rangePoints - 用幾個離散點來分割一個連續的區間。詳情請看連結中的圖例。
ordinal.rangeBands - 用幾個離散區間來分割一個連續的區間。詳情請看連結中的圖例。
ordinal.rangeRoundBands - 用幾個離散區間來分割一個連續的區間，區間邊界和寬度會取整。詳情請看連結中的圖例。
ordinal.rangeBand - 取得離散區間的寬度。
ordinal.rangeExtent - 取得輸出域的最小最大值。
ordinal.copy - 從現有的變換複製出一個變換。
d3.scale.category10 - 用10種顏色建構一個ordinal變換。
d3.scale.category20 - 用20種顏色建構一個ordinal變換。
d3.scale.category20b - 用另外20種顏色建構一個ordinal變換。
d3.scale.category20c - 用另外20種顏色建構一個ordinal變換。