Transfer 穿梭框
左右两个列表,在左边勾选后移到右边,表示“选中了这些”。适合从一批数据里挑出一部分、并且需要同时看到已选和未选的场景,例如给项目分配成员。
引入
import { NsTransfer } from '@ns/ui'
基础用法
data 传全部数据,v-model 绑定右侧列表里数据项的 key 数组。在列表里点数据项勾选,再点中间的按钮移动。某一侧没有数据时显示“暂无数据”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1, 2])
const data: TransferDataItem[] = Array.from({ length: 12 }, (_, index) => ({
key: index + 1,
label: `选项 ${index + 1}`
}))
</script>
<template>
<NsTransfer v-model="value" :data="data" />
</template>
自定义标题和按钮文字
titles 依次是左、右两个列表的标题。button-texts 依次是“移到右侧”“移到左侧”两个按钮的文字,不传时显示 > 和 <。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1, 2])
const data: TransferDataItem[] = [
{ key: 1, label: '张三' },
{ key: 2, label: '李四' },
{ key: 3, label: '王五' },
{ key: 4, label: '赵六' },
{ key: 5, label: '孙七' },
{ key: 6, label: '周八' }
]
</script>
<template>
<NsTransfer
v-model="value"
:data="data"
:titles="['全部成员', '项目成员']"
:button-texts="['加入', '移出']"
/>
</template>
全选
每个列表标题前面有一个全选复选框,点一下勾选这一侧所有没禁用的项,再点一下全部取消;只勾了一部分时显示半选,这时点一下是把剩下的补齐。标题右边的数字是“已勾选数 / 这一侧的总数”。
搜索时全选只作用于当前看得见的项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1, 2, 3])
// 选项 5 是禁用的,全选时不会被勾选
const data: TransferDataItem[] = Array.from({ length: 8 }, (_, index) => ({
key: index + 1,
label: `选项 ${index + 1}`,
disabled: index + 1 === 5
}))
</script>
<template>
<NsTransfer v-model="value" :data="data" />
</template>
可搜索
加上 filterable 后每个列表上方有一个搜索框,默认按文字过滤,不区分大小写。两个搜索框各管各的列表,移动之后这一侧的搜索词会清空。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([])
const data: TransferDataItem[] = [
{ key: 1, label: '北京' },
{ key: 2, label: '上海' },
{ key: 3, label: '广州' },
{ key: 4, label: '深圳' },
{ key: 5, label: '杭州' },
{ key: 6, label: '南京' },
{ key: 7, label: '成都' },
{ key: 8, label: '重庆' }
]
</script>
<template>
<NsTransfer v-model="value" :data="data" filterable filter-placeholder="输入关键字" />
</template>
filter-method 可以换成自己的过滤规则。它的参数是输入框里的原文和数据项,返回 true 的项会显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([])
const data: TransferDataItem[] = [
{ key: 1001, label: '张三' },
{ key: 1002, label: '李四' },
{ key: 2001, label: '赵六' }
]
// 按工号(key)开头匹配,而不是按名字
const filterMethod = (query: string, item: TransferDataItem) =>
String(item.key).startsWith(query.trim())
</script>
<template>
<NsTransfer
v-model="value"
:data="data"
filterable
:filter-method="filterMethod"
filter-placeholder="输入工号"
/>
</template>
禁用
数据项的 disabled: true 禁用这一项:不能勾选,全选也不会选到它,所以它在哪一侧就留在哪一侧。组件上的 disabled 禁用整个穿梭框:数据项、全选框、移动按钮和搜索框都不能操作。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer, NsSpace } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([2])
const data: TransferDataItem[] = [
{ key: 1, label: '选项 1' },
{ key: 2, label: '选项 2' },
{ key: 3, label: '选项 3(禁用)', disabled: true }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTransfer v-model="value" :data="data" />
<NsTransfer v-model="value" :data="data" filterable disabled />
</NsSpace>
</template>
自定义数据项
默认插槽可以自定义每个数据项的显示内容,参数 item 是当前数据项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1002])
const data: TransferDataItem[] = [
{ key: 1001, label: '张三' },
{ key: 1002, label: '李四' },
{ key: 1003, label: '王五' },
{ key: 2001, label: '赵六' }
]
</script>
<template>
<NsTransfer v-model="value" :data="data">
<template #default="{ item }">{{ item.key }} - {{ item.label }}</template>
</NsTransfer>
</template>
列表底部
left-footer、right-footer 插槽的内容显示在对应列表的底部,可以放按钮或说明文字。不写时不占位置。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer, NsButton } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1])
const data = ref<TransferDataItem[]>([
{ key: 1, label: '选项 1' },
{ key: 2, label: '选项 2' }
])
const add = () => {
const next = data.value.length + 1
data.value = [...data.value, { key: next, label: `选项 ${next}` }]
}
</script>
<template>
<NsTransfer v-model="value" :data="data">
<template #left-footer>
<NsButton size="small" @click="add">新增一项</NsButton>
</template>
<template #right-footer>
<NsButton size="small" @click="value = []">全部移回</NsButton>
</template>
</NsTransfer>
</template>
清空勾选
通过 ref 调用 clearChecked(),清空两侧已经勾选但还没移动的项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const transferRef = ref<InstanceType<typeof NsTransfer>>()
const value = ref<TransferKey[]>([1])
const data: TransferDataItem[] = Array.from({ length: 6 }, (_, index) => ({
key: index + 1,
label: `选项 ${index + 1}`
}))
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsButton @click="transferRef?.clearChecked()">清空勾选(clearChecked)</NsButton>
<NsTransfer ref="transferRef" v-model="value" :data="data" />
</NsSpace>
</template>
事件
点移动按钮后触发 change,第二个参数是方向(right 移到右侧、left 移到左侧),第三个参数是这次移动的 key;两侧勾选的项变化时分别触发 left-check-change、right-check-change。最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([4])
const logs = ref<string[]>([])
const data: TransferDataItem[] = Array.from({ length: 6 }, (_, index) => ({
key: index + 1,
label: `选项 ${index + 1}`
}))
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (keys: TransferKey[], direction: 'left' | 'right', moved: TransferKey[]) =>
log(
`change:方向 ${direction},移动了 ${JSON.stringify(moved)},右侧现在是 ${JSON.stringify(keys)}`
)
const onLeftCheck = (keys: TransferKey[]) => log(`left-check-change:${JSON.stringify(keys)}`)
const onRightCheck = (keys: TransferKey[]) => log(`right-check-change:${JSON.stringify(keys)}`)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsTransfer
v-model="value"
:data="data"
@change="onChange"
@left-check-change="onLeftCheck"
@right-check-change="onRightCheck"
/>
<div class="logs">
<div v-if="logs.length === 0">还没有触发事件</div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
数据较多
数据多的时候在列表里滚动,整个组件最高 320px,每个列表宽 200px。需要别的尺寸时用样式覆盖:.ns-transfer 的 max-height 和 .ns-transfer__panel 的 width。下面有 50 条数据,列表加宽到 260px、整体最高 280px:
<script setup lang="ts">
import { ref } from 'vue'
import { NsTransfer } from '@ns/ui'
import type { TransferDataItem, TransferKey } from '@ns/ui'
const value = ref<TransferKey[]>([1, 2, 3])
const data: TransferDataItem[] = Array.from({ length: 50 }, (_, index) => ({
key: index + 1,
label: `员工 ${String(index + 1).padStart(3, '0')}`
}))
</script>
<template>
<NsTransfer v-model="value" :data="data" filterable class="wide-transfer" />
</template>
<style scoped>
.wide-transfer.ns-transfer {
max-height: 280px;
}
.wide-transfer :deep(.ns-transfer__panel) {
width: 260px;
}
</style>
在表单里使用
放在 NsFormItem 里时,点移动按钮让值变化后触发 change 规则;表单禁用时穿梭框也禁用。下面至少要选一个成员:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsMessage, NsSpace, NsTransfer } from '@ns/ui'
import type { FormRule, TransferDataItem, TransferKey } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive<{ members: TransferKey[] }>({ members: [1] })
const rules: Record<string, FormRule[]> = {
members: [{ required: true, message: '至少选一个成员', trigger: 'change' }]
}
const data: TransferDataItem[] = [
{ key: 1, label: '张三' },
{ key: 2, label: '李四' },
{ key: 3, label: '王五' },
{ key: 4, label: '赵六' }
]
const submit = async () => {
const result = await formRef.value?.validate()
if (result?.valid) NsMessage.success('校验通过')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px">
<NsFormItem label="项目成员" prop="members">
<NsTransfer v-model="model.members" :data="data" :titles="['全部成员', '已选成员']" />
</NsFormItem>
<NsFormItem>
<NsSpace>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
键盘操作
全选复选框、没禁用的数据项、移动按钮都可以用 Tab 聚焦。
| 按键 | 作用 |
|---|---|
| Enter、空格 | 焦点在数据项上时勾选或取消勾选;在全选复选框上时全选 |
| ↓、↑ | 焦点在数据项上时移到下一项、上一项,跳过禁用的项 |
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | TransferKey[] | [] | 绑定值,支持 v-model。右侧列表里数据项的 key 数组 |
| data | TransferDataItem[] | [] | 全部数据 |
| titles | [string, string] | ['列表 1', '列表 2'] | 左、右两个列表的标题 |
| buttonTexts | [string, string] | ['', ''] | 两个按钮的文字,依次是“移到右侧”“移到左侧”。空字符串时显示 > 和 < |
| filterable | boolean | false | 是否显示搜索框 |
| filterMethod | (query: string, item: TransferDataItem) => boolean | - | 自定义搜索方法,返回 true 的项会显示。不传时按文字过滤 |
| filterPlaceholder | string | '请输入搜索内容' | 搜索框的占位文本 |
| disabled | boolean | false | 是否禁用 |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: TransferKey[]) | 点移动按钮后触发,v-model 用 |
| change | (value: TransferKey[], direction: 'left' | 'right', movedKeys: TransferKey[]) | 点移动按钮后触发。direction 是移动的方向,movedKeys 是这次移动的项 |
| left-check-change | (keys: TransferKey[]) | 左侧勾选的项变化时触发,参数是左侧当前勾选的全部 key。移动之后勾选被清空时也会触发 |
| right-check-change | (keys: TransferKey[]) | 右侧勾选的项变化时触发,参数是右侧当前勾选的全部 key。移动之后勾选被清空时也会触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | { item: TransferDataItem } | 自定义数据项的内容,不写时显示 label |
| left-footer | - | 左侧列表底部的内容 |
| right-footer | - | 右侧列表底部的内容 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| clearChecked | - | void | 清空两侧已勾选的项,同时触发对应的 *-check-change 事件 |
类型
import type { TransferDataItem, TransferKey } from '@ns/ui'
type TransferKey = string | number
interface TransferDataItem {
key: TransferKey
label: string
disabled?: boolean
}
注意事项
key在data里必须唯一。- 右侧列表按
data里的顺序显示,不是按移入的先后;绑定值数组里新移入的key追加在最后。 - 每个列表宽 200px,整个组件最高 320px,数据多的时候在列表里滚动。需要别的尺寸时用样式覆盖
.ns-transfer的max-height和.ns-transfer__panel的width。 - 外部直接改了绑定值或
data之后,已经不在原来那一侧的勾选会被自动去掉,并触发对应的*-check-change。 - 被搜索隐藏的项如果之前已经勾选,点移动按钮时也会一起移动。
- 默认插槽的
item类型是TransferDataItem,只有key、label、disabled三个字段。要显示其他信息时,按item.key到自己的数据里查。 - 移动按钮的
type是button,放在表单里不会触发提交。
优化点
- [x] 支持自定义数据项内容(默认插槽)
- [x] 支持列表底部插槽和
clearChecked方法 - [ ] 支持拖拽排序
- [ ] 支持分页
- [ ] 右侧列表支持按移入的先后排序
- [ ]
TransferDataItem支持带其他字段(泛型),自定义数据项时不用再按key查 - [ ] 面板的宽度、高度改成可以通过属性或 CSS 变量设置
- [ ] 全选复选框、数据项的复选框改用
NsCheckbox,样式和其他组件统一 - [ ] 空数据提示支持自定义