Transfer穿梭框 - 图1

Transfer 穿梭框

双栏穿梭选择框。

何时使用

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

代码演示

Transfer穿梭框 - 图2

基本用法

最基本的用法，展示了 dataSource、targetKeys、每行的渲染函数 render 以及回调函数 change selectChange scroll 的用法。

  1. <template>
  2.   <div>
  3.     <a-transfer
  4.       :data-source="mockData"
  5.       :titles="['Source', 'Target']"
  6.       :target-keys="targetKeys"
  7.       :selected-keys="selectedKeys"
  8.       :render="item => item.title"
  9.       :disabled="disabled"
  10.       @change="handleChange"
  11.       @selectChange="handleSelectChange"
  12.       @scroll="handleScroll"
  13.     />
  14.     <a-switch
  15.       un-checked-children="enabled"
  16.       checked-children="disabled"
  17.       v-model:checked="disabled"
  18.       style="margin-top: 16px"
  19.     />
  20.   </div>
  21. </template>
  22. <script lang="ts">
  23. import { defineComponent, ref } from 'vue';
  24. interface MockData {
  25.   key: string;
  26.   title: string;
  27.   description: string;
  28.   disabled: boolean;
  29. }
  30. const mockData: MockData[] = [];
  31. for (let i = 0; i < 20; i++) {
  32.   mockData.push({
  33.     key: i.toString(),
  34.     title: `content${i + 1}`,
  35.     description: `description of content${i + 1}`,
  36.     disabled: i % 3 < 1,
  37.   });
  38. }
  40. const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key);
  41. export default defineComponent({
  42.   data() {
  43.     const disabled = ref<boolean>(false);
  45.     const targetKeys = ref<string[]>(oriTargetKeys);
  47.     const selectedKeys = ref<string[]>(['1', '4']);
  49.     const handleChange = (nextTargetKeys: string[], direction: string, moveKeys: string[]) => {
  50.       targetKeys.value = nextTargetKeys;
  51.       console.log('targetKeys: ', nextTargetKeys);
  52.       console.log('direction: ', direction);
  53.       console.log('moveKeys: ', moveKeys);
  54.     };
  55.     const handleSelectChange = (sourceSelectedKeys: string[], targetSelectedKeys: string[]) => {
  56.       selectedKeys.value = [...sourceSelectedKeys, ...targetSelectedKeys];
  57.       console.log('sourceSelectedKeys: ', sourceSelectedKeys);
  58.       console.log('targetSelectedKeys: ', targetSelectedKeys);
  59.     };
  60.     const handleScroll = (direction: string, e: Event) => {
  61.       console.log('direction:', direction);
  62.       console.log('target:', e.target);
  63.     };
  65.     return {
  66.       mockData,
  67.       targetKeys,
  68.       selectedKeys,
  69.       disabled,
  70.       handleChange,
  71.       handleSelectChange,
  72.       handleScroll,
  73.     };
  74.   },
  75. });
  76. </script>

Transfer穿梭框 - 图3

带搜索框

带搜索框的穿梭框，可以自定义搜索函数。

  1. <template>
  2.   <a-transfer
  3.     :data-source="mockData"
  4.     show-search
  5.     :filter-option="filterOption"
  6.     :target-keys="targetKeys"
  7.     :render="item => item.title"
  8.     @change="handleChange"
  9.     @search="handleSearch"
  10.   />
  11. </template>
  12. <script lang="ts">
  13. import { defineComponent, onMounted, ref } from 'vue';
  14. interface MockData {
  15.   key: string;
  16.   title: string;
  17.   description: string;
  18.   chosen: boolean;
  19. }
  20. export default defineComponent({
  21.   setup() {
  22.     const mockData = ref<MockData[]>([]);
  24.     const targetKeys = ref<string[]>([]);
  25.     onMounted(() => {
  26.       getMock();
  27.     });
  28.     const getMock = () => {
  29.       const keys = [];
  30.       const mData = [];
  31.       for (let i = 0; i < 20; i++) {
  32.         const data = {
  33.           key: i.toString(),
  34.           title: `content${i + 1}`,
  35.           description: `description of content${i + 1}`,
  36.           chosen: Math.random() * 2 > 1,
  37.         };
  38.         if (data.chosen) {
  39.           keys.push(data.key);
  40.         }
  41.         mData.push(data);
  42.       }
  43.       mockData.value = mData;
  44.       targetKeys.value = keys;
  45.     };
  46.     const filterOption = (inputValue: string, option: MockData) => {
  47.       return option.description.indexOf(inputValue) > -1;
  48.     };
  49.     const handleChange = (keys: string[], direction: string, moveKeys: string[]) => {
  50.       console.log(keys, direction, moveKeys);
  51.       targetKeys.value = keys;
  52.     };
  54.     const handleSearch = (dir: string, value: string) => {
  55.       console.log('search:', dir, value);
  56.     };
  57.     return {
  58.       mockData,
  59.       targetKeys,
  60.       filterOption,
  61.       handleChange,
  62.       handleSearch,
  63.     };
  64.   },
  65. });
  66. </script>

