選擇 · D3.js API 中文手冊

> [Wiki](Home) ? [[API--中文手冊]] ? [[核心函數]] ? **選擇器** * guluT20141102 * 如發現翻譯不當或有其他問題可以通過以下方式聯系譯者: * 郵箱：zhang_tianxu@sina.com * QQ群：[D3數據可視化](http://jq.qq.com/?_wv=1027&k=ZGcqYF)205076374，[大數據可視化](http://jq.qq.com/?_wv=1027&k=S8wGMe)436442115 一個**選擇**就是從當前文檔中抽取的一組元素。D3使用[[CSS3|http://www.w3.org/TR/css3-selectors/]]來選擇頁面元素。例如，你可以使用的選擇方式有標簽 ("div")、類(“.awesome”)、唯一標識符(“#foo”)、屬性(“[color=red]”)、或者包含(“parent child”)。選擇器可以是交叉(".this.that" 表示邏輯與)的也可以是聯合的(".this, .that" 表示邏輯或)。如果你的瀏覽器不支持選擇器，你可以在D3前包含[[Sizzle|http://sizzlejs.com/]]來支持向后兼容。當選擇完元素之后你可以添加操作。這些操作可以設置或者獲取[屬性](選擇器#attr)、[樣式](選擇器#style)、[特性](選擇器#property)、[選擇器](選擇器#html)和[文本](選擇器#text)內容。屬性值等可以被指定為常量或者函數；后者為每個元素求值。你也可以為數據選擇器加入到[data](選擇器#data)操作；這個數據就可以用做數據驅動的變換的操作符。另外，加上數據產生[enter](選擇器#enter)和[exit](選擇器#exit)子選擇器，你就可以[add](選擇器#add)和[remove](選擇器#remove)元素來響應數據中的改變。一般來說，在D3中你不需要使用for循環后者遞歸來修改文檔。因為你可以一次操作這個選擇器而不是遍歷各個元素。當然，你也可以手動地遍歷各個元素，有一個[each](選擇器#each)操作可以調用任意一個函數，選擇器的結果是數組，所以元素可以訪問(例如`selection[0][0]`)。為了簡便D3支持方法鏈：這個操作返回值是一個選擇器。 ## 選擇元素 D3提供了兩種高級方法來選擇元素：[select](選擇器#d3_select)和[selectAll](選擇器#d3_selectAll)。這些方法接收選擇器字符串。前者只返回第一個匹配的元素，后者選擇在文檔遍歷次序中所有匹配的元素。這個方法也可以接受節點，這可以用來和第三方庫例如JQuery或者開發工具(`$0`)整合。 <a name="d3_select" href="選擇器#d3_select">#</a> d3.<b>select</b>(<i>selector</i>) 選中與指定選擇器字符串匹配的第一個元素，返回單元素選擇結果。如果當前文檔中沒有匹配的元素則返回空的選擇。如果有多個元素被選中，只有第一個匹配的元素（在文檔遍歷次序中）被選中。 <a href="選擇器#d3_select">#</a> d3.<b>select</b>(<i>node</i>) 選擇指定的節點。如果你已經有一個節點的引用這將是很有用的。例如事件監聽器中的`d3.select(this)` 或者一個全局對象例如document.body`。這個函數不會遍歷DOM樹。 <a name="d3_selectAll" href="選擇器#d3_selectAll">#</a> d3.<b>selectAll</b>(<i>selector</i>) 選中匹配指定選擇器的所有的元素。這些元素會按照文檔的遍歷順序（從上到下）選擇。如果當前文檔中沒有匹配的元素則返回空的選擇。 <a href="選擇器#d3_selectAll">#</a> d3.<b>selectAll</b>(<i>nodes</i>) 選擇指定的元素數組。如果你已經有了一些元素的引用這將是很有用的，例如事件監聽器中的`d3.selectAll(this.childNodes)`，或者一個全局對象例如`document.links`。節點的參數不用恰好是數組；任何可以轉化為一個數組的偽數組（例一個`NodeList`或者 arguments`）都可以，這個函數不會遍歷DOM樹。 ## 操作選擇選擇是一組元素。D3綁定額外的方法到數組上。所以你可以在選中的元素上應用操作，例如為所有選中的元素設置屬性值。一個細微的差別是選擇結果是分組的，而不是一個一維數組。每一個選擇都是元素數組中的一個數組。這保留了自選擇的層次結果，大多數情況下你可以忽略這個細節，這就是為什么一個單一的元素選擇看起來像 `[[node]]` 而不是 `[node]` 。想要了解更多關于嵌套選擇的知識請參考[嵌套選擇](http://bost.ocks.org/mike/nest/)。如果你想要學習選擇器是怎么工作的你可以用瀏覽器的開發者工具控制臺交互式地訪問數據。你可以檢查返回數組來查看哪些元素被選中了以及它們是如何分組的。你還可以再應用操作來選擇元素并查看頁面內容的改變。 ### 內容 D3有一系列可以影響文檔內容的操作。這些是你最常用來展示數據的。當操作用來設置文檔內容的時候會返回當前選擇，所以你就可以使用一個簡單的聲明將多個操作鏈接在一起。 <a name="attr" href="選擇器#attr">#</a> selection.<b>attr</b>(<i>name</i>[, <i>value</i>]) 如果指定了*value*參數，將為所有選中的元素通過指定的*name*為指定的*value*設置屬性。如果*value*是一個常數，那么所有的元素都將設置為相同的屬性值；如果*value*是一個函數，那么這個函數會為每個選中的元素（按順序）計算。入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。這個函數的返回值接下來用來設置每個元素的屬性。null值將移除指定的屬性。如果*value*參數沒有指定，就會返回為選擇中第一個非空（null）元素所指定的屬性值。一般來說，只有當你知道選擇中恰好包含一個元素時才有用。指定的*name*參數也會含有一個前綴，例如`xlink:href`是用來指定Xlink命名空間中*href*屬性的。默認情況下，D3支持svg、xhtml、xlink、xml和 xmlns命名空間。可以添加[d3.ns.prefix](命名空間#prefix)來注冊其他的命名空間。 *name*也可以是一個*name*和*value*屬性對象。 <a name="classed" href="選擇器#classed">#</a> selection.<b>classed</b>(<i>name</i>[, <i>value</i>]) 這個操作是用來設置*class*屬性值得便捷程序。它能識別*class*屬性是一個按照空格分隔的標記集合。這樣它就能使用[[classList|https://developer.mozilla.org/en/DOM/element.classList]]（如果有的話）來方便地添加、移除和切換CSS類。如果*value*屬性被指定，不論是否指定類都會與選定元素相結合。如果*value*是一個常量且其值為真，那么所有的元素都會被分配指定的類（還沒分配的話）。如果其值為假，那么就會移除選中元素的class（已經分配過）。如果*value*是一個函數，那么這個函數會為每個選中的元素（按順序）計算。入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。這個函數的返回值接下來用來分配或者不分配每個元素的class。如果你想一次設置多個class可以使用一個對象，文字如同：`selection.classed({'foo': true, 'bar': false})`，或者使用以空格分隔的class列表形如：`selection.classed('foo bar', true)`。如果*value*沒有被指定，當且僅當選擇中首個非空值有指定的class就會返回true。一般來說，只有當你知道選擇中恰好包含一個元素時才有用。 <a name="style" href="選擇器#style">#</a> selection.<b>style</b>(<i>name</i>[, <i>value</i>[, <i>priority</i>]]) 如果*value*參數被指定，通過指定名稱和指定的值為所有選中的元素設置CSS樣式屬性。如果*value*是一個常數，那么所有的元素都設置相同的樣式值；否則，如果值是一個函數，則該函數為每個選定的元件（按順序）計算，入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。該函數的返回值被用來設置每個元素的樣式屬性。 null值將刪除樣式屬性。可選參數*priority*也可以指定，無論是null空或字符串“important”（不帶感嘆號）。如果你想一次設置多個樣式屬性，使用對象文本，如下所示： ```js selection.style({'stroke': 'black', 'stroke-width': 2}) ``` 如果未指定值，則返回在選擇中的第一個非空元素指定樣式屬性的當前計算值。只有當你知道選擇只包含一個元素時是很有用的。需要注意的是計算的值可能與先前設置的值不同，尤其是當樣式屬性使用了簡寫屬性（如“font”樣式，這是簡寫為"font-size"，"font-face",“等）。 <a name="property" href="選擇器#property">#</a> selection.<b>property</b>(<i>name</i>[, <i>value</i>]) 一些HTML元素具有特殊的屬性使用標準的屬性或樣式是不可尋址的。例如，表單文本（text）字段有一個`value`字符串屬性，復選框（checkboxes）有一個`checked`布爾型屬性。可以使用`property`操作符來獲取或設置這些屬性，，或任何其他基本元素的可尋址字段，例如`className`。如果指定了*value*，就為所有選中的元素指定名稱的屬性設置指定的值（value）。如果值是一個常數，那么所有的元素被給予相同的屬性值；如果*value*是一個函數，則該函數為每個選定的元素（按順序）計算，入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。該函數的返回值被用于設置每個元素的屬性。空值將刪除指定的屬性。如果你想一次設置多個屬性，可以使用對象文本，如下所示：`selection.property({'foo': 'bar', 'baz': 'qux'})`。如果未指定值，則返回在選擇中第一個非空元素指定屬性的值。只有當你知道選擇只包含一個元素這通常是很有用的。 <a name="text" href="選擇器#text">#</a> selection.<b>text</b>([<i>value</i>]) 文本操作符是基于`textContent`屬性；設置文本內容將取代任何現有的子元素。如果指定了*value*時，設置所有選擇元素的文本內容為指定的值。如果*value*是一個常數，那么所有的元素被賦予相同的文本內容；如果*value*是一個函數，則該函數被每個選定的元素（按順序）計算，入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。該函數的返回值被用于設置每個元素的文本內容。null值會清除內容。如果未指定*value*，則返回在選擇中第一個非空元素的文本內容。只有當你知道選擇只包含一個元素時這通常是很有用的。 <a name="html" href="選擇器#html">#</a> selection.<b>html</b>([<i>value</i>]) `html`的操作基于[[innerHTML|http://dev.w3.org/html5/spec-LC/apis-in-html-documents.html#innerhtml]]屬性；設置內部HTML內容將取代任何現有的子元素。此外，您可能更愿意使用數據驅動的方式`append`或`insert`操作創建HTML內容;該操作符的目的是，適用于你想用少量但有豐富格式的HTML。如果指定了*value*，為所有選擇的元素設置在內部的HTML內容為指定的值。如果*value*是一個常數，那么所有的元素被給予相同的內部HTML內容；如果*value*是一個函數，則該函數為每個選定的元素（按順序）計算，入參是當前數據元素`d`和當前索引`i`，以及代表當前DOM元素的`this`上下文。該函數的返回值被用于設置每個單元的內部的HTML內容。null值會清除內容。如果未指定*value*，則返回在選擇中第一個非空元素的內部HTML內容。只有當你知道選擇只包含一個元素時這通常是很有用的。注：正如它的名字所暗示的，selection.html僅支持HTML元素。 SVG元素和其它非HTML元素不支持innerHTML屬性，因此與selection.html不相容。請考慮使用[XMLSerializer](https://developer.mozilla.org/en-US/docs/XMLSerializer)轉換DOM樹為文本。靈參見[innersvg polyfill](https://code.google.com/p/innersvg/)，它提供了一個墊片以支持SVG元素的innerHTML屬性。 <a name="append" href="選擇器#append">#</a> selection.<b>append</b>(<i>name</i>) 在當前選擇的每個元素最后追加具有指定名稱的新元素，返回包含追加元素的新選擇。每個新的元素繼承當前元素的數據（如果有的話）和[select](選擇器#select)相同的方式使用子選擇。這個*name*可以被指定為一個常量字符串或一個函數，返回追加的DOM元素。當name被指定為一個字符串，它可能有以下形式的命名空間前綴“namespace:tag”。例如，“svg:text”將在svg命名空間創建“text”元素。默認情況下，D3支持svg，xhtml，xlink的，xml和xmlns命名空間。其他的命名空間可以通過添加到[d3.ns.prefix](命名空間#prefix)注冊。如果沒有指定命名空間，那么命名空間會從封閉的元素繼承；或者，如果該名稱是已知的前綴之一，相應的命名空間將被使用（例如，“svg”表示“svg:svg”）。 <a name="insert" href="選擇器#insert">#</a> selection.<b>insert</b>(<i>name</i>[, <i>before</i>]) 在當前選擇與指定before選擇器匹配的每個元素之前插入具有指定*name*的新元素，返回包含插入的元素的一個新的選擇。如果before選擇器不匹配任何元素，那么新元素將用append追加為最后一個子元素。每一個新元素繼承當前元素（如果有的話）的數據，子選擇（subselections）和[select](選擇器#select)以同樣的方式。這個*name*可以被指定為一個常量字符串或一個函數，返回追加的DOM元素。當*name*被指定為一個字符串，它可能有以下形式的命名空間前綴“namespace:tag”。例如，“svg:text”將在svg命名空間創建“text”元素。默認情況下，D3支持svg，xhtml，xlink的，xml和xmlns命名空間。其他的命名空間可以通過添加到[d3.ns.prefix](命名空間#prefix)注冊。如果沒有指定命名空間，那么命名空間會從封閉的元素繼承；或者，如果該名稱是已知的前綴之一，相應的命名空間將被使用（例如，“svg”表示“svg:svg”）。同樣地，*before*選擇器可以被指定為一個選擇器字符串或一個函數，它返回一個DOM元素。例如，`insert("div", ":first-child")`將在當前選擇前面加上div子節點。對于[enter選擇器](選擇器#enter)，*before*選擇器在這種情況下也可以省略：輸入的元素將被立即插入到更新選擇緊隨的兄弟元素前（如果有的話）。這使您可以插入DOM的元素與綁定的數據是一致的順序。但是請注意，如果更新元素修改了順序，[selection.order](選擇器#order)可能仍然需要。 <a name="remove" href="選擇器#remove">#</a> selection.<b>remove</b>() 刪除從當前文檔當前選擇中的元素。返回“屏幕外（off-screen）”的當前選擇（除去了相同的元素），從DOM分離。需要注意的是目前還沒有一個專門的API來重新添加刪除的元素到文檔；然而，你可以通過一個函數來selection.append或selection.insert重新添加元素。 ###數據 <a name="data" href="選擇器#data">#</a> selection.<b>data</b>([<i>values</i>[, <i>key</i>]]) 連接指定的一組數據的和當前選擇。指定的*values*是一組數據值（例如，數字或對象）或一個函數返回一組值。如果沒有指定*key*函數，則*values*的第一數據被分配到當前選擇中第一元素，第二數據分配給當前選擇的第二個元素，依此類推。當數據被分配給一個元素，它被存儲在屬性`__data__`中，從而使數據“沾粘”，從而使數據可以再選擇。 `data`操作的結果是*update*選擇;這表示選擇的DOM元素已成功綁定到指定的數據元素。*update*選擇還包含對[enter](選擇器#enter)和[exit](選擇器#exit)的選擇，對應于添加和刪除數據節點。有關詳細信息，請參閱簡短的教程[關于連接的思考](http://bost.ocks.org/mike/join/) *key*函數可以被指定為控制數據是如何連接元素。這取代默認的by-index行為;*key*函數被新數據數組中的每個元素調用一次，并再次用于選擇中的每個元素。在這兩種情況下的*key*函數是通過傳遞數據d與索引i。當key 函數上被新的數據元素評價時，`this`上下文是數據數組；當key 函數被現有選擇評估時，`this`上下文是相關的DOM元素。*key*函數，基于先前結合的數據返回一個用于連接數據和相關的元素的字符串。例如，如果每個數據都有一個唯一的字段`name`，該連接可以被指定為`.data(data, function(d) { return d.name; })`。如果指定了*key*函數，`data`操作符也影響節點的索引；該索引被作為第二個參數`i`作為任何運算符函數的參數。然而，請注意，現有的DOM元素不自動重新排序；根據需要使用[sort](#sort)或[order](#order)函數。有關*key*函數如何影響數據連接的更詳細的示例，請參閱教程[[條形圖2|http://bost.ocks.org/mike/bar/2/]] 這個*values*選擇中的**每組數據**。因此，如果選擇具有多個組（例如，一個[d3.selectAll](#d3_selectAll)后跟一個[selection.selectAll](#selectAll))），然后data應該被指定為一個函數，該函數返回一個數組（假設你對每個組想要不同的數據）。該函數將被傳遞的當前組數據（或`undefined`）和索引，組的`this`上下文。例如，可以將一個二維數組和初始選擇綁定，然后將包含的內部數組和每個子選擇綁定。在這種情況下，*values*函數是標識函數：它被每個組中的子元素調用，被傳遞綁定到父元素的數據，并且返回這個數據數組。 ```javascript var matrix = [ [11975, 5871, 8916, 2868], [ 1951, 10048, 2060, 6171], [ 8010, 16145, 8090, 8045], [ 1013, 990, 940, 6907] ]; var tr = d3.select("body").append("table").selectAll("tr") .data(matrix) .enter().append("tr"); var td = tr.selectAll("td") .data(function(d) { return d; }) .enter().append("td") .text(function(d) { return d; }); ``` 如果未指定*values*，則此方法返回選擇中的第一組數據的數組。返回的數組的長度，將與第一組的長度匹配，并且在返回的數組中的每個數據的索引將匹配選擇中相應的索引。如果選擇的某些元素為null，或者如果他們有沒有相關的數據，則數組中的相應元素將是`undefined`。注意：`data`方法不能用于清除先前結合數據；可以使用[selection.datum](#datum)代替。 <a name="enter" href="選擇器#enter">#</a> selection.<b>enter()</b> 返回輸入（enter）選擇：當前選擇中存在但是當前DOM元素中還不存在的每個數據元素的占位符節點。此方法只在由[data](選擇器#data)運算符返回的更新選擇中定義。此外，輸入選擇只定義了[append](選擇器#append)（append），[insert](選擇器#insert)（insert），[select](選擇器#select)（select）和[call](選擇器#call)（call）操作符；您必須使用這些操作符在修改任何內容之前實例化輸入元素。當你傳遞函數的參數給這些插入的元素的操作符時，index參數將反映新的位置，而不一定從零開始或者是連續的。（輸入選擇也支持[empty](選擇器#empty)和[size](選擇器#size)。）舉一個簡單的例子，考慮現有的選擇是空的情況下，我們希望創建新的節點來匹配我們的數據： ```javascript d3.select("body").selectAll("div") .data([4, 8, 15, 16, 23, 42]) .enter().append("div") .text(function(d) { return d; }); ``` 假設body最初是空的，上面的代碼將創建六個新的div元素，將它們按順序追加到body，并指定其文本內容為相應的（強制轉為字符串）號碼： ```html <div>4</div> <div>8</div> <div>15</div> <div>16</div> <div>23</div> <div>42</div> ``` 另一種方式考慮進入的占位符的節點是，它們是指向父節點（在該示例中，就是文檔的body）；然而，他們只支持追加和插入。當你追加或插入時輸入選擇并入到**更新選擇**。而不是對enter和update選擇單獨采用同樣的操作符，現在你可以一次添加節點后，將其應用到更新選擇。如果你發現自己移除整個選擇的元素才重新插入其中大部分，用這個來替代。例如： ```javascript var update_sel = svg.selectAll("circle").data(data) update_sel.attr(/* operate on old elements only */) update_sel.enter().append("circle").attr(/* operate on new elements only */) update_sel.attr(/* operate on old and new elements */) update_sel.exit().remove() /* complete the enter-update-exit pattern */ ``` <a name="exit" href="選擇器#exit">#</a> selection.<b>exit()</b> 返回退出（exit）選擇：找出在當前選擇存在的DOM元素中沒有新的數據元素時。此方法只被定義在[data](選擇器#data)運算符返回的更新選擇。exit選擇定義了所有的正常操作符，但通常你主要使用的是[remove](選擇器#remove)；其他操作符存在的主要目的是讓您可以根據需要定義一個退出的過渡。請注意，exit操作符只是返回一個exit選擇引用，由你來刪除新節點。一個簡單的例子，考慮更新在上面的例子中的enter操作符創建的六個DIV元素。在這里，我們把這些元素和一個含有一些新的，一些舊數據的新數組綁定： ```javascript var div = d3.select("body").selectAll("div") .data([1, 2, 4, 8, 16, 32], function(d) { return d; }); ``` 現在div--data操作符的結果--指的是更新的選擇。因為我們指定的key函數使用標識函數，并且將新數據數組包含數字[4,8,16]，它也存在舊的數據數組中，這個更新選擇包含3 個DIV元素。比方說，我們離開這些元素原樣。我們可以實例化并使用enter選擇添加新的元素[1,2,32]： ```javascript div.enter().append("div") .text(function(d) { return d; }); ``` 同樣，我們可以刪除退出的元素[15, 23, 42]： div.exit().remove(); ```html 現在，文檔body如下： <div>4</div> <div>8</div> <div>16</div> <div>1</div> <div>2</div> <div>32</div> ``` 注意，DOM元素現在是亂序。然而，選擇索引i（操作函數的第二個參數），將正確地與新數據數組相匹配。例如，我們可以指定一個索引屬性： ```javascript d3.selectAll("div").attr("index", function(d, i) { return i; }); ``` 結果是： ```html <div index="2">4</div> <div index="3">8</div> <div index="4">16</div> <div index="0">1</div> <div index="1">2</div> <div index="5">32</div> ``` 如果你想在文檔遍歷，以匹配選擇數據順序，可以使用[sort](#sort)或者[order](#order)。 <a name="filter" href="選擇器#filter">#</a> selection.<b>filter</b>(<i>selector</i>) 過濾選擇，返回一個新的選擇只包含其指定的*selector*是true的元素。*selector*可以被指定為一個函數或作為選擇的字符串，如“.foo”。和其他操作符一樣，該函數被傳遞當前數據`d`和索引`i`，以及this上下文作為當前的DOM元素。過濾器應該只在選擇與DOM元素綁定的時候。例如：從[append](選擇器#append)或[insert](選擇器#insert)。只綁定的元素和數據的一個子集，可以在[data](選擇器#data)參數中調用內置的數組過濾器[filter](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/Filter "https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/Filter")。像內置函數一樣，D3的過濾器*不會*在返回選擇中保留原來的選擇的索引；返回移除元素的副本。如果您想保留的索引，使用[select](選擇器#select)代替。例如，要選擇奇數索引（相對于從零開始的索引）的每一個元素： ```javascript var odds = selection.select(function(d, i) { return i & 1 ? this : null; }); ``` 等價地，使用的過濾器函數： ```javascript var odds = selection.filter(function(d, i) { return i & 1; }); ``` 或過濾選擇器（注意：nth-child偽類是一開始的索引，而不是從零開始的索引）： ```javascript var odds = selection.filter(":nth-child(even)"); ``` 因此，您可以使用選擇或過濾器操作符應用到元素的一個子集上。 <a name="datum" href="選擇器#datum">#</a> selection.<b>datum</b>([<i>value</i>]) 獲取或設置每個選定的元素綁定的數據。不像[selection.data](#data)方法，這種方法不計算一個連接（并因此不計算enter和exit的選擇）。此方法在[selection.property](#property)之上實現： ```js d3.selection.prototype.datum = function(value) { return arguments.length < 1 ? this.property("__data__") : this.property("__data__", value); }; ``` 如果指定*value*，就為所有選中的元素設置元素的綁定數據為指定的值。如果*value*是一個常數，所有的元素被給予相同的數據；否則，如果*value*是一個函數，則該函數為每個選定的元素計算，被傳遞以前的數據`d`與當前索引`i`，使用`this`上下文作為當前的DOM元素。該函數之后被用來確定每個元素的數據。null值將刪除綁定的數據。該操作數對索引沒有影響。如果未指定*value*，則返回在選擇中綁定第一個非空的元素的數據。只有當你知道選擇只包含一個元素這通常是很有用的。注意：此方法是以前所謂的“map”。舊名已被棄用。 datum 方法用D3訪問HTML5自定義數據屬性非常有用。例如，給定下列元素： ```html <ul id="list"> <li data-username="shawnbot">Shawn Allen</li> <li data-username="mbostock">Mike Bostock</li> </ul> ``` 你可以公開通過設置每個元素的數據作為內置的[dataset](http://www.w3.org/TR/html5/dom.html#dom-dataset "http://www.w3.org/TR/html5/dom.html#dom-dataset")屬性自定義數據屬性D3： ```javascript selection.datum(function() { return this.dataset; }) ``` 這可以用來，例如，按照用戶名排序元素。[示例](http://bl.ocks.org/mbostock/1323729) <a name="sort" href="#sort">#</a> selection.<b>sort</b>([<i>comparator</i>]) 根據指定的*comparator*函數對當前選擇的元素排序。比較器函數默認為[d3.ascending](https://github.com/mbostock/d3/wiki/Arrays#d3_ascending)，通過傳遞兩個數據元素*a*和*b*進行比較，并返回任一負的，正的，或零值。如果為負，則*a*應該在*b*之前；如果為正，則*a*應該為*b*后；否則a和b被認為是相等的順序是任意的。需要注意的是，這種排序是不保證是穩定的；然而，它保證與瀏覽器內置的數組[排序](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort "https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort")方法具有相同的行為。 <a name="order" href="#order">#</a> selection.<b>order</b>() 重新插入元素到文檔這樣文檔順序選與擇順序就相匹配。這等同于調用sort()如果數據已經排序，但要快得多。 ### 動畫和交互 <a name="on" href="#on">#</a> selection.<b>on</b>(<i>type</i>[, <i>listener</i>[, <i>capture</i>]]) 在當前選擇的每個元素，為指定的類型*type*，添加或刪除事件監聽器*listener* 。*type*是一個字符串事件類型的名稱，如“點擊”，“鼠標懸停”，或“提交”。基本上支持任何[DOM事件](https://developer.mozilla.org/en-US/docs/Web/Events#Standard_events)。有關D3支持的事件類型的更多詳細信息，請查看Mozilla或Stackoverflow。指定的listener 與其他操作符函數調用方式相同，被傳遞的當前數據`d`和索引`i`與`this`上下文作為當前的DOM元素。為了在偵聽器內訪問當前事件，使用全局函數[d3.event](選擇器#d3_event)。事件偵聽器的返回值將被忽略。如果所選擇的元素相同類型的一個事件監聽已經注冊了，新的偵聽加入之前的現有偵聽被除去。為注冊相同事件類型的多個監聽器，該類型可以跟一個可選的命名空間，如“click.foo”和“click.bar”。要刪除一個監聽器，傳遞null給*listener*，刪除特定事件類型所有監聽，傳遞null給listener，指定`.type`的類型，如：`selection.on(".foo", null)`。一個可選的捕獲*capture*標志可以指定，對應于W3C的[useCapture標志](http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-registration "http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-registration")：“開始捕獲后，所有指定類型的事件將被分派到注冊的EventListener在被分派到事件樹任何EventTargets下，事件是沿著樹向上冒泡而不會觸發一個EventListener指定使用捕獲”。如果未指定監聽器，指定類型（如果有）返回當前分配的監聽器。 <a name="d3_event" href="選擇器#d3_event">#</a> d3.<b>event</b> 存儲當前的事件（如果有的話）。這個全局函數是在事件偵聽器回調過程中使用[on](選擇器#on)操作符注冊的。當監聽器在`finally`塊被通知后當前事件被重置。這使偵聽器函數與其他操作符函數具有相同的形式，傳遞當前數據`d`和索引`i`。 `d3.event`對象是[DOM事件](https://developer.mozilla.org/en-US/docs/DOM/event "https://developer.mozilla.org/en-US/docs/DOM/event")，并實現了標準事件字段，像時間戳`timeStamp`和鍵代碼`keyCode`，以及`preventDefault()`方法和的`stopPropagation()`方法。當然你可以使用原生事件的[pageX](https://developer.mozilla.org/en/DOM/event.pageX "https://developer.mozilla.org/en/DOM/event.pageX") and [pageY](https://developer.mozilla.org/en/DOM/event.pageY "https://developer.mozilla.org/en/DOM/event.pageY")，它往往更方便轉變事件位置為接收該事件容器的局部坐標系。例如，如果你在網頁的正常流程嵌入SVG，你可能想事件的位置是相對于SVG圖像的左上角的。如果您的SVG包含轉換，你也可能想知道事件的相對于那些變換的位置。標準鼠標指針使用[d3.mouse](#d3_mouse)運算符，[d3.touches](#d3_touches)用在iOS多點觸控事件上。 <a name="d3_mouse" href="#d3_mouse">#</a> d3.<b>mouse</b>(<i>container</i>) 返回當前[d3.event](#d3_event)相對于指定的容器的x和y坐標，。該容器可以是一個HTML或SVG容器元素，如[svg:g](http://www.w3.org/TR/SVG/struct.html#Groups "http://www.w3.org/TR/SVG/struct.html#Groups")或[svg:svg](http://www.w3.org/TR/SVG/struct.html#SVGElement "http://www.w3.org/TR/SVG/struct.html#SVGElement")。該坐標返回為一個包含兩個元素的數組[*x*, *y*]。 <a name="d3_touch" href="#d3_touch">#</a> d3.<b>touch</b>(<i>container</i>[, <i>touches</i>], <i>identifier</i>) 返回指定標識符觸摸當前[d3.event](#d3_event)相應的x和y坐標，相對于指定容器。如果未指定*touches*時，默認為當前事件的[changedTouches](http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/changedTouches "http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/changedTouches")。該容器可以是一個HTML或SVG容器元件，如一個的svg:g或svg:svg。坐標被返回為兩元素數組的數組[ [ *x1*, *y1*], [ *x2*, *y2*], … ]。如果在指定的標識符*touches*沒有接觸，則返回null；這對于忽略touchmove那些只是touches移動了的事件是很有用的。 <a name="d3_touches" href="#d3_touches">#</a> d3.<b>touches</b>(<i>container</i>[, <i>touches</i>]) 返回與當前[d3.event](#d3_event)相關聯的每個觸摸*x*和*y*坐標，基于[touches](http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/touches "http://developer.apple.com/library/safari/documentation/UserExperience/Reference/TouchEventClassReference/TouchEvent/TouchEvent.html#//apple_ref/javascript/instp/TouchEvent/touches")屬性，相對于指定的容器中。該容器可以是一個HTML或SVG容器元素，如svg:g 或 svg:svg。坐標返回兩個元素的數組的數組[ [ *x1*, *y1*], [ *x2*, *y2*], … ]。如果指定了觸摸，返回指定觸摸的位置，如果沒有指定*touches*時，則默認為當前事件的`touches`屬性。 <a name="transition" href="Selections#transition">#</a> selection.<b>transition</b>([<i>name</i>]) 開始為當前選擇的[過渡](Transitions)。轉換的行為很像選擇，除了操作符動畫平滑的隨著時間的推移，而不是瞬間完成。 <a name="interrupt" href="#interrupt">#</a> selection.<b>interrupt</b>([<i>name</i>]) 立即中斷當前的[過渡](Transitions)（如果有的話）。不會取消任何尚未啟動的預定的轉變。最好要取消原定過渡，簡單地創建中斷當前的過渡后，一個新的零延遲過渡： ```javascript selection .interrupt() // 取消當前過渡 .transition(); //搶占任何預定的轉換 ``` ### 子選擇頂層的select方法查詢整個文檔，一個選擇的[select](選擇器#select)和[selectAll](選擇器#selectAll)操作符限定查詢每個選定元素的后代；我們稱之為“部分選擇”。例如，`d3.selectAll("p").select("b")`返回在每一個段落("p")元素中的第一個bold("b")元素。部分選擇通過selectAll通過祖先分組元素。因此，`d3.selectAll("p").selectAll("b")`。通過段落分組而d3.selectAll("p b") 返回一個扁平的選擇。部分選擇通過select是相似的，但保留了團體和傳播數據。分組起在數據連接中起重要的作用，和功能性操作符可依賴于其組內的當前元素的數值索引。 <a name="select" href="Selections#select">#</a> selection.<b>select</b>(<i>selector</i>) 對當前選中的每個元素，選中第一個匹配特定的選擇器字符串*selector*的子代元素。如果當前元素沒有元素匹配特定的選擇器，當前索引處的元素在返回的選擇中將是空值null。運算符（除了[data](選擇器#data)）自動跳過null元素，從而保持現有選擇的索引。如果當前元素具有相關聯的數據，該數據由返回的子選擇繼承，并且自動綁定到新選定的元素。如果有多個元素匹配選擇器，只有在文檔遍歷順序中第一個匹配的元素會被選中。選擇器也可以被指定為一個函數，返回一個元素，或者null（如果沒有匹配的元素）。在這種情況下，指定的選擇器以和其他操作函數同樣的方式被調用，被傳遞的當前數據`d`和索引`i`，與`this`上下文作為當前的DOM元素。 <a name="selectAll" href="Selections#selectAll">#</a> selection.<b>selectAll</b>(<i>selector</i>) 對當前選擇的每個元素，選取匹配指定選擇器字符串的后代元素。返回的選擇是通過在當前選擇的祖先節點進行分組。如果沒有元素和當前元素的指定選擇器相匹配，返回的選擇中當前索引處的組將是null。部分選取不從當前選擇繼承數據，但如果數據值指定為一個函數，這個函數會被調用，帶有的祖先節點的數據d和組索引i來確定部分選定的數據綁定。通過selectAll的分組也將影響后續進入的占位節點。因此，為追加進入的節點指定父節點，使用select后緊跟selectAll： ```javascript d3.select("body").selectAll("div") ``` 您可以通過檢查各組數據的parentNode屬性查看每個組的父節點，例如selection[0].parentNode。選擇器也可以被指定為一個函數，返回元素的數組（或節點列表NodeList），或者空數組（如果沒有匹配的元素）。在這種情況下，指定的選擇器以和其他操作函數同樣的方式被調用，被傳遞的當前數據`d`和索引`i`，與`this`上下文作為當前的DOM元素。 ### 控制對于高級用法，D3有一些額外的用戶控制流操作符。 <a name="each" href="Selections#each">#</a> selection.<b>each</b>(<i>function</i>) 為當前選擇的每個元素，調用指定的函數，傳遞當前數據`d`和索引`i`，與當前的DOM元素的`this`上下文。這個操作符幾乎被所有的其他操作符內部使用，并可以用于調用任意代碼為每個選定的元素。`each`操作符可以用來處理遞歸的選擇，通過在回調函數內使用`d3.select(this)`。 <a name="call" href="Selections#call">#</a> selection.<b>call</b>(<i>function</i>[, <i>arguments…</i>]) 調用指定的函數一次，通過在當前的選擇以及任何可選參數。無論指定函數的返回值是什么，call操作符總是返回當前的選擇。通過call調用函數與手動調用函數是完全一樣的；但它可以更容易地使用方法鏈。例如，假設我們要在許多不同的地方以同樣的方式設置一些屬性。我們采取的代碼，把它包在一個可重復使用的功能： ```javascript function foo(selection) { selection .attr("name1", "value1") .attr("name2", "value2"); } ``` 現在我們可以這樣寫： ```javascript foo(d3.selectAll("div")); ``` 或者等價的方式： ```javascript d3.selectAll("div").call(foo); ``` 被調用函數的`this`上下文也是當前的選擇。第一個參數是略顯多余的，這我們可能在未來解決。如果您使用的`selection.call`的對象，方法和需要`this`指向該對象創建之前調用綁定到對象的函數。 ```javascript function Foo(text) { this.text = text; } Foo.prototype.setText = function(selection) { selection.text(this.text); } var bar = new Foo("Bar"); d3.selectAll("span").call(bar.setText.bind(bar)); // Or d3.selectAll("span").call(Foo.prototype.setText.bind(bar)); ``` <a name="empty" href="Selections#empty">#</a> selection.<b>empty</b>() 返回true如果當前選擇為空；一個選擇是空的，如果它不包含任何元素或null元素。 <a name="node" href="Selections#node">#</a> selection.<b>node</b>() 返回當前選擇的第一個非空的元素。如果選擇為空，則返回null。 <a name="size" href="Selections#size">#</a> selection.<b>size</b>() Returns the total number of elements in the current selection. ### 擴展 <a name="d3_selection" href="#d3_selection">#</a> d3.<b>selection</b>() 返回根的選擇，相當于`d3.select(document.documentElement)`。此函數還可以用于檢查一個對象是一個選擇：`o instanceof d3.selection`。您還可以添加新的方法到選擇的原形中。例如，添加一個便捷的方法，用于設置復選框的`checked`屬性，你可能這樣寫： ```js d3.selection.prototype.checked = function(value) { return arguments.length < 1 ? this.property("checked") : this.property("checked", value); };