Transfer穿梭框

双栏穿梭选择框。

何时使用

  • 需要在多个可选项中进行多选时。

  • 比起 Select 和 TreeSelect，穿梭框占据更大的空间，可以展示可选项的更多信息。

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

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

代码演示

Transfer穿梭框 - 图1

基本用法

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

  1. import { Space, Transfer, Switch } from 'antd';
  3. const mockData = [];
  4. for (let i = 0; i < 20; i++) {
  5.   mockData.push({
  6.     key: i.toString(),
  7.     title: `content${i + 1}`,
  8.     description: `description of content${i + 1}`,
  9.     disabled: i % 3 < 1,
  10.   });
  11. }
  13. const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key);
  15. class App extends React.Component {
  16.   state = {
  17.     targetKeys: oriTargetKeys,
  18.     selectedKeys: [],
  19.     disabled: false,
  20.   };
  22.   handleChange = (nextTargetKeys, direction, moveKeys) => {
  23.     this.setState({ targetKeys: nextTargetKeys });
  25.     console.log('targetKeys: ', nextTargetKeys);
  26.     console.log('direction: ', direction);
  27.     console.log('moveKeys: ', moveKeys);
  28.   };
  30.   handleSelectChange = (sourceSelectedKeys, targetSelectedKeys) => {
  31.     this.setState({ selectedKeys: [...sourceSelectedKeys, ...targetSelectedKeys] });
  33.     console.log('sourceSelectedKeys: ', sourceSelectedKeys);
  34.     console.log('targetSelectedKeys: ', targetSelectedKeys);
  35.   };
  37.   handleScroll = (direction, e) => {
  38.     console.log('direction:', direction);
  39.     console.log('target:', e.target);
  40.   };
  42.   handleDisable = disabled => {
  43.     this.setState({ disabled });
  44.   };
  46.   render() {
  47.     const { targetKeys, selectedKeys, disabled } = this.state;
  48.     return (
  49.       <div>
  50.         <Transfer
  51.           dataSource={mockData}
  52.           titles={['Source', 'Target']}
  53.           targetKeys={targetKeys}
  54.           selectedKeys={selectedKeys}
  55.           onChange={this.handleChange}
  56.           onSelectChange={this.handleSelectChange}
  57.           onScroll={this.handleScroll}
  58.           render={item => item.title}
  59.           disabled={disabled}
  60.         />
  61.         <Space style={{ marginTop: 16 }}>
  62.           <Switch
  63.             unCheckedChildren="disabled"
  64.             checkedChildren="disabled"
  65.             checked={disabled}
  66.             onChange={this.handleDisable}
  67.           />
  68.         </Space>
  69.       </div>
  70.     );
  71.   }
  72. }
  74. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图2

单向样式

通过 oneWay 将 Transfer 转为单向样式。

  1. import { Space, Transfer, Switch } from 'antd';
  3. const mockData = [];
  4. for (let i = 0; i < 20; i++) {
  5.   mockData.push({
  6.     key: i.toString(),
  7.     title: `content${i + 1}`,
  8.     description: `description of content${i + 1}`,
  9.     disabled: i % 3 < 1,
  10.   });
  11. }
  13. const oriTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key);
  15. class App extends React.Component {
  16.   state = {
  17.     targetKeys: oriTargetKeys,
  18.     selectedKeys: [],
  19.     disabled: false,
  20.   };
  22.   handleChange = (nextTargetKeys, direction, moveKeys) => {
  23.     this.setState({ targetKeys: nextTargetKeys });
  25.     console.log('targetKeys: ', nextTargetKeys);
  26.     console.log('direction: ', direction);
  27.     console.log('moveKeys: ', moveKeys);
  28.   };
  30.   handleSelectChange = (sourceSelectedKeys, targetSelectedKeys) => {
  31.     this.setState({ selectedKeys: [...sourceSelectedKeys, ...targetSelectedKeys] });
  33.     console.log('sourceSelectedKeys: ', sourceSelectedKeys);
  34.     console.log('targetSelectedKeys: ', targetSelectedKeys);
  35.   };
  37.   handleScroll = (direction, e) => {
  38.     console.log('direction:', direction);
  39.     console.log('target:', e.target);
  40.   };
  42.   handleDisable = disabled => {
  43.     this.setState({ disabled });
  44.   };
  46.   render() {
  47.     const { targetKeys, selectedKeys, disabled } = this.state;
  48.     return (
  49.       <div>
  50.         <Transfer
  51.           dataSource={mockData}
  52.           titles={['Source', 'Target']}
  53.           targetKeys={targetKeys}
  54.           selectedKeys={selectedKeys}
  55.           onChange={this.handleChange}
  56.           onSelectChange={this.handleSelectChange}
  57.           onScroll={this.handleScroll}
  58.           render={item => item.title}
  59.           disabled={disabled}
  60.           oneWay
  61.         />
  62.         <Space style={{ marginTop: 16 }}>
  63.           <Switch
  64.             unCheckedChildren="disabled"
  65.             checkedChildren="disabled"
  66.             checked={disabled}
  67.             onChange={this.handleDisable}
  68.           />
  69.         </Space>
  70.       </div>
  71.     );
  72.   }
  73. }
  75. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图3

