动态加载器

概述

TxMotionLoader 保留 Amicro 的 134 个命名加载实现，再加入 3 个 CSS 加载器。每个变体都有对应源码的几何结构、运动轨迹、相位和节奏。下表保留原始 ID 和导出名。组件用于进度未知的等待状态，不会报告业务完成。

根节点是礼貌播报的状态区域，带有稳定的无障碍名称。动画画面不进入无障碍树。只有 playing=true、组件已挂载且可见、页面可见、用户未要求减少动态效果时才播放。任意条件关闭后，组件取消原生动画，保留可读静态画面。恢复时重新开始对应源码的节奏。

用法

全部命名场景

筛选完整目录，逐项或批量控制播放，并调整尺寸、速度和本地化状态文字。滚动目录包含全部 137 项，离开可见区域的项目不会播放动画。

受控播放

playing 表示播放请求，可见性和减少动态效果设置仍优先。修改源 ID 会切换几何结构。旧场景先释放资源，新场景再开始播放。

<script setup lang="ts">
import { ref } from 'vue'
import { TxMotionLoader } from '@talex-touch/tuffex'

const playing = ref(true)
</script>

<template>
  <TxMotionLoader
    variant="wave-physics-loader"
    :playing="playing"
    :labels="{ loading: '加载中', paused: '已暂停' }"
  />
  <button type="button" @click="playing = !playing">切换播放状态</button>
</template>

最佳实践

• 首次加载的内容占位优先使用 TxSkeleton 或 TxRowSkeleton。短时间、进度未知的等待状态可以选择适合当前界面的动态加载器。
• 让 playing 跟随真实等待状态。暂停动画不代表请求完成，因此状态区域仍标记为忙碌。
• 按当前语言提供 label 和 labels。文本变体使用这些文字，包括逐字波浪和弹起场景。
• 进度可计算时使用 TxProgressBar。加载器不会模拟百分比，也不会在定时器到期后伪报成功。
• 保持适中的速度。离屏、隐藏页面、KeepAlive 和减少动态效果的暂停由组件统一处理。

API 参考

属性

文字配置

事件

无组件专属事件。宿主控制真实等待状态和 playing 属性。

插槽

无插槽。文本场景从 labels 读取内容，不以通用画面替代缺失内容。

导出

• TxMotionLoader 和可安装的 MotionLoader 组件。
• MOTION_LOADER_VARIANTS：枚举全部 137 个源 ID 的只读元组。MotionLoaderVariant 从这个元组推导。
• MOTION_LOADER_SOURCES：每项包含 id、原始导出名 name 和固定上游路径 source 的类型化记录。
• MotionLoaderProps、MotionLoaderLabels、MotionLoaderSize、MotionLoaderSource 和 TxMotionLoaderInstance。

来源映射

来源固定在 Amicro 提交 43c29ce9cdd16459e3eab4992381b8d35b38776a，遵循 MIT 许可，Copyright (c) 2026 SYED SUBHAN UDDIN。下表记录源码的运动值和逐节点相位，不按名称推测动画。原生 spin 工具类保留一秒线性旋转。源码未指定缓动时使用原有的 ease-out 默认值。

技术实现

源声明渲染为原生 HTML 和 SVG，不依赖 React、Framer Motion 或 Tailwind 运行时。Web Animations 保留独立属性轨道、明确的关键帧停点和错峰延迟。标记为 spring 的场景使用 TuffEx 共享 resolveTransition 编译器。文字值变化使用 TxTextMorph。Skeleton、SkeletonLoader 和 FluidSkeleton 组合现有 TxSkeleton 的几何结构，不创建第二个失去控制的骨架屏循环。

WavePhysicsLoader 保留 15 根柱条、201 个采样相位、每次横穿的 4 次抛物线弹跳、余弦影响半径、落点压入和小球挤压伸展。四秒往返轨迹不替换为通用波浪。292px 源场景先应用 0.38 的展示倍率，再应用公共尺寸倍率。

TextDots 保留三个源停点列表：[0, 0.2, 0.8, 1]、[0, 0.4, 0.8, 1] 和 [0, 0.6, 0.8, 1]。MatrixGridLoader 保留 [0, 0.5, 0.75, 1] 和 0.2、0.4、0.8、0.6 秒的四个延迟。AppleEqualizer 固定源码随机延迟的采样值为 0.06、0.41、0.19、0.32 秒，使服务端渲染保持确定性，不在水合时生成新的随机节奏。颜色使用主题令牌。SVG 黏连滤镜的 ID 使用 Vue 水合稳定的 useId()。

共享 useMotionActivity 负责可见性、减少动态效果和 KeepAlive 生命周期。每个场景持有自己的原生动画，在暂停、切换源和卸载时取消。不支持 Web Animations 的浏览器保留相同的静态画面。