本文详解 SVG.js 3.x 版本中如何让图形（如矩形）沿 SVG 路径平滑移动，重点解决因 API 变更导致的 getPointAtLength 非有限值错误，并提供兼容、健壮的动画实现方案。
本文详解 svg.js 3.x 版本中如何让图形（如矩形）沿 svg 路径平滑移动，重点解决因 api 变更导致的 `getpointatlength` 非有限值错误，并提供兼容、健壮的动画实现方案。
在 SVG.js 从 v2 升级到 v3 的过程中，动画（animate）API 发生了显著变化，直接沿用 v2 的写法会导致运行时错误（如 Uncaught TypeError: Failed to execute 'getPointAtLength'... non-finite），根本原因在于参数顺序调整与回调函数签名变更。
✅ 正确调用方式（SVG.js v3.0.5）
animate() 参数顺序变更：
v2 中为 (duration, ease, delay)，而 v3 中为 (duration, delay, when) —— ease 不再是第二个参数，需通过链式 .ease() 方法单独设置。during() 回调参数简化：
v2 回调接收 (pos, morph, eased, situation) 四个参数；v3 仅传递一个归一化进度值 eased（范围 0–1），代表当前动画完成比例（已自动应用缓动函数）。
✅ 完整可运行示例
<title>SVG.js v3.0.5 沿路径动画</title><style>
html, body, #drawing { width: 100%; height: 100%; margin: 0; }
</style><script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js@3.0.5/dist/svg.min.js"></script><div id="drawing"></div>
<script>
function onload() {
const draw = SVG().addTo('#drawing').size(800, 800);
// 创建矩形（目标动画元素）
const rect = draw.rect(100, 100).attr({ fill: '#f06' });
// 定义复杂路径（支持贝塞尔曲线等）
const pathData = "m 357.64532,453.84097 c 17.62007,8.02216 -2.12058,27.70935 -13.33334,29.28571 " +
"-30.3859,4.27185 -48.34602,-29.97426 -45.23807,-55.9524 5.5594,-46.46879 " +
"56.1311,-70.59787 98.57145,-61.19043 62.28294,13.8058 93.32728,82.57702 " +
"77.1428,141.19051 C 453.21679,585.29693 365.67122,623.42358 290.97859,600.26951 " +
"196.98554,571.13248 151.71003,464.56996 181.93108,373.84089 218.53281,263.95583 " +
"344.23687,211.49702 450.97875,248.84102 576.77037,292.84963 636.43303,437.76771 " +
"591.93099,560.50775 540.55162,702.21597 376.3736,769.09583 237.6452,717.41234 " +
"80.01319,658.68628 5.9069261,475.21736 64.788247,320.50751 130.84419,146.94643 " +
"333.62587,65.607117 504.31214,131.69819 693.80625,205.0718 782.38357,427.18225 " +
"709.07382,613.84113";
const path = draw.path(pathData)
.fill('none')
.stroke({ width: 1, color: '#ccc' });
// ✅ 关键：获取路径总长度（必须在渲染后调用）
const length = path.length();
console.log('路径总长度:', length); // 确保 length > 0，否则 pointAt 会报错
// ✅ 正确动画链式调用
rect.animate(5000) // duration: 5秒
.ease('<>') // 缓动类型：正弦缓入缓出
.during(function(eased) { // 注意：仅接收一个参数 eased (0~1)
const p = path.pointAt(eased * length); // 计算路径上对应位置
rect.center(p.x, p.y); // 将矩形中心对齐该点
})
.loop(true, true); // 循环播放（无限循环 + 反向回放）
}
</script>
⚠️ 注意事项与最佳实践
- 路径必须已渲染且非空：path.length() 在未添加到文档或路径数据非法时可能返回 0 或 NaN，务必检查返回值有效性（建议加 if (length
- .center(x, y) vs .move(x, y)：center() 以中心点定位，适合居中矩形；若需左上角对齐，请改用 move(p.x - 50, p.y - 50)（假设宽高为 100）。
- 性能优化：对于高频动画（如 60fps），避免在 during 中重复调用 path.pointAt()——可预先缓存路径采样点数组，或使用 SVG.Path#array() 分段近似。
- 兼容性提示：v3.0.5 后续版本（如 v3.1+）保持相同 API，但建议锁定 CDN 版本（如 @3.0.5）避免意外升级破坏。
通过遵循上述规范，即可在 SVG.js v3 中稳定实现路径跟随动画，规避因 API 迁移引发的常见错误。
