修改元素

🌐 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:

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:

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)

来源 · 如果指定了 value，则将所选元素的指定 name 属性设置为指定的值，并返回该选择。

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

如果value是一个常数，则所有元素都会被赋予相同的属性值；否则，如果value是一个函数，它会针对每个被选中的元素依次进行计算，并传入当前数据(d)、当前索引(i)以及当前组(nodes), 其中this为当前的DOM元素(nodes[i])。函数的返回值随后用于设置每个元素的属性。null值将移除指定的属性。

🌐 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.

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

如果未指定 value，则返回选择中第一个（非空）元素的指定属性的当前值。只有在你确定选择中恰好包含一个元素时，这通常才有用。

🌐 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.

指定的name可能有一个命名空间前缀，例如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)

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

selection.classed("foo", true)

指定的 names 是一个由空格分隔的类名字符串。例如，要将类 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:

selection.classed("foo bar", true)

如果 value 为真值，则所有元素都会被分配指定的类；否则，这些类将被取消分配。

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

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

如果 value 是一个函数，它会对每个选中的元素进行评估，按照顺序，传入当前数据 (d)、当前索引 (i) 和当前组 (nodes)，其中 this 是当前的 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.

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

如果未指定 value，则仅当第一个（非空）选中的元素具有指定的 classes 时返回 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("color", "red")

如果 value 是常量，则所有元素都会被赋予相同的样式属性值；否则，如果 value 是一个函数，则该函数会按顺序为每个选定元素进行计算，传入当前数据 (d)、当前索引 (i) 和当前组 (nodes)，且 this 为当前的 DOM 元素 (nodes[i])。函数的返回值随后用于设置每个元素的样式属性。null 值将移除该样式属性。还可以指定一个可选的 priority，可以为 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).

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.

小心

与许多 SVG 属性不同，CSS 样式通常有相关的单位。例如，3px 是有效的 stroke-width 属性值，而 3 则不是。一些浏览器会将 px（像素）单位隐式分配给数值，但不是所有浏览器都会这样做：例如，IE 会抛出“无效参数”错误！

选择.属性(名称, 值)

🌐 selection.property(name, value)

源 · 一些 HTML 元素具有不能通过属性或样式访问的特殊属性，例如表单字段的文本 value 和复选框的 checked 布尔值。使用此方法可以获取或设置这些属性。

selection.property("checked", true)

如果指定了 value，则将选定元素上指定 name 的属性设置为指定的值。如果 value 是常量，那么所有元素都会获得相同的属性值；否则，如果 value 是函数，则会对每个选定元素按顺序进行评估，将当前数据 (d)、当前索引 (i) 和当前组 (nodes) 传入，函数的上下文 this 为当前 DOM 元素 (nodes[i])。然后使用函数的返回值来设置每个元素的属性。null 值将删除指定的属性。

🌐 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.

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

如果未指定 value，则返回选择中第一个（非空）元素的指定属性的值。只有在你确定选择中恰好包含一个元素时，这通常才有用。

🌐 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("Hello, world!")

如果value是一个常量，则所有元素都采用相同的文本内容；否则，如果value是一个函数，则会对每个选定的元素进行求值，按顺序传入当前数据(d)、当前索引(i)和当前组(nodes)，并将this设为当前的DOM元素(nodes[i])。然后使用函数的返回值来设置每个元素的文本内容。null值将清空内容。

🌐 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.

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

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

🌐 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)

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

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

如果value是一个常量，则所有元素都采用相同的内部 HTML；否则，如果value是一个函数，则会对每个选定的元素按顺序进行评估，并传入当前数据 (d)、当前索引 (i) 和当前组 (nodes)，其中this为当前的 DOM 元素 (nodes[i])。函数的返回值将用于设置每个元素的内部 HTML。值为 null 将清空内容。

🌐 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.

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

如果未指定value，则返回选择中第一个（非空）元素的内部 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.

请改用 selection.append 或 selection.insert 来创建数据驱动的内容；此方法适用于你只想添加少量 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)

来源 · 如果指定的 type 是字符串，则将该类型（标签名）的新元素附加为每个选中元素的最后一个子元素，或者如果这是一个 enter selection，则附加在紧随其后的兄弟元素之前。进入选择的这种行为允许你根据新绑定的数据以一致的顺序将元素插入到 DOM 中；然而，请注意，如果更新元素会改变顺序（即，新数据的顺序与旧数据不一致），仍可能需要使用 selection.order。

如果指定的 type 是一个函数，则会对每个选定的元素依次进行评估，函数接收当前数据 (d)、当前索引 (i) 和当前组 (nodes) 作为参数，且 this 为当前 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:

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

这等同于：

🌐 This is equivalent to:

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

这等同于：

🌐 Which is equivalent to:

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.

指定的 name 可能包含命名空间前缀，例如 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)

来源 · 如果指定的 type 是字符串，则在每个选定元素中，在第一个匹配指定 before 选择器的元素之前插入一个该类型（标签名）的新元素。例如，before 选择器 :first-child 将在第一个子元素之前插入节点。如果未指定 before，则默认为 null。（要按与绑定数据一致的顺序追加元素，请使用 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:

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

这等同于：

🌐 This is equivalent to:

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

这等同于：

🌐 Which is equivalent to:

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.

指定的 name 可能包含命名空间前缀，例如 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()

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

selection.clone(deep)

来源 · 在所选元素之后立即插入所选元素的克隆，并返回新添加克隆的选择。如果 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 被视为相等，顺序是任意的。

🌐 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.sort，但速度更快。

selection.raise()

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

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

selection.lower()

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

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

create(name)

来源 · 给定指定的元素name，返回一个包含当前文档中指定名称的独立元素的单元素选择。该方法假设使用 HTML 命名空间，因此在创建 SVG 或其他非 HTML 元素时必须显式指定命名空间；有关支持的命名空间前缀的详细信息，请参见命名空间。

d3.create("svg") // equivalent to svg:svg

d3.create("svg:svg") // more explicitly

d3.create("svg:g") // an SVG G element

d3.create("g") // an HTML G (unknown) element

创建者(name)

🌐 creator(name)

Source · 给定指定的元素 name，返回一个函数，该函数创建一个指定名称的元素，假设 this 是父元素。此方法在内部被 selection.append 和 selection.insert 用于创建新元素。例如，这个:

selection.append("div");

等同于：

🌐 Is equivalent to:

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

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

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