d3-transition 元素修改 API 详解：attr、style、text 与 Tween 插值机制

本文以 d3 仓库中 d3-transition 元素修改文档 为纲，系统讲解过渡（transition）的八组修改方法：attr、attrTween、style、styleTween、text、textTween、remove 与 tween。读完本篇，你将掌握如何在选定元素并创建过渡后，用目标值或自定义插值器逐帧驱动 DOM 属性、样式与文本变化，并理解 d3 如何根据目标值类型自动选择插值器，以及如何通过 tween 命名约定实现可组合的动画。

过渡与选择：从 selection 到 transition

d3 中，过渡是"类选择集（selection-like）"的接口：它不立即改变 DOM，而是在给定时长内把 DOM 从当前状态平滑插值到目标状态。典型流程是先用 selection.transition 从 selection 派生出过渡，再调用过渡自身的修改方法来影响文档内容。例如：

d3.select("body")
  .transition()
    .style("background-color", "red");

过渡支持大部分选择集修改方法（用 transition.attr 与 transition.style 取代 selection.attr 与 selection.style），但并非所有方法都支持：例如必须在过渡开始前先追加元素或绑定数据。过渡还额外提供了 transition.remove，用于在过渡结束时便捷地移除元素。

在仓库层面，d3-transition 是 d3 主包声明的独立依赖：package.json 中列有 "d3-transition": "^3.0.1"，并由 src/index.js 统一再导出；rollup.config.js 将其与其余模块打包为 UMD/ESM 产物。本文所述各方法的实现在 d3-transition 包内（如 src/transition/attr.js、src/transition/tween.js），当前主仓库以源码链接与文档形式引用它们。

transition.attr(name, value)

对每个选中的元素，为指定 name 的属性分派一个属性 tween，使其插值到目标 value。tween 的起始值是过渡开始时刻该属性的值；目标 value 可以是常量，也可以是函数——函数会对每个选中元素按顺序立即求值，接收当前数据 (d)、当前索引 (i) 与当前分组 (nodes)，this 为当前 DOM 元素。

null 与插值器选择规则：若目标值为 null，属性会在过渡开始时被移除；否则按以下算法根据目标值类型自动选择插值器：

1. 若 value 是数字，使用 interpolateNumber；
2. 若 value 是 颜色 或可转为颜色的字符串，使用 interpolateRgb；
3. 否则使用 interpolateString。

需要其他插值器时，改用 transition.attrTween。这一"数字 → 颜色 → 字符串"的探测顺序也解释了为什么诸如 "12px"、带内嵌数字的字符串（常见于 padding、font-size、路径 d 属性）能被自动逐数字插值——它们落入第 3 条 interpolateString 分支。

transition.attrTween(name, factory)

这是属性层面的底层插值器接口。若 factory 已指定且非 null，则为指定 name 的属性分派插值器工厂。插值器工厂是一个返回 interpolator 的函数：过渡开始时，factory 对每个选中元素按顺序求值，接收 (d)、(i)、(nodes)，this 为当前 DOM 元素；随后，返回的插值器在过渡的每一帧被调用，接收经过缓动处理的时间 t（通常在 [0, 1] 区间），插值器必须返回一个字符串，该返回值被用于设置属性值。

三态调用约定（在 styleTween、textTween 中同样成立）：

• factory 非 null：设置 tween；
• factory 为 null：移除先前为该 name 分派的属性 tween（若有）；
• 未指定 factory：返回当前已分派的插值器工厂，若不存在则返回 undefined。

文档给出的三个示例覆盖了从"固定两端"到"取当前值"再到"完全自定义"的谱系：

// 1. 固定从红插值到蓝
transition.attrTween("fill", () => d3.interpolateRgb("red", "blue"));

// 2. 从当前 fill 值插值到蓝（等价于 attr 的行为）
transition.attrTween("fill", function() {
  return d3.interpolateRgb(this.getAttribute("fill"), "blue");
});

