D3选择v4(1、selection)中文

时间 2019-11-07

标签 d3 选择 v4 selection 中文繁體版

原文原文链接

选择容许对文档对象模型（DOM）进行强大的数据驱动转换：设置属性，样式，属性，HTML或文本内容等。使用数据链接的进入和退出选择，您还能够添加或删除与数据对应的元素。javascript

选择方法一般返回当前选择或新选择，容许经过方法链对给定选择上的多个操做进行简洁应用。例如，要设置当前文档中全部段落元素的类和颜色样式：html

d3.selectAll("p") .attr("class", "graf") .style("color", "red");html5

这至关于：java

var p = d3.selectAll("p"); p.attr("class", "graf"); p.style("color", "red");

按照惯例，返回当前选择的选择方法使用四个缩进空间，而返回新选择的方法仅使用两个。这有助于经过使它们脱离链条来揭示上下文的变化：

d3.select("body") .append("svg") .attr("width", 960) .attr("height", 500) .append("g") .attr("transform", "translate(20,20)") .append("rect") .attr("width", 920) .attr("height", 460);
选择是不可变的。影响选择哪些元素（或其顺序）的全部选择方法都返回新选择而不是修改当前选择。但请注意，元素必然是可变的，由于选择驱动文档的转换！

安装

若是您使用NPM， npm install d3-selection。不然，请下载最新版本。您也能够直接从d3js.org加载，做为独立库或做为D3 4.0的一部分。支持AMD，CommonJS和vanilla环境。在vanilla中，d3全球出口：node

<script src="https://d3js.org/d3-selection.v1.min.js"></script> <script>  var div = d3.selectAll("div");  </script>

在浏览器中尝试d3选择。

API参考

选择元素

选择方法接受W3C选择器字符串，例如.fancy选择具备类花哨的元素，或div选择DIV元素。选择方法有两种形式：select和selectAll：前者只选择第一个匹配元素，然后者按文档顺序选择全部匹配元素。顶级选择方法d3.select和d3.selectAll查询整个文档; 部分选取方法，selection.select和 selection.selectAll，限制选择到所选择的元素的后代。git

# d3.selection() <>
选择根元素。此函数还可用于测试选择（）或扩展选择原型。例如，要添加检查复选框的方法：
document.documentElementinstanceof d3.selection

d3.selection.prototype.checked = function(value) { return arguments.length < 1 ? this.property("checked") : this.property("checked", !!value); };

而后使用：

d3.selectAll("input[type=checkbox]").checked(true);

# d3.select(selector) <>

选择与指定选择器字符串匹配的第一个元素。若是没有元素与选择器匹配，则返回空选择。若是多个元素与选择器匹配，则仅选择第一个匹配元素（按文档顺序）。例如，要选择第一个锚元素：
var anchor = d3.select("a");
若是选择器不是字符串，则选择指定的节点; 若是您已经拥有对节点的引用，例如在事件侦听器或全局范围内，则此选项很是有用。例如，要将单击的段落设置为红色：
thisdocument.body

d3.selectAll("p").on("click", function() { d3.select(this).style("color", "red"); });

# d3.selectAll(selector) <>es6

选择与指定选择器字符串匹配的全部元素。将按文档顺序（从上到下）选择元素。若是文档中没有元素与选择器匹配，或者选择器为null或未定义，则返回空选择。例如，要选择全部段落：github

var paragraph = d3.selectAll("p");
若是选择器不是字符串，而是选择指定的节点数组; 若是您已经拥有对节点的引用，例如在事件侦听器或全局范围内，那么这颇有用。节点能够替代地是诸如a 或的伪阵列。例如，要将全部连接着色为红色：
this.childNodesdocument.linksNodeListarguments

d3.selectAll(document.links).style("color", "red");

# selection.select(selector) <>
对于每一个选定的元素，选择与指定的选择器字符串匹配的第一个后代元素。若是没有元素与当前元素的指定选择器匹配，则当前索引处的元素在返回的选择中将为null。（若是选择器为null，则返回选择中的每一个元素都将为空，从而致使选择为空。）若是当前元素具备关联数据，则此数据将传播到相应的选定元素。若是多个元素与选择器匹配，则仅选择文档顺序中的第一个匹配元素。例如，要选择每一个段落中的第一个粗体元素：

var b = d3.selectAll("p").select("b");

