Transfer 穿梭框

穿梭框提供两个并排的面板，用户可以将选项从一个列表移动到另一个列表，常用于权限分配、角色关联等场景。

---

基础用法

通过 :data 传入选项列表，v-model 绑定已选中的 key 数组。选项中的 disabled 属性可禁用该选项。

<script setup>
interface Option {
  key: number
  label: string
  disabled?: boolean
}

const data = ref<Option[]>(
  Array.from({ length: 15 }, (_, i) => ({
    key: i + 1,
    label: `选项 ${i + 1}`,
    disabled: (i + 1) % 4 === 0,
  }))
)
const value = ref<number[]>([])
</script>

<TTransfer v-model="value" :data="data" />

---

带初始值

为 v-model 赋予初始值数组，右侧面板默认包含指定项。

<TTransfer v-model="value" :data="data" />

// 初始选中 key 为 2, 4, 6, 8 的项
const value = ref<number[]>([2, 4, 6, 8])

---

可搜索过滤

设置 filterable 属性开启搜索过滤。默认按 label 字段匹配，也可通过 filter-method 自定义逻辑。

<TTransfer v-model="value" :data="data" filterable />

---

保留源列表模式

设置 keep-source 属性，左侧列表所有项始终可见。已移入右侧的项在左侧显示为已勾选+禁用状态，移回后恢复可选。

<TTransfer v-model="value" :data="data" keep-source />

---

API

Props

属性	类型	默认值	说明
data	TransferOption[]	[]	全部选项列表
model-value / v-model	(string | number)[]	[]	已选中的 key 数组
filterable	boolean	false	是否可搜索过滤
filter-method	(query: string, option: TransferOption) => boolean	—	自定义过滤函数
filter-placeholder	string	'搜索'	搜索框占位文本
left-title	string	'待选列表'	左侧面板标题
right-title	string	'已选列表'	右侧面板标题
empty-text	string	'暂无数据'	空数据提示文本
keep-source	boolean	false	保留源列表模式：左侧列表始终展示全部项，已移入右侧的显示为勾选+禁用

TransferOption

字段	类型	说明
key	string | number	唯一标识
label	string	显示文本
disabled	boolean	是否禁用

Slots

插槽	参数	说明
default	{ item: TransferOption, checked: boolean }	自定义列表项渲染内容