穿梭框（Transfer）

Element-UI 的穿梭框组件用于在两个列表之间转移数据项，适用于需要多项选择和双向选择的场景。

提示

穿梭框（Transfer）组件官方文档：https://element.eleme.cn/#/zh-CN/component/transfer (opens new window)

1. 基本用法

基本语法：在 Vue 组件中使用 <el-transfer> 标签创建一个穿梭框，通过 v-model 绑定选中的值，并通过 data 提供数据源。

<template>
  <el-transfer
    v-model="selectedItems"
    :data="transferData"
  ></el-transfer>
</template>

<script>
export default {
  data() {
    return {
      selectedItems: [], // 选中的项，绑定在 v-model 上
      transferData: [    // 数据源，每项数据包含 key、label 和 disabled 属性
        { key: 1, label: '选项 1', disabled: false },
        { key: 2, label: '选项 2', disabled: false },
        { key: 3, label: '选项 3', disabled: false }
      ]
    };
  }
};
</script>

• v-model 绑定：穿梭框的选中项通过 v-model 与 selectedItems 绑定。当用户选择项时，selectedItems 会自动更新。
• 数据源：通过 data 属性提供穿梭框的选项数据，数据项包含 key、label 和 disabled 属性。
• 选项数据：Transfer 的数据通过 data 属性传入。数据需要是一个对象数组，每个对象有以下属性：key 为数据的唯一性标识，label 为显示文本，disabled 表示该项数据是否禁止转移。
• 目标列表：目标列表中的数据项会同步到绑定至 v-model 的变量，值为数据项的 key 所组成的数组。
• 

Transfer 属性

参数	说明	类型	可选值	默认值
value / v-model	绑定值	array	—	—
data	Transfer 的数据源，包含 key、label 和 disabled 属性	array[{ key, label, disabled }]	—	[]
filterable	是否可搜索	boolean	—	false
filter-placeholder	搜索框占位符	string	—	请输入搜索内容
filter-method	自定义搜索方法	function	—	—
target-order	右侧列表元素的排序策略	string	original / push / unshift	original
titles	自定义列表标题	array	—	['列表 1', '列表 2']
button-texts	自定义按钮文案	array	—	[]
render-content	自定义数据项渲染函数	function(h, option)	—	—
format	列表顶部勾选状态文案	object{noChecked, hasChecked}	—	{ noChecked: '${checked}/${total}', hasChecked: '${checked}/${total}' }
props	数据源的字段别名	object{key, label, disabled}	—	{ key: 'key', label: 'label', disabled: 'disabled' }
left-default-checked	初始状态下左侧列表的已勾选项的 key 数组	array	—	[]
right-default-checked	初始状态下右侧列表的已勾选项的 key 数组	array	—	[]

Transfer 事件

事件名称	说明	回调参数
change	右侧列表元素变化时触发	当前值、数据移动的方向（'left' / 'right'）、发生移动的数据 key 数组
left-check-change	左侧列表元素被用户选中 / 取消选中时触发	当前被选中的元素的 key 数组、选中状态发生变化的元素的 key 数组
right-check-change	右侧列表元素被用户选中 / 取消选中时触发	当前被选中的元素的 key 数组、选中状态发生变化的元素的 key 数组

Transfer 插槽

名称	说明
left-footer	左侧列表底部的内容
right-footer	右侧列表底部的内容

Transfer 作用域插槽

名称	说明
—	自定义数据项的内容，参数为 { option }

Transfer 方法

方法名	说明	参数
clearQuery	清空某个面板的搜索关键词	'left' / 'right'，指定需要清空的面板

2. 穿梭框示例

可搜索的穿梭框

通过 filterable 属性启用搜索功能，并通过 filter-placeholder 设置搜索框的占位符。

<template>
  <el-transfer
    v-model="selectedItems"
    :data="transferData"
    filterable
    filter-placeholder="请输入搜索内容"
  ></el-transfer>
</template>