带搜索框

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

  1. import { Transfer } from 'antd';
  3. class App extends React.Component {
  4.   state = {
  5.     mockData: [],
  6.     targetKeys: [],
  7.   };
  9.   componentDidMount() {
  10.     this.getMock();
  11.   }
  13.   getMock = () => {
  14.     const targetKeys = [];
  15.     const mockData = [];
  16.     for (let i = 0; i < 20; i++) {
  17.       const data = {
  18.         key: i.toString(),
  19.         title: `content${i + 1}`,
  20.         description: `description of content${i + 1}`,
  21.         chosen: Math.random() * 2 > 1,
  22.       };
  23.       if (data.chosen) {
  24.         targetKeys.push(data.key);
  25.       }
  26.       mockData.push(data);
  27.     }
  28.     this.setState({ mockData, targetKeys });
  29.   };
  31.   filterOption = (inputValue, option) => option.description.indexOf(inputValue) > -1;
  33.   handleChange = targetKeys => {
  34.     this.setState({ targetKeys });
  35.   };
  37.   handleSearch = (dir, value) => {
  38.     console.log('search:', dir, value);
  39.   };
  41.   render() {
  42.     return (
  43.       <Transfer
  44.         dataSource={this.state.mockData}
  45.         showSearch
  46.         filterOption={this.filterOption}
  47.         targetKeys={this.state.targetKeys}
  48.         onChange={this.handleChange}
  49.         onSearch={this.handleSearch}
  50.         render={item => item.title}
  51.       />
  52.     );
  53.   }
  54. }
  56. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图4

高级用法

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

  1. import { Transfer, Button } from 'antd';
  3. class App extends React.Component {
  4.   state = {
  5.     mockData: [],
  6.     targetKeys: [],
  7.   };
  9.   componentDidMount() {
  10.     this.getMock();
  11.   }
  13.   getMock = () => {
  14.     const targetKeys = [];
  15.     const mockData = [];
  16.     for (let i = 0; i < 20; i++) {
  17.       const data = {
  18.         key: i.toString(),
  19.         title: `content${i + 1}`,
  20.         description: `description of content${i + 1}`,
  21.         chosen: Math.random() * 2 > 1,
  22.       };
  23.       if (data.chosen) {
  24.         targetKeys.push(data.key);
  25.       }
  26.       mockData.push(data);
  27.     }
  28.     this.setState({ mockData, targetKeys });
  29.   };
  31.   handleChange = targetKeys => {
  32.     this.setState({ targetKeys });
  33.   };
  35.   renderFooter = () => (
  36.     <Button size="small" style={{ float: 'right', margin: 5 }} onClick={this.getMock}>
  37.       reload
  38.     </Button>
  39.   );
  41.   render() {
  42.     return (
  43.       <Transfer
  44.         dataSource={this.state.mockData}
  45.         showSearch
  46.         listStyle={{
  47.           width: 250,
  48.           height: 300,
  49.         }}
  50.         operations={['to right', 'to left']}
  51.         targetKeys={this.state.targetKeys}
  52.         onChange={this.handleChange}
  53.         render={item => `${item.title}-${item.description}`}
  54.         footer={this.renderFooter}
  55.       />
  56.     );
  57.   }
  58. }
  60. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图5

