motion-v-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

motiondivision/motion-vue

motion-v

motiondivision/motion-vue

motion-v

Version: 2.0.0-beta.4 (Feb 2026) Deps: framer-motion@^12.29.2, hey-listen@^1.0.8, motion-dom@^12.29.2, motion-utils@^12.29.2 Tags: latest: 2.0.0-beta.4 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

**版本：**2.0.0-beta.4（2026年2月） **依赖：**framer-motion@^12.29.2, hey-listen@^1.0.8, motion-dom@^12.29.2, motion-utils@^12.29.2 **标签：**latest: 2.0.0-beta.4（2026年2月）

参考文档：文档 — API参考、使用指南 • GitHub Issues — 问题反馈、解决方案、边缘场景 • GitHub Discussions — 问答、模式参考、使用示例 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING:
```
focus
```
,
```
hover
```
,
```
press
```
,
```
inView
```
shorthand props — removed in v2.0.0-beta.1. Use
```
whileFocus
```
,
```
whileHover
```
,
```
whilePress
```
, and
```
whileInView
```
for animations, and full event handlers (e.g.
```
@hoverStart
```
,
```
@pressStart
```
) for logic source
NEW:
```
v-motion
```
directive — new in v2.0.0-beta.1, enables declarative animations on any element without requiring a
```
<motion>
```
component wrapper source
BREAKING: ESM-only — v2.0.0-beta.1 dropped CommonJS support. The package now only ships ESM (
```
.mjs
```
) exports source
NEW:
```
MotionPlugin
```
— new in v2.0.0-beta.1, a Vue plugin for global
```
v-motion
```
and custom preset directive registration
NEW:
```
createPresetDirective()
```
— new in v2.0.0-beta.1, allows creating reusable animation directives with baked-in motion options
BREAKING:
```
AnimatePresence
```
lazy discovery — v2.0.0-beta.1 refactored to use
```
data-ap
```
attribute for lazy discovery instead of eager registration source
DEPRECATED:
```
staggerChildren
```
and
```
staggerDirection
```
— deprecated in v1.4.0 in favor of using the
```
stagger()
```
utility within the
```
transition
```
prop source
NEW:
```
stagger()
```
utility — correctly handles staggering for newly-entering siblings alongside existing ones since v1.7.0 source
NEW:
```
useTransform
```
output maps — supports providing multiple output value maps for complex coordinate transformations since v1.9.0 source
NEW:
```
Reorder
```
auto-scrolling — supports automatic parent container scrolling when a
```
Reorder.Item
```
is dragged to the edges since v1.8.0 source
NEW:
```
useScroll
```
VueInstance support —
```
container
```
and
```
target
```
options now accept
```
VueInstance
```
(ref to component) since v1.6.0 source
NEW:
```
useInView
```
```
root
```
option — now accepts
```
MaybeRef
```
for dynamic root element assignment since v1.6.0 source
NEW:
```
AnimatePresence
```
direct children — supports multiple direct
```
motion
```
components as children since v1.10.0 source
NEW:
```
delayInMs
```
— exported as a standalone utility function for time-based animation delays since v1.6.0 source

Also changed:

useTransform

reactive update fix (v1.2.1) ·

sequence

at relative start (v1.3.0) ·

AnimatePresence

custom prop fix (v1.3.0) ·

motionGlobalConfig

exported (v2.0.0-beta.1) ·

FeatureBundle

tree-shaking architecture (v2.0.0-beta.1)

本部分记录各版本专属的API变更，请优先关注近期的主要/次要版本更新。

破坏性变更：
```
focus
```
,
```
hover
```
,
```
press
```
,
```
inView
```
简写属性 — 在v2.0.0-beta.1中移除。动画效果请使用
```
whileFocus
```
、
```
whileHover
```
、
```
whilePress
```
和
```
whileInView
```
，逻辑处理请使用完整事件处理器（如
```
@hoverStart
```
、
```
@pressStart
```
）来源
新增：
```
v-motion
```
指令 — v2.0.0-beta.1新增，无需使用
```
<motion>
```
组件包裹，即可为任意元素添加声明式动画来源
破坏性变更：仅支持ESM — v2.0.0-beta.1移除了CommonJS支持。该包现在仅提供ESM（.mjs）格式的导出来源
新增：
```
MotionPlugin
```
— v2.0.0-beta.1新增，是一个Vue插件，用于全局注册
```
v-motion
```
和自定义预设指令
新增：
```
createPresetDirective()
```
— v2.0.0-beta.1新增，允许创建包含内置动画选项的可复用动画指令
破坏性变更：
```
AnimatePresence
```
惰性发现 — v2.0.0-beta.1重构为使用
```
data-ap
```
属性进行惰性发现，而非提前注册来源
已弃用：
```
staggerChildren
```
和
```
staggerDirection
```
— 在v1.4.0中被弃用，建议在
```
transition
```
属性中使用
```
stagger()
```
工具函数替代来源
新增：
```
stagger()
```
工具函数 — 自v1.7.0起，可正确处理新进入的兄弟元素与现有元素的交错动画来源
新增：
```
useTransform
```
输出映射 — 自v1.9.0起，支持提供多个输出值映射以实现复杂的坐标转换来源
新增：
```
Reorder
```
自动滚动 — 自v1.8.0起，当
```
Reorder.Item
```
被拖拽到容器边缘时，支持父容器自动滚动来源
新增：
```
useScroll
```
Vue实例支持 — 自v1.6.0起，
```
container
```
和
```
target
```
选项现在接受
```
VueInstance
```
（组件的ref引用）来源
新增：
```
useInView
```
```
root
```
选项 — 自v1.6.0起，支持接受
```
MaybeRef
```
以动态设置根元素来源
新增：
```
AnimatePresence
```
直接子元素 — 自v1.10.0起，支持多个直接
```
motion
```
组件作为子元素来源
新增：
```
delayInMs
```
— 自v1.6.0起，作为独立的工具函数导出，用于基于时间的动画延迟来源

