文档

示例

获取 Motion+

文档

示例

获取 Motion+

文档

示例

获取 Motion+

文档

文档

JS

React

Vue

开始使用

示例

动画

手势

Motion 值

工具

集成

指南

JS

React

Vue

开始使用

示例

动画

手势

Motion 值

工具

集成

指南

JavaScript

animate

animate

animate() 函数是用于创建和控制动画的强大工具。

animate("li", { opacity: 0 })

它有两种尺寸：mini (2.3kb) 和 hybrid (18kb)。

mini 版本可以使用原生浏览器 API 为 HTML 和 SVG 样式制作动画，以获得惊人的性能。

hybrid 版本还可以额外为以下内容制作动画：

  • 独立的变换 (x/y/rotateZ 等)

  • 更多样式，例如 mask-image 和渐变

  • CSS 变量

  • SVG 路径

  • 动画序列

  • 颜色/字符串/数字

  • JavaScript 对象和 WebGL

用法

animate 可以从 "motion" 包中导入

// Hybrid
import { animate } from "motion"

// Mini
import { animate } from "motion/mini"

HTML & SVG

animate 的两个版本都能够通过直接传递元素或通过 CSS 选择器为 HTML 和 SVG 样式制作动画。

// Element(s)
const box = document.getElementById("box")

animate(box, { opacity: 0 }, { duration: 0.5 })

// CSS selectors
animate("div", { opacity: 0 }, { duration: 0.5 })

变换

hybrid 版本的 animate 可以独立地为每个变换轴制作动画

  • 平移: x, y, z

  • 缩放: scale, scaleX, scaleY

  • 旋转: rotate, rotateX, rotateY, rotateZ

  • 倾斜: skew, skewX, skewY

  • 透视: transformPerspective

animate("div", { rotate: 360 })

CSS 变量

Hybrid animate 可以在所有浏览器中为 CSS 变量制作动画

animate(element, { "--rotate": "360deg" })

Mini animate 只能为已注册的 CSS 属性在现代浏览器中制作动画。

SVG 路径

hybrid animate 函数可以使用三个特殊属性：pathLength、pathSpacing 和 pathOffset，对大多数 SVG 元素执行线条绘制动画。

animate("circle", { pathLength: [0, 1] })

所有这三个属性都设置为介于 0 和 1 之间的进度值，1 表示路径的总长度。

路径动画与 circle、ellipse、line、path、polygon、polyline 和 rect 元素兼容。

单个值

通过传递 to 和 from 值，hybrid animate 将最新的值输出到提供的 onUpdate 回调。

// Numbers
animate(0, 100, {
  onUpdate: latest => console.log(latest)
})

// Colors
animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

Motion 值

通过传递 hybrid animate 一个React motion 值，它将自动使用最新的值进行更新。

const x = motionValue(0)

animate(x, 200, { duration: 0.5 })

对象

可以像 HTML 和 SVG 元素一样为对象制作动画。

const values = {
  x: 100,
  color: "#f00"
}

animate(values, { x: 200, color: "#00f" })

任何对象都可以制作动画，例如来自Three.js:

const camera = new THREE.Camera()

animate(camera.rotation, { y: 360 }, { duration: 10 })

时间线序列

hybrid animate 函数还可以接受复杂的动画序列。

const sequence = []

animate(sequence)

序列 是 animate 定义的数组

const sequence = [
  ["ul", { opacity: 1 }, { duration: 0.5 }],
  ["li", 100, { ease: "easeInOut" }]
]

默认情况下，每个定义将按顺序播放。

可以通过传递一个at选项来更改片段的播放时间，该选项可以是绝对时间、相对时间或标签。

const sequence = [
  ["ul", { opacity: 1 }],
  ["li", { x: [-100, 0] }, { at: 1 }]
]

每个片段都可以接受所有 animate选项（除了 repeatDelay 和 repeatType），以控制该片段的持续时间和其他动画设置。

const sequence = [
  ["ul", { opacity: 1 }, { duration: 1 }]
]

支持 type: "keyframes" 和 type: "spring" 两种过渡类型。

也可以单独覆盖每个值的过渡。

const sequence = [
  [
    "ul",
    { opacity: 1, x: 100 },
    { duration: 1, x: { duration: 2 }}
   ]
]

序列持续时间会自动计算，但也可以传递任何 animate选项来更改整体播放

animate(sequence, { duration: 10, repeat: 2 })

您还可以定义默认过渡设置，通过 defaultTransition 选项传递给序列中的所有项目

animate(sequence, {
  defaultTransition: { duration: 0.2 }
})

animate 支持的任何值都可以在序列中制作动画，在同一动画中混合 HTML 和 SVG、motion 值和对象

const color = motionValue("rgba(255, 0, 0, 1)")
const box = new THREE.BoxGeometry()

const sequence = [
  ["li", { x: 100 }],
  [box.position, { y: 10 }],
  [color, "#444"]
]

交错

当为多个元素制作动画时，可以通过将 stagger 函数传递给 delay 来交错动画。

import { stagger, animate } from "motion"

animate(".item", { x: 300 }, { delay: stagger(0.1) })

选项

可以使用过渡选项配置动画。默认情况下，提供的选项将影响每个动画值。

animate(
  element,
  { x: 100, rotate: 0 },
  { duration: 1 }
)

