antd Transfer 穿梭框基础用法全解析:dataSource、targetKeys、render 与三大回调函数实战指南

原创2026-09-19 19:26:341,705 阅读
文章标签:前端UI组件设计系统

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 可以看到底层逻辑:

  1. 先对 dataSource 逐项处理:若传入了 rowKey,则用 rowKey(record) 的返回值覆盖 key 字段;
  2. 将 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 的渲染流程可以概括为:

  1. 数据准备:通过 useData(dataSource, rowKey, targetKeys) 得到 [mergedDataSource, leftDataSource, rightDataSource] 三份数据——合并了 key 的全量数据、左栏数据、右栏数据;
  2. 选中拆分:通过 useSelection(leftDataSource, rightDataSource, selectedKeys) 把外部传入的 selectedKeys 拆成 sourceSelectedKeys 与 targetSelectedKeys 两组;
  3. 渲染三部件:左栏 List + 中间 Operation(方向按钮区)+ 右栏 List;
  4. 事件分发:Operation 的点击触发 moveToRight / moveToLeft,最终收敛到 onChange;List 的条目勾选收敛到 onSelectChange;列表滚动收敛到 onScroll。

此外,组件还从 ConfigContext 读取前缀类名与方向(支持 RTL),并从 FormItemInputContext 合并表单校验状态(status),这些属于进阶能力,不影响基础用法。

一个值得注意的细节:当未传入 selectedKeys prop 时,组件内部会自行维护选中状态(见 index.tsx),因此即使业务上不管理选中,勾选交互依然可用;但传入后即变为受控,需像示例那样同步回写。

七、延伸阅读

掌握基础用法后,可继续探索 demo 目录下的其他示例:

完整 API 参数表(含 filterOption、footer、listStyle、locale、selectAllLabels、showSelectAll、status、pagination 等全部配置项的类型、默认值与版本信息)请查阅 index.zh-CN.md;组件整体架构可结合 index.tsx、list.tsx、operation.tsx 阅读;交互行为可通过 index.test.tsx 等测试用例验证。

登录后查看全文
ant-design