React Move 实战:基于 Animate 组件实现 Flubber 形变与 Enter/Exit 过渡动画
React Move 实战:基于 Animate 组件实现 Flubber 形变与 Enter/Exit 过渡动画
react-move 是一个专注于数据驱动动画的 React 动画库,整个库只对外暴露两个组件:处理单元素的 <Animate /> 与处理元素数组的 <NodeGroup />。本文以官方文档站 docs/src/pages/demos/animate/animate.md 页面为骨架,围绕其中陈列的两个高价值示例——"Flubber"(SVG Path 形变动画)与 "Enter/Exit Transition"(进入/离开过渡动画)——逐行拆解 <Animate /> 的 start、enter、update、leave、show、interpolation 等核心 API,并结合 组件实现源码 与 测试用例 解释其底层工作原理,读完即可在自己的项目里复刻这两类动画。
示例页面:demo 占位符如何变成可运行示例
animate.md 正文极其精简,只有两个小节标题和两条 demo 引用:
##### Flubber
{{demo='pages/demos/animate/Example1.js'}}
##### Enter/Exit Transition
{{demo='pages/demos/animate/Example2.js'}}
这并非残缺文档,而是文档站约定的写法:{{demo='...'}} 是占位符,会被 MarkdownDocs 组件 通过正则 ^demo='(.*)'$ 解析,把其中的路径交给 Demo 组件 渲染:
requireDemos(require.context('docs/src', true, /\.js$/))按路径加载示例组件,把实时效果渲染进Paper面板;requireDemoSource(!raw-loader!docs/src)以纯文本形式加载示例源码,用户可点击 "Source" 按钮查看完整代码。
也就是说,该文档页面的"正文内容"就是 Example1.js 与 Example2.js 两个完整可运行示例。路由注册见 AppRouter.js,所有 demos/*.md 都会通过 demo.map(...) 自动注册到 /demos/:name 路径下。
Animate 组件核心 API 一览
在深入示例之前,先建立对 <Animate /> 的完整认知。它的全部 props 定义在 src/Animate/index.js 中,与 README 组件文档 一致:
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
show |
bool | true |
布尔值,决定子元素是否渲染(false 时触发 leave 过渡) |
interpolation |
function | numeric |
给定起止值与属性名,返回一个插值函数 |
start |
func / object | —— | 起始状态对象,或返回该对象的函数 |
enter |
func / array / object | —— | 描述进入时状态如何变换 |
update |
func / array / object | —— | 描述数据更新时状态如何变换;建议显式指定以处理被打断的 enter/leave |
leave |
func / array / object | —— | 描述离开时状态如何变换 |
children |
function(必填) | —— | 接收当前动画状态,返回要渲染的元素 |
从实现上看,Animate 是建立在 NodeGroup 之上的薄封装(详见后文"底层原理"),因此它的核心约定完全继承自 NodeGroup。下面两个示例就是这套 API 的最佳演示。
实战一:Flubber —— SVG Path 形变动画
完整源码见 Example1.js。它用 flubber 在 SVG 路径之间做平滑形变,视觉上是美国版图从一个州的轮廓"流动"到下一个州。先看完整代码:
import React, { PureComponent } from 'react'
import { feature } from 'topojson-client'
import { easeQuadOut } from 'd3-ease'
import { Animate } from 'react-move'
import { interpolate } from 'flubber'
import Surface from 'docs/src/components/Surface' // this is just a responsive SVG
import statesJSON from './states.json'
// **************************************************
// SVG Layout
// **************************************************
const view = [1000, 450] // [width, height]
const trbl = [10, 10, 10, 10] // [top, right, bottom, left] margins
class Example extends PureComponent {
state = {
states: feature(statesJSON, statesJSON.objects.states).features.map(d => {
return d.geometry.coordinates[0]
}),
}
update = () => {
// take the first one, put it at the end
this.setState(({ states }) => ({
states: [...states.slice(1), states[0]],
}))
}
render() {
const {
update,
state: { states },
} = this
const interpolator = interpolate(states[0], states[1])
return (
<div>
<button onClick={update}>Update</button>
<Surface view={view} trbl={trbl}>
<Animate
start={{
opacity: 0,
d: interpolator(1),
}}
enter={[
{
opacity: [0.7],
timing: { duration: 1000 },
},
]}
update={{
d: interpolator,
timing: { duration: 1000, ease: easeQuadOut },
}}
>
{state => {
return (
<g transform="translate(100, 0) scale(0.8)">
<path fill="#ff69b4" {...state} />
</g>
)
}}
</Animate>
</Surface>
</div>
)
}
}
export default Example
数据准备:从 TopoJSON 到 SVG path
states.json(数据文件)是一份美国各州边界的 TopoJSON 拓扑数据,objects.states下包含 48 个多边形区域(47 个州加华盛顿特区,不含阿拉斯加与夏威夷)。feature(statesJSON, statesJSON.objects.states)来自topojson-client,把拓扑数据还原成 GeoJSON Feature 集合;示例取每个 Feature 的geometry.coordinates[0],即多边形外环的坐标数组,作为 flubber 可用的路径形状。update方法每点一次按钮,就把states数组第一个元素移到末尾,形成"逐个州轮换"的数据流。由于每次点击后state.states都是新数组引用,Animate的update过渡就会被触发。
核心一行:flubber 插值器
const interpolator = interpolate(states[0], states[1])
flubber 的 interpolate(a, b) 返回一个接收进度 t(0~1)、返回中间路径字符串的函数。示例把插值器同时用在两个地方:
start.d: interpolator(1)—— 传t = 1得到的是states[1](下一个州)的最终路径,作为起始状态,让图形"先就位、再出现";update.d: interpolator—— 直接把插值器函数本身作为update配置里d的值。这正是react-move支持的第四种值类型:函数会被当作自定义 tween 函数。于是每次点击 Update,路径都会借助 flubber 从当前州轮廓平滑变形到下一个州轮廓。
start / enter / update 的配合
start:opacity: 0(从透明开始)、d为最终路径。start也可以是函数,但这里直接用对象即可,因为状态不依赖外部数据。enter:只过渡opacity到0.7,timing: { duration: 1000 }——1 秒内淡入到 70% 不透明度。注意enter里没有d,所以d保持start的值不变。update:过渡d(通过 flubber 插值器形变),timing: { duration: 1000, ease: easeQuadOut }——easeQuadOut是d3-ease提供的缓动函数,让形变先快后慢,收尾更自然。
d 是 SVG 路径的 d 属性,opacity 是透明度,这些正是 react-move 所说的 "attrs"(属性)。children 渲染函数接收插值后的 state,通过 <path fill="#ff69b4" {...state} /> 把两个属性直接展开到 SVG 元素上——{...state} 一次展开既省代码又直观。
关于 Surface
Surface.js 是文档站自己写的"响应式 SVG 容器",并非 react-move 的一部分:它接收 view(视口宽高,示例为 1000 × 450)与 trbl(上右下左四边距),利用 CSS padding-bottom 等比缩放技巧(代码注释引用了 css-tricks 的 Scale SVG 方案)让 SVG 自适应容器宽度。它在示例中的作用只是提供一个稳定的 SVG 舞台,与动画逻辑无关。
实战二:Enter/Exit Transition —— 挂载/卸载过渡与颜色切换
完整源码见 Example2.js。它展示单元素进出场动画的完整生命周期:进入淡入、更新换色、离场先变色再淡出。看完整代码:
import React, { PureComponent } from 'react'
import { interpolate, interpolateTransformSvg } from 'd3-interpolate'
import { range } from 'd3-array'
import { easeExpInOut } from 'd3-ease'
import { Animate } from 'react-move'
function getRandomColor() {
return range(6).reduce((m) => {
return `${m}${'0123456789ABCDEF'[Math.floor(Math.random() * 16)]}`
}, '#')
}
class Example extends PureComponent {
state = {
show: false,
color: '#00cf77',
}
updateShow = () => {
this.setState((prev) => ({ show: !prev.show }))
}
updateColor = () => {
this.setState(() => ({ show: true, color: getRandomColor() }))
}
render() {
const { updateShow, updateColor, state: { show, color } } = this
return (
<div>
<button onClick={updateShow}>
Toggle
</button>
{show ? (
<button onClick={updateColor}>
Update Color
</button>
) : null}
<Animate
show={show}
start={{
opacity: 0,
backgroundColor: color,
}}
enter={{
opacity: [1],
timing: { duration: 1000, ease: easeExpInOut },
}}
update={{
opacity: [1],
backgroundColor: [color],
timing: { duration: 500, ease: easeExpInOut },
}}
leave={[
{
backgroundColor: ['#ff0063'],
timing: { duration: 500, ease: easeExpInOut },
},
{
opacity: [0],
timing: { delay: 500, duration: 500, ease: easeExpInOut },
},
]}
interpolation={(begValue, endValue, attr) => {
if (attr === 'transform') {
return interpolateTransformSvg(begValue, endValue)
}
return interpolate(begValue, endValue)
}}
>
{({ opacity, backgroundColor }) => {
return (
<div style={{
opacity,
width: 200,
height: 200,
marginTop: 10,
color: 'white',
backgroundColor,
}}
>
{opacity.toFixed(3)}
</div>
)
}}
</Animate>
</div>
)
}
}
export default Example
show 开关与条件渲染
- 初始
show: false,页面加载时不渲染动画元素;点击 Toggle 后show变true,Animate挂载元素并执行enter过渡; show为true时出现 "Update Color" 按钮,点击后color更新,元素执行update过渡换色;- 再点 Toggle,
show变false,元素不立即消失,而是先执行leave过渡,完成后才卸载。
注意 updateColor 里同时把 show 置为 true——这是一种"防御性"写法,保证在元素尚未挂载时更新颜色,也能让元素以新颜色进入。
enter / update / leave 三种状态变换
-
enter:opacity从start的0过渡到[1],1 秒完成,使用easeExpInOut(指数缓动)。 -
update:backgroundColor从当前颜色过渡到[color](随机生成的新颜色),500ms;opacity维持[1]。这里体现了 react-move 的[value]写法:从一个属性当前值过渡到指定值。 -
leave:用的是数组形式的配置对象序列,两段动画接力完成离场:- 第一段:500ms 内把背景色过渡到
'#ff0063'(粉色); - 第二段:
delay: 500等第一段结束后,再花 500ms 把opacity过渡到0。
于是离场效果是"先变粉、再淡出",两段各自拥有独立的
duration/delay/ease。这是 react-move 相对 react-motion 类库的一个重要能力:进入、更新、离开可以用不同动画,每个 key 还能单独配置 delay、duration 与缓动(对比说明见 README 的 React-Move vs React-Motion 小节)。 - 第一段:500ms 内把背景色过渡到
自定义 interpolation:让颜色字符串可插值
示例引入了自定义 interpolation,这是本项目 API 升级后的关键设计。react-move 默认只做数值插值(见后文 numeric 实现),而本示例要插值的是 backgroundColor 这种 '#00cf77' 形式的颜色字符串——数值插值会得到 NaN。因此示例注入基于 d3-interpolate 的插值器:
interpolation={(begValue, endValue, attr) => {
if (attr === 'transform') {
return interpolateTransformSvg(begValue, endValue)
}
return interpolate(begValue, endValue)
}}
d3-interpolate 的 interpolate 会智能识别值类型:颜色字符串自动走颜色插值(内部依赖 d3-color),数字走数值插值;interpolateTransformSvg 则专门处理 SVG transform 字符串(如 translate(...) scale(...))。README 称之为 "Cadillac Interpolation"——npm install d3-interpolate 之后按此接入即可;若只需要数值插值,则无需任何额外依赖(这正是 react-move 4.0 起解除对 d3-interpolate 硬依赖的原因,详见 README 升级说明)。
children 渲染函数解构出 { opacity, backgroundColor } 应用到 div 的行内样式,并把 opacity.toFixed(3) 实时显示在色块上——这也是调试动画进度的实用技巧。
底层原理:Animate 到 NodeGroup 的调用链
两个示例都用的是 <Animate />,但它的实现本质上是对 NodeGroup 的封装(src/Animate/index.js):
const data = typeof start === 'function' ? start() : start
return (
<NodeGroup
data={show ? [data] : []}
start={() => data}
keyAccessor={keyAccessor} // () => '$$key$$',永远只有唯一节点
interpolation={interpolation}
enter={typeof enter === 'function' ? enter : () => enter}
update={typeof update === 'function' ? update : () => update}
leave={typeof leave === 'function' ? leave : () => leave}
>
{nodes => {
if (!nodes[0]) return null
return children(nodes[0].state)
}}
</NodeGroup>
)
要点:
keyAccessor固定返回'$$key$$',保证Animate永远只管理一个节点;show通过data={show ? [data] : []}决定"有一个节点"还是"没有节点";show: true时挂载即进入,立即执行enter过渡;show翻转为false时数据变为空数组,唯一节点进入LEAVE类型,播放leave过渡后卸载;- 所有 props 都被规范化为"返回配置的函数"形式,所以
enter/update/leave传对象、数组或函数都可以。
再往下看 NodeGroup(src/NodeGroup/index.js):
getDerivedStateFromProps在nextProps.data !== prevState.data(引用不同)时做节点差异化:遍历新旧 key,为新增节点标记ENTER、为持续存在的节点标记UPDATE、为消失的节点标记LEAVE(类型常量见 src/core/types.js);- 新增节点先
n.setState(start(...))设置起始状态,紧接着n.transition(enter(...))开始进入过渡;后续节点分别调用update/leave的过渡配置; - 节点合并顺序由 src/core/mergeKeys.js 决定,其实现思路来自 react-motion 的
mergeDiff(源码注释明确标注),对两份存在部分重叠的 key 列表做确定性的拓扑排序,对应的单元测试 验证了[a, b]与[c, b, d]会合并为[a, c, b, d]; - 动画驱动依赖
kapellmeister提供的interval(见 package.json 依赖):startInterval启动逐帧回调,每帧遍历节点,只要有节点处于isTransitioning()状态就继续,LEAVE过渡结束后把该节点从nodeHash删除,全部结束后interval.stop()停止渲染循环。
Animate 的测试套件 用 enzyme 挂载组件验证了这些行为,可作为你理解生命周期的对照:
show为true时,挂载后 500ms 内opacity会从0过渡到1("should run enter transition immediately after mounting");show为false时,children 渲染函数根本不会被调用("should NOT call the child function");- 通过
wrapper.setProps({ show: false })触发 leave 过渡,断言结束后opacity为0; enter、update均支持函数形式。
编写 Animate 配置的实践要点
起始状态的两条铁律
README 的 Starting state 小节 明确指出,start 必须是一个叶子值为字符串或数字的对象,并给出两条规则:
- 不要把
"timing"或"events"用作 attr 或 namespace(它们被配置系统占用); - 对象中任何位置都不允许出现数组。
attr 指对象叶子键(如 opacity、d、backgroundColor),namespace 是纯粹用于组织状态的中间层对象(例如用 inner / outer 分组内外元素的属性),interpolation 函数接收的第 4 个参数就是 namespace 字符串。
过渡值的四种写法
在 enter / update / leave 配置中,每个键的值有四种语义(示例恰好用到了其中三种):
| 写法 | 语义 |
|---|---|
字符串或数字 |
立即设置,不产生过渡,忽略所有 timing |
[value] |
从该键当前值过渡到指定值(示例中 opacity: [1]、backgroundColor: [color]) |
[value1, value2] |
从 value1 过渡到 value2 |
函数 |
作为自定义 tween 函数(示例中 update.d: interpolator) |
配置对象还支持两个特殊键:timing(过渡参数)与 events(生命周期回调)。同一个 enter/update/leave 可以传对象数组,让不同键使用不同的 timing——Example2 的 leave 两段式就是标准示范。
timing 与 events
未指定 timing 时使用默认值(README 明确给出):
const defaultTiming = {
delay: 0,
duration: 250,
ease: easeLinear
};
你只需覆盖需要的字段,ease 直接传函数即可(可用任意缓动函数,如 d3-ease 导出的 easeQuadOut、easeExpInOut)。events 支持三个回调:
events: {
start: () => { /* 过渡开始 */ },
interrupt: () => { /* 过渡被打断(数据更新) */ },
end: () => { /* 过渡结束 */ },
}
建议用箭头函数以保留外层组件上下文。
默认数值插值器
不传 interpolation 时,Animate.defaultProps 使用 numeric(定义见 src/utils.js):
export function numeric(beg, end) {
const a = +beg
const b = +end - a
return function(t) {
return a + b * t
}
}
它把起止值强制转为数字后做线性插值——零依赖、体积小,但只能处理数字。只要你的动画涉及颜色、SVG path、SVG transform 等字符串值,就需要像两个示例那样接入 d3-interpolate(甚至 flubber)自定义 interpolation。同时注意:interpolation 在过渡期间会被高频调用(每帧每个属性都会触发),README 提醒实现应避免重逻辑与重计算。
总结
docs/src/pages/demos/animate/animate.md 这个极简页面,实际浓缩了 react-move 动画能力的两个代表性切面:Flubber 示例展示了 start / enter / update 与自定义 tween 函数的组合,让 SVG 路径在数据轮换时平滑形变;Enter/Exit 示例则完整演示了 show 驱动的挂载/卸载生命周期,以及数组形式 leave 配置实现的多段离场动画。配合 Animate 组件源码 与 NodeGroup 源码 的封装关系、"四种值类型"与"timing 默认值"等约定,你完全可以把这两套模式迁移到自己的图表、列表或通用 UI 过渡场景中。