For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/transfer.md.

Transfer 穿梭框

在两个列表之间选择和移动项目。

基本用法

可选项目10
已选项目2
basic.tsx
import { Transfer } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function TransferBasic() {
  const items = Array.from({ length: 12 }, (_, index) => ({
    key: String(index),
    label: `资源 ${index + 1}`,
    disabled: index === 4,
  }));
  const [value, setValue] = useState<readonly string[]>(['1', '3']);
  return <Transfer items={items} value={value} onChange={setValue} />;
}

更多用法

全部成员2000
团队成员0
advanced.tsx
import { Transfer } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function TransferVirtual() {
  const [items] = useState(() =>
    Array.from({ length: 2000 }, (_, index) => ({
      key: String(index),
      label: `成员 ${index + 1}`,
      description: index % 2 ? 'Designer' : 'Developer',
    })),
  );
  return <Transfer items={items} virtual height={240} titles={['全部成员', '团队成员']} />;
}

使用说明

value 表示右侧列表的项目 key,selectedKeys 表示当前勾选项。支持搜索、批量移动、单向移动与虚拟列表;name 提交 JSON 数组字符串。

类型

组装数据、定义回调和使用 ref 时,可以导入这些类型。

import type { TransferChangeInfo, TransferItem, TransferProps } from '@ifhover/leaf-ui';

TransferChangeInfo API

属性类型默认值说明
direction'left' | 'right'必填排列方向或移动方向
movedKeysstring[]必填本次移动标识

TransferItem API

属性类型默认值说明
keystring必填唯一且稳定的标识
labelReactNode必填显示内容
descriptionstring—补充说明
disabledboolean—禁止交互
searchLabelstring—搜索使用的纯文字

TransferProps API

属性类型默认值说明
itemsreadonly TransferItem[]必填数据项目,保持 key 唯一且稳定
valuereadonly string[]—受控值
defaultValuereadonly string[][]初始值;非受控表单 reset 时恢复
onChange(keys: string[], info: TransferChangeInfo) => void—值变化回调
selectedKeysreadonly string[]—待移动的勾选项目
onSelectionChange(keys: string[]) => void—待移动项目变化
titlesreadonly [ReactNode, ReactNode]—左、右标题
searchablebooleantrue显示搜索框
filterOption(query: string, item: TransferItem) => boolean—自定义搜索规则
renderItem(item: TransferItem) => ReactNode—自定义项目内容
disabledboolean—禁止交互
heightnumber180高度,数字按像素计算
virtualbooleanfalse仅渲染可见项目
namestring—表单字段名称
formstring—关联表单 ID
requiredboolean—表单必填验证
oneWaybooleanfalse只允许向右移入