Transfer 穿梭框
基础用法
数据通过 data 属性传入 Transfer。 这是一个对象数组,每个对象有以下属性: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 即可正常工作。
自定义空内容 2.9.0
可以自定义列表为空或没有过滤结果时的显示内容。
使用 left-empty 和 right-empty 插槽来自定义每个面板的空内容。
属性别名
默认情况下,Transfer 会在数据项中查找 key、label 和 disabled。 如果你的数据项具有不同的键名,可以使用 props 属性定义别名。
本例中的数据项没有 key 或 label,而是具有 value 和 desc。 因此,你需要为 key 和 label 设置别名。
Transfer API
Transfer 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | array | [] |
| data | 数据源 | array | [] |
| filterable | 是否可搜索 | boolean | false |
| filter-placeholder | 搜索框占位符 | string | — |
| filter-method | 自定义搜索方法 | Function | — |
| target-order | 右侧列表元素的排序策略。 若为 original,则保持与数据源相同的顺序;若为 push,则新添加的元素将被推至底部;若为 unshift,则新添加的元素将被插至顶部 | 枚举 | 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 |
Transfer 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| change | 右侧列表元素变化时触发 | Function |
| left-check-change | 用户改变左侧列表任意数据项勾选状态时触发 | Function |
| right-check-change | 用户改变右侧列表任意数据项勾选状态时触发 | Function |
Transfer 插槽
| 名称 | 描述 | 类型 |
|---|---|---|
| default | 自定义数据项内容。 | object |
| left-footer | 左侧列表底部内容 | — |
| right-footer | 右侧列表底部内容 | — |
| left-empty 2.9.0 | 当左侧面板为空或没有匹配过滤的数据时的内容 | — |
| right-empty 2.9.0 | 当右侧面板为空或没有匹配过滤的数据时的内容 | — |
Transfer 暴露项
| 名称 | 描述 | 类型 |
|---|---|---|
| clearQuery | 清空某个面板的搜索关键词 | Function |
| leftPanel | 左侧面板实例 | object |
| rightPanel | 右侧面板实例 | object |
Transfer Panel API
Transfer Panel 暴露项
| 名称 | 描述 | 类型 |
|---|---|---|
| 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
}