若是选择器是一个函数，则按顺序计算每一个选定元素，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i ]）。它必须返回一个元素，若是没有匹配元素，则返回null。例如，要选择每一个段落的上一个兄弟：

var previous = d3.selectAll("p").select(function() { return this.previousElementSibling; });


与选择 .selectAll不一样，selection .select不会影响分组：它保留现有的组结构和索引，并将数据（若是有的话）传播给选定的子组。分组在数据链接中起着重要做用。有关此主题的更多信息，请参阅嵌套选择和如何选择。

# selection.selectAll(selector) <>

对于每一个选定的元素，选择与指定的选择器字符串匹配的后代元素。返回选择中的元素按此选择中的相应父节点分组。若是没有元素与当前元素的指定选择器匹配，或者选择器为null，则当前索引处的组将为空。所选元素不会今后选择中继承数据; 使用selection .data将数据传播给子节点。例如，要选择每一个段落中的粗体元素：

var b = d3.selectAll("p").selectAll("b");

若是选择器是一个函数，则按顺序计算每一个选定元素，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i ]）。它必须返回一个元素数组（或一个伪数组，如NodeList），若是没有匹配的元素，则返回空数组。例如，要选择每一个段落的上一个和下一个兄弟节点：

var sibling = d3.selectAll("p").selectAll(function() { return [ this.previousElementSibling, this.nextElementSibling ]; });

与选择 .select不一样，选择 .selectAll确实会影响分组：每一个选定的后代都按原始选择中的父元素分组。分组在数据链接中起着重要做用。有关此主题的更多信息，请参阅嵌套选择和如何选择。

# selection.filter(filter) <>

过滤选择，返回仅包含指定过滤器为true 的元素的新选择。该过滤器能够或者做为选择字符串或函数来指定。若是过滤器是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i ]）。
例如，要过滤选择的表行以仅包含偶数行：

var even = d3.selectAll("tr").filter(":nth-child(even)");
这大体至关于直接使用d3.selectAll，尽管索引可能不一样：

var even = d3.selectAll("tr:nth-child(even)");

一样，使用一个函数：

var even = d3.selectAll("tr").filter(function(d, i) { return i & 1; });

或使用selection.select：

var even = d3.selectAll("tr").select(function(d, i) { return i & 1 ? this : null; })

请注意，:nth-child伪类是基于一的索引而不是从零开始的索引。并且，上述滤波器功能的含义并不彻底相同:nth-child; 它们依赖于选择索引而不是DOM中前面的兄弟元素的数量。npm

返回的筛选选择会保留此选择的父项，但与array.filter,同样，它不会保留索引，由于某些元素可能会被删除; 若是须要，使用selection .select保留索引。api

# selection.merge(other) <>

返回将此选择与指定的其余选择合并的新选择。返回的选择与此选择具备相同数量的组和相同的父项。此选择中的任何缺乏（null）元素都将使用指定选择中的相应元素（若是存在（非空））填充。（若是其余选择包含其余组或父项，则会忽略它们。）

经过selection.join在内部使用此方法来合并绑定数据后的输入和更新选择。您也能够明确合并。例如：

var circle = svg.selectAll("circle").data(data) // UPDATE .style("fill", "blue"); circle.exit().remove(); // EXIT circle = circle.enter().append("circle") // ENTER .style("fill", "green") .merge(circle) // ENTER + UPDATE .style("stroke", "black");

有关更多信息，请参阅selection.data

可是，此方法不用于链接任意选择：若是此选择和指定的其余选择都在同一索引处具备（非空）元素，则在合并中返回此选择的元素，并忽略其余选择的元素。

# d3.matcher(selector) <>
给定指定的选择器，返回一个函数，若是element 匹配指定的选择器，则返回true 。此方法在选择 .filter内部使用。例如，这个：
this

var div = selection.filter("div");
至关于：

var div = selection.filter(d3.matcher("div"));

（虽然D3不是兼容层，但因为最近element.matches的标准化，此实现确实支持供应商前缀实现。）

# d3.selector(selector) <>

给定指定的选择器，返回一个函数，该函数返回与指定选择器匹配的元素的第一个后代。此方法在内部经过selection.select使用。例如，这个：
this

var div = selection.select("div");

至关于：

var div = selection.select(d3.selector("div"));

# d3.selectorAll(selector) <>

给定指定的选择器，返回一个函数，该函数返回this与指定选择器匹配的元素的全部后代。此方法在内部经过selection.selectAll使用。例如，这个：

