Motion 通用交互

用法

Registry 交互

TxMotion 提供 7 种入场、4 种悬停、3 种指针和 3 种滚动效果。演示逐项展示全部变体、实际指针坐标、滚动进度、固定内容，以及图标状态切换和视口挂载。

示例加载中...

命名变体

分组	ID 与行为
入场	`fade-in` 改变透明度；`fade-up` / `fade-down` 使用垂直偏移；`slide-left` / `slide-right` 使用水平偏移；`scale-in` 从 0.92 缩放并回弹；`zoom-in` 从 0.85 缩放并消除 12px 模糊。
悬停	`card-hover` 在调用方条目之间移动共用背景；`tilt-card` 将归一化指针坐标映射为三维旋转；`magnetic-button` 在距离阈值内磁吸；`glow-button` 将 120px 径向光移到指针位置。
指针	`cursor-trail` 使用逐渐缩小、各有 spring 参数的圆点；`spotlight` 在内容上移动 250px 聚光；`mouse-follow` 用 spring 跟随指针，并提供 `cursor` 插槽。
滚动	`scroll-reveal` 进入配置的视口后揭示内容；`progress-indicator` 用 spring 跟随实际滚动进度；`sticky-reveal` 将目标相对滚动进度映射为当前条目与固定画面。
支持组件	`icon-swap` 承载 IconSwap / IconSwapItem，按 key 切换缩放、模糊和透明度；`in-view` 承载 InViewRender，在接近视口时挂载插槽。

最佳实践

由调用方提供内容、条目和操作处理。组件不执行导航、复制或发布，也不制造业务成功状态。
原生磁吸按钮、发光按钮和进度条应提供 label。卡片条目有 href 时渲染原生链接，否则渲染原生按钮并发出 select。
默认将指针效果限定在当前组件内。global 将全局指针层和顶部进度条 Teleport 到 body，避免祖先 transform 改变固定定位。装饰指针不向辅助技术朗读。
嵌套滚动应把实际元素传给 scrollContainer。未传时读取文档滚动。固定揭示舞台与步骤按该容器的可见高度布置并监听尺寸变化，不把文档 vh 当作嵌套容器高度；调用方仍须保留有效滚动范围。
修改 stateKey 或调用暴露的 replay() 回放入场。icon-swap 的 key 应随真实状态更新，插槽同时提供对应图标。
enabled=false 暂停动画及输入资源，保留可读内容。减少动态效果时，语义滚动进度继续更新，内容与图标立即显示最终状态。
in-view 的宿主应保留稳定尺寸，避免布局跳动。once=true 在首次进入后保留挂载内容；once=false 在离开视口时卸载内容。

API 参考

属性

属性	类型	默认值	说明
`variant`	`MotionVariant`	`'fade-in'`	上表所有命名变体；枚举导出为 `MOTION_VARIANTS`。
`as`	`string`	磁吸/发光为原生 `button`，其余为 `div`	根元素。原生按钮属性与事件透传。
`enabled`	`boolean`	`true`	启用动态效果和输入追踪。
`disabled`	`boolean`	`false`	禁用原生按钮和输入驱动效果。
`label`	`string`	—	无障碍名称；图标按钮与进度条应提供。
`duration`	`number`	入场依变体为 500 / 600 / 700ms；图标为 300ms	持续时间，单位毫秒。
`delay`	`number`	`0`	入场延迟，单位毫秒。
`xOffset`	`number`	向左为 `40`，向右为 `-40`，其余为 `0`	入场起始 x 坐标。
`yOffset`	`number`	向上为 `20`，向下为 `-20`，滚动揭示为 `30`，其余为 `0`	入场起始 y 坐标。
`initialScale`	`number`	scale 为 `0.92`，zoom 为 `0.85`，滚动揭示为 `0.95`，其余为 `1`	起始缩放。
`initialBlur`	`number`	`12`	Zoom 的起始模糊半径，单位像素。
`maxTilt`	`number`	`15`	指针到边缘时的最大旋转角。
`range`	`number`	`45`	磁吸中心距离阈值，单位像素。
`strength`	`number`	`0.35`	磁吸坐标倍率。
`spring`	`SpringConfig`	各来源参数	覆盖指针、拖尾与进度的 stiffness、damping 和 mass；使用共用 spring 积分器。
`glowColor`	`string`	`'var(--tx-color-primary)'`	聚光、指针与进度颜色，建议传主题 token。
`glowSize`	`number`	发光按钮 `120`；聚光 `250`	径向效果半径，单位像素。
`cursorSize`	`number`	`8`	拖尾首点直径；跟随指针的轮廓至少为 24px。
`cursorCount`	`number`	`6`	拖尾圆点数量，限制为 1～64。各点独立缩小并使用不同 spring。
`global`	`boolean`	`false`	全局指针坐标与 Teleport；固定顶部进度条。
`scrollContainer`	`HTMLElement \| null`	文档	观察视口与进度的滚动容器。
`progressHeight`	`number`	`4`	进度条高度，单位像素。
`stickyTop`	`number`	`20`	固定画面的顶部偏移，单位像素。
`items`	`MotionItem[]`	`[]`	卡片/固定揭示内容：`{ id, title, description?, href?, disabled? }`。
`once`	`boolean`	`true`	保留首次入场或可见性挂载。
`rootMargin`	`string`	揭示 `'-15%'`；in-view `'200px'`	IntersectionObserver 边距。
`stateKey`	`string \| number \| boolean`	`0`	入场回放标识或图标身份。
`transition`	`Transition`	来源入场缓动 / 共用 `'smooth'`	覆盖入场与卡片背景运动的共用转场参数。