通过提供命名的过渡，可以在每个值的基础上覆盖这些过渡

animate(
  element,
  { x: 100, rotate: 0 },
  {
    duration: 1,
    rotate: { duration: 0.5, ease: "easeOut" }
  }
)

type

type 决定要使用的动画类型。

Mini animate 可以使用默认的关键帧动画或 spring 进行动画制作

import { animate } from "motion/mini"
import { spring } from "motion"

animate(
  element,
  { transform: "translateX(100px)" },
  { type: spring, stiffness: 300 }
)

Hybrid animate 内置了所有动画类型，可以设置为 "tween"、"spring" 或 "inertia"。

Tween 动画通过持续时间和缓动曲线设置。

Spring 动画可以是基于物理的，也可以是基于持续时间的。

基于物理的 spring 动画通过 stiffness、damping 和 mass 设置，并且这些动画结合了任何现有手势或动画的速度，以实现自然的反馈。

基于持续时间的 spring 动画通过 duration 和 bounce 设置。这些动画不结合速度，但更容易理解。

Inertia 动画根据值的初始速度减速，通常用于实现惯性滚动。

animate("path", { pathLength: 1 }, { duration: 2, type: "tween" })

Tween

duration

默认值: 0.3 (如果定义了多个关键帧，则为 0.8)

动画的持续时间。当也设置了 bounce 时，也可以用于 "spring" 动画。

animate("ul > li", { opacity: 1 }, { duration: 1 })

ease

用于 tween 动画的缓动函数。接受

  • 缓动函数名称。例如 "linear"

  • 一个由四个数字组成的数组，用于定义三次贝塞尔曲线。例如 [.17,.67,.83,.67]

  • 一个 JavaScript 缓动函数，它接受并返回一个 0-1 之间的值。

以下是可用的缓动函数名称

  • "linear"

  • "easeIn", "easeOut", "easeInOut"

  • "circIn", "circOut", "circInOut"

  • "backIn", "backOut", "backInOut"

  • "anticipate"

当为关键帧制作动画时，ease 可以选择设置为缓动函数数组，以在每个值之间设置不同的缓动

animate(
  element,
  { x: [0, 100, 0] },
  { ease: ["easeIn", "easeOut"] }
)

times

当为多个关键帧制作动画时，可以使用 times 来调整每个关键帧在整个动画中的位置。

times 中的每个值都是介于 0 和 1 之间的值，表示动画的开始和结束。

animate(
  element,
  { x: [0, 100, 0] },
  { times: [0, 0.3, 1] }
)

times 的数量必须与关键帧的数量相同。默认为均匀分布的持续时间数组。

Spring

bounce

默认值: 0.25

bounce 确定 spring 动画的“回弹”程度。

0 表示不回弹，1 表示回弹非常强烈。

注意: 如果设置了 stiffness、damping 或 mass，则 bounce 和 duration 将被覆盖。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", bounce: 0.25 }
)

visualDuration

如果设置了 visualDuration，则它将覆盖 duration。

视觉持续时间是一个时间，以秒为单位设置，动画将花费这么长时间在视觉上达到其目标。

换句话说，过渡的大部分将在此时间之前发生，“回弹部分”将主要在此时间之后发生。

这使得编辑 spring 更容易，并且可以使其在视觉上与其他基于时间的动画协调一致。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", visualDuration: 0.5, bounce: 0.25 }
)

stiffness

默认值: 1

spring 的刚度。值越高，产生的运动越突然。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", stiffness: 50 }
)

damping

默认值: 10

反作用力的强度。如果设置为 0，spring 将无限期地振荡。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", damping: 300 }
)

mass

默认值: 1

运动物体的质量。值越高，运动越迟缓。

animate(
  "feTurbulence",
  { baseFrequency: 0.5 },
  { type: "spring", mass: 0.5 }
)

velocity

默认值: 当前值速度

spring 的初始速度。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", velocity: 2 }
)

restSpeed

默认值: 0.1

如果绝对速度（单位为单位/秒）降至此值以下，并且 delta 小于 restDelta，则结束动画。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", restSpeed: 2 }
)

restDelta

默认值: 0.01

如果距离低于此值且速度低于 restSpeed，则结束动画。当动画结束时，spring 将结束。

animate(
  ".my-element",
  { x: 200 },
  { type: "spring", restDelta: 0.5 }
)

编排

delay

默认值: 0

将动画延迟此持续时间（以秒为单位）。

animate(element, { filter: "blur(10px)" }, { delay: 0.3 })

通过将 delay 设置为负值，动画将从动画开始后这么长时间开始。例如，要从 1 秒开始，可以将 delay 设置为 -1。

repeat

默认值: 0

过渡重复的次数。设置为 Infinity 以进行永久动画。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: Infinity, duration: 2 }
)

repeatType

默认值: "loop"

如何重复动画。可以是以下之一

  • loop：从头开始重复动画。

  • reverse：在向前和向后播放之间交替。

  • mirror：在每次迭代时切换动画原点和目标。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatType: "reverse", duration: 2 }
)

repeatDelay

默认值: 0

注意: 在 animate mini 中不可用。

当重复动画时，repeatDelay 将设置每次重复之间等待的时间长度，以秒为单位。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatDelay: 1 }
)

at