其他变更：

useTransform

响应式更新修复（v1.2.1）·

sequence

相对起始位置（v1.3.0）·

AnimatePresence

自定义属性修复（v1.3.0）·

motionGlobalConfig

导出（v2.0.0-beta.1）·

FeatureBundle

摇树优化架构（v2.0.0-beta.1）

Best Practices

最佳实践

Create motion-supercharged components using
```
motion.create()
```
outside of the template to avoid re-creating the component on every render, which would break animations source

// Preferred
const MotionComponent = motion.create(Component)

// Avoid - re-created every render
<component :is="motion.create(Component)" />

Use
```
MotionValue
```
s in the
```
style
```
prop to animate values outside of the Vue render cycle, significantly improving performance by avoiding frequent re-renders source

vue

<script setup>
const x = useMotionValue(0)
</script>

<template>
  <motion.div :style="{ x }" />
</template>

Reduce initial bundle size from ~34kb to ~6kb by using the
```
m
```
component paired with
```
LazyMotion
```
to load features synchronously or asynchronously only when needed source

vue

<template>
  <LazyMotion :features="domAnimation">
    <m.div :animate="{ opacity: 1 }" />
  </LazyMotion>
</template>

Enable the
```
strict
```
prop on
```
LazyMotion
```
during development to catch accidental usage of the full
```
motion
```
component, which would negate the bundle size benefits of lazy loading source
Centralize animation settings like global transitions and site-wide
```
reducedMotion
```
policies using
```
MotionConfig
```
to ensure consistent behavior across all child components source
(experimental) Apply declarative animations directly to any standard HTML/SVG element using the
```
v-motion
```
directive in v2.0.0-beta.1+ without needing to wrap elements in a
```
<motion>
```
component source
Ensure
```
AnimatePresence
```
children have unique, stable
```
key
```
props and are direct children of the component to correctly track their removal for exit animations source
Synchronize layout animations across unrelated components (those that don't share a parent-child relationship but affect each other's layout) by wrapping them in a
```
LayoutGroup
```
source
Prevent visual distortion of child elements during parent layout animations by applying the
```
layout
```
prop to the immediate children as well, enabling scale correction source
Mark scrollable ancestors with
```
layoutScroll
```
and fixed-position ancestors with
```
layoutRoot
```
to ensure Motion correctly accounts for scroll offsets during layout measurements source

在模板外部使用
```
motion.create()
```
创建增强动画的组件，避免每次渲染时重新创建组件，否则会导致动画失效来源

// Preferred
const MotionComponent = motion.create(Component)

// Avoid - re-created every render
<component :is="motion.create(Component)" />

在
```
style
```
属性中使用
```
MotionValue
```
来在Vue渲染周期外执行动画，通过避免频繁重渲染显著提升性能来源

vue

<script setup>
const x = useMotionValue(0)
</script>

<template>
  <motion.div :style="{ x }" />
</template>

通过搭配使用
```
m
```
组件和
```
LazyMotion
```
，将初始包体积从约34kb减小到约6kb，实现按需同步或异步加载所需功能来源

vue

<template>
  <LazyMotion :features="domAnimation">
    <m.div :animate="{ opacity: 1 }" />
  </LazyMotion>
</template>

在开发阶段为
```
LazyMotion
```
启用
```
strict
```
属性，防止意外使用完整的
```
motion
```
组件，否则会抵消懒加载带来的包体积优化效果来源
使用
```
MotionConfig
```
集中管理动画设置，比如全局过渡效果和站点级
```
reducedMotion
```
策略，确保所有子组件的行为一致来源
（实验性）在v2.0.0-beta.1及以上版本中，可使用
```
v-motion
```
指令直接为任意标准HTML/SVG元素添加声明式动画，无需将元素包裹在
```
<motion>
```
组件中来源
确保
```
AnimatePresence
```
的子元素拥有唯一且稳定的
```
key
```
属性，并且是该组件的直接子元素，这样才能正确跟踪元素的移除并执行退出动画来源
通过将不相关的组件（无父子关系但会互相影响布局的组件）包裹在
```
LayoutGroup
```
中，实现跨组件的布局动画同步来源
在父组件执行布局动画时，为直接子元素添加
```
layout
```
属性以启用缩放校正，防止子元素出现视觉变形来源
为可滚动的祖先元素添加
```
layoutScroll
```
属性，为固定定位的祖先元素添加
```
layoutRoot
```
属性，确保Motion在测量布局时正确考虑滚动偏移来源