motion-v-skilld

motion-v（Motion for Vue）2.4.4

Motion for Vue 是 Motion（原名 Framer Motion）的 Vue 移植版。 它通过 props、运动值和混合引擎为 DOM 和 SVG 添加动画。

已从准备好的源代码中核实的事实：

• 软件包：motion-v 2.4.4，MIT 许可证，仅支持 ESM（package.json:4，package.json:20-33）。
• 对等依赖：vue >= 3.0.0、@vueuse/core >= 10.0.0（package.json:53-56）。
• 引擎依赖：framer-motion、motion-dom、motion-utils，版本均为 ^13.3.0（package.json:57-62）。
• 入口点：motion-v、motion-v/nuxt、motion-v/resolver（package.json:20-33）。
• 根入口重新导出了 framer-motion/dom 的所有内容（dist/es/index.d.ts:1）。因此，animate、stagger、arc、缓动函数等均来自 Motion 引擎。
• 仓库和文档：https://github.com/motiondivision/motion-vue、https://motion.dev/docs/vue

快速开始

npm install motion-v

<script setup>
import { motion } from 'motion-v'
</script>

<template>
  <motion.div :initial="{ opacity: 0 }" :animate="{ opacity: 1, x: 100 }" />
</template>

motion 是一个命名空间，包含适用于每种 HTML 和 SVG 标签的类型化组件 （dist/es/components/motion/index.d.ts:3-182）。例如 motion.div、motion.svg、motion.path 等。

核心模型

• 将 initial、animate、exit、whileHover、whilePress、whileInView、whileFocus、whileDrag 设置为值或变体标签。
• 当 animate 的值发生变化时，元素会向这些值变化。
• transition 用于配置时间、弹簧、延迟和交错效果。
• variants 配合 custom 可支持动态的、针对单个元素的目标值。
• 可动画的值包括独立变换（x、y、scale、rotate、skewX）、颜色和 CSS 变量（dist/es/types/state.d.ts:45-47）。
• 在模板中，使用 : 前缀绑定 motion props。它们是 props，而不是属性。

完整的 props 和钩子列表：references/api-surface.md

硬性规则

这些规则可避免最常见的错误。每条规则都注明了来源。

1. 关注包体积时，使用 m 和 LazyMotion，不要使用 motion。 motion 会打包所有功能，约 34 kb。m 的起始体积接近 6 kb。 对于变体、手势和退出动画，加载 domAnimation。对于拖动和布局动画，加载 domMax。 将 strict 设为 true，以便在开发环境中发现意外使用的 motion。 https://motion.dev/docs/vue-lazymotion, dist/es/components/lazy-motion/index.d.ts:4-13

2. 切勿在 AnimatePresence 本身上使用 v-if。如果它被卸载，就无法拦截子元素的退出动画。 应将条件放在直接子元素上：

   <AnimatePresence>
     <motion.div v-if="isVisible" :exit="{ opacity: 0 }" />
   </AnimatePresence>
   

   https://motion.dev/docs/vue-animate-presence

3. 对于布局动画，将变化的 CSS 应用到 :style，绝不要应用到 :animate。 layout 属性会为测量到的变化添加动画。:animate 中的值会与 FLIP 测量相冲突。 https://motion.dev/docs/vue-layout-animations

4. 将 borderRadius 和 boxShadow 作为内联样式设置在 layout 元素上。 只有当这两个属性作为 :style 中的动态值时，Motion 才会修正缩放失真。 https://motion.dev/docs/vue-layout-animations#scale-correction

5. 在可滚动的祖先元素上添加 layoutScroll，在固定定位的祖先元素上添加 layoutRoot。 如果不添加这些属性，滚动或视口偏移不为零时，布局测量就会出错。 dist/es/components/motion/props.d.ts:71-78

6. 在根级 MotionConfig 上设置 reducedMotion="user"。 默认值为 "never"，因此除非显式启用，否则动画会忽略操作系统的辅助功能设置。 dist/es/components/motion-config/types.d.ts:5-20

7. 使用带 custom 的动态变体实现交错动画，不要在响应式状态中计算延迟。 传入 :custom="index"，并在变体函数中解析 delay。 https://motion.dev/docs/vue-animation

8. 在演示和读数中，使用 <RowValue :value="mv" /> 渲染动态 Motion 值。 它会直接写入 innerHTML，让快速变化的值不经过 Vue 渲染流程。 dist/es/components/RowValue.d.ts:1-15

9. 当包装组件不适用时，对普通元素使用 v-motion。 使用 app.use(MotionPlugin) 进行全局注册，或使用 createPresetDirective 创建预设。 该指令通过 getSSRProps 支持 SSR，并默认启用 domMax 功能。 dist/es/directive/index.mjs:153-172

10. 手势简写属性 focus、hover、press、inView 已在 v2.0.0 中移除。 动画请使用 whileFocus、whileHover、whilePress、whileInView，逻辑请使用 onHoverStart 等事件属性。 参见 references/migration.md

常见任务

进入和退出、交错动画、拖动、滚动联动、命令式 useAnimate、共享布局、Reorder 列表、指令用法、LazyMotion 和 Nuxt 设置，每项均附有可运行的代码片段：references/recipes.md

自 2.2.1 基线版本以来的变更

• 2.3.0：新增沿圆弧运动的 arc()，可用作 transition: { path: arc(...) }。useAnimate 现在会遵循 MotionConfig skipAnimations。
• 2.4.0：Reorder 支持多维度；Reorder.Group 新增 axis="xy"。
• 2.4.2：恢复了 KeepAlive 缓存组件的退出和进入动画。
• 2.4.4：Nuxt 模块在构建时不再转译 motion-v。

详情和链接：references/migration.md

特定版本说明

• SVG 位置使用 attrX、attrY、attrScale，而不是 x、y、scale（dist/es/types/state.d.ts:15-20）。
• useSpring 接受一个值或 MotionValue 源，并返回匹配的类型（dist/es/value/use-spring.d.ts:6-7）。
• useTransform 可映射范围，也可在一次调用中返回带名称的输出映射（dist/es/value/use-transform.d.ts:54-97）。
• AnimatePresence 支持 mode 值 sync、wait、popLayout，并支持用于指定 popLayout 退出方向的 anchorX（dist/es/components/animate-presence/types.d.ts:1-8）。
• 指令和组件共用一个解析器，因此 v-motion 会继承变体、presence 和配置上下文（dist/es/utils/resolve-motion-props.d.ts:11-15）。