当将动画定义为较大序列的一部分时，每个定义将一个接一个地开始

const sequence = [
  ["ul", { opacity: 1 }],
  // This will start when ul opacity is 1
  ["li", { x: [-100, 0] }]
]

通过传递 at，可以更改此行为。

传递一个数字以定义特定时间

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 from the start of the whole timeline:
  ["nav", { x: 100 }, { at: 0.5 }],
]

传递一个以 + 或 - 开头的字符串，以相对于上一个动画的结尾开始

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 seconds after the previous animation:
  ["nav", { x: 100 }, { at: "+0.5" }],
  // This will start 0.2 seconds before the end of the previous animation:
  ["nav li", { opacity: 1 }, { at: "-0.2" }],
]

传递 "<" 以与上一个片段同时开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  // This will start at the same time as the x: 100 animation
  ["li", { opacity: 1 }, { at: "<" }],
]

或传递标签名称以与原始标签定义相同的点开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  "my-label",
  ["li", { opacity: 1 }],
  // my-label was defined at 1 second
  ["a", { scale: 1.2 }, { at: "my-label" }],
]

onUpdate

一个函数，提供最新的动画值。

注意: 目前仅适用于单值和 motion 值动画。

animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

控件

animate() 返回动画播放控件。这些控件可用于暂停、播放、取消、更改播放速度等。

const animation = animate(element, { opacity: 1 })

animation.time = 0.5
animation.stop()

duration

返回动画的持续时间。

这是动画单次迭代的持续时间，不包括延迟或重复选项。它是只读的。

const animation = animate(element, { opacity: 0 })

const duration = animation.duration

time

获取和设置动画的当前时间。

const animation = animate(x, 100, { duration: 1 })

// Set animation time to 0.5 seconds
animation.time = 0.5

// Get animation time
console.log(animation.time) // 0.5

speed

获取和设置动画的当前播放速度。

  • 1 是正常速度。

  • 0.5 是半速。

  • 2 使播放速度加倍。

  • -1 反转播放。

const animation = animate(element, { opacity: 0 })

const currentSpeed = animation.speed

// Double current speed
animation.speed = currentSpeed * 2

then()

一个类似 Promise 的 API，在动画完成时解析

const animation = animate(element, { opacity: 0 })

// Async/await
await animation
console.log("Animation complete")

// Promise
animation.then(() => {
  console.log("Animation complete")
})

注意: 当动画完成时，会创建一个新的 Promise。如果随后通过 play() 方法重新播放动画，则任何旧的回调都不会再次触发。

pause()

暂停动画，直到使用 play() 恢复。

const animation = animate(element, { opacity: 0 })
animation.pause()

play()

播放动画。

  • 如果动画处于暂停状态，它将从当前的 time 恢复。

  • 如果动画已完成，它将重新启动。

animation.pause()

// Will resume from 1 second
animation.time = 1
animation.play()

// Will play from start
await animation
animation.play()

complete()

立即完成动画，使其运行到最终状态。

animation.complete()

cancel()

取消动画，使其恢复到初始状态。

const animation = animate(element, { opacity: 0 })
animation.cancel()

stop()

停止动画。

通过 Web Animations API 制作动画的任何值都将通过 style 提交到元素。

停止的动画无法重新启动。

const animation = animate(element, { opacity: 0 })
animation.stop()

animate() 函数是用于创建和控制动画的强大工具。

animate("li", { opacity: 0 })

它有两种尺寸：mini (2.3kb) 和 hybrid (18kb)。

mini 版本可以使用原生浏览器 API 为 HTML 和 SVG 样式制作动画，以获得惊人的性能。

hybrid 版本还可以额外为以下内容制作动画：

  • 独立的变换 (x/y/rotateZ 等)

  • 更多样式，例如 mask-image 和渐变

  • CSS 变量

  • SVG 路径

  • 动画序列

  • 颜色/字符串/数字

  • JavaScript 对象和 WebGL

用法

animate 可以从 "motion" 包中导入

// Hybrid
import { animate } from "motion"

// Mini
import { animate } from "motion/mini"

HTML & SVG

animate 的两个版本都能够通过直接传递元素或通过 CSS 选择器为 HTML 和 SVG 样式制作动画。

// Element(s)
const box = document.getElementById("box")

animate(box, { opacity: 0 }, { duration: 0.5 })

// CSS selectors
animate("div", { opacity: 0 }, { duration: 0.5 })

变换

hybrid 版本的 animate 可以独立地为每个变换轴制作动画

  • 平移: x, y, z

  • 缩放: scale, scaleX, scaleY

  • 旋转: rotate, rotateX, rotateY, rotateZ

  • 倾斜: skew, skewX, skewY

  • 透视: transformPerspective

animate("div", { rotate: 360 })

CSS 变量

Hybrid animate 可以在所有浏览器中为 CSS 变量制作动画

animate(element, { "--rotate": "360deg" })

Mini animate 只能为已注册的 CSS 属性在现代浏览器中制作动画。

SVG 路径

hybrid animate 函数可以使用三个特殊属性：pathLength、pathSpacing 和 pathOffset，对大多数 SVG 元素执行线条绘制动画。

animate("circle", { pathLength: [0, 1] })

所有这三个属性都设置为介于 0 和 1 之间的进度值，1 表示路径的总长度。

