TransitionGroup 过渡动画组

介绍

列表过渡动画容器，配合 Transition / TransitionCollapse 子项实现列表增删时的进入、离开动画，并支持按序错开延时。

基础用法

通过 data 传入完整数据源，使用 v-model 绑定当前渲染列表；子项设置 item-key 与数据唯一标识对应。高度折叠类动画（如 enter-right）推荐使用 vd-transition-collapse：

<vd-transition-group
  v-model="values"
  :data="data"
  data-key="id"
  name="enter-right"
  :duration="{ enter: 400, leave: 600 }"
  :delay="{ enter: 100, leave: 100 }"
>
  <vd-transition-collapse
    v-for="item in values"
    :key="item.id"
    :item-key="item.id"
  >
    <view class="item">{{ item.name }}</view>
  </vd-transition-collapse>
</vd-transition-group>

const data = ref([
  { id: 1, name: '项目 1' },
  { id: 2, name: '项目 2' },
]);

const values = ref<any[]>([]);

function addItem() {
  data.value.push({
    id: Date.now(),
    name: `项目 ${data.value.length + 1}`,
  });
}

function removeItem(id: number) {
  const index = data.value.findIndex(item => item.id === id);
  if (index !== -1) {
    data.value.splice(index, 1);
  }
}

TIP

v-for 请遍历 v-model 绑定的 values，不要直接遍历 data。增删请修改 data，组件会自动同步 values 并触发子项动画。

约定说明

组内优先使用 TransitionGroup 的统一配置；子项未传时回退到父级：

配置项	写在哪里	说明
name	TransitionGroup（推荐）	子项未传 name 时使用父级；子项显式传入则以子项为准
duration	TransitionGroup（推荐）	子项未传 duration 时使用父级；子项显式传入则以子项为准
delay	TransitionGroup（推荐）	子项未传 delay 时按项顺序叠加父级延时；子项显式传入则以子项为准
item-key	子项（必填）	与 data-key 对应的唯一标识，用于匹配增删动画

因此子项通常只需设置 item-key，由 Group 统一控制动画：

<vd-transition-group
  v-model="values"
  :data="data"
  name="fade"
  :duration="300"
  :delay="{ enter: 80, leave: 50 }"
>
  <vd-transition
    v-for="item in values"
    :key="item.id"
    :item-key="item.id"
  >
    <view class="item">{{ item.name }}</view>
  </vd-transition>
</vd-transition-group>

子项选用 Transition / TransitionCollapse

子项类型需与 Group 的 name 匹配，不要混用：

子项组件	适用 Group name	说明
Transition	fade / slide-* / zoom-* / flip-* 等	普通透明度、位移、缩放动画
TransitionCollapse	collapse / collapse-fade / enter-left / enter-right	高度折叠动画，内置测高层，更稳定

<!-- 普通动画：使用 Transition -->
<vd-transition-group v-model="values" :data="data" name="fade">
  <vd-transition
    v-for="item in values"
    :key="item.id"
    :item-key="item.id"
  >
    <view class="item">{{ item.name }}</view>
  </vd-transition>
</vd-transition-group>

<!-- 折叠动画：使用 TransitionCollapse -->
<vd-transition-group v-model="values" :data="data" name="enter-right">
  <vd-transition-collapse
    v-for="item in values"
    :key="item.id"
    :item-key="item.id"
  >
    <view class="item">{{ item.name }}</view>
  </vd-transition-collapse>
</vd-transition-group>

动画名称

在 TransitionGroup 上设置 name，支持内置动画名与进入/离开分别配置。折叠类名称请搭配 TransitionCollapse 子项。

<vd-transition-group v-model="values" :data="data" name="fade">
  <!-- Transition 子项 -->
</vd-transition-group>

<vd-transition-group
  v-model="values"
  :data="data"
  :name="{ enter: 'slide-up', leave: 'zoom-out' }"
>
  <!-- Transition 子项 -->
</vd-transition-group>

<vd-transition-group
  v-model="values"
  :data="data"
  :name="{ enter: 'enter-right', leave: 'collapse-fade' }"
>
  <!-- TransitionCollapse 子项 -->
</vd-transition-group>

动画时长与延时

在 TransitionGroup 上设置 duration、delay，支持统一数值或 { enter, leave }。delay 会按列表项顺序叠加，形成依次进入/离开效果（该能力仅属于动画组）。

<vd-transition-group
  v-model="values"
  :data="data"
  :duration="300"
  :delay="{ enter: 80, leave: 50 }"
>
  <!-- ... -->
</vd-transition-group>

唯一标识 dataKey

通过 data-key 指定数据项唯一标识，默认读取 id 字段。支持键路径与函数：

<!-- 嵌套字段 -->
<vd-transition-group
  v-model="values"
  :data="data"
  :data-key="['user', 'id']"
>
  <!-- ... -->
</vd-transition-group>

const data = ref([
  { user: { id: 'a1', name: '张三' } },
  { user: { id: 'b2', name: '李四' } },
]);

<!-- 自定义函数 -->
<vd-transition-group
  v-model="values"
  :data="data"
  :data-key="getItemKey"
>
  <!-- ... -->
</vd-transition-group>

import type { TransitionGroupDataKey } from 'vital-design';

const getItemKey: TransitionGroupDataKey = (item) => item.user.id;

API

Props

参数	说明	类型	默认值
v-model	当前渲染的数据列表	any[]	[]
data	数据源	any[]	[]
data-key	数据项唯一标识键名，支持键路径与函数	TransitionGroupDataKey	'id'
name	动画名称；子项未传时使用该值	TransitionName	'fade'
duration	动画时长，单位 ms；子项未传时使用该值	TransitionDuration	300
delay	动画延时，单位 ms；子项未传时按项顺序叠加	TransitionDuration	0

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点 id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
update:model-value	渲染列表更新时触发	any[]

Slots

名称	说明
default	动画子项：vd-transition 或 vd-transition-collapse，需设置 item-key；未传 name / duration / delay 时回退父级 Group

类型定义

组件导出以下类型定义：

import type {
  TransitionGroupDataKey,
  TransitionName,
  TransitionDuration,
} from 'vital-design';