|
|
---
|
|
|
category: Components
|
|
|
type: 数据录入
|
|
|
title: Transfer
|
|
|
subtitle: 穿梭框
|
|
|
cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*EAApQ5ephigAAAAAAAAAAAAADrJ8AQ/original
|
|
|
coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*yv12S4sSRAEAAAAAAAAAAAAADrJ8AQ/original
|
|
|
---
|
|
|
|
|
|
双栏穿梭选择框。
|
|
|
|
|
|
## 何时使用
|
|
|
|
|
|
- 需要在多个可选项中进行多选时。
|
|
|
- 比起 Select 和 TreeSelect，穿梭框占据更大的空间，可以展示可选项的更多信息。
|
|
|
|
|
|
穿梭选择框用直观的方式在两栏中移动元素，完成选择行为。
|
|
|
|
|
|
选择一个或以上的选项后，点击对应的方向键，可以把选中的选项移动到另一栏。其中，左边一栏为 `source`，右边一栏为 `target`，API 的设计也反映了这两个概念。
|
|
|
|
|
|
## 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 \| { pageSize: number, simple: boolean, showSizeChanger?: boolean, showLessItems?: boolean } | flase | 3.0.0 |
|
|
|
| render | 每行数据渲染函数，该函数的入参为 `dataSource` 中的项，返回值为 element。或者返回一个普通对象，其中 `label` 字段为 element，`value` 字段为 title | Function(record)\| slot | | |
|
|
|
| selectAllLabels | 自定义顶部多选框标题的集合 | VueNode \| ((info: { selectedCount: number; totalCount: number }) => VueNode); | - | 3.0.0 |
|
|
|
| selectedKeys(v-model) | 设置哪些项应该被选中 | string\[] | \[] | |
|
|
|
| showSearch | 是否显示搜索框 | boolean | false | |
|
|
|
| showSelectAll | 是否展示全选勾选框 | boolean | true | |
|
|
|
| status | 设置校验状态 | 'error' \| 'warning' | - | 3.3.0 |
|
|
|
| targetKeys(v-model) | 显示在右侧框数据的 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` 自定义渲染列表，并返回以下参数：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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\[] | |
|
|
|
|
|
|
#### 参考示例
|
|
|
|
|
|
```html
|
|
|
<a-transfer>
|
|
|
<template
|
|
|
#children="{
|
|
|
direction,
|
|
|
filteredItems,
|
|
|
selectedKeys,
|
|
|
disabled: listDisabled,
|
|
|
onItemSelectAll,
|
|
|
onItemSelect,
|
|
|
}"
|
|
|
>
|
|
|
<your-component />
|
|
|
<template>
|
|
|
</a-transfer>
|
|
|
```
|
|
|
|
|
|
## 注意
|
|
|
|
|
|
按照 Vue 最新的规范，所有的组件数组最好绑定 key。在 Transfer 中，`dataSource`里的数据值需要指定 `key` 值。对于 `dataSource` 默认将每列数据的 `key` 属性作为唯一的标识。
|
|
|
|
|
|
如果你的数据没有这个属性，务必使用 `rowKey` 来指定数据列的主键。
|
|
|
|
|
|
```jsx
|
|
|
// 比如你的数据主键是 uid
|
|
|
return <Transfer :rowKey="record => record.uid" />;
|
|
|
```
|