路径动画与 circle、ellipse、line、path、polygon、polyline 和 rect 元素兼容。

单个值

通过传递 to 和 from 值，hybrid animate 将最新的值输出到提供的 onUpdate 回调。

// Numbers
animate(0, 100, {
  onUpdate: latest => console.log(latest)
})

// Colors
animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

Motion 值

通过传递 hybrid animate 一个React motion 值，它将自动使用最新的值进行更新。

const x = motionValue(0)

animate(x, 200, { duration: 0.5 })

对象

可以像 HTML 和 SVG 元素一样为对象制作动画。

const values = {
  x: 100,
  color: "#f00"
}

animate(values, { x: 200, color: "#00f" })

任何对象都可以制作动画，例如来自Three.js:

const camera = new THREE.Camera()

animate(camera.rotation, { y: 360 }, { duration: 10 })

时间线序列

hybrid animate 函数还可以接受复杂的动画序列。

const sequence = []

animate(sequence)

序列 是 animate 定义的数组

const sequence = [
  ["ul", { opacity: 1 }, { duration: 0.5 }],
  ["li", 100, { ease: "easeInOut" }]
]

默认情况下，每个定义将按顺序播放。

可以通过传递一个at选项来更改片段的播放时间，该选项可以是绝对时间、相对时间或标签。

const sequence = [
  ["ul", { opacity: 1 }],
  ["li", { x: [-100, 0] }, { at: 1 }]
]

每个片段都可以接受所有 animate选项（除了 repeatDelay 和 repeatType），以控制该片段的持续时间和其他动画设置。

const sequence = [
  ["ul", { opacity: 1 }, { duration: 1 }]
]

支持 type: "keyframes" 和 type: "spring" 两种过渡类型。

也可以单独覆盖每个值的过渡。

const sequence = [
  [
    "ul",
    { opacity: 1, x: 100 },
    { duration: 1, x: { duration: 2 }}
   ]
]

序列持续时间会自动计算，但也可以传递任何 animate选项来更改整体播放

animate(sequence, { duration: 10, repeat: 2 })

您还可以定义默认过渡设置，通过 defaultTransition 选项传递给序列中的所有项目

animate(sequence, {
  defaultTransition: { duration: 0.2 }
})

animate 支持的任何值都可以在序列中制作动画，在同一动画中混合 HTML 和 SVG、motion 值和对象

const color = motionValue("rgba(255, 0, 0, 1)")
const box = new THREE.BoxGeometry()

const sequence = [
  ["li", { x: 100 }],
  [box.position, { y: 10 }],
  [color, "#444"]
]

交错

当为多个元素制作动画时，可以通过将 stagger 函数传递给 delay 来交错动画。

import { stagger, animate } from "motion"

animate(".item", { x: 300 }, { delay: stagger(0.1) })

选项

可以使用过渡选项配置动画。默认情况下，提供的选项将影响每个动画值。

animate(
  element,
  { x: 100, rotate: 0 },
  { duration: 1 }
)

通过提供命名的过渡，可以在每个值的基础上覆盖这些过渡

animate(
  element,
  { x: 100, rotate: 0 },
  {
    duration: 1,
    rotate: { duration: 0.5, ease: "easeOut" }
  }
)

type

type 决定要使用的动画类型。

Mini animate 可以使用默认的关键帧动画或 spring 进行动画制作

import { animate } from "motion/mini"
import { spring } from "motion"

animate(
  element,
  { transform: "translateX(100px)" },
  { type: spring, stiffness: 300 }
)

Hybrid animate 内置了所有动画类型，可以设置为 "tween"、"spring" 或 "inertia"。

Tween 动画通过持续时间和缓动曲线设置。

Spring 动画可以是基于物理的，也可以是基于持续时间的。

基于物理的 spring 动画通过 stiffness、damping 和 mass 设置，并且这些动画结合了任何现有手势或动画的速度，以实现自然的反馈。

基于持续时间的 spring 动画通过 duration 和 bounce 设置。这些动画不结合速度，但更容易理解。

Inertia 动画根据值的初始速度减速，通常用于实现惯性滚动。

animate("path", { pathLength: 1 }, { duration: 2, type: "tween" })

Tween

duration

默认值: 0.3 (如果定义了多个关键帧，则为 0.8)

动画的持续时间。当也设置了 bounce 时，也可以用于 "spring" 动画。

animate("ul > li", { opacity: 1 }, { duration: 1 })

ease

用于 tween 动画的缓动函数。接受

  • 缓动函数名称。例如 "linear"

  • 一个由四个数字组成的数组，用于定义三次贝塞尔曲线。例如 [.17,.67,.83,.67]

  • 一个 JavaScript 缓动函数，它接受并返回一个 0-1 之间的值。

以下是可用的缓动函数名称

  • "linear"

  • "easeIn", "easeOut", "easeInOut"

  • "circIn", "circOut", "circInOut"

  • "backIn", "backOut", "backInOut"

  • "anticipate"

当为关键帧制作动画时，ease 可以选择设置为缓动函数数组，以在每个值之间设置不同的缓动

animate(
  element,
  { x: [0, 100, 0] },
  { ease: ["easeIn", "easeOut"] }
)

times

当为多个关键帧制作动画时，可以使用 times 来调整每个关键帧在整个动画中的位置。