Transfer穿梭框 - 图4

高级用法

穿梭框高级用法，可配置操作文案，可定制宽高，可对底部进行自定义渲染。

  1. <template>
  2.   <a-transfer
  3.     :data-source="mockData"
  4.     show-search
  5.     :list-style="{
  6.       width: '250px',
  7.       height: '300px',
  8.     }"
  9.     :operations="['to right', 'to left']"
  10.     :target-keys="targetKeys"
  11.     :render="item => `${item.title}-${item.description}`"
  12.     @change="handleChange"
  13.   >
  14.     <template #footer>
  15.       <a-button size="small" style="float: right; margin: 5px" @click="getMock">reload</a-button>
  16.     </template>
  17.     <template #notFoundContent>
  18.       <span>没数据</span>
  19.     </template>
  20.   </a-transfer>
  21. </template>
  22. <script lang="ts">
  23. import { defineComponent, ref, onMounted } from 'vue';
  24. interface MockData {
  25.   key: string;
  26.   title: string;
  27.   description: string;
  28.   chosen: boolean;
  29. }
  30. export default defineComponent({
  31.   setup() {
  32.     const mockData = ref<MockData[]>([]);
  34.     const targetKeys = ref<string[]>([]);
  35.     onMounted(() => {
  36.       getMock();
  37.     });
  38.     const getMock = () => {
  39.       const keys = [];
  40.       const mData = [];
  41.       for (let i = 0; i < 20; i++) {
  42.         const data = {
  43.           key: i.toString(),
  44.           title: `content${i + 1}`,
  45.           description: `description of content${i + 1}`,
  46.           chosen: Math.random() * 2 > 1,
  47.         };
  48.         if (data.chosen) {
  49.           keys.push(data.key);
  50.         }
  51.         mData.push(data);
  52.       }
  53.       mockData.value = mData;
  54.       targetKeys.value = keys;
  55.     };
  56.     const handleChange = (keys: string[], direction: string, moveKeys: string[]) => {
  57.       targetKeys.value = keys;
  58.       console.log(keys, direction, moveKeys);
  59.     };
  60.     return {
  61.       mockData,
  62.       targetKeys,
  63.       handleChange,
  64.       getMock,
  65.     };
  66.   },
  67. });
  68. </script>

Transfer穿梭框 - 图5

自定义渲染行数据

自定义渲染每一个 Transfer Item，可用于渲染复杂数据。

  1. <template>
  2.   <a-transfer
  3.     :data-source="mockData"
  4.     :list-style="{
  5.       width: '300px',
  6.       height: '300px',
  7.     }"
  8.     :target-keys="targetKeys"
  9.     @change="handleChange"
  10.   >
  11.     <template #render="item">
  12.       <span class="custom-item" style="color: red">{{ item.title }} - {{ item.description }}</span>
  13.     </template>
  14.   </a-transfer>
  15. </template>
  16. <script lang="ts">
  17. import { defineComponent, ref, onMounted } from 'vue';
  18. interface MockData {
  19.   key: string;
  20.   title: string;
  21.   description: string;
  22.   chosen: boolean;
  23. }
  24. export default defineComponent({
  25.   setup() {
  26.     const mockData = ref<MockData[]>([]);
  28.     const targetKeys = ref<string[]>([]);
  29.     onMounted(() => {
  30.       getMock();
  31.     });
  32.     const getMock = () => {
  33.       const keys = [];
  34.       const mData = [];
  35.       for (let i = 0; i < 20; i++) {
  36.         const data = {
  37.           key: i.toString(),
  38.           title: `content${i + 1}`,
  39.           description: `description of content${i + 1}`,
  40.           chosen: Math.random() * 2 > 1,
  41.         };
  42.         if (data.chosen) {
  43.           keys.push(data.key);
  44.         }
  45.         mData.push(data);
  46.       }
  47.       mockData.value = mData;
  48.       targetKeys.value = keys;
  49.     };
  50.     const handleChange = (keys: string[], direction: string, moveKeys: string[]) => {
  51.       targetKeys.value = keys;
  52.       console.log(keys, direction, moveKeys);
  53.     };
  54.     return {
  55.       mockData,
  56.       targetKeys,
  57.       handleChange,
  58.       getMock,
  59.     };
  60.   },
  61. });
  62. </script>

