TechUI Docs

简中

EN

简中

EN

主题

转场动画 ​

⭐明星组件

TechUI 基于现代浏览器原生的 View Transitions API，封装了一套高性能的视图转场系统。它可以在路由跳转、主题切换或任意 DOM 更新时，自动捕获界面快照并执行影院级的过渡动画。

它是一个全局的过渡动效工具，可以实现以下功能

  • 路由切换过渡动效
    • 可以实现有序切换（配合路由Order参数，实现类似，左侧翻转，右侧翻转等效果）
    • 可以实现无序切换
  • 主题切换过渡动效
  • 局部切换动效（如特定Dom容器）

兼容性说明 ​

由于使用了 document.startViewTransition API，该功能仅支持 Chromium 内核 浏览器（如 Chrome 111+、Edge 111+）。

在不支持的浏览器（如 Firefox、Safari）中，系统会自动降级处理：直接执行状态更新或路由跳转，不播放过渡动画，不会影响业务逻辑的正常运行。

核心用法 ​

在组件中，您可以通过注入 $global 来获取转场相关的核心方法。

javascript
import { inject } from 'vue';

const { 
  routerTransition, // 路由跳转转场
  themeToggle,      // 主题切换转场
  viewTransToggle,  // 手动配置转场参数
  viewTransStart    // 手动触发转场
} = inject('$global');

路由跳转 (routerTransition) ​

这是最常用的方法，用于替代 Vue Router 的 router.push，让页面跳转具备动画效果。

基础用法：

javascript
// 跳转到仪表盘，使用默认动画
routerTransition({ path: '/dashboard' });

指定动画效果：

javascript
routerTransition({ 
  path: '/login',
  transName: 'vt-ripple', // 指定涟漪效果
  transDur: 1.5           // 动画时长 1.5s
});

基于顺序自动判断方向： 如果在路由配置 (meta.order) 中定义了顺序索引，开启 useOrder 后，系统会自动判断是“前进”还是“后退”动画。

javascript
// 如果当前 order: 1，目标 order: 2，则播放前进动画 (vt-slide-left)
// 如果当前 order: 2，目标 order: 1，则播放后退动画 (vt-slide-right)
routerTransition({ 
  path: '/detail',
  useOrder: true 
});

API 参数表：

参数名类型默认值说明
pathString-目标路由路径（必填）。
query
V0.0.5+		Object-路由查询参数。
transNameStringnull指定动画名称（见下文列表）。若为空则使用默认配置。
transTargetStringnull动画作用目标（如 'root', 'layout'）。
transDurNumbernull动画持续时间（秒）。
useOrderBooleanfalse是否根据 meta.order 自动判断动画方向。

主题切换 (themeToggle) ​

TechUI 内置了主题切换的转场封装。当您调用此方法时，系统会以当前点击位置或中心点为圆心，播放圆形扩散（或配置的其他）动画。

javascript
// 切换到深蓝主题
themeToggle('darkBlue', 'dark');

自定义转场 ​

如果您需要在非路由、非主题切换的场景下（例如手动更新某个 DOM 节点内容）使用转场动画，可以组合使用 viewTransToggle 和 viewTransStart。

javascript
const handleUpdate = async () => {
  // 1. 配置动画参数：作用于 root 节点，使用溶解效果，时长 0.5s
  viewTransToggle('root', 'vt-dissolve', 0.5);
  
  // 2. 等待 DOM 更新准备就绪
  await nextTick();
  
  // 3. 开始转场
  viewTransStart({
    callback: () => {
      // 在回调中执行实际的 DOM 更新操作
      showDetail.value = true; 
    },
    enable: true, // 强制开启
    complete: () => {
      // 动画完成后的回调，通常用于重置参数
      viewTransToggle(); 
    }
  });
};

全局配置 ​

您可以在 $globalConfig 中控制转场功能的全局开关。

  • transition: Boolean
    • true: 启用转场动画（默认）。
    • false: 全局禁用，所有 routerTransition 将直接跳转无动画。

动画效果列表 ​

TechUI 预设了丰富的动画效果，您可以在 transName 参数中直接使用这些名称。

几何/遮罩类 ​

适合大幅度的场景切换或主题切换。

  • vt-overlap: 重叠缩放（默认通用效果）。
  • vt-circle: 圆形扩散（中心）。
  • vt-circle-rt: 圆形扩散（右上角）。
  • vt-circle-tc: 圆形扩散（顶部中心）。
  • vt-ripple: 涟漪扩散。

渐变/溶解类 ​

适合内容更新或温和的页面切换。

  • vt-fade: 标准淡入淡出。
  • vt-dissolve: 溶解过渡。

滑动类 (Slide) ​

适合具有空间层级关系的页面切换。

  • vt-slide-up: 向上滑入。
  • vt-slide-down: 向下滑入。
  • vt-slide-left: 向左滑入（通常用于“前进”）。
  • vt-slide-right: 向右滑入（通常用于“后退”）。

翻转类 (Flip) ​

适合卡片翻转或特殊的展示效果。

  • vt-flip-up: 向上翻转。
  • vt-flip-down: 向下翻转。
  • vt-flip-left: 向左翻转。
  • vt-flip-right: 向右翻转。

致谢与出处 ​

前端老鹰
前端老鹰
BiliBili

关于全局转场效果的构想最早萌芽于一些技术博客，但因故搁置。直到偶然看到 前端老鹰 的分享，才真正促使我将其落地，并首先应用于 TechUI 的主题切换功能。

随着开发的深入，我发现这一效果不应局限于“换肤”。通过进一步的抽象与封装，我将其升级为一个功能强大的通用组件。现在，它不仅能处理复杂的主题切换，还能通过丰富的配置项，完美支持区分方向的路由跳转、Vue 组件切换以及各类局部动效需求。

请点击这里查看原视频讲解 前端老鹰-主题切换动画效果