var div = selection.selectAll("div");

至关于：

var div = selection.selectAll(d3.selectorAll("div"));

# d3.window(node) <>

返回指定节点的全部者窗口。若是node是节点，则返回全部者文档的默认视图; 若是node是文档，则返回其默认视图; 不然返回节点。


# d3.style(node, name) <>

返回具备指定节点的指定名称的style属性的值。若是节点具备指定名称的内联样式，则返回其值; 不然，返回计算的属性值。另请参见selection .style。

 修改元素
选择元素后，使用选择的转换方法来影响文档内容。例如，要设置锚元素的名称属性和颜色样式：

d3.select("a") .attr("name", "fred") .style("color", "red");

要试验选择，请访问d3js.org并打开浏览器的开发者控制台！（在Chrome中，使用⌥⌘J打开控制台。）选择元素，而后检查返回的选择以查看选择了哪些元素以及如何对它们进行分组。调用选择方法并查看页面内容如何更改。
# selection.attr(name[, value]) <>

若是指定了值，则将具备指定名称的属性设置为所选元素上的指定值，并返回此选择。若是值是常量，则全部元素都被赋予相同的属性值; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM element（nodes [ i ]）。而后使用函数的返回值来设置每一个元素的属性。空值将删除指定的属性。

若是未指定值，则返回选择中第一个（非null）元素的指定属性的当前值。仅当您知道选择包含一个元素时，这一般颇有用。

指定的名称能够具备名称空间前缀，例如在XLink名称空间中xlink:href指定href属性。见命名空间为支持的名字空间的地图; 能够经过添加到地图来注册其余名称空间。

# selection.classed(names[, value]) <>

若是指定了值，则经过设置属性或修改属性来指定或取消分配所选元素上的指定CSS类名，并返回此选择。指定的名称是一个空格分隔的类名称字符串。例如，要分配类和选定的元素：classclassListfoobar

selection.classed("foo bar", true);

若是该值是真实的，则为全部元素分配指定的类; 不然，这些类是未分配的。若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i ]）。而后，函数的返回值用于为每一个元素分配或取消分配类。例如，要将类foo随机地与所选元素的一半相关联：

selection.classed("foo", function() { return Math.random() > 0.5; });


若是未指定值，则当且仅当第一个（非null）所选元素具备指定的类时，才返回true 。仅当您知道选择包含一个元素时，这一般颇有用。

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

若是指定了值，则将具备指定名称的style属性设置为所选元素上的指定值，并返回此选择。若是值是常量，则全部元素都被赋予相同的样式属性值; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i]）。而后使用函数的返回值来设置每一个元素的样式属性。null值将删除style属性。还能够指定可选优先级，能够是null或字符串important（不带感叹号）。

若是未指定值，则返回选择中第一个（非null）元素的指定样式属性的当前值。当前值定义为元素的内联值（若是存在），不然定义为其计算值。仅当您知道选择包含一个元素时，才能访问当前样式值。

警告：与许多SVG属性不一样，CSS样式一般具备关联的单元。例如，3px是有效的笔画宽度属性值，而3不是。有些浏览器隐式地将px（像素）单元分配给数值，但并不是全部浏览器都这样作：例如，IE会抛出“无效参数”错误！

# selection.property(name[, value]) <>

某些HTML元素具备使用属性或样式没法寻址的特殊属性，例如表单字段的文本value和复选框的checked布尔值。使用此方法获取或设置这些属性。

若是指定了值，则将具备指定名称的属性设置为所选元素上的指定值。若是该值是常量，则全部元素都被赋予相同的属性值; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM element（nodes [ i ]）。而后使用函数的返回值来设置每一个元素的属性。空值将删除指定的属性。

若是未指定值，则返回选择中第一个（非null）元素的指定属性的值。仅当您知道选择包含一个元素时，这一般颇有用。


# selection.text([value]) <>

若是指定了值，则将文本内容设置为全部选定元素上的指定值，替换任何现有子元素。若是值是常量，则全部元素都被赋予相同的文本内容; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM element（nodes [ i ]）。而后使用函数的返回值来设置每一个元素的文本内容。空值将清除内容。

若是未指定值，则返回选择中第一个（非null）元素的文本内容。仅当您知道选择包含一个元素时，这一般颇有用。

# selection.html([value]) <>