Transfer穿梭框 - 图6

表格穿梭框

使用 Table 组件作为自定义渲染列表。

  1. <template>
  2.   <div>
  3.     <a-transfer
  4.       :data-source="mockData"
  5.       :target-keys="targetKeys"
  6.       :disabled="disabled"
  7.       :show-search="showSearch"
  8.       :filter-option="(inputValue, item) => item.title.indexOf(inputValue) !== -1"
  9.       :show-select-all="false"
  10.       @change="onChange"
  11.     >
  12.       <template
  13.         #children="{
  14.           direction,
  15.           filteredItems,
  16.           selectedKeys,
  17.           disabled: listDisabled,
  18.           onItemSelectAll,
  19.           onItemSelect,
  20.         }"
  21.       >
  22.         <a-table
  23.           :row-selection="
  24.             getRowSelection({
  25.               disabled: listDisabled,
  26.               selectedKeys,
  27.               onItemSelectAll,
  28.               onItemSelect,
  29.             })
  30.           "
  31.           :columns="direction === 'left' ? leftColumns : rightColumns"
  32.           :data-source="filteredItems"
  33.           size="small"
  34.           :style="{ pointerEvents: listDisabled ? 'none' : null }"
  35.           :custom-row="
  36.             ({ key, disabled: itemDisabled }) => ({
  37.               onClick: () => {
  38.                 if (itemDisabled || listDisabled) return;
  39.                 onItemSelect(key, !selectedKeys.includes(key));
  40.               },
  41.             })
  42.           "
  43.         />
  44.       </template>
  45.     </a-transfer>
  46.     <a-switch
  47.       un-checked-children="disabled"
  48.       checked-children="disabled"
  49.       v-model:checked="disabled"
  50.       style="margin-top: 16px"
  51.     />
  52.     <a-switch
  53.       un-checked-children="showSearch"
  54.       checked-children="showSearch"
  55.       v-model:checked="showSearch"
  56.       style="margin-top: 16px"
  57.     />
  58.   </div>
  59. </template>
  60. <script lang="ts">
  61. import { difference } from 'lodash-es';
  62. import { defineComponent, ref } from 'vue';
  63. interface MockData {
  64.   key: string;
  65.   title: string;
  66.   description: string;
  67.   disabled: boolean;
  68. }
  69. type tableColumn = Record<string, string>;
  70. const mockData: MockData[] = [];
  71. for (let i = 0; i < 20; i++) {
  72.   mockData.push({
  73.     key: i.toString(),
  74.     title: `content${i + 1}`,
  75.     description: `description of content${i + 1}`,
  76.     disabled: i % 4 === 0,
  77.   });
  78. }
  80. const originTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key);
  82. const leftTableColumns = [
  83.   {
  84.     dataIndex: 'title',
  85.     title: 'Name',
  86.   },
  87.   {
  88.     dataIndex: 'description',
  89.     title: 'Description',
  90.   },
  91. ];
  92. const rightTableColumns = [
  93.   {
  94.     dataIndex: 'title',
  95.     title: 'Name',
  96.   },
  97. ];
  99. export default defineComponent({
  100.   setup() {
  101.     const targetKeys = ref<string[]>(originTargetKeys);
  102.     const disabled = ref<boolean>(false);
  103.     const showSearch = ref<boolean>(false);
  104.     const leftColumns = ref<tableColumn[]>(leftTableColumns);
  105.     const rightColumns = ref<tableColumn[]>(rightTableColumns);
  107.     const onChange = (nextTargetKeys: string[]) => {
  108.       targetKeys.value = nextTargetKeys;
  109.     };
  111.     const getRowSelection = ({
  112.       disabled,
  113.       selectedKeys,
  114.       onItemSelectAll,
  115.       onItemSelect,
  116.     }: Record<string, any>) => {
  117.       return {
  118.         getCheckboxProps: (item: Record<string, string | boolean>) => ({
  119.           disabled: disabled || item.disabled,
  120.         }),
  121.         onSelectAll(selected: boolean, selectedRows: Record<string, string | boolean>[]) {
  122.           const treeSelectedKeys = selectedRows
  123.             .filter(item => !item.disabled)
  124.             .map(({ key }) => key);
  125.           const diffKeys = selected
  126.             ? difference(treeSelectedKeys, selectedKeys)
  127.             : difference(selectedKeys, treeSelectedKeys);
  128.           onItemSelectAll(diffKeys, selected);
  129.         },
  130.         onSelect({ key }: Record<string, string>, selected: boolean) {
  131.           onItemSelect(key, selected);
  132.         },
  133.         selectedRowKeys: selectedKeys,
  134.       };
  135.     };
  136.     return {
  137.       mockData,
  138.       targetKeys,
  139.       disabled,
  140.       showSearch,
  141.       leftColumns,
  142.       rightColumns,
  143.       onChange,
  144.       getRowSelection,
  145.     };
  146.   },
  147. });
  148. </script>

