Transfer 穿梭框

何时使用

• 需要在多个可选项中进行多选时。
• 比起 Select 和 TreeSelect，穿梭框占据更大的空间，可以展示可选项的更多信息。

穿梭选择框用直观的方式在两栏中移动元素，完成选择行为。

选择一个或以上的选项后，点击对应的方向键，可以把选中的选项移动到另一栏。其中，左边一栏为 source，右边一栏为 target，API 的设计也反映了这两个概念。

示例

基础穿梭框：

<template>
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      v-model:selected-keys="selectedKeys"
      :data-source="mockData"
      :render="item => item.title"
      @change="handleChange"
      @selectChange="handleSelectChange"
      @scroll="handleScroll"
    />
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
interface MockData {
  key: string
  title: string
  description: string
  disabled: boolean
}
const mockData: MockData[] = []
for (let i = 0; i < 20; i++) {
  mockData.push({
    key: i.toString(),
    title: `content${i + 1}`,
    description: `description of content${i + 1}`,
    disabled: i % 3 < 1,
  })
}

const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key)
export default defineComponent({
  data() {
    const disabled = ref<boolean>(false)

    const targetKeys = ref<string[]>(oriTargetKeys)

    const selectedKeys = ref<string[]>(['1', '4'])

    const handleChange = (nextTargetKeys: string[], direction: string, moveKeys: string[]) => {
      console.log('targetKeys: ', nextTargetKeys)
      console.log('direction: ', direction)
      console.log('moveKeys: ', moveKeys)
    }
    const handleSelectChange = (sourceSelectedKeys: string[], targetSelectedKeys: string[]) => {
      console.log('sourceSelectedKeys: ', sourceSelectedKeys)
      console.log('targetSelectedKeys: ', targetSelectedKeys)
    }
    const handleScroll = (direction: string, e: Event) => {
      console.log('direction:', direction)
      console.log('target:', e.target)
    }

    return {
      mockData,
      targetKeys,
      selectedKeys,
      disabled,
      handleChange,
      handleSelectChange,
      handleScroll,
    }
  },
})
</script>

表格穿梭框：

<template>
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      :data-source="mockData"
      :disabled="disabled"
      :show-search="showSearch"
      :filter-option="(inputValue, item) => item.title.indexOf(inputValue) !== -1"
      :show-select-all="false"
      @change="onChange"
    >
      <template
        #children="{ direction, filteredItems, selectedKeys, disabled: listDisabled, onItemSelectAll, onItemSelect }"
      >
        <f-table
          :row-selection="
            getRowSelection({
              disabled: listDisabled,
              selectedKeys,
              onItemSelectAll,
              onItemSelect,
            })
          "
          :columns="direction === 'left' ? leftColumns : rightColumns"
          :data-source="filteredItems"
          :style="{ pointerEvents: listDisabled ? 'none' : null }"
          :custom-row="
            ({ key, disabled: itemDisabled }) => ({
              onClick: () => {
                if (itemDisabled || listDisabled) return
                onItemSelect(key, !selectedKeys.includes(key))
              },
            })
          "
        />
      </template>
    </f-transfer>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
interface MockData {
  key: string
  title: string
  description: string
  disabled: boolean
}
type tableColumn = Record<string, string>
const mockData: MockData[] = []
for (let i = 0; i < 10; i++) {
  mockData.push({
    key: i.toString(),
    title: `content${i + 1}`,
    description: `description of content${i + 1}`,
    disabled: i % 4 === 0,
  })
}

const originTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key)

const leftTableColumns = [
  {
    dataIndex: 'title',
    title: 'Name',
  },
  {
    dataIndex: 'description',
    title: 'Description',
  },
]
const rightTableColumns = [
  {
    dataIndex: 'title',
    title: 'Name',
  },
]

