Vueuse/Motion 指令式动画使用指南

Vueuse/Motion 指令式动画使用指南

指令式动画简介

在 Vue 生态中，Vueuse/Motion 提供了一种优雅的指令式动画解决方案，允许开发者直接在模板中为元素添加动画效果，无需额外的组件封装。这种方式既保持了代码的简洁性，又提供了强大的动画控制能力。

基本用法

v-motion 指令基础

v-motion 是 Vueuse/Motion 的核心指令，可以应用于任何 HTML 元素、SVG 元素或 Vue 组件。指令的使用方式非常直观：

<template>
  <div v-motion />
</template>

动画状态变体

Vueuse/Motion 提供了多种预设的动画状态变体（variants），这些变体对应元素的不同交互状态：

1. initial - 元素挂载前的初始状态
2. enter - 元素挂载后的进入动画
3. visible - 元素进入视口时的动画（离开视口会恢复初始状态）
4. visible-once - 元素首次进入视口时的动画（只触发一次）
5. hovered - 鼠标悬停时的动画效果
6. focused - 元素获得焦点时的动画效果
7. tapped - 点击/触摸时的动画效果

完整示例

<template>
  <div
    v-motion
    :initial="{ opacity: 0, y: 100 }"
    :enter="{ opacity: 1, y: 0, scale: 1 }"
    :variants="{ custom: { scale: 2 } }"
    :hovered="{ scale: 1.2 }"
    :delay="200"
    :duration="1200"
  />
</template>

高级特性

快捷属性

为了简化动画配置，Vueuse/Motion 提供了两个快捷属性：

• delay - 动画延迟时间（毫秒）
• duration - 动画持续时间（毫秒）

这些属性会自动应用到 visible、visible-once 或 enter 变体上，如果没有这些变体，则会应用到 initial 变体。

变体对象整合

除了直接在模板中定义各个变体外，还可以通过 :variants 属性传递一个包含多个变体的对象：

<template>
  <div
    v-motion
    :variants="{
      initial: { opacity: 0 },
      enter: { opacity: 1 },
      custom: { scale: 1.5 }
    }"
  />
</template>

这种方式特别适合需要管理多个复杂变体的场景。

动画实例控制

获取动画实例引用

要为指令式动画添加程序控制，可以通过命名引用和 useMotions 组合式函数来实现：

<template>
  <div
    v-motion="'customAnimation'"
    :initial="{ opacity: 0 }"
    :enter="{ opacity: 1 }"
  />
</template>

<script>
import { useMotions } from '@vueuse/motion'

export default {
  setup() {
    const { customAnimation } = useMotions()
    
    const triggerCustomVariant = () => {
      customAnimation.variant.value = 'custom'
    }
    
    return { triggerCustomVariant }
  }
}
</script>

动画实例方法

获取到的动画实例提供了丰富的方法和属性，可以实现动画的精细控制，包括：

• 动态切换变体
• 手动触发动画
• 监听动画状态变化
• 控制动画暂停/继续

自定义全局指令

Vueuse/Motion 允许开发者注册自定义的全局动画指令，实现动画效果的复用：

import { MotionPlugin } from '@vueuse/motion'
import { createApp } from 'vue'

const app = createApp(App)

app.use(MotionPlugin, {
  directives: {
    'pop-bottom': {
      initial: {
        scale: 0,
        opacity: 0,
        y: 100,
      },
      visible: {
        scale: 1,
        opacity: 1,
        y: 0,
      },
    },
  },
})

app.mount('#app')

注册后，就可以在整个应用中使用 v-motion-pop-bottom 指令：

<template>
  <div v-motion-pop-bottom />
</template>

最佳实践

1. 性能优化：对于复杂的动画序列，建议使用 visible-once 替代 visible 以避免不必要的重复计算
2. 响应式设计：动画属性可以绑定到响应式数据，实现动态动画效果
3. 组合使用：指令式动画可以与组件式动画结合使用，发挥各自优势
4. 调试技巧：在开发过程中，可以通过 useMotions 获取实例并检查当前动画状态

通过 Vueuse/Motion 的指令式动画系统，开发者可以轻松地为 Vue 应用添加专业级的动画效果，同时保持代码的简洁性和可维护性。