MotionPath

gsap.registerPlugin(MotionPathPlugin) 

gsap.to("#div", {
  motionPath: {
    path: "#path",
  },
  transformOrigin: "50% 50%",
  duration: 5,
});

沿任意路径（或甚至通过任意属性值）动画化任何对象。motionPath 可以定义为以下任意一种形式：

• 一个 SVG<path>元素（选择器文本或直接引用），例如：

  motionPath: "#pathID";
  

• A SVG 路径数据字符串例如：

  motionPath: "M9,100c0,0,18-41,49-65";
  

• 一个包含x、y 坐标对象的数组。默认情况下，它会穿过这些坐标绘制一条曲线路径穿过这些坐标，但如果它们描述的是立方贝塞尔曲线，请设置type: "cubic"参数：

  // plot a curve through these coordinates. The target's current coordinates will automatically be added to the start:
  motionPath: [{x:100, y:50}, {x:200, y:0}, {x:300, y:100}]
  
  // cubic bezier coordinates (anchor, two control points, anchor, two control points, etc.):
  motionPath: {
    path: [{x:0, y:0}, {x:20, y:0}, {x:30, y:50}, {x:50, y:50}],
    type: "cubic"
  }
  

• 一个包含其他属性的对象数组其他属性（不一定是 "x" 和 "y"）。这将在每个值过渡时基本平滑速度变化：

  // property values through which to animate (the target's current property values will be added to the start):
  motionPath: [
    { scale: 0.5, rotation: 10 },
    { scale: 1, rotation: -10 },
    { scale: 0.8, rotation: 3 },
  ];
  

• A 配置对象它具有上述任意一种格式的path属性，以及其他的配置细节例如：

  motionPath: {
    path: "#pathID",
    align: "#pathID",
    alignOrigin: [0.5, 0.5],
    autoRotate: true,
    start: 0.25,
    end: 0.75
  }
  

其他功能​

配置对象​

这个motionPath可以用作path的快捷方式（如下所述），也可以作为配置对象使用以下任一属性：下面的代码将使一个 div 对齐到 SVG<path>。假设有一个具有idid 为"div"的 DOM 元素和一个 SVG<path>具有idid 为"#path".

属性

描述

• path

  字符串 | 元素 | 数组[必需] 用于动画化目标的运动路径。它可以是以下任意一种：

  • 一个 SVG元素（选择器文本或直接引用），例如：

    // selector text: motionPath: {    path: "#pathID" }  // or direct reference to a  element: let myPath = document.querySelector("#pathID"); ... motionPath: {    path: myPath }

  • A SVG 路径数据字符串例如：

    // path data: motionPath: {    path: "M9,100c0,0,18-41,49-65" }

  • 一个包含x、y 坐标对象的数组。系统将根据这些坐标绘制一条曲线路径穿过这些坐标，或者设置type: "cubic"参数将其解释为连续的立方贝塞尔坐标（顺序类似：锚点、两个控制点、锚点、两个控制点等等）：

    // plot a curve through these coordinates (the target's current coordinates will automatically be added to the start): motionPath: {   path: [{x:100, y:50}, {x:200, y:0}, {x:300, y:100}] }  // cubic bezier coordinates (anchor, two control points, anchor, two control points, etc.): motionPath: {   path: [{x:0, y:0}, {x:20, y:0}, {x:30, y:50}, {x:50, y:50}],   type: "cubic" }

  • 一个包含其他属性的对象数组其他属性（不一定是 "x" 和 "y"）。这将在每个值过渡时基本平滑速度变化：

    // property values through which to animate (the target's current property values will be added to the start): motionPath: {   path: [{scale:0.5, rotation:10}, {scale:1, rotation:-10}, {scale:0.8, rotation:3}] }

• align

  字符串 | 元素- 默认情况下，path数据中的原始坐标值会直接插入到目标的 x/y 变换中，但align属性会调整坐标空间，以确保不管它们嵌套在多少经过变换的容器中，都能准确地将目标放置在路径正上方（或将路径移动到目标位置）！您也可以对path进行对齐。换句话说，path和align可以指向同一个元素。align可以是以下任意一种：

  • 选择器文本，例如"#path"将选择 ID 为 "path" 的元素，并将补间动画的目标移动，使其左上角与 "#path" 元素完美对齐。如果您希望在该位置居中显示目标，请使用alignOrigin: [0.5, 0.5]
  • 元素，比如一个 DOM 元素的引用。
  • "self"将路径移动到补间动画的目标位置，这样它们不会一开始跳跃。换句话说，就像路径是从它们当前位置开始绘制的一样。

  您还可以使用offsetX和offsetY来微调对齐。