export default defineComponent({
  setup() {
    const targetKeys = ref<string[]>(originTargetKeys)
    const disabled = ref<boolean>(false)
    const showSearch = ref<boolean>(false)
    const leftColumns = ref<tableColumn[]>(leftTableColumns)
    const rightColumns = ref<tableColumn[]>(rightTableColumns)

    const onChange = (nextTargetKeys: string[]) => {
      console.log('nextTargetKeys', nextTargetKeys)
    }

    const getRowSelection = ({ disabled, selectedKeys, onItemSelectAll, onItemSelect }: Record<string, any>) => {
      return {
        getCheckboxProps: (item: Record<string, string | boolean>) => ({
          disabled: disabled || item.disabled,
        }),
        onSelectAll(selected: boolean, selectedRows: Record<string, string | boolean>[]) {
          const treeSelectedKeys = selectedRows.filter(item => !item.disabled).map(({ key }) => key)
          onItemSelectAll(treeSelectedKeys, selected)
        },
        onSelect({ key }: Record<string, string>, selected: boolean) {
          onItemSelect(key, selected)
        },
        selectedRowKeys: selectedKeys,
      }
    }
    return {
      mockData,
      targetKeys,
      disabled,
      showSearch,
      leftColumns,
      rightColumns,
      onChange,
      getRowSelection,
    }
  },
})
</script>

树形结构穿梭框：

<template>
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      class="tree-transfer"
      :data-source="dataSource"
      :render="item => item.title"
      :show-select-all="false"
    >
      <template #children="{ direction, selectedKeys, onItemSelect }">
        <f-tree
          v-if="direction === 'left'"
          block-node
          checkable
          check-strictly
          default-expand-all
          :checked-keys="[...selectedKeys, ...targetKeys]"
          :tree-data="treeData"
          @check="
            (_, props) => {
              onChecked(props, [...selectedKeys, ...targetKeys], onItemSelect)
            }
          "
          @select="
            (_, props) => {
              onChecked(props, [...selectedKeys, ...targetKeys], onItemSelect)
            }
          "
        />
      </template>
    </f-transfer>
  </div>
</template>
<script lang="ts">
import { computed, defineComponent, ref } from 'vue'
import type { TransferProps, TreeProps } from 'ant-design-vue'
const tData: TransferProps['dataSource'] = [
  { key: '0-0', title: '0-0' },
  {
    key: '0-1',
    title: '0-1',
    children: [
      { key: '0-1-0', title: '0-1-0' },
      { key: '0-1-1', title: '0-1-1' },
    ],
  },
  { key: '0-2', title: '0-3' },
]

const transferDataSource: TransferProps['dataSource'] = []
function flatten(list: TransferProps['dataSource'] = []) {
  list.forEach(item => {
    transferDataSource.push(item)
    flatten(item.children)
  })
}
flatten(JSON.parse(JSON.stringify(tData)))

function isChecked(selectedKeys: (string | number)[], eventKey: string | number) {
  return selectedKeys.indexOf(eventKey) !== -1
}

function handleTreeData(treeNodes: TransferProps['dataSource'], targetKeys: string[] = []) {
  return treeNodes.map(({ children, ...props }) => ({
    ...props,
    disabled: targetKeys.includes(props.key as string),
    children: handleTreeData(children ?? [], targetKeys),
  }))
}

export default defineComponent({
  setup() {
    const targetKeys = ref<string[]>([])

    const dataSource = ref(transferDataSource)

    const treeData = computed(() => {
      return handleTreeData(tData, targetKeys.value)
    })

    const onChecked = (
      e: Parameters<TreeProps['onCheck']>[1] | Parameters<TreeProps['onSelect']>[1],
      checkedKeys: string[],
      onItemSelect: (n: any, c: boolean) => void
    ) => {
      const { eventKey } = e.node
      onItemSelect(eventKey, !isChecked(checkedKeys, eventKey))
    }
    return {
      targetKeys,
      dataSource,
      treeData,
      onChecked,
    }
  },
})
</script>

带搜索穿梭框：

<template>
  <f-transfer
    v-model:target-keys="targetKeys"
    :data-source="mockData"
    show-search
    :filter-option="filterOption"
    :render="item => item.title"
    @change="handleChange"
    @search="handleSearch"
  />