若是指定了值，则将内部HTML设置为全部选定元素上的指定值，替换任何现有子元素。若是值是常量，那么全部元素都被赋予相同的内部HTML; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM element（nodes [ i ]）。而后使用函数的返回值来设置每一个元素的内部HTML。空值将清除内容。

若是未指定值，则返回选择中第一个（非null）元素的内部HTML。仅当您知道选择包含一个元素时，这一般颇有用。

使用 selection.append或 selection.insert来建立数据驱动的内容; 此方法适用于须要一点HTML的状况，例如丰富的格式。此外，仅在HTML元素上支持选择 .html。SVG元素和其余非HTML元素不支持innerHTML属性，所以与选择 .html 不兼容。考虑使用XMLSerializer将DOM子树转换为文本。另请参阅innersvg polyfill，它提供了一个shim来支持SVG元素的innerHTML属性。

# selection.append(type) <>

若是指定的类型是字符串，则将此类型的新元素（标记名称）做为每一个所选元素的最后一个子元素添加，或者在更新选择中的下一个兄弟元素以前添加（若是这是输入选择）。输入选择的后一种行为容许您按照与新绑定数据一致的顺序将元素插入DOM; 但请注意，若是更新元素更改顺序（即，若是新数据的顺序与旧数据不一致），则仍可能须要选择 .order。

若是指定的类型是一个函数，则按顺序为每一个选定元素计算它，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（nodes [ i ]）。此函数应返回要追加的元素。（该函数一般会建立一个新元素，但它可能会返回一个现有元素。）例如，要将DIV元素附加到每一个段落：

d3.selectAll("p").append("div");
这至关于：
d3.selectAll("p").append(function() { return document.createElement("div"); });
这至关于：

d3.selectAll("p").select(function() { return this.appendChild(document.createElement("div")); });

在这两种状况下，此方法都返回包含附加元素的新选择。每一个新元素都以与selection .select相同的方式继承当前元素的数据（若是有）。

指定的名称能够具备名称空间前缀，例如在SVG名称空间中svg:text指定text属性。见命名空间为支持的名字空间的地图; 能够经过添加到地图来注册其余名称空间。若是未指定名称空间，则名称空间将从父元素继承; 或者，若是名称是已知前缀之一，则将使用相应的命名空间（例如，svg暗示svg:svg）。

# selection.insert(type[, before]) <>

若是指定的类型是字符串，则在匹配指定的before选择器的第一个元素以前，为每一个选定元素插入此类型的新元素（标记名称）。例如，before选择器:first-child将在第一个子节点以前添加节点。若是未指定before，则默认为null。（要按照与绑定数据一致的顺序追加元素，请使用selection .append。）

两个类型和以前能够替代地指定为其中为每一个选择的元件进行评价，为了功能，正在传递的当前数据（d），当前指数（我），和当前组（节点），与此做为当前DOM元素（nodes [ i ]）。的类型函数应该返回要插入的元件; 在以前函数返回的元素应该被插入以后的子元素。例如，要将DIV元素附加到每一个段落

d3.selectAll("p").insert("div");

这至关于：

d3.selectAll("p").insert(function() { return document.createElement("div"); });

这至关于：

d3.selectAll("p").select(function() { return this.insertBefore(document.createElement("div"), null); });

在这两种状况下，此方法都返回包含附加元素的新选择。每一个新元素都以与selection .select相同的方式继承当前元素的数据（若是有）。

# selection.remove() <>

从文档中删除选定的元素。返回此选择（已删除的元素），这些选择如今与DOM分离。目前没有专门的API将已删除的元素添加回文档; 可是，您能够将函数传递给selection.append或selection.insert以从新添加元素。
# selection.clone([deep]) <>
在所选元素后面紧跟插入所选元素的克隆，并返回新添加克隆的选择。若是深度是真实的，那么所选元素的后代节点也将被克隆。不然，只会克隆元素自己。至关于：

selection.select(function() { return this.parentNode.insertBefore(this.cloneNode(deep), this.nextSibling); });
# selection.sort(compare) <>

返回一个新选择，其中包含根据compare函数排序的此选择中每一个组的副本。排序后，从新插入元件，以（每所得顺序相匹配 selection.order）。

比较函数默认为升序，传递两个元素的数据a和b进行比较。它应返回负值，正值或零值。若是是否认的，那么a应该在b以前; 若是是确定的，那么a应该在b以后; 不然，a和b被认为是相等的，而且顺序是任意的。

