D3

选择元素 ​

¥Selecting elements

Transitions are derived from selections via selection.transition。你还可以使用 d3.transition 在文档根元素上创建过渡效果。

¥Transitions are derived from selections via selection.transition. You can also create a transition on the document root element using d3.transition.

selection.transition(name) {#selection_transition} ​

源代码 · 返回给定选择集上具有指定名称的新过渡。如果未指定名称，则使用 null。新的过渡仅与同名的其他过渡互斥。

¥Source · Returns a new transition on the given selection with the specified name. If a name is not specified, null is used. The new transition is only exclusive with other transitions of the same name.

如果名称是 transition 实例，则返回的过渡与指定的过渡具有相同的 ID 和名称。如果所选元素上已存在具有相同 ID 的过渡，则返回该元素的现有过渡。否则，返回的过渡效果的时间将从每个选定元素最近祖级元素上具有相同 ID 的现有过渡效果继承。因此，此方法可用于在多个选择之间同步过渡，或为特定元素重新选择过渡并修改其配置。例如：

¥If the name is a transition instance, the returned transition has the same id and name as the specified transition. If a transition with the same id already exists on a selected element, the existing transition is returned for that element. Otherwise, the timing of the returned transition is inherited from the existing transition of the same id on the nearest ancestor of each selected element. Thus, this method can be used to synchronize a transition across multiple selections, or to re-select a transition for specific elements and modify its configuration. For example:

js
const t = d3.transition()
    .duration(750)
    .ease(d3.easeLinear);

d3.selectAll(".apple").transition(t)
    .style("fill", "red");

d3.selectAll(".orange").transition(t)
    .style("fill", "orange");

如果在选定节点或其祖级节点上未找到指定的过渡（例如过渡 已结束），则使用默认的计时参数；但是，在未来的版本中，这可能会被更改为抛出错误。请参阅 #59。

¥If the specified transition is not found on a selected node or its ancestors (such as if the transition already ended), the default timing parameters are used; however, in a future release, this will likely be changed to throw an error. See #59.

transition(name) ​

源代码 · 返回根元素 document.documentElement 上具有指定名称的新过渡。如果未指定名称，则使用 null。新的过渡仅与同名的其他过渡互斥。名称也可以是 transition 实例；参见 selection.transition。此方法等效于：

¥Source · Returns a new transition on the root element, document.documentElement, with the specified name. If a name is not specified, null is used. The new transition is only exclusive with other transitions of the same name. The name may also be a transition instance; see selection.transition. This method is equivalent to:

js
d3.selection()
  .transition(name)

此函数还可用于测试转换（instanceof d3.transition）或扩展转换原型。

¥This function can also be used to test for transitions (instanceof d3.transition) or to extend the transition prototype.

transition.select(selector) {#transition_select} ​

源代码 · 对于每个选定元素，选择第一个与指定选择器字符串匹配的后代元素（如果有），并在结果选择上返回过渡效果。选择器可以指定为选择器字符串或函数。如果指定了函数，则按顺序为每个选定元素求值，传递当前数据 (d)、当前索引 (i) 和当前组（节点），并将其作为当前 DOM 元素。新的过渡与当前过渡具有相同的 ID、名称和时间；但是，如果所选元素上已经存在具有相同 ID 的过渡，则将为该元素返回现有的过渡。

¥Source · For each selected element, selects the first descendant element that matches the specified selector string, if any, and returns a transition on the resulting selection. The selector may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.

此方法等效于通过 transition.selection 导出此过渡的选择，通过 selection.select 创建子选择，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, creating a subselection via selection.select, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .select(selector)
  .transition(transition)

transition.selectAll(selector) {#transition_selectAll} ​

源代码 · 对于每个选定元素，选择所有与指定选择器字符串匹配的后代元素（如果有），并在结果选择上返回过渡效果。选择器可以指定为选择器字符串或函数。如果指定了函数，则按顺序为每个选定元素求值，传递当前数据 (d)、当前索引 (i) 和当前组（节点），并将其作为当前 DOM 元素。新的过渡与当前过渡具有相同的 ID、名称和时间；但是，如果所选元素上已经存在具有相同 ID 的过渡，则将为该元素返回现有的过渡。

¥Source · For each selected element, selects all descendant elements that match the specified selector string, if any, and returns a transition on the resulting selection. The selector may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.

此方法等效于通过 transition.selection 导出此过渡的选择，通过 selection.selectAll 创建子选择，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, creating a subselection via selection.selectAll, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .selectAll(selector)
  .transition(transition)

transition.selectChild(selector) {#transition_selectChild} ​

源代码 · 对于每个选定元素，选择第一个与指定选择器字符串匹配的子元素（如果有），并在结果选择上返回过渡效果。选择器可以指定为选择器字符串或函数。如果指定了函数，则按顺序为每个选定元素求值，传递当前数据 (d)、当前索引 (i) 和当前组（节点），并将其作为当前 DOM 元素。新的过渡与当前过渡具有相同的 ID、名称和时间；但是，如果所选元素上已经存在具有相同 ID 的过渡，则将为该元素返回现有的过渡。

¥Source · For each selected element, selects the first child element that matches the specified selector string, if any, and returns a transition on the resulting selection. The selector may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.

此方法等效于通过 transition.selection 导出此过渡的选择，通过 selection.selectChild 创建子选择，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, creating a subselection via selection.selectChild, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .selectChild(selector)
  .transition(transition)

transition.selectChildren(selector) {#transition_selectChildren} ​

源代码 · 对于每个选定元素，选择所有与指定选择器字符串匹配的子元素（如果有），并在结果选择上返回过渡效果。选择器可以指定为选择器字符串或函数。如果指定了函数，则按顺序为每个选定元素求值，传递当前数据 (d)、当前索引 (i) 和当前组（节点），并将其作为当前 DOM 元素。新的过渡与当前过渡具有相同的 ID、名称和时间；但是，如果所选元素上已经存在具有相同 ID 的过渡，则将为该元素返回现有的过渡。

¥Source · For each selected element, selects all children that match the specified selector string, if any, and returns a transition on the resulting selection. The selector may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.

此方法等效于通过 transition.selection 导出此过渡的选择，通过 selection.selectChildren 创建子选择，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, creating a subselection via selection.selectChildren, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .selectChildren(selector)
  .transition(transition)

transition.filter(filter) {#transition_filter} ​

源代码 · 对于每个选定元素，仅选择与指定过滤器匹配的元素，并在结果选择上返回过渡效果。过滤器可以指定为选择器字符串或函数。如果指定了函数，则按顺序为每个选定元素求值，传递当前数据 (d)、当前索引 (i) 和当前组（节点），并将其作为当前 DOM 元素。新的过渡与当前过渡具有相同的 ID、名称和时间；但是，如果所选元素上已经存在具有相同 ID 的过渡，则将为该元素返回现有的过渡。

¥Source · For each selected element, selects only the elements that match the specified filter, and returns a transition on the resulting selection. The filter may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.

此方法等效于通过 transition.selection 导出此过渡的选择，通过 selection.filter 创建子选择，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, creating a subselection via selection.filter, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .filter(filter)
  .transition(transition)

transition.merge(other) {#transition_merge} ​

源代码 · 返回一个新的过渡，该过渡将当前过渡与指定的其他过渡合并，指定的其他过渡必须与当前过渡具有相同的 ID。返回的过渡与此过渡具有相同数量的组、相同的父节点、相同的名称和相同的 ID。此转换集中任何缺失（空）元素都将使用其他转换集中的相应元素（如果存在，则为非空）填充。

¥Source · Returns a new transition merging this transition with the specified other transition, which must have the same id as this transition. The returned transition has the same number of groups, the same parents, the same name and the same id as this transition. Any missing (null) elements in this transition are filled with the corresponding element, if present (not null), from the other transition.

此方法等效于通过 transition.selection 导出此过渡的选择，并与通过 selection.merge 从另一个过渡导出的选择合并，然后通过 selection.transition 创建新过渡：

¥This method is equivalent to deriving the selection for this transition via transition.selection, merging with the selection likewise derived from the other transition via selection.merge, and then creating a new transition via selection.transition:

js
transition
  .selection()
  .merge(other.selection())
  .transition(transition)

transition.transition() {#transition_transition} ​

源代码 · 返回与当前过渡相同的选定元素上的新过渡，计划在此过渡结束时启动。新的过渡继承的参考时间等于当前过渡的时间加上其 delay 和 duration。新的过渡还继承了当前过渡的名称、持续时间和 easing。此方法可用于安排一系列链式转换。例如：

¥Source · Returns a new transition on the same selected elements as this transition, scheduled to start when this transition ends. The new transition inherits a reference time equal to this transition’s time plus its delay and duration. The new transition also inherits this transition’s name, duration, and easing. This method can be used to schedule a sequence of chained transitions. For example:

js
d3.selectAll(".apple")
  .transition() // First fade to green.
    .style("fill", "green")
  .transition() // Then red.
    .style("fill", "red")
  .transition() // Wait one second. Then brown, and remove.
    .delay(1000)
    .style("fill", "brown")
    .remove();

每次转换的延迟都相对于前一次转换。因此，在上面的例子中，苹果在最后一次转换为棕色之前会保持红色一秒钟。

¥The delay for each transition is relative to its previous transition. Thus, in the above example, apples will stay red for one second before the last transition to brown starts.

transition.selection() {#transition_selection} ​

源代码 · 返回与此转换对应的 selection。

¥Source · Returns the selection corresponding to this transition.

active(node, name) ​

示例 · 源代码 · 返回指定节点上具有指定名称的活动转换（如果有）。如果未指定名称，则使用空值。如果指定节点上没有这样的活动转换，则返回 null。此方法对于创建链式过渡很有用。例如，启动迪斯科模式：

¥Examples · Source · Returns the active transition on the specified node with the specified name, if any. If no name is specified, null is used. Returns null if there is no such active transition on the specified node. This method is useful for creating chained transitions. For example, to initiate disco mode:

js
d3.selectAll("circle").transition()
    .delay((d, i) => i * 50)
    .on("start", function repeat() {
        d3.active(this)
            .style("fill", "red")
          .transition()
            .style("fill", "green")
          .transition()
            .style("fill", "blue")
          .transition()
            .on("start", repeat);
      });