D3

修改元素 ​

¥Modifying elements

选择元素后，使用选择来修改元素。例如，设置类和颜色样式当前文档中所有段落元素的顺序：

¥After selecting elements, use the selection to modify the elements. For example, to set the class and color style of all paragraph elements in the current document:

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

选择方法通常返回当前选择或新的选择，从而允许通过方法链对给定选择简洁地应用多个操作。以上内容等同于：

¥Selection methods typically return the current selection, or a new selection, allowing the concise application of multiple operations on a given selection via method chaining. The above is equivalent to:

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

选择是不可变的。所有影响所选元素（或其顺序）的选择方法都会返回新的选择，而不是修改当前选择。但是，请注意，元素必然是可变的，因为选择会驱动文档的变换！

¥Selections are immutable. All selection methods that affect which elements are selected (or their order) return a new selection rather than modifying the current selection. However, note that elements are necessarily mutable, as selections drive transformations of the document!

selection.attr(name, value) {#selection_attr} ​

源代码 · 如果指定了值，则将选定元素上具有指定名称的属性设置为指定值，并返回此选择。

¥Source · If a value is specified, sets the attribute with the specified name to the specified value on the selected elements and returns this selection.

js
selection.attr("color", "red")

如果值是常量，则所有元素都将赋予相同的属性值；否则，如果该值是一个函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于设置每个元素的属性 (attribute)。空值将移除指定的属性。

¥If the value is a constant, all elements are given the same attribute value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s attribute. A null value will remove the specified attribute.

js
selection.attr("color") // "red"

如果未指定值，则返回选择项中第一个（非空）元素的指定属性的当前值。这通常仅在你知道选择内容仅包含一个元素时才有用。

¥If a value is not specified, returns the current value of the specified attribute for the first (non-null) element in the selection. This is generally useful only if you know that the selection contains exactly one element.

指定的名称可以包含命名空间前缀，例如 xlink:href 表示在 XLink 命名空间中指定 href 属性。有关受支持的命名空间的映射，请参阅 namespaces；可以通过添加到地图来注册额外的命名空间。

¥The specified name may have a namespace prefix, such as xlink:href to specify the href attribute in the XLink namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map.

selection.classed(names, value) {#selection_classed} ​

源代码 · 如果指定了值，则通过设置 class 属性或修改 classList 属性，为所选元素分配或取消分配指定的 CSS 类名，并返回此选择。

¥Source · If a value is specified, assigns or unassigns the specified CSS class names on the selected elements by setting the class attribute or modifying the classList property and returns this selection.

js
selection.classed("foo", true)

指定的名称是一个以空格分隔的类名字符串。例如，要将类 foo 和 bar 分配给选定元素：

¥The specified names is a string of space-separated class names. For example, to assign the classes foo and bar to the selected elements:

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

如果值为真，则所有元素均会被分配指定的类；否则，未分配类。

¥If the value is truthy, then all elements are assigned the specified classes; otherwise, the classes are unassigned.

js
selection.classed("foo", () => Math.random() > 0.5)

如果值为函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于为每个元素分配或取消分配类。

¥If the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to assign or unassign classes on each element.

js
selection.classed("foo") // true, perhaps

如果未指定值，则当且仅当第一个选定（非空）元素具有指定的类时才返回 true。这通常仅在你知道选择内容仅包含一个元素时才有用。

¥If a value is not specified, returns true if and only if the first (non-null) selected element has the specified classes. This is generally useful only if you know the selection contains exactly one element.

selection.style(name, value, priority) {#selection_style} ​

源代码 · 如果指定了值，则将选定元素上具有指定名称的样式属性设置为指定值，并返回此选择。

¥Source · If a value is specified, sets the style property with the specified name to the specified value on the selected elements and returns this selection.

js
selection.style("color", "red")

如果值为常量，则所有元素均会被赋予相同的 style 属性值；否则，如果该值是一个函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于设置每个元素的样式 (style) 属性。空值将移除样式属性。还可以指定一个可选的优先级，可以是 null 或字符串 important（不带感叹号）。

¥If the value is a constant, then all elements are given the same style property value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s style property. A null value will remove the style property. An optional priority may also be specified, either as null or the string important (without the exclamation point).

js
selection.style("color") // "red"

如果未指定值，则返回选择项中第一个（非空）元素的指定样式属性的当前值。当前值定义为元素的内联值（如果存在），否则定义为其 计算值。通常，只有当你知道选择内容恰好包含一个元素时，访问当前样式值才有用。

¥If a value is not specified, returns the current value of the specified style property for the first (non-null) element in the selection. The current value is defined as the element’s inline value, if present, and otherwise its computed value. Accessing the current style value is generally useful only if you know the selection contains exactly one element.

CAUTION

Unlike many SVG attributes, CSS styles typically have associated units.例如，3px 是有效的 stroke-width 属性值，而 3 则不是。某些浏览器会隐式地将 px（像素）单位分配给数值，但并非所有浏览器都这样做：例如，IE 会抛出“无效参数”错误！

¥Unlike many SVG attributes, CSS styles typically have associated units. For example, 3px is a valid stroke-width property value, while 3 is not. Some browsers implicitly assign the px (pixel) unit to numeric values, but not all browsers do: IE, for example, throws an “invalid arguments” error!

selection.property(name, value) {#selection_property} ​

源代码 · 某些 HTML 元素具有无法使用属性或样式寻址的特殊属性，例如表单字段的文本 value 和复选框的布尔值 checked。Use this method to get or set these properties.

¥Source · Some HTML elements have special properties that are not addressable using attributes or styles, such as a form field’s text value and a checkbox’s checked boolean. Use this method to get or set these properties.

js
selection.property("checked", true)

如果指定了值，则在选定元素上将具有指定名称的属性设置为指定值。如果值为常量，则所有元素均会被赋予相同的属性值；否则，如果该值是一个函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于设置每个元素的属性 (property)。空值将删除指定的属性。

¥If a value is specified, sets the property with the specified name to the specified value on selected elements. If the value is a constant, then all elements are given the same property value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s property. A null value will delete the specified property.

js
selection.property("checked") // true, perhaps

如果未指定值，则返回选择集中第一个（非空）元素的指定属性值。这通常仅在你知道选择内容仅包含一个元素时才有用。

¥If a value is not specified, returns the value of the specified property for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

selection.text(value) {#selection_text} ​

源代码 · 如果指定了值，则将所有选定元素的 文本内容 设置为指定值，并替换所有现有子元素。

¥Source · If a value is specified, sets the text content to the specified value on all selected elements, replacing any existing child elements.

js
selection.text("Hello, world!")

如果值为常量，则所有元素均会被赋予相同的文本内容；否则，如果该值是一个函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于设置每个元素的文本内容。空值将清除内容。

¥If the value is a constant, then all elements are given the same text content; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s text content. A null value will clear the content.

js
selection.text() // "Hello, world!"

如果未指定值，则返回选择集中第一个（非空）元素的文本内容。这通常仅在你知道选择内容仅包含一个元素时才有用。

¥If a value is not specified, returns the text content for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

selection.html(value) {#selection_html} ​

源代码 · 如果指定了值，则将所有选定元素的 内部 HTML 设置为指定值，并替换所有现有子元素。

¥Source · If a value is specified, sets the inner HTML to the specified value on all selected elements, replacing any existing child elements.

js
selection.html("Hello, <i>world</i>!")

如果值为常量，则所有元素均会被赋予相同的内部 HTML；否则，如果该值是一个函数，则按顺序为每个选定元素求值，并传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。该函数的返回值随后会用于设置每个元素的内部 HTML。空值将清除内容。

¥If the value is a constant, then all elements are given the same inner HTML; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s inner HTML. A null value will clear the content.

js
selection.html() // "Hello, <i>world</i>!"

如果未指定值，则返回选择集中第一个（非空）元素的内部 HTML。这通常仅在你知道选择内容仅包含一个元素时才有用。

¥If a value is not specified, returns the inner HTML for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

Use selection.append or selection.insert instead to create data-driven content;此方法适用于需要少量 HTML 内容的情况，例如用于丰富的格式。此外，selection.html 仅支持 HTML 元素。SVG 元素和其他非 HTML 元素不支持 innerHTML 属性，因此与 selection.html 不兼容。考虑使用 XMLSerializer 将 DOM 子树转换为文本。另请参阅 innersvg polyfill，它提供了一个垫片来支持 SVG 元素上的 innerHTML 属性。

¥Use selection.append or selection.insert instead to create data-driven content; this method is intended for when you want a little bit of HTML, say for rich formatting. Also, selection.html is only supported on HTML elements. SVG elements and other non-HTML elements do not support the innerHTML property, and thus are incompatible with selection.html. Consider using XMLSerializer to convert a DOM subtree to text. See also the innersvg polyfill, which provides a shim to support the innerHTML property on SVG elements.

selection.append(type) {#selection_append} ​

源代码 · 如果指定的类型是字符串，则将此类型的新元素（标签名称）作为每个选定元素的最后一个子元素附加；如果是 输入选择，则将此类型的新元素（标签名称）附加到更新选择中的下一个同级元素之前。后一种输入选择的行为允许你按照与新绑定数据一致的顺序将元素插入 DOM；然而，请注意，如果更新元素的顺序发生变化（即，如果新数据的顺序与旧数据的顺序不一致），可能仍然需要 selection.order。

¥Source · If the specified type is a string, appends a new element of this type (tag name) as the last child of each selected element, or before the next following sibling in the update selection if this is an enter selection. The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data; however, note that selection.order may still be required if updating elements change order (i.e., if the order of new data is inconsistent with old data).

如果指定的类型是函数，则按顺序为每个选定元素计算该过渡，传递当前数据 (d)、当前索引 (i) 和当前组 (nodes)，并将其作为当前 DOM 元素 (nodes[i])。此函数应返回要附加的元素。（该函数通常会创建一个新元素，但也可能返回一个现有元素。）例如，向每个 DIV 元素附加一个段落：

¥If the specified type is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) For example, to append a paragraph to each DIV element:

js
d3.selectAll("div").append("p");

这等同于：

¥This is equivalent to:

js
d3.selectAll("div").append(() => document.createElement("p"));

这等同于：

¥Which is equivalent to:

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

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

¥In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as selection.select.

指定的名称可以包含命名空间前缀，例如 svg:text 表示在 SVG 命名空间中指定 text 属性。有关受支持的命名空间的映射，请参阅 namespaces；可以通过添加到地图来注册额外的命名空间。如果未指定命名空间，则命名空间将从父元素继承；或者，如果名称是已知前缀之一，则将使用相应的命名空间（例如，svg 隐含 svg:svg）。

¥The specified name may have a namespace prefix, such as svg:text to specify a text attribute in the SVG namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, svg implies svg:svg).

selection.insert(type, before) {#selection_insert} ​

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

¥Source · If the specified type is a string, inserts a new element of this type (tag name) before the first element matching the specified before selector for each selected element. For example, a before selector :first-child will prepend nodes before the first child. If before is not specified, it defaults to null. (To append elements in an order consistent with bound data, use selection.append.)

type 和 before 都可以指定为函数，这些函数会按顺序为每个选定元素执行求值，并传递当前数据 (d)、当前索引 (i) 和当前组（nodes），并将 this 作为当前 DOM 元素 (nodes[i])。type 函数应返回要插入的元素；before 函数应返回元素应插入到其前的子元素。例如，向每个 DIV 元素附加一个段落：

¥Both type and before may instead be specified as functions which are evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The type function should return an element to be inserted; the before function should return the child element before which the element should be inserted. For example, to append a paragraph to each DIV element:

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

这等同于：

¥This is equivalent to:

js
d3.selectAll("div").insert(() => document.createElement("p"));

这等同于：

¥Which is equivalent to:

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

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

¥In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as selection.select.

指定的名称可以包含命名空间前缀，例如 svg:text 表示在 SVG 命名空间中指定 text 属性。有关受支持的命名空间的映射，请参阅 namespaces；可以通过添加到地图来注册额外的命名空间。如果未指定命名空间，则命名空间将从父元素继承；或者，如果名称是已知前缀之一，则将使用相应的命名空间（例如，svg 隐含 svg:svg）。

¥The specified name may have a namespace prefix, such as svg:text to specify a text attribute in the SVG namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, svg implies svg:svg).

selection.remove() {#selection_remove} ​

源代码 · 从文档中移除选定的元素。返回此选择集（已移除的元素），这些元素现已从 DOM 中分离。目前没有专门的 API 可以将已移除的元素添加回文档；但是，你可以将函数传递给 selection.append 或 selection.insert 来重新添加元素。

¥Source · Removes the selected elements from the document. Returns this selection (the removed elements) which are now detached from the DOM. There is not currently a dedicated API to add removed elements back to the document; however, you can pass a function to selection.append or selection.insert to re-add elements.

selection.clone(deep) {#selection_clone} ​

源代码 · 在所选元素后立即插入所选元素的克隆，并返回新添加的克隆的选择。如果 deep 为真，则所选元素的后代节点也将被克隆。否则，仅克隆元素本身。等同于：

¥Source · Inserts clones of the selected elements immediately following the selected elements and returns a selection of the newly added clones. If deep is truthy, the descendant nodes of the selected elements will be cloned as well. Otherwise, only the elements themselves will be cloned. Equivalent to:

js
selection.select(function() {
  return this.parentNode.insertBefore(this.cloneNode(deep), this.nextSibling);
});

selection.sort(compare) {#selection_sort} ​

源代码 · 返回一个新的选择集，其中包含此选择集中每个组的副本，并根据比较函数进行排序。排序后，重新插入元素以匹配结果顺序（根据 selection.order）。

¥Source · Returns a new selection that contains a copy of each group in this selection sorted according to the compare function. After sorting, re-inserts elements to match the resulting order (per selection.order).

比较函数默认为 ascending，传入两个元素的数据 a 和 b 进行比较。它应该返回负值、正值或零值。如果为负数，则 a 应位于 b 之前；如果为正数，则 a 应该位于 b 之后；否则，a 和 b 被视为相等，顺序任意。

¥The compare function, which defaults to ascending, is passed two elements’ data a and b to compare. It should return either a negative, positive, or zero value. If negative, then a should be before b; if positive, then a should be after b; otherwise, a and b are considered equal and the order is arbitrary.

selection.order() {#selection_order} ​

源代码 · 将元素重新插入文档，使每个组的文档顺序与选择顺序匹配。这相当于在数据已排序的情况下调用 selection.sort，但速度更快。

¥Source · Re-inserts elements into the document such that the document order of each group matches the selection order. This is equivalent to calling selection.sort if the data is already sorted, but much faster.

selection.raise() {#selection_raise} ​

源代码 · 按顺序将每个选定元素重新插入为其父元素的最后一个子元素。等同于：

¥Source · Re-inserts each selected element, in order, as the last child of its parent. Equivalent to:

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

selection.lower() {#selection_lower} ​

源代码 · 按顺序将每个选定元素重新插入为其父元素的第一个子元素。等同于：

¥Source · Re-inserts each selected element, in order, as the first child of its parent. Equivalent to:

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

create(name) ​

源代码 · 给定指定的元素名称，返回当前文档中一个包含给定名称的分离元素的单元素选择。此方法假定 HTML 命名空间，因此在创建 SVG 或其他非 HTML 元素时必须明确指定命名空间；有关支持的命名空间前缀的详细信息，请参阅 namespace。

¥Source · Given the specified element name, returns a single-element selection containing a detached element of the given name in the current document. This method assumes the HTML namespace, so you must specify a namespace explicitly when creating SVG or other non-HTML elements; see namespace for details on supported namespace prefixes.

js
d3.create("svg") // equivalent to svg:svg
js
d3.create("svg:svg") // more explicitly
js
d3.create("svg:g") // an SVG G element
js
d3.create("g") // an HTML G (unknown) element

creator(name) ​

源代码 · 给定指定的元素名称，返回一个函数，该函数创建给定名称的元素，并假设 this 是父元素。此方法由 selection.append 和 selection.insert 内部使用，用于创建新元素。例如，如下：

¥Source · Given the specified element name, returns a function which creates an element of the given name, assuming that this is the parent element. This method is used internally by selection.append and selection.insert to create new elements. For example, this:

js
selection.append("div");

等同于：

¥Is equivalent to:

js
selection.append(d3.creator("div"));

有关受支持的命名空间前缀（例如 SVG 元素）的详细信息，请参阅 namespace。

¥See namespace for details on supported namespace prefixes, such as for SVG elements.