跳过主要内容

MotionPath

快速入门

CDN 链接

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
    }

其他功能

特性亮点
  • 魔法般的能力align功能它可以调整坐标系统,使得目标精确地定位在路径上方(或者将路径移动到目标位置),无论它们嵌套在多少经过变换的容器中!这是极其方便的,网络上没有其他工具提供这个功能。
  • **autoRotate**当目标沿路径移动时使其自动旋转方向对齐于路径。
  • 定义特定的start和/或end路径上的位置(进度值从 0 到 1)。甚至可以环绕或倒退!
  • 一个单独的MotionPathHelper工具启用在浏览器中直接交互式编辑路径!
  • 不需要提供 SVG 路径 - 您可以通过指定一系列坐标来绘制曲线路径包括可调节弯曲度的完整功能
  • 大量的辅助方法用于执行高级操作,例如:

配置对象

这个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进行对齐。换句话说,pathalign可以指向同一个元素。align可以是以下任意一种:
    • 选择器文本,例如"#path"将选择 ID 为 "path" 的元素,并将补间动画的目标移动,使其左上角与 "#path" 元素完美对齐。如果您希望在该位置居中显示目标,请使用alignOrigin: [0.5, 0.5]
    • 元素,比如一个 DOM 元素的引用。
    • "self"将路径移动到补间动画的目标位置,这样它们不会一开始跳跃。换句话说,就像路径是从它们当前位置开始绘制的一样。
    您还可以使用offsetXoffsetY来微调对齐。
  • 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",
});

加载中...

注意事项

当你align启动motionPath时,这些计算是在动画刚开始时完成的——它是响应式的,因此如果屏幕调整大小导致路径受到影响,对齐不会重新应用。为什么?因为从CPU的角度来看,每次tick都不断检查并重新计算是非常昂贵的。但在这种情况下,你完全可以自己设置resize监听器并手动处理(存储补间动画的进度,progress(0).kill()中止它,创建新的补间动画并跳转到记录的进度)。

动画播放时通过其他属性(非坐标)

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

加载中...

视频

转换坐标

方法

MotionPathPlugin.arrayToRawPath( values:Array, vars:Object ) : RawPath数组

接收一个坐标数组并通过它们绘制一条曲线,返回相应的RawPath数组。如果在type: "cubic"参数对象中声明了vars,这些坐标将被解释为类似锚点、两个控制点、锚点、两个控制点、锚点等一系列的立方贝塞尔曲线点。

MotionPathPlugin.convertCoordinates( fromElement:Element | window, toElement:Element | window, point:Object ) : Object(点或Matrix2D)

将一个点从某个元素的局部坐标系统转换为另一个元素的局部坐标系统中的对应位置,无论多少嵌套变换影响着这些元素!

MotionPathPlugin.convertToPath( shape:String | Element, swap:Boolean ) : Array

将SVG形状比如<circle>, <rect>, <ellipse>,或者<line>进入<path>

MotionPathPlugin.getAlignMatrix( fromElement:Element | window, toElement:Element | window, fromOrigin:Array, toOrigin:Array | String ) : Matrix2D

获取用于在不同坐标空间之间转换的 Matrix2D,通常这样你可以移动fromElement以使其与toElement对齐,同时考虑所有变换(即使是嵌套的)。该矩阵允许你使用它的 apply() 方法转换任意点/坐标。

MotionPathPlugin.getGlobalMatrix( element:Element, inverse:Boolean, adjustGOffset:Boolean ) : Matrix2D

获取用于将元素的本地坐标空间转换为全局坐标空间的 Matrix2D。例如,如果你对一个点应用{x:0, y:0}apply()该矩阵,则得到的点将是该元素左上角在视口中的坐标。

MotionPathPlugin.getLength( path:Element | String | RawPath ) : Number

返回路径的长度

MotionPathPlugin.getPositionOnPath( rawPath:Array, progress:Number, includeAngle:Boolean ) : Object

计算与沿 RawPath 的特定进度值对应的 x/y 位置(以及可选的角度)

MotionPathPlugin.getRawPath( value:String | Element ) : RawPath (Array)

获取所提供的元素或原始 SVG <path> 数据的 RawPath (Array)。RawPath 实质上是一个包含多个数组的数组,每个连续的线段对应一个子数组,其中交替存储着 x、y、x、y 的三次贝塞尔曲线数据。

MotionPathPlugin.getRelativePosition( fromElement:Element | window, toElement:Element | window, fromOrigin:Array | Object, toOrigin:Array | Object | String ) : Object

获取两个元素之间的 x 和 y 距离,无论是否存在嵌套变换!给该方法传入两个元素,它将根据 fromElement 父级的坐标系统返回它们之间的空隙作为一个点 {x, y}。

MotionPathPlugin.pointsToSegment( points:Array, curviness:Number ) : Array

绘制一条穿过所提供 x,y 坐标的弯曲三次贝塞尔路径,返回一个通常插入到 RawPath 数组中的线段数组

MotionPathPlugin.rawPathToString( rawPath:Array ) : String

MotionPathPlugin.sliceRawPath( rawPath:Array, start:Number, end:Number ) : RawPath

在指定的起始和结束位置切分所提供的 RawPath 数组,并返回新的切分后的 RawPath

MotionPathPlugin.stringToRawPath( data:String ) : RawPath

示例演示

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