事件

事件	参数	说明
`complete`	—	入场动画正常完成。暂停时取消动画，不报告完成。
`progress`	`number`	0～1 的实际滚动进度。
`active-change`	`number`	当前固定揭示条目索引。
`select`	`(item: MotionItem, index: number)`	可用卡片通过指针或键盘激活。
`visible-change`	`boolean`	揭示/in-view 交集改变。

插槽与暴露状态

名称	参数 / 类型	说明
`default`	通用效果为 `{ pointer, progress, active }`	调用方内容；`icon-swap` 应传入与 `stateKey` 一致的图标。
`item`	`{ item, index, active }`	卡片条目或固定揭示文字。
`visual`	`{ item, index, active }`	固定画面。非当前层使用 `inert`，并对辅助技术隐藏。
`cursor`	—	跟随指针装饰。
`replay()`	`() => void`	动态效果活跃时回放入场。
`progress`	`number`	实际滚动进度；Vue 对内部只读 ref 自动解包。
`activeIndex`	`number`	固定揭示选择；Vue 对内部 computed ref 自动解包。

Vue 辅助 API

从 @talex-touch/tuffex/motion 导入以下能力，不改用 utils barrel。浏览器资源遵循挂载、KeepAlive 与文档可见性。SSR 不访问浏览器 API。

导出	输入	实际输出
`useMousePosition`	可选目标 ref、启用 getter、全局 getter	只读 ref：`{ x, y, elementX, elementY, width, height, inside }`，来自原生指针坐标。触摸不生成悬停装饰。
`useScrollProgress`	容器 getter、启用 getter、可选目标 getter	只读 0～1 ref。未传目标时为 scrollTop / 滚动范围；传目标时为 start-start 到 end-end 的相对进度。
`useStagger`	数量 getter、`{ baseDelay?, staggerDelay?, from? }` getter	毫秒延迟数组。默认起始 0ms、步长 50ms、从首项开始；支持末项、中心和数值起点。
`useReducedMotion`	—	既有共用响应式偏好，不另建媒体查询实现。
`useScreenSize`	可选启用 getter	只读视口宽高，SSR 初值为 0/0。
`useIsMobile`	断点 getter，默认 `768`	只读媒体查询结果。屏幕宽度不被当作用户的减少动态效果偏好。
`useLoopFlag`	目标 ref、启用 getter、间隔 getter（`2000ms`）	只读递增标记。离屏、隐藏、禁用、减少动态效果和停用时暂停。
`useWebHaptics`	可选启用 getter	`{ supported, trigger(type) }`。触发返回 `{ supported, accepted }`；类型为 light、medium、heavy、success、warning 和 error。复用既有震动工具。
`useCanvasSetup`	Canvas ref、启用 getter	缓存逻辑尺寸 `{ width, height, dpr }`，更新实际像素尺寸，并返回 `active`、`visible`、`reduced`。DPR 最大为 2，绘制由调用方负责。

accepted=true 只表示浏览器接受了 Vibration API 请求，不能证明设备实际震动。不支持该 API 的 macOS 桌面浏览器返回 supported=false，组件不宣称设备已产生反馈。

概述

共用 spring 驱动倾斜、磁吸、各个拖尾圆点、鼠标跟随和滚动进度。逐帧工作静止后停止，失活时取消。页面隐藏、离屏、KeepAlive 停用或卸载时，WAAPI 入场与图标转场取消。观察器、尺寸/指针/滚动监听、循环定时器和震动归属由 Vue 生命周期释放。没有 IntersectionObserver 时，仍提供可读内容。

来源为 Amicro 的 MIT 入场、悬停、指针和滚动 registry，以及 IconSwap、InViewRender 与辅助 hooks。Copyright (c) 2026 SYED SUBHAN UDDIN。实现使用 Vue、既有 motion-activity、Liquid spring 和震动工具，不加入 React、Motion 或 Tailwind 运行时。验证由负责集成的 Build 执行，本页不宣称已经完成浏览器验收。