// 3. 完全自定义的"彩虹"插值器
transition.attrTween("fill", () => (t) => `hsl(${t * 360},100%,50%)`);

该方法的价值在于指定自定义插值器，典型场景是动画化 SVG 路径 d 属性。文档特别推荐的技术是数据插值（data interpolation）：用 interpolateObject 插值两个数据值，再用 shape 生成器（如 d3.line()、d3.area()）由插值后的数据计算新的属性值——即"先插值数据、再重算几何"，而非直接字符串插值路径。

注意删除属性的两条路径：过渡开始时删属性用 transition.attr（传 null）；过渡结束时删属性则用 transition.on 监听 end 事件后手动移除。

transition.style(name, value, priority)

与 attr 结构一致，但作用于 CSS 样式，并多一个 priority 参数（通常取 "important" 或省略）。tween 的起始值是：若存在内联样式则取其内联值，否则取计算值（computed value）——这个"内联优先、回退到计算值"的取法保证了即使样式来自样式表，动画也能从视觉上正确的起点开始。目标 value 可以是常量或函数，函数按 (d)、(i)、(nodes) 顺序求值，this 为当前 DOM 元素。

null 目标值同样在过渡开始时移除样式；否则沿用与 attr 相同的三步插值器选择算法：

1. 数字 → interpolateNumber；
2. 颜色或可转颜色字符串 → interpolateRgb；
3. 其余 → interpolateString。

需要其他插值器时改用 transition.styleTween。

transition.styleTween(name, factory, priority)

样式层面的底层插值器接口，语义与 attrTween 对称：工厂在过渡开始时按元素求值，返回的插值器每帧接收缓动后的时间 t（[0, 1]），必须返回字符串，用于以指定 priority 设置样式值。三态调用约定（null 移除、缺省读取）与 attrTween 完全相同。

// 固定从红到蓝
transition.styleTween("fill", () => d3.interpolateRgb("red", "blue"));

// 从当前 fill 到蓝（等价于 style 的行为）
transition.styleTween("fill", function() {
  return d3.interpolateRgb(this.style.fill, "blue");
});

// 自定义彩虹插值器
transition.styleTween("fill", () => (t) => `hsl(${t * 360},100%,50%)`);

样式删除路径与属性一致：过渡开始时删除用 transition.style，结束时删除用 transition.on 监听 end 事件。同样可配合数据插值技术：用 interpolateObject 插值数据后再计算新的样式值。

transition.text(value) 与 transition.textTween(factory)

text：对每个选中元素，在过渡开始时把 textContent 直接设为目标 value。value 可以是常量或按 (d)、(i)、(nodes) 求值的函数（this 为当前 DOM 元素），返回值用于设置各元素文本内容；null 值会清空内容。

关键设计决策：文本默认不做插值——因为逐帧变化文本通常是 undesirable 的（例如数字跳动的阅读干扰）。若要插值文本而非在开始时一次性设置，有两种方式：使用 transition.textTween，或追加一个替换元素并对 opacity 做交叉淡化（cross-fade）。

textTween：若 factory 已指定且非 null，则为文本分派插值器工厂，其余机制（每元素求值、每帧调用、接收缓动时间 t、必须返回字符串）与 attrTween 一致。经典示例是把文本从 0 数到 100：

transition.textTween(() => d3.interpolateRound(0, 100));

三态约定不变：factory 为 null 时移除已有文本 tween；未指定时返回当前工厂或 undefined。

transition.remove()

对每个选中元素，在过渡结束时将其从 DOM 中移除——但有一个安全条件：只有当该元素没有其他处于活动或等待状态（pending）的过渡时才会真正移除；若元素还挂着其他过渡，此方法什么都不做。这与 d3 的过渡排他模型一致：同名过渡互斥（见 selection.transition），而 remove 通过检查节点上的过渡计数避免"半删除"——即一个过渡结束时元素被删掉、而另一个过渡仍在引用它。

transition.tween(name, factory)

