X6 图编辑器动画使用完全指南：从声明式配置到 Web Animation API 深度实践

X6 图编辑器动画使用完全指南从声明式配置到 Web Animation API 深度实践【免费下载链接】X6 JavaScript diagramming library that uses SVG and HTML for rendering.项目地址: https://gitcode.com/GitHub_Trending/x6/X6导读本指南以 X6基于 SVG 与 HTML 渲染的 JavaScript 图编辑库的动画使用示例为核心系统讲解节点/边动画的声明式配置语法、组合动画与关键帧、播放控制 API、自定义属性动画以及 CSS 动画方案。示例全部来源于仓库 site/examples/animation/usage/demo 目录底层原理可对照 src/model/animation 源码进行印证。读完本文你将能够独立完成从让节点动起来到精细化控制动画播放的完整实战。一、动画体系总览两种使用方式X6 的动画能力围绕Web Animation API的Animation与KeyframeEffect模型实现见 src/model/animation/animation.ts 的类注释使用方式分为两类声明式配置在graph.addNode/graph.addEdge时通过animation字段声明动画节点/边创建后自动播放适合图元自带动态效果的场景如呼吸、涟漪、流动线。命令式控制通过cell.getAnimations()获取动画实例再调用play()/pause()/cancel()/updatePlaybackRate()/reverse()/finish()等方法进行播放控制适合交互场景如点击按钮暂停、加速。从源码结构看每个 Cell节点/边内部持有一个AnimationManagersrc/model/animation/animationManager.tscell.getAnimations()即委托它返回当前动画列表入口定义在 src/model/cell.ts。二、基本使用四种最常用的动画目标示例 basic.ts 通过 6 个节点演示了最基本的动画写法其核心结构是animation: [ [ { position/x: 50 }, // 关键帧目标值 { duration: 1000, direction: alternate, iterations: Infinity }, // 播放选项 ], ]外层数组的每一项是一组独立动画每组内部第一个对象描述动画目标目标路径与目标值第二个对象描述播放选项。示例覆盖四类常用目标动画目标路径效果示例值position/x水平位移{ position/x: 50 }attrs/body/fill填充颜色渐变{ attrs/body/fill: [#9254de, #06b6d4] }size/width宽度伸缩{ size/width: 120 }angle旋转{ angle: 360 }attrs/body/opacity透明度变化{ attrs/body/opacity: [0.5, 1] }attrs/text/fontSize文字字号变化{ attrs/text/fontSize: [10, 16] }关键点说明目标值是单值如50时表示从当前值动画到该值目标值是数组如[#9254de, #06b6d4]时表示在多个关键帧之间插值。direction: alternate让动画正向→反向往复iterations: Infinity表示无限循环配合alternate即形成经典的往复循环效果。三、组合动画多属性并行、多组独立、多关键帧示例 composition.ts 展示了三种进阶组合方式3.1 单组内并行多个属性在一个关键帧对象中同时写入多个路径它们将并行插值animation: [ [ { size/width: 85, size/height: 85, attrs/body/opacity: [1, 0.9], }, { duration: 900, iterations: Infinity }, ], ]3.2 多组动画分别配置外层数组可包含多组动画每组独立设置时长、方向等选项animation: [ [{ angle: [0, 360] }, { duration: 3000, iterations: Infinity }], [{ attrs/body/fill: #D94F00 }, { duration: 2000, iterations: Infinity, direction: alternate }], ]例如示例中星星图形一边 3 秒旋转一周、一边 2 秒往复变色。3.3 多关键帧数组内多个值目标值数组超过两个元素时即构成多个关键帧可构造复杂轨迹animation: [ [ { position/x: [370, 390, 350], position/y: [40, 50, 60], angle: [0, 40, 0, 30], }, { duration: 2000, direction: alternate, iterations: Infinity }, ], ]position/x在 370→390→350 三点间移动angle在 0→40→0→30 四帧间旋转各属性关键帧长度可以不同未定义 offset 时按均分处理。四、控制动画播放取消、倍速、暂停与继续示例 control.ts 演示了通过node:click事件驱动动画控制的完整流程graph.on(node:click, ({ cell }) { const [ani] cell.getAnimations() if (cell cancelNode) { ani.cancel() // 取消动画 } if (cell rateNode) { ani.updatePlaybackRate(2) // 2 倍速播放 } if (cell pauseNode) { if (label 点击暂停动画) { ani.pause() // 暂停 } else { ani.play() // 继续播放 } } })对照 src/model/animation/animation.ts 源码这些方法的行为如下cancel()animation.ts停止动画、状态回到idle并通过KeyframeEffect.apply(null)把属性恢复到动画前原始值随后触发animation:cancel事件oncancel回调。updatePlaybackRate(2)animation.ts设置倍速源码中当动画正在运行时会按新旧倍速重算_startTime保证切换倍速的瞬间画面不跳变见playbackRate的 setteranimation.ts。pause()animation.ts记录当前时间_pausedTime停止requestAnimationFrame循环状态置为paused。play()animation.ts若处于暂停态则从_pausedTime处继续若处于初始态则从 0 开始并启动内部_tick()的 rAF 循环。Animation类还提供reverse()反转播放方向、finish()跳到结束并依据fill模式落定最终状态等方法可组合实现更丰富的交互控制。此外动画实例还暴露onfinish、oncancel回调以及currentTime、playbackRate、playState等属性animation.ts。五、边动画流动虚线、沿线移动标记与渐变流光示例 edge.ts 展示了四种边动画实战5.1 流动虚线通过让strokeDashoffset循环递减虚线产生向前流动效果graph.addEdge({ source: { x: 60, y: 60 }, target: { x: 240, y: 60 }, attrs: { line: { strokeDasharray: 5, strokeDashoffset: 0 } }, animation: [[{ attrs/line/strokeDashoffset: -20 }, { duration: 1000, iterations: Infinity }]], })5.2 标记沿边移动自定义marker元素并动画其atConnectionRatio连接线上位置比例 0→1实现圆点沿平滑曲线connector: { name: smooth }滑行markup: [ { tagName: circle, selector: marker, attrs: { stroke: none, r: 5 } }, ...Shape.Edge.getMarkup(), ], attrs: { line: { strokeDasharray: 5, strokeDashoffset: 0, stroke: #9DADCE }, marker: { fill: #C7D5F6, atConnectionRatio: 0 } }, animation: [[{ attrs/marker/atConnectionRatio: 1 }, { duration: 2000, iterations: Infinity }]],5.3 不同 easing 的多组动画同一组动画可以分别指定不同的缓动函数例如描边粗细用ease-in-out-back、透明度用ease-in-out-quad还支持路径 单值的简写形式路径、目标值、选项三段式animation: [ [{ attrs/line/strokeWidth: 4 }, { duration: 2500, iterations: Infinity, direction: alternate, easing: ease-in-out-back }], [attrs/line/opacity, 1, { duration: 2500, iterations: Infinity, direction: alternate, easing: ease-in-out-quad }], ]5.4 渐变流光结合线性渐变stroketype: linearGradient 三段stops与strokeDashoffset循环并叠加透明度呼吸形成彩色流光animation: [ [{ attrs/line/opacity: [0.7, 1] }, { duration: 1000, fill: forwards, direction: alternate, iterations: Infinity }], [{ attrs/line/strokeDashoffset: [30, 0] }, { duration: 500, iterations: Infinity }], ],这里显式使用了fill: forwards表示动画结束后保留最后一帧状态源码 keyframeEffect.ts 的EffectTiming定义支持none/forwards/backwards/both四种模式。六、自定义属性动画让 HTML 节点跟随数据变化示例 custom-attr.ts 演示了如何对自定义节点的自定义数据属性做动画通过Shape.HTML.register注册custom-html节点其html(cell)回调根据cell.getData().ratio动态计算 div 尺寸然后对data/ratio声明动画Shape.HTML.register({ shape: custom-html, width: 160, height: 80, effect: [data], html(cell) { const { ratio } cell.getData() ?? {} // ...根据 ratio 计算并返回 div }, }) graph.addNode({ shape: custom-html, x: 80, y: 80, data: { ratio: 1 }, animation: [[{ data/ratio: 3 / 5 }, { duration: 1000, iterations: Infinity }]], })其底层原理是KeyframeEffect在初始化时用target.getPropByPath(prop)收集动画属性的原始值在每一帧插值后用target.setPropByPath(prop, value)写回keyframeEffect.ts 与 keyframeEffect.ts。因此只要属性路径可读可写包括data/*这类自定义路径就能被动画驱动——这正是自定义属性动画能够成立的关键机制。七、呼吸效果多节点统一动画示例 breathing-circle.ts 通过自定义markup为每个圆形节点叠加一层wrapper圆环动画其半径attrs/wrapper/r从radius放大到radius 10再往复配合wrapper的opacity: 0.4形成柔和的呼吸光晕markup: [ { tagName: circle, selector: wrapper }, { tagName: circle, selector: body }, ], attrs: { body: { fill: color, strokeWidth: 0 }, wrapper: { r: radius, cx: radius, cy: radius, fill: color, opacity: 0.4, strokeWidth: 0 }, }, animation: [[{ attrs/wrapper/r: radius 10 }, { duration: 1000, direction: alternate, iterations: Infinity }]],八、涟漪效果利用 delay 制造相位差示例 ripple-circle.ts 用程序化markup生成 5 层涟漪圆环ripple0ripple4共享groupSelector: rippleGroup并为每层生成一组动画通过delay参数错开启动时间形成依次扩散的水波animation: Array.from({ length }).map((_, aniIndex) [ { [attrs/ripple${aniIndex}/r]: [r, r length * 5], [attrs/ripple${aniIndex}/opacity]: [opacity, 0], }, { duration: 1000 * length, iterations: Infinity, delay: 1000 * aniIndex, // 每层延迟 1 秒启动 }, ]),delay是EffectTiming的标准字段默认 0见 keyframeEffect.ts 的默认值定义在Animation._tick()中以currentTime - delay计算播放进度从而支持精确的错峰编排。九、CSS 动画两种接入方式示例 css.ts 说明动画也可以完全交给 CSS 处理X6 图元本质是 DOM 元素SVG/HTML因此 CSS 动画天然可用内联 style 直接声明在 attrs 的style中写animationattrs: { body: { fill: #efdbff, stroke: none, rx: 10, style: { animation: trans 1s infinite linear }, }, },添加 class 引入样式在 attrs 中指定class动画样式定义在外部样式表attrs: { body: { fill: #85C054, stroke: none, rx: 10, class: css-animation-node } },keyframes trans { to { transform: translateX(50px); } } .css-animation-node { animation: trans 1s infinite linear; }示例使用insert-css仅为演示方便实际项目建议将样式写入样式文件。声明式动画配置与 CSS 动画的选择依据需要与图元数据/几何状态联动、需要在运行时精细控制播放暂停、倍速、取消的场景优先使用animation配置纯视觉表现如平移、闪烁可直接走 CSS成本更低。十、底层原理关键帧插值与播放选项10.1 关键帧标准化与 offset 计算KeyframeEffect支持数组关键帧与属性索引对象两种写法对象写法会被拆分为多个关键帧未显式指定offset时自动均分首帧为 0、末帧为 1、中间帧按index / (length - 1)计算keyframeEffect.ts。示例中position/x: [370, 390, 350]即被解析为 offset 0 / 0.5 / 1 的三帧。10.2 插值策略按值类型自动选择apply(iterationTime)在每帧计算当前进度后根据属性值类型自动选择插值器keyframeEffect.ts以#开头的字符串 → 颜色插值Interp.color以transform结尾的属性且非数值 → 变换矩阵插值Interp.transform含单位如px、%由unitReg判断→ 单位插值Interp.unit其余 → 数值插值Interp.number。每个关键帧还可以携带独立的easing未指定时继承前序帧或总选项中的 easingkeyframeEffect.ts最终经Timing[easingName]查表得到缓动函数如ease-in-out-back、ease-in-out-quad缺省回退linear。10.3 EffectTiming 播放选项总表结合 keyframeEffect.ts 的接口定义与默认值animation第二项播放选项可用字段如下字段类型默认值说明durationnumber0单次播放时长毫秒示例常用 5003000delaynumber0延迟启动时间毫秒涟漪示例用于错峰iterationsnumber1播放次数Infinity表示无限循环directionnormal \| reverse \| alternate \| alternate-reversenormal播放方向alternate实现往复easingCamelToKebabCaseTiming.Nameslinear缓动函数名如ease-in-out-quadfillnone \| forwards \| backwards \| bothnone动画结束后的填充模式forwards保留末帧需要说明的是源码注释标注backwards与both的初始应用效果尚在实现完善中keyframeEffect.ts生产使用建议优先forwards/none并对动画结束后的状态做显式设计。十一、运行与查看示例示例代码可直接在仓库的 site 工程中运行查看进入site目录安装依赖后启动开发服务即可在动画示例页Usage 分组逐个预览基本使用、组合动画、控制播放、边动画、自定义属性动画、呼吸、涟漪与 CSS 动画共 8 个 demo每个 demo 的源码对应 demo 目录下的basic.ts、composition.ts、control.ts、edge.ts、custom-attr.ts、breathing-circle.ts、ripple-circle.ts、css.tsdemo 标题与截图信息见 meta.json。结语X6 的动画能力覆盖了声明式配置 命令式控制 CSS 兜底三档方案animation数组声明让图元开箱即动getAnimations()结合Animation类方法实现细粒度交互控制而KeyframeEffect的多关键帧、自动 offset、按类型插值与EffectTiming选项则提供了接近 Web Animation API 的表达力。结合仓库 site/examples/animation/usage 的示例与 src/model/animation 的实现开发者可以快速搭建出呼吸、涟漪、流动线、数据驱动 HTML 节点动画等常见图编辑动效。【免费下载链接】X6 JavaScript diagramming library that uses SVG and HTML for rendering.项目地址: https://gitcode.com/GitHub_Trending/x6/X6创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考