• 如發現翻譯不當或有其他問題可以通過以下方式聯絡譯者:
• QQ群：D3.js:437278817，大資料視覺化：436442115

引用

原文

一個選擇就是從當前文件中抽取的一組元素。D3使用CSS3來選擇頁面元素。例如，你可以使用的選擇方式有標籤 ("div")、類(“.awesome”)、唯一識別符號(“#foo”)、屬性(“[color=red]”)、或者包含(“parent child”)。選擇器可以是交叉(".this.that" 表示邏輯與)的也可以是聯合的(".this, .that" 表示邏輯或)。如果你的瀏覽器不支援選擇器，你可以在D3前包含Sizzle來支援向後相容。

當選擇完元素之後你可以新增操作。這些操作可以設定或者獲取

屬性、樣式、特性、選擇器和文字內容。屬性值等可以被指定為常量或者函式；後者為每個元素求值。你也可以為資料選擇器加入到data操作；這個資料就可以用做資料驅動的變換的操作符。另外，加上資料產生enter和exit子選擇器，你就可以add和remove元素來響應資料中的改變。

一般來說，在D3中你不需要使用for迴圈後者遞迴來修改文件。因為你可以一次操作這個選擇器而不是遍歷各個元素。當然，你也可以手動地遍歷各個元素，有一個each操作可以呼叫任意一個函式，選擇器的結果是陣列，所以元素可以訪問(例如selection[0][0])。為了簡便D3支援方法鏈：這個操作返回值是一個選擇器。

選擇元素

D3提供了兩種高階方法來選擇元素：

select和selectAll。這些方法接收選擇器字串。前者只返回第一個匹配的元素，後者選擇在文件遍歷次序中所有匹配的元素。這個方法也可以接受節點，這可以用來和第三方庫例如JQuery或者開發工具($0)整合。

# d3.select(selector)

選中與指定選擇器字串匹配的第一個元素，返回單元素選擇結果。如果當前文件中沒有匹配的元素則返回空的選擇。如果有多個元素被選中，只有第一個匹配的元素（在文件遍歷次序中）被選中。

# d3.select(node)

選擇指定的節點。如果你已經有一個節點的引用這將是很有用的。例如事件監聽器中的d3.select(this) 或者一個全域性物件例如document.body

。這個函式不會遍歷DOM樹。

# d3.selectAll(selector)

選中匹配指定選擇器的所有的元素。這些元素會按照文件的遍歷順序（從上到下）選擇。如果當前文件中沒有匹配的元素則返回空的選擇。

# d3.selectAll(nodes)

選擇指定的元素陣列。如果你已經有了一些元素的引用這將是很有用的，例如事件監聽器中的d3.selectAll(this.childNodes)，或者一個全域性物件例如document.links。節點的引數不用恰好是陣列；任何可以轉化為一個數組的偽陣列（例一個NodeList或者 arguments）都可以，這個函式不會遍歷DOM樹。

操作選擇

選擇是一組元素。D3繫結額外的方法到陣列上。所以你可以在選中的元素上應用操作，例如為所有選中的元素設定屬性值。一個細微的差別是選擇結果是分組的，而不是一個一維陣列。每一個選擇都是元素陣列中的一個數組。這保留了自選擇的層次結果，大多數情況下你可以忽略這個細節，這就是為什麼一個單一的元素選擇看起來像 [[node]] 而不是 [node] 。想要了解更多關於巢狀選擇的知識請參考巢狀選擇。如果你想要學習選擇器是怎麼工作的你可以用瀏覽器的開發者工具控制檯互動式地訪問資料。你可以檢查返回陣列來檢視哪些元素被選中了以及它們是如何分組的。你還可以再應用操作來選擇元素並檢視頁面內容的改變。

內容

D3有一系列可以影響文件內容的操作。這些是你最常用來展示資料的。當操作用來設定文件內容的時候會返回當前選擇，所以你就可以使用一個簡單的宣告將多個操作連結在一起。

# selection.attr(name[, value])

如果指定了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來註冊其他的名稱空間。

name也可以是一個name和value屬性物件。

# selection.classed(name[, value])

這個操作是用來設定class屬性值得便捷程式。它能識別class屬性是一個按照空格分隔的標記集合。這樣它就能使用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。一般來說，只有當你知道選擇中恰好包含一個元素時才有用。

# selection.style(name[, value[, priority]])

如果value引數被指定，通過指定名稱和指定的值為所有選中的元素設定CSS樣式屬性。如果value是一個常數，那麼所有的元素都設定相同的樣式值；否則，如果值是一個函式，則該函式為每個選定的元件（按順序）計算，入參是當前資料元素d和當前索引i，以及代表當前DOM元素的this上下文。該函式的返回值被用來設定每個元素的樣式屬性。 null值將刪除樣式屬性。可選引數priority也可以指定，無論是null空或字串“important”（不帶感嘆號）。

如果你想一次設定多個樣式屬性，使用物件文字，如下所示：

selection.style({'stroke': 'black', 'stroke-width': 2})

如果未指定值，則返回在選擇中的第一個非空元素指定樣式屬性的當前計算值。只有當你知道選擇只包含一個元素時是很有用的。需要注意的是計算的值可能與先前設定的值不同，尤其是當樣式屬性使用了簡寫屬性（如“font”樣式，這是簡寫為"font-size"，"font-face",“等）。

# selection.property(name[, value])

一些HTML元素具有特殊的屬性使用標準的屬性或樣式是不可定址的。例如，表單文字（text）欄位有一個value字串屬性，複選框（checkboxes）有一個checked布林型屬性。可以使用property操作符來獲取或設定這些屬性，，或任何其他基本元素的可定址欄位，例如className。

如果指定了value，就為所有選中的元素指定名稱的屬性設定指定的值（value）。如果值是一個常數，那麼所有的元素被給予相同的屬性值；如果value是一個函式，則該函式為每個選定的元素（按順序）計算，入參是當前資料元素d和當前索引i，以及代表當前DOM元素的this上下文。該函式的返回值被用於設定每個元素的屬性。空值將刪除指定的屬性。

如果你想一次設定多個屬性，可以使用物件文字，如下所示：selection.property({'foo': 'bar', 'baz': 'qux'})。

如果未指定值，則返回在選擇中第一個非空元素指定屬性的值。只有當你知道選擇只包含一個元素這通常是很有用的。

# selection.text([value])

文字操作符是基於textContent屬性；設定文字內容將取代任何現有的子元素。

如果指定了value時，設定所有選擇元素的文字內容為指定的值。如果value是一個常數，那麼所有的元素被賦予相同的文字內容；如果value是一個函式，則該函式被每個選定的元素（按順序）計算，入參是當前資料元素d和當前索引i，以及代表當前DOM元素的this上下文。該函式的返回值被用於設定每個元素的文字內容。null值會清除內容。

如果未指定value，則返回在選擇中第一個非空元素的文字內容。只有當你知道選擇只包含一個元素時這通常是很有用的。

# selection.html([value])

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轉換DOM樹為文字。靈參見innersvg polyfill，它提供了一個墊片以支援SVG元素的innerHTML屬性。

# selection.append(name)

在當前選擇的每個元素最後追加具有指定名稱的新元素，返回包含追加元素的新選擇。每個新的元素繼承當前元素的資料（如果有的話）和select相同的方式使用子選擇。

這個name可以被指定為一個常量字串或一個函式，返回追加的DOM元素。當name被指定為一個字串，它可能有以下形式的名稱空間字首“namespace:tag”。例如，“svg:text”將在svg名稱空間建立“text”元素。預設情況下，D3支援svg，xhtml，xlink的，xml和xmlns名稱空間。其他的名稱空間可以通過新增到d3.ns.prefix註冊。如果沒有指定名稱空間，那麼名稱空間會從封閉的元素繼承；或者，如果該名稱是已知的字首之一，相應的名稱空間將被使用（例如，“svg”表示“svg:svg”）。

# selection.insert(name[, before])

在當前選擇與指定before選擇器匹配的每個元素之前插入具有指定name的新元素，返回包含插入的元素的一個新的選擇。如果before選擇器不匹配任何元素，那麼新元素將用append追加為最後一個子元素。每一個新元素繼承當前元素（如果有的話）的資料，子選擇（subselections）和select以同樣的方式。

這個name可以被指定為一個常量字串或一個函式，返回追加的DOM元素。當name被指定為一個字串，它可能有以下形式的名稱空間字首“namespace:tag”。例如，“svg:text”將在svg名稱空間建立“text”元素。預設情況下，D3支援svg，xhtml，xlink的，xml和xmlns名稱空間。其他的名稱空間可以通過新增到d3.ns.prefix註冊。如果沒有指定名稱空間，那麼名稱空間會從封閉的元素繼承；或者，如果該名稱是已知的字首之一，相應的名稱空間將被使用（例如，“svg”表示“svg:svg”）。

同樣地，before選擇器可以被指定為一個選擇器字串或一個函式，它返回一個DOM元素。例如，insert("div", ":first-child")將在當前選擇前面加上div子節點。對於enter選擇器，before選擇器在這種情況下也可以省略：輸入的元素將被立即插入到更新選擇緊隨的兄弟元素前（如果有的話）。這使您可以插入DOM的元素與繫結的資料是一致的順序。但是請注意，如果更新元素修改了順序，selection.order可能仍然需要。

# selection.remove()

刪除從當前文件當前選擇中的元素。返回“螢幕外（off-screen）”的當前選擇（除去了相同的元素），從DOM分離。需要注意的是目前還沒有一個專門的API來重新新增刪除的元素到文件；然而，你可以通過一個函式來selection.append或selection.insert重新新增元素。

資料

# selection.data([values[, key]])

連線指定的一組資料的和當前選擇。指定的values是一組資料值（例如，數字或物件）或一個函式返回一組值。如果沒有指定key函式，則values的第一資料被分配到當前選擇中第一元素，第二資料分配給當前選擇的第二個元素，依此類推。當資料被分配給一個元素，它被儲存在屬性__data__中，從而使資料“沾粘”，從而使資料可以再選擇。

data操作的結果是update選擇;這表示選擇的DOM元素已成功繫結到指定的資料元素。update選擇還包含對enter和exit的選擇，對應於新增和刪除資料節點。有關詳細資訊，請參閱簡短的教程關於連線的思考

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或order函式。有關key函式如何影響資料連線的更詳細的示例，請參閱教程條形圖2

這個values選擇中的每組資料。因此，如果選擇具有多個組（例如，一個d3.selectAll後跟一個selection.selectAll)），然後data應該被指定為一個函式，該函式返回一個數組（假設你對每個組想要不同的資料）。該函式將被傳遞的當前組資料（或undefined）和索引，組的this上下文。 例如，可以將一個二維陣列和初始選擇繫結，然後將包含的內部陣列和每個子選擇繫結。在這種情況下，values函式是標識函式：它被每個組中的子元素呼叫，被傳遞繫結到父元素的資料，並且返回這個資料陣列。

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代替。