自定义渲染行数据

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

  1. import { Transfer } from 'antd';
  3. class App extends React.Component {
  4.   state = {
  5.     mockData: [],
  6.     targetKeys: [],
  7.   };
  9.   componentDidMount() {
  10.     this.getMock();
  11.   }
  13.   getMock = () => {
  14.     const targetKeys = [];
  15.     const mockData = [];
  16.     for (let i = 0; i < 20; i++) {
  17.       const data = {
  18.         key: i.toString(),
  19.         title: `content${i + 1}`,
  20.         description: `description of content${i + 1}`,
  21.         chosen: Math.random() * 2 > 1,
  22.       };
  23.       if (data.chosen) {
  24.         targetKeys.push(data.key);
  25.       }
  26.       mockData.push(data);
  27.     }
  28.     this.setState({ mockData, targetKeys });
  29.   };
  31.   handleChange = (targetKeys, direction, moveKeys) => {
  32.     console.log(targetKeys, direction, moveKeys);
  33.     this.setState({ targetKeys });
  34.   };
  36.   renderItem = item => {
  37.     const customLabel = (
  38.       <span className="custom-item">
  39.         {item.title} - {item.description}
  40.       </span>
  41.     );
  43.     return {
  44.       label: customLabel, // for displayed item
  45.       value: item.title, // for title and filter matching
  46.     };
  47.   };
  49.   render() {
  50.     return (
  51.       <Transfer
  52.         dataSource={this.state.mockData}
  53.         listStyle={{
  54.           width: 300,
  55.           height: 300,
  56.         }}
  57.         targetKeys={this.state.targetKeys}
  58.         onChange={this.handleChange}
  59.         render={this.renderItem}
  60.       />
  61.     );
  62.   }
  63. }
  65. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图6

分页

大数据下使用分页。

  1. import { Transfer, Switch } from 'antd';
  3. const App = () => {
  4.   const [oneWay, setOneWay] = React.useState(false);
  5.   const [mockData, setMockData] = React.useState([]);
  6.   const [targetKeys, setTargetKeys] = React.useState([]);
  8.   React.useEffect(() => {
  9.     const newTargetKeys = [];
  10.     const newMockData = [];
  11.     for (let i = 0; i < 2000; i++) {
  12.       const data = {
  13.         key: i.toString(),
  14.         title: `content${i + 1}`,
  15.         description: `description of content${i + 1}`,
  16.         chosen: Math.random() * 2 > 1,
  17.       };
  18.       if (data.chosen) {
  19.         newTargetKeys.push(data.key);
  20.       }
  21.       newMockData.push(data);
  22.     }
  24.     setTargetKeys(newTargetKeys);
  25.     setMockData(newMockData);
  26.   }, []);
  28.   const onChange = (newTargetKeys, direction, moveKeys) => {
  29.     console.log(newTargetKeys, direction, moveKeys);
  30.     setTargetKeys(newTargetKeys);
  31.   };
  33.   return (
  34.     <>
  35.       <Transfer
  36.         dataSource={mockData}
  37.         targetKeys={targetKeys}
  38.         onChange={onChange}
  39.         render={item => item.title}
  40.         oneWay={oneWay}
  41.         pagination
  42.       />
  43.       <br />
  44.       <Switch
  45.         unCheckedChildren="one way"
  46.         checkedChildren="one way"
  47.         checked={oneWay}
  48.         onChange={setOneWay}
  49.       />
  50.     </>
  51.   );
  52. };
  54. ReactDOM.render(<App />, mountNode);

Transfer穿梭框 - 图7