</template>
<script lang="ts">
import { defineComponent, onMounted, ref } from 'vue'
interface MockData {
  key: string
  title: string
  description: string
  chosen: boolean
}
export default defineComponent({
  setup() {
    const mockData = ref<MockData[]>([])

    const targetKeys = ref<string[]>([])
    onMounted(() => {
      getMock()
    })
    const getMock = () => {
      const keys = []
      const mData = []
      for (let i = 0; i < 20; i++) {
        const data = {
          key: i.toString(),
          title: `content${i + 1}`,
          description: `description of content${i + 1}`,
          chosen: Math.random() * 2 > 1,
        }
        if (data.chosen) {
          keys.push(data.key)
        }
        mData.push(data)
      }
      mockData.value = mData
      targetKeys.value = keys
    }
    const filterOption = (inputValue: string, option: MockData) => {
      return option.description.indexOf(inputValue) > -1
    }
    const handleChange = (keys: string[], direction: string, moveKeys: string[]) => {
      console.log(keys, direction, moveKeys)
    }

    const handleSearch = (dir: string, value: string) => {
      console.log('search:', dir, value)
    }
    return {
      mockData,
      targetKeys,
      filterOption,
      handleChange,
      handleSearch,
    }
  },
})
</script>

带分页穿梭框：

<template>
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      :data-source="mockData"
      :render="item => item.title"
      :disabled="disabled"
      pagination
      @change="handleChange"
    />
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
interface MockData {
  key: string
  title: string
  description: string
}
const mockData: MockData[] = []
for (let i = 0; i < 200; i++) {
  mockData.push({
    key: i.toString(),
    title: `content${i + 1}`,
    description: `description of content${i + 1}`,
  })
}

const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key)
export default defineComponent({
  data() {
    const disabled = ref<boolean>(false)

    const targetKeys = ref<string[]>(oriTargetKeys)

    const handleChange = (nextTargetKeys: string[], direction: string, moveKeys: string[]) => {
      console.log('targetKeys: ', nextTargetKeys)
      console.log('direction: ', direction)
      console.log('moveKeys: ', moveKeys)
    }

    return {
      mockData,
      targetKeys,
      disabled,
      handleChange,
    }
  },
})
</script>

单向模式：

头部默认移除全部所选Icon

头部自定义移除全部所选Icon

<template>
  头部默认移除全部所选Icon
  <br />
  <br />
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      v-model:selected-keys="selectedKeys"
      :data-source="mockData"
      :render="item => item.title"
      one-way
      @change="handleChange"
      @selectChange="handleSelectChange"
      @scroll="handleScroll"
      @removeAllTargetKeys="onRemoveAllTargetKeys"
    >
    </f-transfer>
  </div>
  <br />
  <br />
  头部自定义移除全部所选Icon
  <br />
  <br />
  <div>
    <f-transfer
      v-model:target-keys="targetKeys"
      v-model:selected-keys="selectedKeys"
      :data-source="mockData"
      :render="item => item.title"
      one-way
      @change="handleChange"
      @selectChange="handleSelectChange"
      @scroll="handleScroll"
    >
      <template #rightTitleIcon>
        <f-icon
          type="icon-shanchu"
          style="font-size: 12px"
          v-if="targetKeys.length > 0"
          @click="handleRemoveAll"
        ></f-icon>
      </template>
    </f-transfer>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref, watchEffect } from 'vue'
interface MockData {
  key: string
  title: string
  description: string
  disabled: boolean
}
const mockData: MockData[] = []
for (let i = 0; i < 12; i++) {
  mockData.push({
    key: i.toString(),
    title: `content${i + 1}`,
    description: `description of content${i + 1}`,
    disabled: i % 3 < 1,
  })
}

const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key)
export default defineComponent({
  data() {
    const disabled = ref<boolean>(false)

    const targetKeys = ref<string[]>(oriTargetKeys)

    const selectedKeys = ref<string[]>(['1', '4'])

    watchEffect(() => {
      console.log('watchEffect:targetKeys=>', targetKeys.value)
    })

    const handleChange = (nextTargetKeys: string[], direction: string, moveKeys: string[]) => {
      console.log('targetKeys: ', nextTargetKeys)
      console.log('direction: ', direction)
      console.log('moveKeys: ', moveKeys)
    }
    const handleSelectChange = (sourceSelectedKeys: string[], targetSelectedKeys: string[]) => {
      console.log('sourceSelectedKeys: ', sourceSelectedKeys)
      console.log('targetSelectedKeys: ', targetSelectedKeys)
    }
    const handleScroll = (direction: string, e: Event) => {
      console.log('direction:', direction)
      console.log('target:', e.target)
    }

    // 监听移除右侧全部
    const onRemoveAllTargetKeys = () => {
      console.log('onRemoveAllTargetKeys=>', targetKeys.value)
    }

    // 自定义图标 移除右侧全部
    const handleRemoveAll = () => {
      targetKeys.value = []
    }

    return {
      mockData,
      targetKeys,
      selectedKeys,
      disabled,
      handleChange,
      handleSelectChange,
      handleScroll,
      handleRemoveAll,
      onRemoveAllTargetKeys,
    }
  },
})
</script>