• alignOrigin

  数组- 确定目标上与路径对齐的点。alignOrigin是一个包含 x 和 y 轴上进度值的数组，所以[0.5, 0.5]表示中心点，[1, 0]表示右上角等。设置alignOrigin同时也会自动设置transformOrigin为目标上对应的点，以方便使用。（GSAP 3.2.0 新增）

• autoRotate

  布尔值 | 数值- 按照路径方向旋转元素。true完全匹配路径的角度，但您可以通过定义autoRotate参数来增加任意角度偏移量数值（单位为度）。例如，autoRotate: 90将在元素沿路径移动时添加 90 度旋转。如果您希望元素围绕其中心旋转，请简单设置transformOrigin: "50% 50%"要使路径与目标的中心对齐，可以使用alignOrigin: [0.5, 0.5]或者在motionPath补间动画之前在目标上设置xPercent: -50, yPercent: -50。

• start

  数字- 沿着路径开始的位置，其中0是起点，1是终点，0.5是中间点。它可以是任何正或负的小数。例如，0.3将会使元素在曲线30%的位置开始。默认值为0。

• end

  数字- 沿着路径结束的位置，其中0是起点，1是终点，0.5是中间点。它可以是任何正或负的小数，包括比start还要小的值（这将使对象向后移动）。例如，0.3将会使元素在曲线30%的位置结束。1.5将使其绕回起点并在一半的位置停止。默认值为1。

• curviness

  数字- 仅适用于当path是一个通过其中绘制曲线的点数组时。它决定了生成路径的“弯曲程度”。因此，0会使路径成为直线（硬角），1（默认值）会创建一个漂亮的曲线路径，而2则会更加弯曲。可以将其想象成随着数值越高，控制点从锚点向外拉得更远。默认值为1。

• offsetX

  数字- 添加到x坐标的一个量，用于微调对齐。默认值为0。

• offsetY

  数字- 添加到y坐标的一个量，用于微调对齐。默认值为0。

• fromCurrent

  Boolean- 当false为true时，会导致它不包含传入非数组中的当前属性值。例如，如果目标当前位于path，然后你执行了一个x: 0, y: 0 and then you do a motionPath: {path: [{x: 100, y: 100}, {x: 200, y: 0}, {x: 300, y: 200}]}补间动画，默认情况下它会将{x: 0, y: 0}添加到该数组的start位置，以便从当前位置平滑地进行动画播放，当前的位置，但你可以设置fromCurrent: false来避免这种情况，并直接让其跳转到补间动画开始处的x: 100, y: 100。（3.7.0版本中添加）

• relative

  Boolean- 仅适用于当path是一个数组时。如果为truetrue，则每个后续值都会被解释为相对于前一个值。例如，如果目标的x起始于100且路径为relative to the previous one. For example, if the target's x starts at 100 and the path is [{x:5}, {x:10}, {x:-2}] ，它将首先移动至105，接着到115，最终在113处结束。

• type

  字符串- 仅适用于当path是一个带有x/y属性的对象数组时——设置type: "cubic"以使其被解释为以下顺序的一系列立方贝塞尔曲线：锚点、两个控制点、锚点、两个控制点、锚点等，依此类推若干次迭代，但显然要确保它以锚点开头和结尾。

• resolution

  数字- 仅适用于当path是一个数组时。由于贝塞尔曲线的特性，在时间上沿着路径运动的对象前进过程可能会因控制点的放置以及路径上每一连续段的长度而出现加速或减速的视觉效果。所以MotionPathPlugin实现了一种技术来减少甚至消除这种变化，但它需要将各段分割成一定数量的片段，这个数量由resolution控制。数值越大，时间映射越精确。但更高的精度需要更多的处理开销。默认值为12一般足够完美，但如果注意到路径上的行进速度有轻微变化，可以增加resolution值。或者，如果你更看重性能，可以减小此数值。

• useRadians

  Boolean- 如果为true，传递给旋转的值将使用弧度而非角度。这对于与其他默认使用弧度的脚本或库（如Pixi.js）配合使用特别有用。默认值为false。

演示​

gsap.to("#div", {
  motionPath: {
    path: "#path",
    align: "#path",
    alignOrigin: [0.5, 0.5],
    autoRotate: true,
  },
  transformOrigin: "50% 50%",
  duration: 5,
  ease: "power1.inOut",
});

动画播放时通过其他属性（非坐标）​

你可以传入一个定义了其他属性的对象数组（不一定是"x"和"y"），它基本上会在达到每个值时平滑过渡速度变化。在下面的示例中，我们使用curviness值为0和2来动画化不同的scale值；请注意较高曲率时速度变化更加平滑：

视频​

方法​

示例演示​

查看完整系列的SVG 动画演示在 CodePen 上。