请注意，排序不保证稳定; 可是，它保证与您的浏览器在数组上的内置排序方法具备相同的行为。

# selection.order() <>

将元素从新插入到文档中，以使每一个组的文档顺序与选择顺序匹配。这至关于调用 selection.sort若是数据已经排序，但速度要快得多。
# selection.raise() <>
按顺序从新插入每一个选定元素做为其父元素的最后一个子元素。至关于：

selection.each(function() { this.parentNode.appendChild(this); });

# selection.lower() <>
按顺序从新插入每一个选定元素做为其父元素的第一个子元素。至关于：

selection.each(function() { this.parentNode.insertBefore(this, this.parentNode.firstChild); });

# d3.create(name) <>
给定指定的元素名称，返回包含当前文档中给定名称的分离元素的单元素选择。
# d3.creator(name) <>
给定指定的元素名称，返回一个建立给定名称元素的函数，假设它是父元素。经过选择selection.append和选择selection.insert在内部使用此方法来建立新元素。例如，这个：
this

selection.append("div");
至关于：
selection.append(d3.creator("div"));
有关支持的名称空间前缀的详细信息，请参阅名称空间，例如SVG元素。

加入数据

有关D3数据链接的介绍，请参阅Thinking with Joins。另请参阅常规更新模式示例。

# selection.data([data[, key]]) <>

使用所选元素绑定指定的数据数组，返回表示更新选择的新选择：成功绑定到数据的元素。还定义了返回选择的输入和退出选择，可用于添加或删除与新数据对应的元素。指定的数据是任意值的数组（例如，数字或对象），或返回每一个组的值数组的函数。将数据分配给元素时，它将存储在属性中__data__，从而使数据“粘滞”并在从新选择时可用。

该数据被指定为每一个组中选择。若是选择有多个组（例如d3.selectAll后跟selection.selectAll），则一般应将数据指定为函数。将按顺序为每一个组评估此函数，传递组的父数据（d，多是未定义的），组索引（i）和选择的父节点（节点），并将其做为组的父元素。

结合selection.join（或更明确地 selection.enter, selection.exit, selection.append 和selection.remove），选择 .data可用于输入，更新和退出元素以匹配数据。例如，要从数字矩阵建立HTML表：

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) .join("tr"); var td = tr.selectAll("td") .data(function(d) { return d; }) .join("td") .text(function(d) { return d; });

在此示例中，数据函数是标识函数：对于每一个表行，它返回数据矩阵中的相应行。

若是一个键未指定功能，则在第一数据的数据被分配给第一选择的元素，第二数据至该第二选择的元素，依此类推。甲关键功能能够被指定为控制哪些数据被分配给哪一个元素，替换默认加入逐索引，经过计算每一个数据和元件的串标识符。为每一个选定的元素评估此关键函数，按顺序传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点 [ i]]）; 返回的字符串是元素的键。键功能，而后还评价了在每个新的基准数据，正在传递的当前数据（d），当前指数（我），以及该组的新数据，与此做为组的父DOM元素; 返回的字符串是数据的键。给定键的数据被分配给具备匹配键的元素。若是多个元素具备相同的键，则将重复的元素放入出口选择中; 若是多个数据具备相同的密钥，则将重复数据放入输入选择中。

例如，鉴于此文件：

<div id="Ford"></div> <div id="Jarrah"></div> <div id="Kwon"></div> <div id="Locke"></div> <div id="Reyes"></div> <div id="Shephard"></div>

您能够按键加入数据，以下所示：

var data = [ {name: "Locke", number: 4}, {name: "Reyes", number: 8}, {name: "Ford", number: 15}, {name: "Jarrah", number: 16}, {name: "Shephard", number: 23}, {name: "Kwon", number: 42} ]; d3.selectAll("div") .data(data, function(d) { return d ? d.name : this.id; }) .text(function(d) { return d.number; });

此示例键函数使用数据d（若是存在），不然返回到元素的id属性。因为这些元素先前未绑定到数据，所以在对所选元素计算关键函数时，数据d为空，而在对新数据计算关键函数时，数据为非空。

该更新和输入选择在数据顺序返回，而退出选择保留以前加入选择顺序。若是指定了键功能，则选择中元素的顺序可能与文档中的顺序不匹配; 根据须要使用selection .order或selection .sort。有关键函数如何影响链接的更多信息，请参阅条形图，第2部分和对象常量。

