vueuse-motion-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vueuse/motion

@vueuse/motion

vueuse/motion

@vueuse/motion

Version: 3.0.3 (Mar 2025) Deps: @vueuse/core@^13.0.0, @vueuse/shared@^13.0.0, defu@^6.1.4, framesync@^6.1.2, popmotion@^11.0.5, style-value-types@^5.1.2 Tags: beta: 2.0.0-beta.29 (May 2023), latest: 3.0.3 (Mar 2025)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • Releases — changelog, breaking changes, new APIs

版本：3.0.3（2025年3月） 依赖：@vueuse/core@^13.0.0、@vueuse/shared@^13.0.0、defu@^6.1.4、framesync@^6.1.2、popmotion@^11.0.5、style-value-types@^5.1.2 标签：beta: 2.0.0-beta.29（2023年5月）、latest: 3.0.3（2025年3月）

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

API Changes

API变更

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

BREAKING: ESM-only —
```
@vueuse/motion
```
v3.0.0 dropped CommonJS (CJS) support, the package is now ESM-only source
NEW: VueUse v13 support — updated dependencies to support the latest VueUse features in v3.0.0 source
NEW:
```
<Motion>
```
component — declarative component for animations, offering better SSR and MDC support since v2.2.0 source
NEW:
```
<MotionGroup>
```
component — renderless component introduced in v2.2.0 to apply motion configurations to all child elements source
NEW:
```
duration
```
and
```
delay
```
shorthand props — support for setting transition timing directly on elements/components since v2.2.0 source
BREAKING: Drop Vue 2 support — v2.0.0 and above exclusively support Vue 3 source
NEW: Full SSR support — significantly improved server-side rendering compatibility for both components and directives in v2.0.0 source
NEW: kebab-case directive support —
```
v-motion-initial
```
and other directive variants now support kebab-case since v2.1.0 source
NEW:
```
useMotionFeatures
```
export — this composable is now exported for manual feature registration since v2.2.6 source
NEW:
```
useMotion
```
dynamic keys — support for dynamic variant keys when calling
```
.apply()
```
and other methods since v2.1.0 source
NEW:
```
reactive-style
```
and
```
reactive-transform
```
— specialized composables for direct style and transform manipulation since v2.0.0 source
NEW:
```
MotionPlugin
```
types — enhanced TypeScript definitions for the main Vue plugin in v2.2.5 source
BREAKING:
```
onComplete
```
triggers — fixed in v2.2.0 to trigger after each property animation completes instead of only once source
NEW:
```
unref
```
directive bindings — directives now unref initial bindings, supporting refs within objects since v2.0.0 source

Also changed:

visibilityOnce

variant new v2.0.0 ·

useSpring

documentation update v2.2.0 ·

preset

mutation fix v2.2.0 ·

useMotions

dynamic keys v2.1.0 ·

useMotionVariants

internal updates v2.0.0

本节记录了特定版本的API变更——优先关注近期的主要/次要版本更新。

破坏性变更：仅支持ESM ——
```
@vueuse/motion
```
v3.0.0 移除了对CommonJS (CJS)的支持，当前包仅支持ESM 来源
新增：支持VueUse v13 —— v3.0.0中更新了依赖以支持VueUse的最新特性来源
新增：
```
<Motion>
```
组件 —— 声明式动画组件，自v2.2.0起提供更好的SSR和MDC支持来源
新增：
```
<MotionGroup>
```
组件 —— 自v2.2.0起引入的无渲染组件，用于为所有子元素应用动画配置来源
新增：
```
duration
```
和
```
delay
```
简写属性 —— 自v2.2.0起支持直接在元素/组件上设置过渡时间来源
破坏性变更：移除Vue 2支持 —— v2.0.0及以上版本仅支持Vue 3 来源
新增：完整SSR支持 —— v2.0.0中显著提升了组件和指令的服务端渲染兼容性来源
新增：短横线命名法指令支持 —— 自v2.1.0起，
```
v-motion-initial
```
及其他指令变体支持短横线命名法来源
新增：导出
```
useMotionFeatures
```
—— 自v2.2.6起，该组合式函数被导出用于手动注册特性来源
新增：
```
useMotion
```
动态键 —— 自v2.1.0起，调用
```
.apply()
```
及其他方法时支持动态变体键来源
新增：
```
reactive-style
```
和
```
reactive-transform
```
—— 自v2.0.0起新增的专用组合式函数，用于直接操作样式和变换来源
新增：
```
MotionPlugin
```
类型定义 —— v2.2.5中增强了主Vue插件的TypeScript类型定义来源
破坏性变更：
```
onComplete
```
触发时机 —— v2.2.0中修复为在每个属性动画完成后触发，而非仅触发一次来源
新增：指令绑定支持
```
unref
```
—— 自v2.0.0起，指令现在支持对初始绑定进行unref，支持对象内的refs 来源