times 中的每个值都是介于 0 和 1 之间的值，表示动画的开始和结束。

animate(
  element,
  { x: [0, 100, 0] },
  { times: [0, 0.3, 1] }
)

times 的数量必须与关键帧的数量相同。默认为均匀分布的持续时间数组。

Spring

bounce

默认值: 0.25

bounce 确定 spring 动画的“回弹”程度。

0 表示不回弹，1 表示回弹非常强烈。

注意: 如果设置了 stiffness、damping 或 mass，则 bounce 和 duration 将被覆盖。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", bounce: 0.25 }
)

visualDuration

如果设置了 visualDuration，则它将覆盖 duration。

视觉持续时间是一个时间，以秒为单位设置，动画将花费这么长时间在视觉上达到其目标。

换句话说，过渡的大部分将在此时间之前发生，“回弹部分”将主要在此时间之后发生。

这使得编辑 spring 更容易，并且可以使其在视觉上与其他基于时间的动画协调一致。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", visualDuration: 0.5, bounce: 0.25 }
)

stiffness

默认值: 1

spring 的刚度。值越高，产生的运动越突然。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", stiffness: 50 }
)

damping

默认值: 10

反作用力的强度。如果设置为 0，spring 将无限期地振荡。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", damping: 300 }
)

mass

默认值: 1

运动物体的质量。值越高，运动越迟缓。

animate(
  "feTurbulence",
  { baseFrequency: 0.5 },
  { type: "spring", mass: 0.5 }
)

velocity

默认值: 当前值速度

spring 的初始速度。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", velocity: 2 }
)

restSpeed

默认值: 0.1

如果绝对速度（单位为单位/秒）降至此值以下，并且 delta 小于 restDelta，则结束动画。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", restSpeed: 2 }
)

restDelta

默认值: 0.01

如果距离低于此值且速度低于 restSpeed，则结束动画。当动画结束时，spring 将结束。

animate(
  ".my-element",
  { x: 200 },
  { type: "spring", restDelta: 0.5 }
)

编排

delay

默认值: 0

将动画延迟此持续时间（以秒为单位）。

animate(element, { filter: "blur(10px)" }, { delay: 0.3 })

通过将 delay 设置为负值，动画将从动画开始后这么长时间开始。例如，要从 1 秒开始，可以将 delay 设置为 -1。

repeat

默认值: 0

过渡重复的次数。设置为 Infinity 以进行永久动画。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: Infinity, duration: 2 }
)

repeatType

默认值: "loop"

如何重复动画。可以是以下之一

  • loop：从头开始重复动画。

  • reverse：在向前和向后播放之间交替。

  • mirror：在每次迭代时切换动画原点和目标。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatType: "reverse", duration: 2 }
)

repeatDelay

默认值: 0

注意: 在 animate mini 中不可用。

当重复动画时，repeatDelay 将设置每次重复之间等待的时间长度，以秒为单位。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatDelay: 1 }
)

at

当将动画定义为较大序列的一部分时，每个定义将一个接一个地开始

const sequence = [
  ["ul", { opacity: 1 }],
  // This will start when ul opacity is 1
  ["li", { x: [-100, 0] }]
]

通过传递 at，可以更改此行为。

传递一个数字以定义特定时间

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 from the start of the whole timeline:
  ["nav", { x: 100 }, { at: 0.5 }],
]

传递一个以 + 或 - 开头的字符串，以相对于上一个动画的结尾开始

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 seconds after the previous animation:
  ["nav", { x: 100 }, { at: "+0.5" }],
  // This will start 0.2 seconds before the end of the previous animation:
  ["nav li", { opacity: 1 }, { at: "-0.2" }],
]

传递 "<" 以与上一个片段同时开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  // This will start at the same time as the x: 100 animation
  ["li", { opacity: 1 }, { at: "<" }],
]

或传递标签名称以与原始标签定义相同的点开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  "my-label",
  ["li", { opacity: 1 }],
  // my-label was defined at 1 second
  ["a", { scale: 1.2 }, { at: "my-label" }],
]

onUpdate

一个函数，提供最新的动画值。

注意: 目前仅适用于单值和 motion 值动画。

animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

控件

animate() 返回动画播放控件。这些控件可用于暂停、播放、取消、更改播放速度等。

const animation = animate(element, { opacity: 1 })

animation.time = 0.5
animation.stop()

duration

返回动画的持续时间。

这是动画单次迭代的持续时间，不包括延迟或重复选项。它是只读的。

const animation = animate(element, { opacity: 0 })

const duration = animation.duration

time

获取和设置动画的当前时间。

const animation = animate(x, 100, { duration: 1 })

// Set animation time to 0.5 seconds
animation.time = 0.5

// Get animation time
console.log(animation.time) // 0.5

speed

获取和设置动画的当前播放速度。

  • 1 是正常速度。

  • 0.5 是半速。

  • 2 使播放速度加倍。

  • -1 反转播放。

const animation = animate(element, { opacity: 0 })

const currentSpeed = animation.speed

// Double current speed
animation.speed = currentSpeed * 2

then()

一个类似 Promise 的 API，在动画完成时解析

const animation = animate(element, { opacity: 0 })

// Async/await
await animation
console.log("Animation complete")

// Promise
animation.then(() => {
  console.log("Animation complete")
})