若是未指定数据，则此方法返回所选元素的数据数组。

此方法不能用于清除绑定数据; 使用 selection.datum代替。

# selection.join(enter[, update][, exit]) <>
根据须要追加，删除和从新排序元素，以匹配先前由

selection.data绑定的数据，返回合并的输入和更新选择。此方法是更明确selection.enter，selection.exit，selection.append和selection.remove）的替代方法。例如：

svg.selectAll("circle") .data(data) .join( enter => enter.append("circle").attr("fill", "green"), update => update.attr("fill", "blue") ) .attr("stroke", "black");

有关更多示例，请参阅 selection.join Observable笔记本。

这至关于通常更新模式：

var circle = svg.selectAll("circle") // 1 .data(data) // 2 .attr("fill", "blue"); // 3 circle.exit().remove(); // 4 circle = circle.enter().append("circle") // 5, 9 .attr("fill", "green") // 6 .merge(circle) // 7 .order() // 8 .attr("stroke", "black"); // 9

将其分解为不连续的步骤：

任何现有的圆（属于的后代svg选择）的选择。
这些圈子链接到新的data，返回匹配的圈子：更新选择。
这些更新圈子被给予蓝色填充。
将删除与新数据不匹配的任何现有圆圈- 退出选择。
对于与任何现有圆圈不匹配的任何新数据，将附加新圆圈：输入选择。
这些进入的圆圈被赋予绿色填充。
建立表示输入和更新圆的并集的新选择。
这些输入和更新圈子被从新排序以匹配数据（若是须要）。
圆圈呈黑色划线。
圆圈存储在变量中circle。

如前面段落所述，“匹配”逻辑由传递给选择 .data 的键函数肯定; 因为在上面的代码示例中没有使用键函数，所以元素和数据经过索引链接。

# selection.enter() <>

返回输入选择：占位符节点，用于选择中没有相应DOM元素的每一个数据。（对于 selection.data未返回的选择，输入选择为空。）

输入选择一般用于建立与新数据相对应的“缺失”元素。例如，要从数字数组建立DIV元素：

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

若是正文最初为空，则上面的代码将建立六个新的DIV元素，按顺序将它们附加到正文，并将其文本内容指定为关联的（字符串强制）数字：

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

从概念上讲，输入选择的占位符是指向父元素的指针（在本例中为文档主体）。输入选择一般仅暂时用于附加元素，而且一般在附加后与更新选择合并，使得修改能够应用于输入和更新元素。
# selection.exit() <>

返回退出选择：选择中没有找到新数据的现有DOM元素。（对于 selection.data未返回的选择，退出选择为空。）

退出选择一般用于删除与旧数据相对应的“多余”元素。例如，要使用新的数字数组更新先前建立的DIV元素：

div = div.data([1, 2, 4, 8, 16, 32], function(d) { return d; });

因为指定了键函数（做为标识函数），而且新数据包含与文档中现有元素匹配的数字[4,8,16]，所以更新选择包含三个DIV元素。将这些元素保留为原样，咱们可使用输入选择为[1,2,32]添加新元素：

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

一样，要删除现有元素[15,23,42]：

div.exit().remove();
如今文档正文以下所示：
<div>1</div> 
<div>2</div> 
<div>4</div> 
<div>8</div> 
<div>16</div> 
<div>32</div>
DOM元素的顺序与数据的顺序匹配，由于旧数据的顺序和新数据的顺序是一致的。若是新数据的顺序不一样，请使用selection.order从新排序DOM中的元素。有关数据链接的更多信息，请参阅常规更新模式示例线程。
# selection.datum([value]) <>

获取或设置每一个选定元素的绑定数据。与 selection.data不一样，此方法不计算链接，也不影响索引或输入和退出选择。

若是指定了值，则将元素的绑定数据设置为全部选定元素上的指定值。若是该值是常量，则全部元素都被赋予相同的数据; 不然，若是值是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM element（nodes [ i ]）。而后，该函数用于设置每一个元素的新数据。空值将删除绑定数据。

若是未指定值，则返回选择中第一个（非null）元素的bound数据。仅当您知道选择包含一个元素时，这一般颇有用。

此方法对于访问HTML5 自定义数据属性颇有用。例如，给出如下要素：

