Transfer 穿梭框
穿梭框将多个列表项从一个列表移动到另一个列表。通常用于权限分配、角色绑定等场景。
基础用法
列表 1共 5 项
- Illinois
- Maryland
- Florida
- Colorado
- Connecticut
列表 2共 2 项
- California
- Texas
基础用法
可搜索
列表 1共 7 项
- California
- Illinois
- Maryland
- Texas
- Florida
- Colorado
- Connecticut
列表 2共 0 项
无数据
可搜索
自定义文案
Source共 3 项
- Option 1
- Option 2
- Option 3
Target共 0 项
无数据
自定义文案
数据映射
列表 1共 3 项
- 研发部
- 人事部
- 财务部
列表 2共 1 项
- 市场部
字段别名
内容自定义
列表 1共 7 项
- 1 - California
- 2 - Illinois
- 3 - Maryland
- 4 - Texas
- 5 - Florida
- 6 - Colorado
- 7 - Connecticut
列表 2共 0 项
无数据
列表 1共 7 项
- California
- Illinois
- Maryland
- Texas
- Florida
- Colorado
- Connecticut
列表 2共 0 项
无数据
内容自定义
虚拟滚动
列表 1共 2000 项
- Option 0
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
列表 2共 0 项
无数据
虚拟滚动
按钮区自定义
列表 1共 3 项
- Item A
- Item B
- Item C
列表 2共 0 项
无数据
按钮区域自定义
在 Nuxt 中使用
Transfer 组件完全支持 Nuxt 3/4 环境。在服务器端渲染（SSR）时，组件会预先渲染左右两个列表面板的基础 HTML 结构，确保首屏加载时内容可见，无水合闪烁。
列表 1共 2 项
- Nuxt 2
- Nuxt 4
列表 2共 1 项
- Nuxt 3
Nuxt 中使用
SSR 注意事项：
- ✅ 初始选中的状态（modelValue）在服务端正确渲染至右侧列表
- ✅ 列表项的标签（label）和禁用状态支持 SSR 渲染
- ✅ 虚拟滚动（virtual）支持首屏基础节点渲染
- ⚠️ 按钮交互、列表搜索匹配、选中状态切换在客户端激活（Hydration）后生效
- 💡 下拉或浮层提示（如 Tooltip）通过 Teleport 挂载，不影响主 HTML 结构
渲染性能
对于万级数据，Transfer 内部采用了高效的组件模板编译优化。即便在没有开启 virtual 的情况下，首屏生成的 HTML 也是经过精简的，确保了 SSR 性能。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | TransferKey[] | [] |
| data | 数据源 | TransferData[] | [] |
| filterable | 是否可搜索 | boolean | false |
| filter-placeholder | 搜索框占位符 | string | '请输入关键词' |
| filter-method | 自定义搜索方法 | (query, item) => boolean | — |
| target-order | 右侧排序策略 | 'original' | 'push' | 'unshift' | 'original' |
| titles | 列表标题 | [string, string] | ['列表 1', '列表 2'] |
| button-texts | 按钮文案 | [string, string] | [] |
| render-content | 自定义渲染内容 | (h, option) => VNode | — |
| props | 数据源别名配置 | TransferPropsAlias | — |
| left-default-checked | 左侧默认勾选 | TransferKey[] | [] |
| right-default-checked | 右侧默认勾选 | TransferKey[] | [] |
| virtual | 开启虚拟滚动 | boolean | false |
| height | 列表高度 | number | 280 |
| item-height | 行高（虚拟滚动） | number | 40 |
| empty-text | 空数据文本 | string | '暂无数据' |
| show-all-checkbox | 是否显示全选 | boolean | true |
| left-title | 左侧标题 | string | — |
| right-title | 右侧标题 | string | — |
| disabled | 是否禁用 | boolean | false |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 右侧列表元素变化时触发 | (value, direction, movedKeys) |
| left-check-change | 左侧勾选变化时触发 | (value, movedKeys) |
| right-check-change | 右侧勾选变化时触发 | (value, movedKeys) |
Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
| default | 自定义数据项内容 | { option } |
| left-header | 左侧头部内容 | — |
| right-header | 右侧头部内容 | — |
| left-footer | 左侧底部内容 | — |
| right-footer | 右侧底部内容 | — |
| left-empty | 左侧空内容 | — |
| right-empty | 右侧空内容 | — |
| buttons | 自定义操作按钮区 | { moveToLeft, moveToRight, leftChecked, rightChecked } |
Expose
| 方法名 | 说明 | 类型 |
|---|---|---|
| clearLeftChecked | 清空左侧勾选 | () => void |
| clearRightChecked | 清空右侧勾选 | () => void |
| leftPanel | 左面板实例 | TransferPanelExpose |
| rightPanel | 右面板实例 | TransferPanelExpose |
主题变量
| Variable Name | Default | Description |
|---|---|---|
--yh-transfer-panel-width | 200px | 面板宽度 |
--yh-transfer-panel-height | 300px | 面板高度 |
--yh-transfer-header-height | 40px | 头部高度 |
--yh-transfer-header-bg | #f5f7fa | 头部背景 |
--yh-transfer-item-height | 32px | 行高 |
--yh-transfer-border-color | #ebeef5 | 边框颜色 |