tween 是最底层的通用接口：attrTween/styleTween/textTween 本质上都是对 tween 的封装，且 d3 用命名前缀（如 attr.fill、style.fill）把它们登记到同一命名空间，从而避免互相覆盖、允许按名查询。

对每个选中元素，tween 为指定 name 分派一个 value 函数。value 必须是返回函数的函数（工厂）：过渡开始时按元素顺序求值，接收 (d)、(i)、(nodes)，this 为当前 DOM 元素；返回的函数在过渡每帧被调用，接收缓动后的时间 t（[0, 1]）。若 value 为 null，移除该 name 先前分派的 tween。

文档示例展示了手工实现"fill 属性插值到蓝"（等价于 attr 的行为），可以看到工厂返回的闭包如何在每帧写入 DOM：

transition.tween("attr.fill", function() {
  const i = d3.interpolateRgb(this.getAttribute("fill"), "blue");
  return function(t) {
    this.setAttribute("fill", i(t));
  };
});

注意 tween 的第二参是插值器工厂本身（或 null），而内层函数每帧执行副作用——这也意味着你可以用它实现任意副作用型动画（如滚动偏移量），而不限于属性或样式。

八组方法速查与选择策略

方法	作用对象	起始值来源	自定义插值器	命名/附加参数
attr(name, value)	属性	过渡开始时属性值	否（自动选择）	—
attrTween(name, factory)	属性	由工厂决定	是	—
style(name, value, priority)	样式	内联值，否则计算值	否（自动选择）	priority（如 "important"）
styleTween(name, factory, priority)	样式	由工厂决定	是	priority
text(value)	textContent	—（开始时刻直接设置）	否	null 清空
textTween(factory)	textContent	由工厂决定	是	—
remove()	元素节点	—（过渡结束时删除）	—	受其他过渡保护
tween(name, factory)	任意（副作用）	由工厂决定	是	命名前缀约定

选择策略可以归纳为：先用高层方法（attr/style/text），让 d3 按"数字 → 颜色 → 字符串"算法自动选插值器；需要控制插值路径时升级到对应的 *Tween 方法；需要任意副作用或多属性协同时落到 tween。所有 *Tween 方法都支持 null 移除、缺省查询的三态调用，便于调试时读取当前已注册的插值器工厂。

仓库中的印证与验证方式

• 依赖与导出：package.json 声明 d3-transition ^3.0.1，src/index.js 中 export * from "d3-transition" 使本文所有方法经 d3 命名空间可用；
• 文档锚点治理：本仓库用 test/docs-test.js 自动爬取 docs/ 下全部 Markdown 的链接与 {#anchor} 定义，断言内部锚点链接无失效项——修改类文档中的 #transition_attr、#transition_tween 等锚点即受此约束，这也是文档内各方法采用显式 {#...} 锚点的原因；
• 配套文档：修改方法所依赖的"过渡从何而来"（派生、命名、同步）见 d3-transition 选择文档，缓动时间 t 的语义见 timing 文档，end 事件与过渡生命周期见 control-flow 文档；
• 适用前提：当前主仓库版本为 7.9.0（见 package.json），d3-transition 为 3.x 线 API；文中行为描述以 docs/d3-transition/modifying.md 与上述文档为准，运行环境需支持标准 DOM 与浏览器端执行。

小结

d3-transition 的元素修改 API 呈现清晰的三层结构：attr/style/text 提供"给目标值、自动插值"的高层便捷层；attrTween/styleTween/textTween 提供"给插值器"的定制层；tween 提供"每帧任意副作用"的通用层，而 remove 则在过渡生命周期末端收束元素删除。理解"工厂在开始时求值、插值器每帧接收缓动时间 t"这一统一模型，加上"数字 → 颜色 → 字符串"的插值器选择算法，即可覆盖绝大多数 d3 动画场景；对 SVG 路径等复杂形状，则优先采用数据插值配合 shape 生成器的方案，而非直接插值路径字符串。