Transfer穿梭框 - 图7

树穿梭框

使用 Tree 组件作为自定义渲染列表。

  1. <template>
  2.   <div>
  3.     <a-transfer
  4.       class="tree-transfer"
  5.       :data-source="dataSource"
  6.       :target-keys="targetKeys"
  7.       :render="item => item.title"
  8.       :show-select-all="false"
  9.       @change="onChange"
  10.     >
  11.       <template #children="{ direction, selectedKeys, onItemSelect }">
  12.         <a-tree
  13.           v-if="direction === 'left'"
  14.           blockNode
  15.           checkable
  16.           checkStrictly
  17.           defaultExpandAll
  18.           :checkedKeys="[...selectedKeys, ...targetKeys]"
  19.           :treeData="treeData"
  20.           @check="
  21.             (_, props) => {
  22.               onChecked(_, props, [...selectedKeys, ...targetKeys], onItemSelect);
  23.             }
  24.           "
  25.           @select="
  26.             (_, props) => {
  27.               onChecked(_, props, [...selectedKeys, ...targetKeys], onItemSelect);
  28.             }
  29.           "
  30.         />
  31.       </template>
  32.     </a-transfer>
  33.   </div>
  34. </template>
  35. <script lang="ts">
  36. import { CheckEvent } from 'ant-design-vue/es/tree/Tree';
  37. import { computed, defineComponent, ref } from 'vue';
  38. interface TreeDataItem {
  39.   key: string;
  40.   title: string;
  41.   disabled?: boolean;
  42.   children?: TreeDataItem[];
  43. }
  44. const tData: TreeDataItem[] = [
  45.   { key: '0-0', title: '0-0' },
  46.   {
  47.     key: '0-1',
  48.     title: '0-1',
  49.     children: [
  50.       { key: '0-1-0', title: '0-1-0' },
  51.       { key: '0-1-1', title: '0-1-1' },
  52.     ],
  53.   },
  54.   { key: '0-2', title: '0-3' },
  55. ];
  57. const transferDataSource: TreeDataItem[] = [];
  58. function flatten(list: TreeDataItem[] = []) {
  59.   list.forEach(item => {
  60.     transferDataSource.push(item);
  61.     flatten(item.children);
  62.   });
  63. }
  64. flatten(JSON.parse(JSON.stringify(tData)));
  66. function isChecked(selectedKeys: string[], eventKey: string) {
  67.   return selectedKeys.indexOf(eventKey) !== -1;
  68. }
  70. function handleTreeData(data: TreeDataItem[], targetKeys: string[] = []): TreeDataItem[] {
  71.   data.forEach(item => {
  72.     item['disabled'] = targetKeys.includes(item.key);
  73.     if (item.children) {
  74.       handleTreeData(item.children, targetKeys);
  75.     }
  76.   });
  77.   return data;
  78. }
  80. export default defineComponent({
  81.   setup() {
  82.     const targetKeys = ref<string[]>([]);
  84.     const dataSource = ref<TreeDataItem[]>(transferDataSource);
  86.     const treeData = computed<TreeDataItem[]>(() => {
  87.       return handleTreeData(tData, targetKeys.value);
  88.     });
  90.     const onChange = (keys: string[]) => {
  91.       targetKeys.value = keys;
  92.     };
  93.     const onChecked = (
  94.       _: Record<string, string[]>,
  95.       e: CheckEvent,
  96.       checkedKeys: string[],
  97.       onItemSelect: (n: any, c: boolean) => void,
  98.     ) => {
  99.       const { eventKey } = e.node;
  100.       onItemSelect(eventKey, !isChecked(checkedKeys, eventKey));
  101.     };
  102.     return {
  103.       targetKeys,
  104.       dataSource,
  105.       treeData,
  106.       onChange,
  107.       onChecked,
  108.     };
  109.   },
  110. });
  111. </script>
  112. <style scoped>
  113. .tree-transfer .ant-transfer-list:first-child {
  114.   width: 50%;
  115.   flex: none;
  116. }
  117. </style>