注意: 当动画完成时，会创建一个新的 Promise。如果随后通过 play() 方法重新播放动画，则任何旧的回调都不会再次触发。

pause()

暂停动画，直到使用 play() 恢复。

const animation = animate(element, { opacity: 0 })
animation.pause()

play()

播放动画。

  • 如果动画处于暂停状态，它将从当前的 time 恢复。

  • 如果动画已完成，它将重新启动。

animation.pause()

// Will resume from 1 second
animation.time = 1
animation.play()

// Will play from start
await animation
animation.play()

complete()

立即完成动画，使其运行到最终状态。

animation.complete()

cancel()

取消动画，使其恢复到初始状态。

const animation = animate(element, { opacity: 0 })
animation.cancel()

stop()

停止动画。

通过 Web Animations API 制作动画的任何值都将通过 style 提交到元素。

停止的动画无法重新启动。

const animation = animate(element, { opacity: 0 })
animation.stop()

animate() 函数是用于创建和控制动画的强大工具。

animate("li", { opacity: 0 })

它有两种尺寸：mini (2.3kb) 和 hybrid (18kb)。

mini 版本可以使用原生浏览器 API 为 HTML 和 SVG 样式制作动画，以获得惊人的性能。

hybrid 版本还可以额外为以下内容制作动画：

  • 独立的变换 (x/y/rotateZ 等)

  • 更多样式，例如 mask-image 和渐变

  • CSS 变量

  • SVG 路径

  • 动画序列

  • 颜色/字符串/数字

  • JavaScript 对象和 WebGL

用法

animate 可以从 "motion" 包中导入

// Hybrid
import { animate } from "motion"

// Mini
import { animate } from "motion/mini"

HTML & SVG

animate 的两个版本都能够通过直接传递元素或通过 CSS 选择器为 HTML 和 SVG 样式制作动画。

// Element(s)
const box = document.getElementById("box")

animate(box, { opacity: 0 }, { duration: 0.5 })

// CSS selectors
animate("div", { opacity: 0 }, { duration: 0.5 })

变换

hybrid 版本的 animate 可以独立地为每个变换轴制作动画

  • 平移: x, y, z

  • 缩放: scale, scaleX, scaleY

  • 旋转: rotate, rotateX, rotateY, rotateZ

  • 倾斜: skew, skewX, skewY

  • 透视: transformPerspective

animate("div", { rotate: 360 })

CSS 变量

Hybrid animate 可以在所有浏览器中为 CSS 变量制作动画

animate(element, { "--rotate": "360deg" })

Mini animate 只能为已注册的 CSS 属性在现代浏览器中制作动画。

SVG 路径

hybrid animate 函数可以使用三个特殊属性：pathLength、pathSpacing 和 pathOffset，对大多数 SVG 元素执行线条绘制动画。

animate("circle", { pathLength: [0, 1] })

所有这三个属性都设置为介于 0 和 1 之间的进度值，1 表示路径的总长度。

路径动画与 circle、ellipse、line、path、polygon、polyline 和 rect 元素兼容。

单个值

通过传递 to 和 from 值，hybrid animate 将最新的值输出到提供的 onUpdate 回调。

// Numbers
animate(0, 100, {
  onUpdate: latest => console.log(latest)
})

// Colors
animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

Motion 值

通过传递 hybrid animate 一个React motion 值，它将自动使用最新的值进行更新。

const x = motionValue(0)

animate(x, 200, { duration: 0.5 })

对象

可以像 HTML 和 SVG 元素一样为对象制作动画。

const values = {
  x: 100,
  color: "#f00"
}

animate(values, { x: 200, color: "#00f" })

任何对象都可以制作动画，例如来自Three.js:

const camera = new THREE.Camera()

animate(camera.rotation, { y: 360 }, { duration: 10 })

时间线序列

hybrid animate 函数还可以接受复杂的动画序列。

const sequence = []

animate(sequence)

序列 是 animate 定义的数组

const sequence = [
  ["ul", { opacity: 1 }, { duration: 0.5 }],
  ["li", 100, { ease: "easeInOut" }]
]

默认情况下，每个定义将按顺序播放。

可以通过传递一个at选项来更改片段的播放时间，该选项可以是绝对时间、相对时间或标签。

const sequence = [
  ["ul", { opacity: 1 }],
  ["li", { x: [-100, 0] }, { at: 1 }]
]

每个片段都可以接受所有 animate选项（除了 repeatDelay 和 repeatType），以控制该片段的持续时间和其他动画设置。

const sequence = [
  ["ul", { opacity: 1 }, { duration: 1 }]
]

支持 type: "keyframes" 和 type: "spring" 两种过渡类型。

也可以单独覆盖每个值的过渡。

const sequence = [
  [
    "ul",
    { opacity: 1, x: 100 },
    { duration: 1, x: { duration: 2 }}
   ]
]

序列持续时间会自动计算，但也可以传递任何 animate选项来更改整体播放

animate(sequence, { duration: 10, repeat: 2 })

您还可以定义默认过渡设置，通过 defaultTransition 选项传递给序列中的所有项目

animate(sequence, {
  defaultTransition: { duration: 0.2 }
})

animate 支持的任何值都可以在序列中制作动画，在同一动画中混合 HTML 和 SVG、motion 值和对象