<script>
export default {
  data() {
    return {
      selectedItems: [], // 选中的项，绑定在 v-model 上
      transferData: [    // 数据源，每项数据包含 key、label 和 disabled 属性
        { key: 1, label: '选项 1', disabled: false },
        { key: 2, label: '选项 2', disabled: false },
        { key: 3, label: '选项 3', disabled: false }
      ]
    };
  }
};
</script>

• 可搜索：通过 filterable 属性启用搜索功能，并通过 filter-placeholder 设置搜索框的占位符。
• 搜索功能：用户可以在搜索框中输入内容以过滤左侧列表中的选项。
• 

自定义列表标题

通过 titles 属性设置左右列表的标题。

<template>
  <el-transfer
    v-model="selectedItems"
    :data="transferData"
    :titles="['源列表', '目标列表']"
  ></el-transfer>
</template>

<script>
export default {
  data() {
    return {
      selectedItems: [], // 选中的项，绑定在 v-model 上
      transferData: [    // 数据源，每项数据包含 key、label 和 disabled 属性
        { key: 1, label: '选项 1', disabled: false },
        { key: 2, label: '选项 2', disabled: false },
        { key: 3, label: '选项 3', disabled: false }
      ]
    };
  }
};
</script>

• 自定义标题：通过 titles 属性设置左右列表的标题，分别为 "源列表" 和 "目标列表"。
• 标题设置：可以根据需求自定义每个列表的标题内容。
• 

自定义数据项渲染

通过 render-content 属性自定义数据项的渲染内容。

<template>
  <el-transfer
    v-model="selectedItems"
    :data="transferData"
    :render-content="renderFunc"
  ></el-transfer>
</template>

<script>
export default {
  data() {
    return {
      selectedItems: [], // 选中的项，绑定在 v-model 上
      transferData: [    // 数据源，每项数据包含 key、label 和 description 属性
        { key: 1, label: '选项 1', description: '这是选项 1 的描述', disabled: false },
        { key: 2, label: '选项 2', description: '这是选项 2 的描述', disabled: false },
        { key: 3, label: '选项 3', description: '这是选项 3 的描述', disabled: false }
      ]
    };
  },
  methods: {
    renderFunc(h, option) {
      return h('div', [
        h('span', option.label),
        h('span', { style: { color: '#999', marginLeft: '10px' } }, option.description)
      ]);
    }
  }
};
</script>

• 自定义渲染：通过 render-content 属性自定义数据项的渲染内容，使用 renderFunc 方法返回带有描述信息的标签。
• 描述信息：每个数据项除了 label 外，还包含 description，在自定义渲染函数中显示。
• 

自定义列表底部内容

通过插槽 left-footer 和 right-footer 自定义

左右列表的底部内容。

<template>
  <el-transfer
    v-model="selectedItems"
    :data="transferData"
  >
    <template slot="left-footer">
      <el-button size="small" @click="clearLeft">清空左侧</el-button>
    </template>
    <template slot="right-footer">
      <el-button size="small" @click="clearRight">清空右侧</el-button>
    </template>
  </el-transfer>
</template>

<script>
export default {
  data() {
    return {
      selectedItems: [], // 选中的项，绑定在 v-model 上
      transferData: [    // 数据源，每项数据包含 key、label 和 disabled 属性
        { key: 1, label: '选项 1', disabled: false },
        { key: 2, label: '选项 2', disabled: false },
        { key: 3, label: '选项 3', disabled: false }
      ]
    };
  },
  methods: {
    clearLeft() {
      this.$refs.transfer.clearQuery('left');
    },
    clearRight() {
      this.$refs.transfer.clearQuery('right');
    }
  }
};
</script>

• 自定义底部内容：通过 left-footer 和 right-footer 插槽分别自定义左侧和右侧列表的底部内容。
• 插槽内容：可以在底部插槽中添加任意内容，如说明文字或操作按钮。
• 

总结

• 灵活的属性配置：通过 filterable、titles、render-content 等属性可以自定义穿梭框的行为和样式。
• 丰富的事件处理：支持 change、left-check-change、right-check-change 等事件，允许开发者在数据移动和选中状态变化时进行自定义处理。
• 多样的展示方式：支持自定义列表标题、自定义数据项渲染、自定义搜索等，通过相关属性进行配置。