API

参数说明类型默认值版本
dataSource数据源，其中的数据将会被渲染到左边一栏中，targetKeys 中指定的除外。[{key: string.isRequired,title: string.isRequired,description: string,disabled: bool}][][]
disabled是否禁用booleanfalse
filterOption接收 inputValue option 两个参数，当 option 符合筛选条件时，应返回 true，反之则返回 false。(inputValue, option): boolean
footer可以设置为一个 作用域插槽slot=”footer” slot-scope=”props”
lazyTransfer 使用了 [vc-lazy-load]优化性能，这里可以设置相关参数。设为 false 可以关闭懒加载。object|boolean{ height: 32, offset: 32 }
listStyle两个穿梭框的自定义样式object
locale各种语言object{ itemUnit: ‘项’, itemsUnit: ‘项’, notFoundContent: ‘列表为空’, searchPlaceholder: ‘请输入搜索内容’ }
operations操作文案集合，顺序从上至下string[][‘>’, ‘<’]
render每行数据渲染函数，该函数的入参为 dataSource 中的项，返回值为 element。或者返回一个普通对象，其中 label 字段为 element，value 字段为 titleFunction(record)| slot
selectedKeys设置哪些项应该被选中string[][]
showSearch是否显示搜索框booleanfalse
showSelectAll是否展示全选勾选框booleantrue
targetKeys显示在右侧框数据的 key 集合string[][]
titles标题集合，顺序从左至右string[][‘’, ‘’]

事件

事件名称说明回调参数版本
change选项在两栏之间转移时的回调函数(targetKeys, direction, moveKeys): void
scroll选项列表滚动时的回调函数(direction, event): void
search搜索框内容时改变时的回调函数(direction: ‘left’|’right’, value: string): void-
selectChange选中项发生改变时的回调函数(sourceSelectedKeys, targetSelectedKeys): void

Render Props

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

  1. {
  2.   "direction": String,
  3.   "disabled": Boolean,
  4.   "filteredItems": Array,
  5.   "selectedKeys": Array,
  6.   "onItemSelect": Function,
  7.   "onItemSelectAll": Function
  8. }
参数说明类型版本
direction渲染列表的方向‘left’ | ‘right’
disabled是否禁用列表boolean
filteredItems过滤后的数据TransferItem[]
selectedKeys选中的条目string[]
itemSelect勾选条目(key: string, selected: boolean)
itemSelectAll勾选一组条目(keys: string[], selected: boolean)

参考示例

  1. <a-transfer>
  2.   <template
  3.     #children="{
  4.       direction,
  5.       filteredItems,
  6.       selectedKeys,
  7.       disabled: listDisabled,
  8.       onItemSelectAll,
  9.       onItemSelect,
  10.     }"
  11.   >
  12.     <your-component />
  13.   <template>
  14. </a-transfer>

注意

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

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

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