Transfer 穿梭框
基础用法
通过 data 传入数据,需为对象数组,每项包含:key(唯一标识)、label(展示文本)、disabled(是否禁用)。右侧列表与 v-model 绑定同步,值为已选目标的 key 数组。若不希望初始右侧为空,可将 v-model 初始化为非空数组。
可搜索
可搜索并筛选数据项。
将 filterable 设为 true 启用筛选。默认当 label 包含关键字即匹配;也可通过 filter-method 自定义筛选函数,在关键字变化时对每项调用,返回 true 则保留。
可定制
可自定义列表标题、按钮文案、数据项渲染、列表底部勾选统计与页脚内容。
使用 titles、button-texts、render-content 与 format 分别自定义标题、按钮文案、数据项渲染与头部勾选文案。也可使用作用域插槽自定义数据项。页脚提供 left-footer、right-footer。若需初始勾选,可使用 left-default-checked 与 right-default-checked。本示例演示 change 事件。注意:JSFiddle 不支持 JSX,本示例无法运行;真实项目配置好依赖后 render-content 可正常工作。
Customize data items using render-content
Customize data items using scoped slot
自定义空状态
列表为空或无筛选结果时可自定义展示内容。
使用 left-empty 与 right-empty 插槽分别自定义两侧空状态。
字段别名
默认读取数据项的 key、label 与 disabled。若字段名不同,可使用 props 定义别名。
本示例数据使用 value 与 desc,需为 key 与 label 设置别名。
穿梭框 API
穿梭框 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | array | [] |
| data | 数据源 | array | [] |
| filterable | 是否可筛选 | boolean | false |
| filter-placeholder | 筛选输入框占位文本 | string | — |
| filter-method | 自定义筛选方法 | Function | — |
| target-order | 右侧列表排序策略:original 与数据源顺序一致;push 新项追加到底部;unshift 新项插入到顶部 | enum | original |
| titles | 自定义列表标题 | array | [] |
| button-texts | 自定义按钮文案 | array | [] |
| render-content | 自定义数据项渲染函数 | object | — |
| format | 列表头部勾选状态文案 | object | {} |
| props | 数据源字段别名 | object | — |
| left-default-checked | 左侧初始已勾选项的 key 数组 | array | [] |
| right-default-checked | 右侧初始已勾选项的 key 数组 | array | [] |
| validate-event | 是否触发表单校验 | boolean | true |
穿梭框 事件
| 名称 | 说明 | 类型 |
|---|---|---|
| change | 右侧列表数据变化时触发 | Function |
| left-check-change | 左侧列表勾选状态变化时触发 | Function |
| right-check-change | 右侧列表勾选状态变化时触发 | Function |
穿梭框 插槽
| 名称 | 说明 | 类型 |
|---|---|---|
| default | 自定义数据项内容 | object |
| left-footer | 左列页脚 | — |
| right-footer | 右列页脚 | — |
| left-empty | 左列为空或无匹配筛选结果时的内容 | — |
| right-empty | 右列为空或无匹配筛选结果时的内容 | — |
穿梭框 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| clearQuery | 清除指定面板的筛选关键字 | Function |
| leftPanel | 左侧面板引用 | object |
| rightPanel | 右侧面板引用 | object |
穿梭框面板 API
穿梭框面板 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| query | 筛选关键字 | string |
类型声明
显示类型声明
import type { h as H, VNode } from 'vue'
type TransferKey = string | number
type TransferDirection = 'left' | 'right'
type TransferDataItem = Record<string, any>
type renderContent<T extends TransferDataItem = TransferDataItem> = (
h: typeof H,
option: T
) => VNode | VNode[]
interface TransferFormat {
noChecked?: string
hasChecked?: string
}
interface TransferPropsAlias {
label?: string
key?: string
disabled?: string
}