API

参数	说明	类型	默认值	版本
dataSource	数据源，其中的数据将会被渲染到左边一栏中，targetKeys 中指定的除外。	[{key: string.isRequired,title: string.isRequired,description: string,disabled: bool}][]	[]
disabled	是否禁用	boolean	false
filterOption	接收 inputValue option 两个参数，当 option 符合筛选条件时，应返回 true，反之则返回 false。	(inputValue, option): boolean
footer	可以设置为一个 作用域插槽	slot="footer" slot-scope="props"
listStyle	两个穿梭框的自定义样式	CSSProperties
locale	各种语言	object	{ itemUnit: '项', itemsUnit: '项', notFoundContent: '列表为空', searchPlaceholder: '请输入搜索内容' }
oneWay	展示为单向样式	boolean	false	3.0.0
operations	操作文案集合，顺序从上至下	string[]	['>', '<']
operationStyle	操作栏的自定义样式	CSSProperties	-	3.0.0
pagination	使用分页样式，自定义渲染列表下无效	boolean |	flase	3.0.0
render	每行数据渲染函数，该函数的入参为 dataSource 中的项，返回值为 element。或者返回一个普通对象，其中 label 字段为 element，value 字段为 title	Function(record)| slot
selectedKeys(v-model)	设置哪些项应该被选中	string[]	[]
showSearch	是否显示搜索框	boolean	false
showSelectAll	是否展示全选勾选框	boolean	true
targetKeys(v-model)	显示在右侧框数据的 key 集合	string[]	[]
titles	标题集合，顺序从左至右	string[]	['', '']
showHeaderDropdown(新)	是否显示头部下拉操作项	boolean	false
removeAll(新)	oneWay模式下，是否可移除全部targetKeys	boolean	true

事件

事件名称	说明	回调参数	版本
change	选项在两栏之间转移时的回调函数	(targetKeys, direction, moveKeys): void
scroll	选项列表滚动时的回调函数	(direction, event): void
search	搜索框内容时改变时的回调函数	(direction: 'left'|'right', value: string): void	-
selectChange	选中项发生改变时的回调函数	(sourceSelectedKeys, targetSelectedKeys): void
removeAllTargetKeys(新)	移除全部目标选项时的回调函数，单向模式下生效	(): void

slots

• 新针对oneWay将slot:rightTitle进行了扩展，支持slot:rightTitleIcon配置头部移除全部icon

Render Props

Transfer 支持接收 children 自定义渲染列表，并返回以下参数：

{
  "direction": String,
  "disabled": Boolean,
  "filteredItems": Array,
  "selectedKeys": Array,
  "onItemSelect": Function,
  "onItemSelectAll": Function
}

参数	说明	类型	版本
direction	渲染列表的方向	'left' | 'right'
disabled	是否禁用列表	boolean
filteredItems	过滤后的数据	TransferItem[]
itemSelect	勾选条目	(key: string, selected: boolean)
itemSelectAll	勾选一组条目	(keys: string[], selected: boolean)
selectedKeys	选中的条目	string[]

参考示例

<f-transfer>
  <template
    #children="{
      direction,
      filteredItems,
      selectedKeys,
      disabled: listDisabled,
      onItemSelectAll,
      onItemSelect,
    }"
  >
    <your-component />
  <template>
</f-transfer>

注意

按照 Vue 最新的规范，所有的组件数组最好绑定 key。在 Transfer 中，dataSource里的数据值需要指定 key 值。对于 dataSource 默认将每列数据的 key 属性作为唯一的标识。

如果你的数据没有这个属性，务必使用 rowKey 来指定数据列的主键。

// 比如你的数据主键是 uid
return <Transfer :rowKey="record => record.uid" />;