antd Transfer 穿梭框基础用法全解析:dataSource、targetKeys、render 与三大回调函数实战指南
antd Transfer 穿梭框基础用法全解析:dataSource、targetKeys、render 与三大回调函数实战指南
导读
本文围绕 Ant Design(antd)穿梭框组件 Transfer 的最基础用法展开,以官方示例 basic.tsx 为骨架,完整讲解 dataSource、targetKeys 两大核心数据属性,以及 render 行渲染函数与 onChange、onSelectChange、onScroll 三个回调函数的实际调用时机与参数含义。读完本文,你将能够从零搭建一个可运行、可受控的 Transfer 穿梭框,并理解组件底层"双栏数据拆分"与"选中状态管理"的实现原理,为后续使用搜索、分页、自定义渲染等高级能力打下基础。
一、示例背景:它解决什么问题
Transfer(穿梭框)是 antd 数据录入类组件,用于在两个栏之间直观地移动选项完成多选行为。左边一栏为 source(源),右边一栏为 target(目标),点击中间的方向操作按钮即可把选中项移动到另一栏。
basic 示例(见 basic.md)演示了组件最核心的受控用法:提供数据源与目标 key 数组,加上渲染函数和若干回调函数,即可完成一个完整可交互的穿梭框。这也是官方文档 Transfer 使用说明 中第一个代码演示,所有更复杂的场景(搜索、分页、树穿梭框等)都建立在这套基础 API 之上。
二、从零搭建:完整的可运行示例
以下代码即 basic.tsx 的完整实现,无需任何额外依赖即可直接运行:
import React, { useState } from 'react';
import { Transfer } from 'antd';
import type { TransferProps } from 'antd';
interface RecordType {
key: string;
title: string;
description: string;
}
const mockData = Array.from({ length: 20 }).map<RecordType>((_, i) => ({
key: i.toString(),
title: `content${i + 1}`,
description: `description of content${i + 1}`,
}));
const initialTargetKeys = mockData
.filter((item) => Number(item.key) > 10)
.map((item) => item.key);
const App: React.FC = () => {
const [targetKeys, setTargetKeys] = useState<TransferProps['targetKeys']>(initialTargetKeys);
const [selectedKeys, setSelectedKeys] = useState<TransferProps['targetKeys']>([]);
const onChange: TransferProps['onChange'] = (nextTargetKeys, direction, moveKeys) => {
console.log('targetKeys:', nextTargetKeys);
console.log('direction:', direction);
console.log('moveKeys:', moveKeys);
setTargetKeys(nextTargetKeys);
};
const onSelectChange: TransferProps['onSelectChange'] = (
sourceSelectedKeys,
targetSelectedKeys,
) => {
console.log('sourceSelectedKeys:', sourceSelectedKeys);
console.log('targetSelectedKeys:', targetSelectedKeys);
setSelectedKeys([...sourceSelectedKeys, ...targetSelectedKeys]);
};
const onScroll: TransferProps['onScroll'] = (direction, e) => {
console.log('direction:', direction);
console.log('target:', e.target);
};
return (
<Transfer
dataSource={mockData}
titles={['Source', 'Target']}
targetKeys={targetKeys}
selectedKeys={selectedKeys}
onChange={onChange}
onSelectChange={onSelectChange}
onScroll={onScroll}
render={(item) => item.title}
/>
);
};
export default App;
运行效果:左栏展示 20 条数据(content1~content20),其中 key 大于 10 的 9 条初始已位于右栏;勾选左栏选项后点击中间的 > 按钮将其移入右栏,勾选右栏选项后点击 < 按钮移回左栏;点击标题栏的多选框可全选/取消全选当前栏。
三、核心数据属性:dataSource 与 targetKeys
3.1 dataSource:数据源
dataSource 是穿梭框的数据源数组,其中的数据默认渲染到左边一栏(targetKeys 中指定的除外)。类型定义为 RecordType extends TransferItem = TransferItem[],默认值为 []。
组件对单项数据的要求很灵活。从源码 index.tsx 可以看到 TransferItem 的约定字段:
export interface TransferItem {
key?: TransferKey;
title?: string;
description?: string;
disabled?: boolean;
[name: string]: any; // 允许任意扩展字段
}
key:唯一标识,用于区分每行数据;title:行标题,当未提供render函数时作为默认渲染文本;description:行描述(在自定义列表场景中使用);disabled:置灰该项,禁止选中与移动;- 其余字段任意扩展,供自定义渲染时使用。
key 是必须的。根据官方文档"注意"一节(见 index.zh-CN.md),React 组件数组必须绑定 key,Transfer 默认取数据项的 key 属性作为唯一标识;若数据主键叫别的名字(如 uid),务必用 rowKey 指定:
return <Transfer rowKey={(record) => record.uid} />;
3.2 targetKeys:目标栏的 key 集合
targetKeys 声明哪些项当前位于右侧目标栏,类型为 string[] | number[],默认 []。它是典型的受控属性:组件本身不维护目标列表,必须由外部通过 onChange 回调更新它,才能驱动界面变化。
数据如何拆分成左右两栏?从源码 useData.ts 可以看到底层逻辑:
- 先对
dataSource逐项处理:若传入了rowKey,则用rowKey(record)的返回值覆盖key字段; - 将
targetKeys建立为 Map,遍历合并后的数据源——命中targetKeys的项放入右栏(且右栏顺序严格按targetKeys的顺序排列),未命中的放入左栏(保持dataSource原始顺序)。
if (targetKeysMap.has(record.key)) {
(rightData as any)[targetKeysMap.get(record.key) as any] = record;
} else {
leftData.push(record as any);
}
这也是"穿梭"的语义基础:目标状态完全由 targetKeys 这一个数组决定,组件只负责把它翻译成左右两栏的视图。
3.3 受控模式:为什么必须用 useState
官方文档明确提示:穿梭框组件只支持受控使用,不支持非受控模式。因此示例中把 targetKeys 和 selectedKeys 都放进 useState,用状态驱动组件:
const [targetKeys, setTargetKeys] = useState<TransferProps['targetKeys']>(initialTargetKeys);
const [selectedKeys, setSelectedKeys] = useState<TransferProps['targetKeys']>([]);
initialTargetKeys 的生成也体现了"数据驱动"的思路——直接从数据源过滤出 key 大于 10 的项作为初始目标:
const initialTargetKeys = mockData
.filter((item) => Number(item.key) > 10)
.map((item) => item.key);
四、行渲染函数 render
render 用于自定义每行数据的展示内容,入参是 dataSource 中的一项,返回值为 ReactNode;也可以返回一个对象,其中 label 字段为 ReactElement、value 字段为 title(用于自定义场景下的取值)。
基础示例中只用了一行代码:
render={(item) => item.title}
即把每行渲染为数据项的 title 文本。在更复杂的场景中,可以返回任意 JSX,例如展示多字段信息或嵌套图标,这正是穿梭框相比 Select 能展示更多选项信息的原因(官方"何时使用"一节也提到这一点)。当 render 未提供时,组件会退回使用 TransferItem 的 title 字段作为默认渲染文本。
五、三个回调函数:触发时机与参数详解
基础示例完整展示了 Transfer 全部三个核心回调,它们是实现业务逻辑的入口。
5.1 onChange:选项转移时触发
const onChange: TransferProps['onChange'] = (nextTargetKeys, direction, moveKeys) => {
console.log('targetKeys:', nextTargetKeys);
console.log('direction:', direction);
console.log('moveKeys:', moveKeys);
setTargetKeys(nextTargetKeys);
};
- 触发时机:点击中间的
>(向右移动)或<(向左移动)按钮时; nextTargetKeys:移动完成后的新目标 key 数组,必须用它setTargetKeys完成受控更新;direction:移动方向,'left' | 'right',即从右栏移回左栏为'left',从左栏移入右栏为'right';moveKeys:本次实际被移动的 key 数组。
从源码 index.tsx 看 moveTo 的实现:向右移动时新目标为 newMoveKeys.concat(targetKeys)(移入的排在最前),向左移动时从 targetKeys 中过滤掉被移回左栏的 key;随后清空对侧栏的选中态,最后调用 onChange?.(newTargetKeys, direction, newMoveKeys)。注意,移动前还会用 groupDisabledKeysMap 过滤掉 disabled 的选项,保证禁用项不会被移动。
5.2 onSelectChange:选中项变化时触发
const onSelectChange: TransferProps['onSelectChange'] = (
sourceSelectedKeys,
targetSelectedKeys,
) => {
console.log('sourceSelectedKeys:', sourceSelectedKeys);
console.log('targetSelectedKeys:', targetSelectedKeys);
setSelectedKeys([...sourceSelectedKeys, ...targetSelectedKeys]);
};
- 触发时机:勾选/取消勾选任意一栏中的条目,或点击标题栏全选/取消全选时;
sourceSelectedKeys:左栏当前选中的 key 数组;targetSelectedKeys:右栏当前选中的 key 数组。
示例把两侧选中 key 合并后写回 selectedKeys 受控属性。选中状态的内部管理在源码 useSelection.ts 中实现:组件内部将 selectedKeys 拆分为左、右两栏各自的选中数组,并通过 filterKeys 过滤掉数据源中不存在的 key;同时当 dataSource 变化时也会自动清理失效的选中项。
在 index.test.tsx 中可以看到大量针对 onSelectChange 的断言,包括单选、全选、以及按住 Shift 键进行连续多选(源码通过 useMultipleSelect 支持)。
5.3 onScroll:列表滚动时触发
const onScroll: TransferProps['onScroll'] = (direction, e) => {
console.log('direction:', direction);
console.log('target:', e.target);
};
- 触发时机:左栏或右栏的选项列表发生滚动时;
direction:发生滚动的栏,'left' | 'right';e:原生 React 合成滚动事件,其target为滚动容器(HTMLUListElement)。
该回调常用于实现"滚动加载更多"等大数据场景的按需取数。源码中左、右栏分别通过 handleLeftScroll / handleRightScroll 包装后传入各自 List 的 onScroll(见 index.tsx)。
5.4 补充:titles 与 operations
示例中还传入了 titles={['Source', 'Target']},用于设置左右两栏的标题,顺序从左至右(类型 ReactNode[])。与之配套的 operations 用于自定义中间操作按钮的文案,默认从上至下为 ['>', '<']。
六、源码级原理:数据拆分与状态管理
将基础示例的 props 传入组件后,index.tsx 的渲染流程可以概括为:
- 数据准备:通过
useData(dataSource, rowKey, targetKeys)得到[mergedDataSource, leftDataSource, rightDataSource]三份数据——合并了 key 的全量数据、左栏数据、右栏数据; - 选中拆分:通过
useSelection(leftDataSource, rightDataSource, selectedKeys)把外部传入的selectedKeys拆成sourceSelectedKeys与targetSelectedKeys两组; - 渲染三部件:左栏
List+ 中间Operation(方向按钮区)+ 右栏List; - 事件分发:
Operation的点击触发moveToRight/moveToLeft,最终收敛到onChange;List 的条目勾选收敛到onSelectChange;列表滚动收敛到onScroll。
此外,组件还从 ConfigContext 读取前缀类名与方向(支持 RTL),并从 FormItemInputContext 合并表单校验状态(status),这些属于进阶能力,不影响基础用法。
一个值得注意的细节:当未传入 selectedKeys prop 时,组件内部会自行维护选中状态(见 index.tsx),因此即使业务上不管理选中,勾选交互依然可用;但传入后即变为受控,需像示例那样同步回写。
七、延伸阅读
掌握基础用法后,可继续探索 demo 目录下的其他示例:
- search.tsx:带搜索框(
showSearch+filterOption+onSearch); - oneWay.tsx:单向模式(
oneWay); - large-data.tsx:分页(
pagination); - table-transfer.tsx:用 Render Props 自定义列表实现表格穿梭框;
- tree-transfer.tsx:树穿梭框;
- advanced.tsx:footer、operation 等高级配置组合。
完整 API 参数表(含 filterOption、footer、listStyle、locale、selectAllLabels、showSelectAll、status、pagination 等全部配置项的类型、默认值与版本信息)请查阅 index.zh-CN.md;组件整体架构可结合 index.tsx、list.tsx、operation.tsx 阅读;交互行为可通过 index.test.tsx 等测试用例验证。