const color = motionValue("rgba(255, 0, 0, 1)")
const box = new THREE.BoxGeometry()

const sequence = [
  ["li", { x: 100 }],
  [box.position, { y: 10 }],
  [color, "#444"]
]

交错

当为多个元素制作动画时，可以通过将 stagger 函数传递给 delay 来交错动画。

import { stagger, animate } from "motion"

animate(".item", { x: 300 }, { delay: stagger(0.1) })

选项

可以使用过渡选项配置动画。默认情况下，提供的选项将影响每个动画值。

animate(
  element,
  { x: 100, rotate: 0 },
  { duration: 1 }
)

通过提供命名的过渡，可以在每个值的基础上覆盖这些过渡

animate(
  element,
  { x: 100, rotate: 0 },
  {
    duration: 1,
    rotate: { duration: 0.5, ease: "easeOut" }
  }
)

type

type 决定要使用的动画类型。

Mini animate 可以使用默认的关键帧动画或 spring 进行动画制作

import { animate } from "motion/mini"
import { spring } from "motion"

animate(
  element,
  { transform: "translateX(100px)" },
  { type: spring, stiffness: 300 }
)

Hybrid animate 内置了所有动画类型，可以设置为 "tween"、"spring" 或 "inertia"。

Tween 动画通过持续时间和缓动曲线设置。

Spring 动画可以是基于物理的，也可以是基于持续时间的。

基于物理的 spring 动画通过 stiffness、damping 和 mass 设置，并且这些动画结合了任何现有手势或动画的速度，以实现自然的反馈。

基于持续时间的 spring 动画通过 duration 和 bounce 设置。这些动画不结合速度，但更容易理解。

Inertia 动画根据值的初始速度减速，通常用于实现惯性滚动。

animate("path", { pathLength: 1 }, { duration: 2, type: "tween" })

Tween

duration

默认值: 0.3 (如果定义了多个关键帧，则为 0.8)

动画的持续时间。当也设置了 bounce 时，也可以用于 "spring" 动画。

animate("ul > li", { opacity: 1 }, { duration: 1 })

ease

用于 tween 动画的缓动函数。接受

  • 缓动函数名称。例如 "linear"

  • 一个由四个数字组成的数组，用于定义三次贝塞尔曲线。例如 [.17,.67,.83,.67]

  • 一个 JavaScript 缓动函数，它接受并返回一个 0-1 之间的值。

以下是可用的缓动函数名称

  • "linear"

  • "easeIn", "easeOut", "easeInOut"

  • "circIn", "circOut", "circInOut"

  • "backIn", "backOut", "backInOut"

  • "anticipate"

当为关键帧制作动画时，ease 可以选择设置为缓动函数数组，以在每个值之间设置不同的缓动

animate(
  element,
  { x: [0, 100, 0] },
  { ease: ["easeIn", "easeOut"] }
)

times

当为多个关键帧制作动画时，可以使用 times 来调整每个关键帧在整个动画中的位置。

times 中的每个值都是介于 0 和 1 之间的值，表示动画的开始和结束。

animate(
  element,
  { x: [0, 100, 0] },
  { times: [0, 0.3, 1] }
)

times 的数量必须与关键帧的数量相同。默认为均匀分布的持续时间数组。

Spring

bounce

默认值: 0.25

bounce 确定 spring 动画的“回弹”程度。

0 表示不回弹，1 表示回弹非常强烈。

注意: 如果设置了 stiffness、damping 或 mass，则 bounce 和 duration 将被覆盖。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", bounce: 0.25 }
)

visualDuration

如果设置了 visualDuration，则它将覆盖 duration。

视觉持续时间是一个时间，以秒为单位设置，动画将花费这么长时间在视觉上达到其目标。

换句话说，过渡的大部分将在此时间之前发生，“回弹部分”将主要在此时间之后发生。

这使得编辑 spring 更容易，并且可以使其在视觉上与其他基于时间的动画协调一致。

animate(
  "section",
  { rotateX: 90 },
  { type: "spring", visualDuration: 0.5, bounce: 0.25 }
)

stiffness

默认值: 1

spring 的刚度。值越高，产生的运动越突然。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", stiffness: 50 }
)

damping

默认值: 10

反作用力的强度。如果设置为 0，spring 将无限期地振荡。

animate(
  "section",
  { rotate: 180 },
  { type: "spring", damping: 300 }
)

mass

默认值: 1

运动物体的质量。值越高，运动越迟缓。

animate(
  "feTurbulence",
  { baseFrequency: 0.5 },
  { type: "spring", mass: 0.5 }
)

velocity

默认值: 当前值速度

spring 的初始速度。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", velocity: 2 }
)

restSpeed

默认值: 0.1

如果绝对速度（单位为单位/秒）降至此值以下，并且 delta 小于 restDelta，则结束动画。

animate(
  ".my-element",
  { rotate: 180 },
  { type: "spring", restSpeed: 2 }
)

restDelta

默认值: 0.01

如果距离低于此值且速度低于 restSpeed，则结束动画。当动画结束时，spring 将结束。

animate(
  ".my-element",
  { x: 200 },
  { type: "spring", restDelta: 0.5 }
)

编排

delay

默认值: 0

将动画延迟此持续时间（以秒为单位）。