# selection.enter()

返回輸入（enter）選擇：當前選擇中存在但是當前DOM元素中還不存在的每個資料元素的佔位符節點。此方法只在由data運算子返回的更新選擇中定義。此外，輸入選擇只定義了append（append），insert（insert），select（select）和call（call）操作符；您必須使用這些操作符在修改任何內容之前例項化輸入元素。當你傳遞函式的引數給這些插入的元素的操作符時，index引數將反映新的位置，而不一定從零開始或者是連續的。 （輸入選擇也支援empty和size。）

舉一個簡單的例子，考慮現有的選擇是空的情況下，我們希望建立新的節點來匹配我們的資料：

d3.select("body").selectAll("div")
    .data([4, 8, 15, 16, 23, 42])
  .enter().append("div")
    .text(function(d) { return d; });

假設body最初是空的，上面的程式碼將建立六個新的div元素，將它們按順序追加到body，並指定其文字內容為相應的（強制轉為字串）號碼：

<div>4</div>
<div>8</div>
<div>15</div>
<div>16</div>
<div>23</div>
<div>42</div>

另一種方式考慮進入的佔位符的節點是，它們是指向父節點（在該示例中，就是文件的body）；然而，他們只支援追加和插入。 當你追加或插入時輸入選擇併入到更新選擇。而不是對enter和update選擇單獨採用同樣的操作符，現在你可以一次新增節點後，將其應用到更新選擇。如果你發現自己移除整個選擇的元素才重新插入其中大部分，用這個來替代。例如：

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 */