其他变更：

visibilityOnce

变体新增于v2.0.0 ·

useSpring

文档更新于v2.2.0 ·

preset

修改修复于v2.2.0 ·

useMotions

动态键支持于v2.1.0 ·

useMotionVariants

内部更新于v2.0.0

Best Practices

最佳实践

Avoid deconstructing
```
useMotions()
```
at the top level of
```
setup
```
because properties are registered after the script execution; access them via the returned object within methods or hooks to ensure reactivity source

// Preferred
const motions = useMotions()
const play = () => motions.myElement?.variant.value = 'play'

// Avoid
const { myElement } = useMotions()

Use camelCase for visibility variants in Nuxt 3 templates (e.g.,
```
visibleOnce
```
) rather than kebab-case (
```
visible-once
```
) to ensure proper directive resolution and avoid warnings source
Prefer the
```
<Motion>
```
component over the
```
v-motion
```
directive for projects requiring robust SSR, as it handles initial state style injection more reliably for SEO and UX source
Define custom directives in the
```
MotionPlugin
```
configuration to create reusable animation presets that can be applied consistently via
```
v-motion-[name]
```
across the application source
Use
```
<MotionGroup>
```
to apply a single animation configuration or preset to multiple child elements, significantly reducing template boilerplate and improving maintainability source
Map the
```
leave
```
helper from the motion instance to the Vue
```
<transition>
```
element's
```
@leave
```
event to perform manual and synchronized exit animations on elements source

const { leave } = useMotion(target, { leave: { opacity: 0 } })

// In template
// <transition @leave="(el, done) => leave(done)">

Always specify an
```
initial
```
variant containing all properties that will be animated to prevent unexpected layout shifts and ensure smooth transitions from a known base state source
Utilize
```
useSpring
```
with
```
useMotionProperties
```
for high-performance, frame-rate independent animations that require physical continuity, such as for interactive gestures source
In Nuxt applications, use
```
runtimeConfig.public.motion.directives
```
to define global custom directives, ensuring they are properly initialized during both client and server rendering source
Pass a reactive reference as the
```
target
```
to
```
useMotion
```
to allow the motion instance to automatically track and apply the current variant to new elements as they are updated source

避免在
```
setup
```
的顶层解构
```
useMotions()
```
，因为属性是在脚本执行后才注册的；应在方法或钩子中通过返回的对象访问它们，以确保响应式来源

// 推荐写法
const motions = useMotions()
const play = () => motions.myElement?.variant.value = 'play'

// 避免写法
const { myElement } = useMotions()

在Nuxt 3模板中对可见性变体使用驼峰命名法（如
```
visibleOnce
```
）而非短横线命名法（
```
visible-once
```
），以确保指令正确解析并避免警告来源
对于需要可靠SSR的项目，优先使用
```
<Motion>
```
组件而非
```
v-motion
```
指令，因为它能更可靠地处理初始状态样式注入，利于SEO和用户体验来源
在
```
MotionPlugin
```
配置中定义自定义指令，创建可复用的动画预设，可通过
```
v-motion-[name]
```
在整个应用中一致地应用来源
使用
```
<MotionGroup>
```
为多个子元素应用单一动画配置或预设，显著减少模板冗余并提升可维护性来源
将motion实例中的
```
leave
```
辅助函数映射到Vue
```
<transition>
```
元素的
```
@leave
```
事件，以实现元素的手动同步退出动画来源

const { leave } = useMotion(target, { leave: { opacity: 0 } })

// 在模板中
// <transition @leave="(el, done) => leave(done)">

始终指定包含所有将被动画化属性的
```
initial
```
变体，以防止意外的布局偏移并确保从已知基础状态开始的平滑过渡来源
结合
```
useSpring
```
和
```
useMotionProperties
```
实现高性能、帧率无关的动画，这类动画需要物理连续性，例如交互式手势场景来源
在Nuxt应用中，使用
```
runtimeConfig.public.motion.directives
```
定义全局自定义指令，确保它们在客户端和服务端渲染期间都能正确初始化来源
向
```
useMotion
```
传入响应式引用作为
```
target
```
，使motion实例能够自动跟踪并将当前变体应用于更新后的新元素来源