<ul id="list"> <li data-username="shawnbot">Shawn Allen</li> <li data-username="mbostock">Mike Bostock</li> </ul>

您能够经过将每一个元素的数据设置为内置数据集属性来公开自定义数据属性：

selection.datum(function() { return this.dataset; })

处理事件

对于交互，选择容许监听和分派事件。
# selection.on(typenames[, listener[, options]]) <>

为指定的事件类型名称的每一个选定元素添加或删除侦听器。所述typenames是一个字符串事件类型，如，，或; 可使用浏览器支持的任何DOM事件类型。类型能够可选地后跟句点（）和名称; 可选名称容许注册多个回调以接收相同类型的事件，例如和。要指定多个类型名称，请使用空格分隔类型名称，例如或。clickmouseoversubmit.click.fooclick.barinput changeclick.foo click.bar

当在所选元素上调度指定事件时，将为元素评估指定的侦听器，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前值DOM元素（nodes [ i ]）。监听器老是看到其元素的最新数据，但索引是选择的属性，而且在分配监听器时是固定的; 更新索引，从新分配监听器。要在侦听器中访问当前事件，请使用d3.event。

若是事件侦听器先前已在所选元素上注册了相同的类型名称，则在添加新侦听器以前将删除旧侦听器。要删除侦听器，请将null做为侦听器传递。要删除给定名称的全部侦听器，请将null做为侦听器并.foo做为typename传递，其中foo名称为; 删除全部没有名称的侦听器，指定.为typename。

可选的选项对象能够指定有关事件侦听器的特征，例如它是捕获仍是被动; 请参阅 element.addEventListener。

若是收听者未指定，返回指定事件的当前分配的侦听类型名称的第一个（非空）选择的元素上，若是有的话。若是指定了多个类型名，则返回第一个匹配的侦听器。

# selection.dispatch(type[, parameters]) <>

按顺序将指定类型的自定义事件调度到每一个选定元素。能够指定可选参数映射以设置事件的其余属性。它可能包含如下字段：

bubbles - 若是为true，则以反向树顺序将事件分派给祖先。
cancelable- 若是为true，则容许事件 .preventDefault。
detail - 与事件相关的任何自定义数据。

若是参数是一个函数，则按顺序计算每一个选定元素的值，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（节点） [ i ]）。它必须返回当前元素的参数映射。

# d3.event

当前event，若是有的话。这是在调用事件侦听器期间设置的，并在侦听器终止后重置。使用此访问标准活动领域，如event.timeStamp以及诸如方法event .preventDefault。虽然您可使用本机event .pageX和event .pageY，但使用d3.mouse，d3.touch或d3.touches将事件位置转换为接收事件的容器的本地坐标系一般更方便。

若是您使用Babel，Webpack或其余ES6到ES5捆绑器，请注意d3.event的值在事件期间会发生变化！导入d3.event必须是实时绑定，所以您可能须要将捆绑程序配置为从D3的ES6模块而不是从生成的UMD包导入; 并不是全部捆绑商都观察到jsnext：main。还要注意与 window.event全局的冲突。

# d3.customEvent(event, listener[, that[, arguments]]) <>
调用指定监听器，使用指定的这 方面并经过指定的参数，若是有的话。在调用期间，d3.event设置为指定的事件 ; 在侦听器返回（或抛出错误）以后，d3.event将恢复为其先前的值。此外，将事件 .sourceEvent 设置为d3.event的先前值，容许自定义事件保留对原始本机事件的引用。返回侦听器返回的值。
# d3.mouse(container) <>
返回当前事件相对于指定容器的x和y坐标。容器能够是HTML或SVG容器元素，例如G元素或SVG元素。坐标以数字[ x，y ] 的双元素数组的形式返回。
# d3.touch(container[, touches], identifier) <>
返回触摸的x和y坐标，其中指定的标识符与当前事件相关的指定标识符相对于指定的容器。容器能够是HTML或SVG容器元素，例如G元素或SVG元素。坐标以数字[ x，y ] 的双元素数组的形式返回。若是存在与指定的标识符没有触摸触摸，则返回null; 这对于忽略只有一些触摸移动的touchmove事件很是有用。若是未指定touches，则默认为当前事件changedTouches属性。
# d3.touches(container[, touches]) <>
返回与当前事件关联的触摸相对于指定容器的x和y坐标。容器能够是HTML或SVG容器元素，例如G元素或SVG元素。坐标以数组[[ x1，y1 ]，[ x2，y2 ]，...] 的双元素数组的数组的形式返回。若是未指定touches，则默认为当前事件的touches属性。
# d3.clientPoint(container, event) <>
返回指定事件相对于指定容器的x和y坐标。（事件也能够是触摸。）容器能够是HTML或SVG容器元素，例如G元素或SVG元素。坐标以数字[ x，y ] 的双元素数组的形式返回。