# selection.exit()

返回退出（exit）選擇：找出在當前選擇存在的DOM元素中沒有新的資料元素時。此方法只被定義在data運算子返回的更新選擇。exit選擇定義了所有的正常操作符，但通常你主要使用的是remove；其他操作符存在的主要目的是讓您可以根據需要定義一個退出的過渡。請注意，exit操作符只是返回一個exit選擇引用，由你來刪除新節點。 一個簡單的例子，考慮更新在上面的例子中的enter操作符建立的六個DIV元素。在這裡，我們把這些元素和一個含有一些新的，一些舊資料的新陣列繫結：

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]：

div.enter().append("div")
    .text(function(d) { return d; });

同樣，我們可以刪除退出的元素[15, 23, 42]： div.exit().remove();

現在，文件body如下：
<div>4</div>
<div>8</div>
<div>16</div>
<div>1</div>
<div>2</div>
<div>32</div>

注意，DOM元素現在是亂序。然而，選擇索引i（操作函式的第二個引數），將正確地與新資料陣列相匹配。例如，我們可以指定一個索引屬性：

d3.selectAll("div").attr("index", function(d, i) { return i; });

結果是：

<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或者order。

# selection.filter(selector)

過濾選擇，返回一個新的選擇只包含其指定的selector是true的元素。selector可以被指定為一個函式或作為選擇的字串，如“.foo”。和其他操作符一樣，該函式被傳遞當前資料d和索引i，以及this上下文作為當前的DOM元素。過濾器應該只在選擇與DOM元素繫結的時候。例如：從append或insert。只繫結的元素和資料的一個子集，可以在data引數中呼叫內建的陣列過濾器filter。像內建函式一樣，D3的過濾器不會在返回選擇中保留原來的選擇的索引；返回移除元素的副本。如果您想保留的索引，使用select代替。 例如，要選擇奇數索引（相對於從零開始的索引）的每一個元素：

var odds = selection.select(function(d, i) { return i & 1 ? this : null; });

等價地，使用的過濾器函式：

var odds = selection.filter(function(d, i) { return i & 1; });

或過濾選擇器（注意：nth-child偽類是一開始的索引，而不是從零開始的索引）：

var odds = selection.filter(":nth-child(even)");

因此，您可以使用選擇或過濾器操作符應用到元素的一個子集上。

# selection.datum([value])

獲取或設定每個選定的元素繫結的資料。不像selection.data方法，這種方法不計算一個連線（並因此不計算enter和exit的選擇）。此方法在selection.property之上實現：