animate(element, { filter: "blur(10px)" }, { delay: 0.3 })

通过将 delay 设置为负值，动画将从动画开始后这么长时间开始。例如，要从 1 秒开始，可以将 delay 设置为 -1。

repeat

默认值: 0

过渡重复的次数。设置为 Infinity 以进行永久动画。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: Infinity, duration: 2 }
)

repeatType

默认值: "loop"

如何重复动画。可以是以下之一

  • loop：从头开始重复动画。

  • reverse：在向前和向后播放之间交替。

  • mirror：在每次迭代时切换动画原点和目标。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatType: "reverse", duration: 2 }
)

repeatDelay

默认值: 0

注意: 在 animate mini 中不可用。

当重复动画时，repeatDelay 将设置每次重复之间等待的时间长度，以秒为单位。

animate(
  element,
  { backgroundColor: "#fff" },
  { repeat: 1, repeatDelay: 1 }
)

at

当将动画定义为较大序列的一部分时，每个定义将一个接一个地开始

const sequence = [
  ["ul", { opacity: 1 }],
  // This will start when ul opacity is 1
  ["li", { x: [-100, 0] }]
]

通过传递 at，可以更改此行为。

传递一个数字以定义特定时间

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 from the start of the whole timeline:
  ["nav", { x: 100 }, { at: 0.5 }],
]

传递一个以 + 或 - 开头的字符串，以相对于上一个动画的结尾开始

const sequence = [
  ["nav", { opacity: 1 }],
  // This will start 0.5 seconds after the previous animation:
  ["nav", { x: 100 }, { at: "+0.5" }],
  // This will start 0.2 seconds before the end of the previous animation:
  ["nav li", { opacity: 1 }, { at: "-0.2" }],
]

传递 "<" 以与上一个片段同时开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  // This will start at the same time as the x: 100 animation
  ["li", { opacity: 1 }, { at: "<" }],
]

或传递标签名称以与原始标签定义相同的点开始

const sequence = [
  ["nav", { x: 100 }, { duration: 1 }],
  "my-label",
  ["li", { opacity: 1 }],
  // my-label was defined at 1 second
  ["a", { scale: 1.2 }, { at: "my-label" }],
]

onUpdate

一个函数，提供最新的动画值。

注意: 目前仅适用于单值和 motion 值动画。

animate("#fff", "#000", {
  duration: 2
  onUpdate: latest => console.log(latest)
})

控件

animate() 返回动画播放控件。这些控件可用于暂停、播放、取消、更改播放速度等。

const animation = animate(element, { opacity: 1 })

animation.time = 0.5
animation.stop()

duration

返回动画的持续时间。

这是动画单次迭代的持续时间，不包括延迟或重复选项。它是只读的。

const animation = animate(element, { opacity: 0 })

const duration = animation.duration

time

获取和设置动画的当前时间。

const animation = animate(x, 100, { duration: 1 })

// Set animation time to 0.5 seconds
animation.time = 0.5

// Get animation time
console.log(animation.time) // 0.5

speed

获取和设置动画的当前播放速度。

  • 1 是正常速度。

  • 0.5 是半速。

  • 2 使播放速度加倍。

  • -1 反转播放。

const animation = animate(element, { opacity: 0 })

const currentSpeed = animation.speed

// Double current speed
animation.speed = currentSpeed * 2

then()

一个类似 Promise 的 API，在动画完成时解析

const animation = animate(element, { opacity: 0 })

// Async/await
await animation
console.log("Animation complete")

// Promise
animation.then(() => {
  console.log("Animation complete")
})

注意: 当动画完成时，会创建一个新的 Promise。如果随后通过 play() 方法重新播放动画，则任何旧的回调都不会再次触发。

pause()

暂停动画，直到使用 play() 恢复。

const animation = animate(element, { opacity: 0 })
animation.pause()

play()

播放动画。

  • 如果动画处于暂停状态，它将从当前的 time 恢复。

  • 如果动画已完成，它将重新启动。

animation.pause()

// Will resume from 1 second
animation.time = 1
animation.play()

// Will play from start
await animation
animation.play()

complete()

立即完成动画，使其运行到最终状态。

animation.complete()

cancel()

取消动画，使其恢复到初始状态。

const animation = animate(element, { opacity: 0 })
animation.cancel()

stop()

停止动画。

通过 Web Animations API 制作动画的任何值都将通过 style 提交到元素。

停止的动画无法重新启动。

const animation = animate(element, { opacity: 0 })
animation.stop()

animate

示例

超越基础

Motion+是一次性付费，终身会员资格。

除了高级 Motion 功能、抢先体验内容和私有 Discord 社区外，您还将解锁对 90 多个高级示例源代码的访问权限，这些示例将此页面上的 API 提升到一个新的水平。

正在加载...
正在加载...
正在加载...

获取 Motion+

获取 Motion+

获取 Motion+

开始使用 Motion

scroll

保持关注

订阅以获取最新消息和更新。

©2025 Motion Division Ltd.
站点

关于

博客

文档

示例

Motion+

赞助商

社交

Discord

GitHub

X/Twitter

Bluesky

保持关注

订阅以获取最新消息和更新。

©2025 Motion Division Ltd.
站点

关于

博客

文档

示例

Motion+

赞助商

社交

Discord

GitHub

X/Twitter

Bluesky