this

控制流

对于高级用法，选择提供自定义控制流的方法。
# selection.each(function) <>
按顺序为每一个选定元素调用指定函数，传递当前数据（d），当前索引（i）和当前组（节点），并将其做为当前DOM元素（nodes [ i ]）。此方法可用于为每一个选定元素调用任意代码，对于建立同时访问父数据和子数据的上下文很是有用，例如：

parent.each(function(p, j) { d3.select(this) .selectAll(".child") .text(function(d, i) { return "child " + d.name + " of " + p.name; }); });

有关示例，请参阅Sized Donut Multiples。
# selection.call(function[, arguments…]) <>
只调用指定的函数一次，传入此选择以及任何可选参数。返回此选择。这至关于手动调用函数，但有助于方法连接。例如，要在可重用函数中设置多个样式：

function name(selection, first, last) { selection .attr("first-name", first) .attr("last-name", last); }

如今说：

d3.selectAll("div").call(name, "John", "Snow");

这大体至关于：

name(d3.selectAll("div"), "John", "Snow");
惟一的区别是，选择 .CALL老是返回的选择，而不是所谓的返回值函数，。
name

# selection.empty() <>

若是此选择不包含（非null）元素，则返回true。

# selection.nodes() <>

返回此选择中全部（非null）元素的数组。

# selection.node() <>

返回此选择中的第一个（非null）元素。若是选择为空，则返回null。

# selection.size() <>

返回此选择中的元素总数。

局部变量

D3 locals容许您定义独立于数据的本地状态。例如，在渲染小倍数的时间序列数据时，您可能但愿全部图表使用相同的x-scale，但须要使用不一样的y -scales来比较每一个度量标准的相对性能。D3 locals由DOM元素肯定范围：在set上，值存储在给定元素上; 在get上，从给定元素或定义它的最近祖先检索该值。
# d3.local() <>
声明一个新的局部变量。例如：

var foo = d3.local();
好比，每一个地方都是一个独特的象征性参考; 不一样的是，每一个局部的值也由DOM肯定范围。
# local.set(node, value) <>
设置此本地指定的值节点的值，并返回指定的值。这一般使用selection.each执行：
selection.each(function(d) { foo.set(this, d.value); });varvar

若是您只是设置单个变量，请考虑使用selection .property：

selection.property(foo, function(d) { return d.value; });

# local.get(node) <>
返回指定节点上此local的值。若是节点未定义此local，则返回定义它的最近祖先的值。若是没有祖先定义此本地，则返回undefined。
# local.remove(node) <>
从指定节点删除此本地值。若是节点在删除以前定义了此本地，则返回true，不然返回false。若是祖先也定义了这个本地，那么这些定义不受影响，所以local.get仍然会返回继承的值。
# local.toString() <>
返回此本地的自动生成的标识符。这是用于在元素上存储本地值的属性的名称，所以您还可使用元素 [ local ]或使用selection .property来设置或获取本地值。

命名空间

XML命名空间颇有趣！对？幸运的是，你能够忽略它们。

# d3.namespace(name) <>

限定指定的名称，该名称可能有也可能没有名称空间前缀。若是名称包含冒号（:），则冒号前的子字符串将被解释为名称空间前缀，该前缀必须在d3.namespaces中注册。返回描述完整命名空间URL和本地名称的对象space和local属性。例如：

d3.namespace("svg:text"); // {space: "http://www.w3.org/2000/svg", local: "text"}

若是名称不包含冒号，则此函数仅返回输入名称。
# d3.namespaces <>
已注册名称空间前缀的映射。初始值是：

{
  svg: "http://www.w3.org/2000/svg", xhtml: "http://www.w3.org/1999/xhtml", xlink: "http://www.w3.org/1999/xlink", xml: "http://www.w3.org/XML/1998/namespace", xmlns: "http://www.w3.org/2000/xmlns/" }

能够根据须要分配附加前缀以在其余命名空间中建立元素或属性。