React Move 实战:基于 Animate 组件实现 Flubber 形变与 Enter/Exit 过渡动画

原创2026-10-14 22:05:291,685 阅读
文章标签:前端UI组件

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:用的是数组形式的配置对象序列,两段动画接力完成离场:

    1. 第一段:500ms 内把背景色过渡到 '#ff0063'(粉色);
    2. 第二段:delay: 500 等第一段结束后,再花 500ms 把 opacity 过渡到 0。

    于是离场效果是"先变粉、再淡出",两段各自拥有独立的 duration / delay / ease。这是 react-move 相对 react-motion 类库的一个重要能力:进入、更新、离开可以用不同动画,每个 key 还能单独配置 delay、duration 与缓动(对比说明见 README 的 React-Move vs React-Motion 小节)。

自定义 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 过渡场景中。

登录后查看全文
react-move