表格穿梭框

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

  1. import { Transfer, Switch, Table, Tag } from 'antd';
  2. import difference from 'lodash/difference';
  4. // Customize Table Transfer
  5. const TableTransfer = ({ leftColumns, rightColumns, ...restProps }) => (
  6.   <Transfer {...restProps} showSelectAll={false}>
  7.     {({
  8.       direction,
  9.       filteredItems,
  10.       onItemSelectAll,
  11.       onItemSelect,
  12.       selectedKeys: listSelectedKeys,
  13.       disabled: listDisabled,
  14.     }) => {
  15.       const columns = direction === 'left' ? leftColumns : rightColumns;
  17.       const rowSelection = {
  18.         getCheckboxProps: item => ({ disabled: listDisabled || item.disabled }),
  19.         onSelectAll(selected, selectedRows) {
  20.           const treeSelectedKeys = selectedRows
  21.             .filter(item => !item.disabled)
  22.             .map(({ key }) => key);
  23.           const diffKeys = selected
  24.             ? difference(treeSelectedKeys, listSelectedKeys)
  25.             : difference(listSelectedKeys, treeSelectedKeys);
  26.           onItemSelectAll(diffKeys, selected);
  27.         },
  28.         onSelect({ key }, selected) {
  29.           onItemSelect(key, selected);
  30.         },
  31.         selectedRowKeys: listSelectedKeys,
  32.       };
  34.       return (
  35.         <Table
  36.           rowSelection={rowSelection}
  37.           columns={columns}
  38.           dataSource={filteredItems}
  39.           size="small"
  40.           style={{ pointerEvents: listDisabled ? 'none' : null }}
  41.           onRow={({ key, disabled: itemDisabled }) => ({
  42.             onClick: () => {
  43.               if (itemDisabled || listDisabled) return;
  44.               onItemSelect(key, !listSelectedKeys.includes(key));
  45.             },
  46.           })}
  47.         />
  48.       );
  49.     }}
  50.   </Transfer>
  51. );
  53. const mockTags = ['cat', 'dog', 'bird'];
  55. const mockData = [];
  56. for (let i = 0; i < 20; i++) {
  57.   mockData.push({
  58.     key: i.toString(),
  59.     title: `content${i + 1}`,
  60.     description: `description of content${i + 1}`,
  61.     disabled: i % 4 === 0,
  62.     tag: mockTags[i % 3],
  63.   });
  64. }
  66. const originTargetKeys = mockData.filter(item => +item.key % 3 > 1).map(item => item.key);
  68. const leftTableColumns = [
  69.   {
  70.     dataIndex: 'title',
  71.     title: 'Name',
  72.   },
  73.   {
  74.     dataIndex: 'tag',
  75.     title: 'Tag',
  76.     render: tag => <Tag>{tag}</Tag>,
  77.   },
  78.   {
  79.     dataIndex: 'description',
  80.     title: 'Description',
  81.   },
  82. ];
  83. const rightTableColumns = [
  84.   {
  85.     dataIndex: 'title',
  86.     title: 'Name',
  87.   },
  88. ];
  90. class App extends React.Component {
  91.   state = {
  92.     targetKeys: originTargetKeys,
  93.     disabled: false,
  94.     showSearch: false,
  95.   };
  97.   onChange = nextTargetKeys => {
  98.     this.setState({ targetKeys: nextTargetKeys });
  99.   };
  101.   triggerDisable = disabled => {
  102.     this.setState({ disabled });
  103.   };
  105.   triggerShowSearch = showSearch => {
  106.     this.setState({ showSearch });
  107.   };
  109.   render() {
  110.     const { targetKeys, disabled, showSearch } = this.state;
  111.     return (
  112.       <div>
  113.         <TableTransfer
  114.           dataSource={mockData}
  115.           targetKeys={targetKeys}
  116.           disabled={disabled}
  117.           showSearch={showSearch}
  118.           onChange={this.onChange}
  119.           filterOption={(inputValue, item) =>
  120.             item.title.indexOf(inputValue) !== -1 || item.tag.indexOf(inputValue) !== -1
  121.           }
  122.           leftColumns={leftTableColumns}
  123.           rightColumns={rightTableColumns}
  124.         />
  125.         <Switch
  126.           unCheckedChildren="disabled"
  127.           checkedChildren="disabled"
  128.           checked={disabled}
  129.           onChange={this.triggerDisable}
  130.           style={{ marginTop: 16 }}
  131.         />
  132.         <Switch
  133.           unCheckedChildren="showSearch"
  134.           checkedChildren="showSearch"
  135.           checked={showSearch}
  136.           onChange={this.triggerShowSearch}
  137.           style={{ marginTop: 16 }}
  138.         />
  139.       </div>
  140.     );
  141.   }
  142. }
  144. ReactDOM.render(<App />, mountNode);
  1. #components-transfer-demo-table-transfer .ant-table td {
  2.   background: transparent;
  3. }

Transfer穿梭框 - 图8

