本文详解 SVG.js 3.0.5+ 版本中如何让图形（如矩形）沿 SVG 路径平滑运动，重点解决因 API 变更导致的 getPointAtLength 非有限值错误，并提供兼容、健壮的动画实现方案。
本文详解 svg.js 3.0.5+ 版本中如何让图形（如矩形）沿 svg 路径平滑运动，重点解决因 api 变更导致的 `getpointatlength` 非有限值错误，并提供兼容、健壮的动画实现方案。
在 SVG.js 从 v2 升级到 v3 的过程中，动画（animate）API 发生了显著变更，直接沿用 v2 的写法会导致运行时错误——最典型的就是控制台报错：
Uncaught TypeError: Failed to execute 'getPointAtLength' on 'SVGGeometryElement': The provided float value is non-finite.
该错误本质是 path.pointAt() 接收了 NaN 或 Infinity，根源在于 eased 参数未被正确计算，而这是由 animate() 方法签名与回调参数约定变更 引起的。
✅ 关键变更点解析
| 项目 | SVG.js v2.x | SVG.js v3.x+ | 说明 |
|---|---|---|---|
| animate() 参数顺序 | .animate(duration, ease, delay) | .animate(duration, delay, when) | ease 不再是第二参数，需链式调用 .ease() |
| during() 回调参数 | (pos, morph, eased, situation) | 仅传入 eased（归一化进度值，0→1） | 移除了冗余参数，简化接口 |
因此，原 v2 写法：
rect.animate(8000, '<>').during(function(pos, morph, eased) {
var p = path.pointAt(eased * length);
rect.center(p.x, p.y);
});在 v3 中必须重构为：
rect.animate(5000).ease('<>').during(function(eased) {
var p = path.pointAt(eased * length);
rect.center(p.x, p.y);
});✅ 完整可运行示例（v3.0.5+）
<!DOCTYPE html>
<html>
<head>
<title>SVG.js v3 Path Animation</title>
<style>
html, body, #drawing { width: 100%; height: 100%; margin: 0; }
</style>
<!-- 使用官方 CDN，确保版本明确 -->
<script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js@3.0.16/dist/svg.min.js"></script>
</head>
<body>
<div id="drawing"></div>
<script>
SVG.on(document, 'DOMContentLoaded', () => {
const draw = SVG().addTo('#drawing').size('100%', '100%');
const rect = draw.rect(80, 40).fill('#ff6b6b');
// 定义一条复杂贝塞尔路径（确保 path 有效且可测长）
const pathData = "M100,200 C150,100 250,100 300,200 C350,300 250,400 200,300 Z";
const path = draw.path(pathData)
.fill('none')
.stroke({ width: 2, color: '#9ca3af', dasharray: [10, 5] });
// ⚠️ 关键：务必先获取路径长度（path.length() 要求 path 已渲染且几何有效）
const length = path.length();
console.log('Path length:', length); // 调试：确认 length > 0 且为有限数
// 正确的 v3 动画链式调用
rect.animate(6000).ease('<>').during(function(eased) {
// eased ∈ [0, 1] → 计算当前路径上的点
const point = path.pointAt(eased * length);
// 将矩形中心对齐到该点（注意：rect.center(x, y) 是中心锚点定位）
rect.center(point.x, point.y);
}).loop(true); // 自动循环播放
});
</script>
</body>
</html>⚠️ 注意事项与最佳实践
-
路径有效性校验：path.length() 在无效路径（如空字符串、语法错误、未闭合且无控制点）下可能返回 0 或 NaN。建议添加防护：
if (!length || !isFinite(length)) { console.error('Invalid path: length is', length); return; } 坐标对齐逻辑：rect.center(x, y) 将矩形几何中心置于指定点。若需左上角或沿路径方向旋转，需额外计算 transform 或使用 path.getPointAtLength() 配合 path.getTangentAtLength() 获取切线角度。
性能优化：高频 during 回调中避免重复 DOM 查询或复杂计算。path.pointAt() 在 v3 中已高效缓存，但路径极长时仍建议预计算关键帧。
替代方案（推荐进阶场景）：对于复杂动画（如变速、暂停、多对象协同），建议使用 Timeline 或结合 GSAP + SVG.js 插件，获得更精细的控制力。
掌握这些 v3 特性变更后，你不仅能修复 non-finite 错误，更能写出更简洁、可维护的 SVG 动画代码。核心口诀：animate().ease().during() 三步链式，eased 是唯一参数，length 必须有效。