树穿梭框

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

  1. import { Transfer, Tree } from 'antd';
  3. // Customize Table Transfer
  4. const isChecked = (selectedKeys, eventKey) => {
  5.   return selectedKeys.indexOf(eventKey) !== -1;
  6. };
  8. const generateTree = (treeNodes = [], checkedKeys = []) => {
  9.   return treeNodes.map(({ children, ...props }) => ({
  10.     ...props,
  11.     disabled: checkedKeys.includes(props.key),
  12.     children: generateTree(children, checkedKeys),
  13.   }));
  14. };
  16. const TreeTransfer = ({ dataSource, targetKeys, ...restProps }) => {
  17.   const transferDataSource = [];
  18.   function flatten(list = []) {
  19.     list.forEach(item => {
  20.       transferDataSource.push(item);
  21.       flatten(item.children);
  22.     });
  23.   }
  24.   flatten(dataSource);
  26.   return (
  27.     <Transfer
  28.       {...restProps}
  29.       targetKeys={targetKeys}
  30.       dataSource={transferDataSource}
  31.       className="tree-transfer"
  32.       render={item => item.title}
  33.       showSelectAll={false}
  34.     >
  35.       {({ direction, onItemSelect, selectedKeys }) => {
  36.         if (direction === 'left') {
  37.           const checkedKeys = [...selectedKeys, ...targetKeys];
  38.           return (
  39.             <Tree
  40.               blockNode
  41.               checkable
  42.               checkStrictly
  43.               defaultExpandAll
  44.               checkedKeys={checkedKeys}
  45.               treeData={generateTree(dataSource, targetKeys)}
  46.               onCheck={(_, { node: { key } }) => {
  47.                 onItemSelect(key, !isChecked(checkedKeys, key));
  48.               }}
  49.               onSelect={(_, { node: { key } }) => {
  50.                 onItemSelect(key, !isChecked(checkedKeys, key));
  51.               }}
  52.             />
  53.           );
  54.         }
  55.       }}
  56.     </Transfer>
  57.   );
  58. };
  60. const treeData = [
  61.   { key: '0-0', title: '0-0' },
  62.   {
  63.     key: '0-1',
  64.     title: '0-1',
  65.     children: [
  66.       { key: '0-1-0', title: '0-1-0' },
  67.       { key: '0-1-1', title: '0-1-1' },
  68.     ],
  69.   },
  70.   { key: '0-2', title: '0-3' },
  71. ];
  73. class App extends React.Component {
  74.   state = {
  75.     targetKeys: [],
  76.   };
  78.   onChange = targetKeys => {
  79.     console.log('Target Keys:', targetKeys);
  80.     this.setState({ targetKeys });
  81.   };
  83.   render() {
  84.     const { targetKeys } = this.state;
  85.     return (
  86.       <div>
  87.         <TreeTransfer dataSource={treeData} targetKeys={targetKeys} onChange={this.onChange} />
  88.       </div>
  89.     );
  90.   }
  91. }
  93. ReactDOM.render(<App />, mountNode);

API

Transfer

参数说明类型默认值版本
dataSource数据源，其中的数据将会被渲染到左边一栏中，targetKeys 中指定的除外。TransferItem[][]
disabled是否禁用booleanfalse
filterOption接收 inputValue option 两个参数，当 option 符合筛选条件时，应返回 true，反之则返回 false。(inputValue, option): boolean
footer底部渲染函数(props) => ReactNode
listStyle两个穿梭框的自定义样式object|({direction: ‘left’|’right’}) => object
locale各种语言{ itemUnit: string; itemsUnit: string; searchPlaceholder: string; notFoundContent: ReactNode; }{ itemUnit: ‘项’, itemsUnit: ‘项’, searchPlaceholder: ‘请输入搜索内容’ }
oneWay展示为单向样式booleanfalse4.3.0
operations操作文案集合，顺序从上至下string[][‘>’, ‘<’]
pagination使用分页样式，自定义渲染列表下无效boolean | { pageSize: number }false4.3.0
render每行数据渲染函数，该函数的入参为 dataSource 中的项，返回值为 ReactElement。或者返回一个普通对象，其中 label 字段为 ReactElement，value 字段为 title(record) => ReactNode
selectedKeys设置哪些项应该被选中string[][]
showSearch是否显示搜索框booleanfalse
showSelectAll是否展示全选勾选框booleantrue
targetKeys显示在右侧框数据的 key 集合string[][]
titles标题集合，顺序从左至右ReactNode[][‘’, ‘’]
selectAllLabels自定义顶部多选框标题的集合(ReactNode | (info: { selectedCount: number, totalCount: number }) => ReactNode)[]
onChange选项在两栏之间转移时的回调函数(targetKeys, direction, moveKeys): void
onScroll选项列表滚动时的回调函数(direction, event): void
onSearch搜索框内容时改变时的回调函数(direction: ‘left’|’right’, value: string): void-
onSelectChange选中项发生改变时的回调函数(sourceSelectedKeys, targetSelectedKeys): void

Render Props

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

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

参考示例

  1. <Transfer {...props}>{listProps => <YourComponent {...listProps} />}</Transfer>

注意

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

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

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

FAQ

怎样让 Transfer 穿梭框列表支持异步数据加载

为了保持页码同步，在勾选时可以不移除选项而以禁用代替：https://codesandbox.io/s/93xeb