> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/transfer.html

> 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.

# Transfer 穿梭框

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

## 基本用法


可选项目10

资源 1

资源 3

资源 5

资源 6

资源 7

资源 8

资源 9

资源 10

资源 11

资源 12

已选项目2

资源 2

资源 4

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/transfer/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

- 成员 1Developer
- 成员 2Designer
- 成员 3Developer
- 成员 4Designer
- 成员 5Developer
- 成员 6Designer
- 成员 7Developer
- 成员 8Designer
- 成员 9Developer
- 成员 10Designer

团队成员0

暂无项目

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/transfer/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 时，可以导入这些类型。

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

## TransferChangeInfo API

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

## TransferItem API

| 属性            | 类型          | 默认值 | 说明       |
| ------------- | ----------- | --- | -------- |
| `key`         | `string`    | 必填  | 唯一且稳定的标识 |
| `label`       | `ReactNode` | 必填  | 显示内容     |
| `description` | `string`    | —   | 补充说明     |
| `disabled`    | `boolean`   | —   | 禁止交互     |
| `searchLabel` | `string`    | —   | 搜索使用的纯文字 |

## TransferProps API

| 属性                  | 类型                                                                              | 默认值     | 说明                  |
| ------------------- | ------------------------------------------------------------------------------- | ------- | ------------------- |
| `items`             | [`readonly TransferItem[]`](#transferitem-api)                                  | 必填      | 数据项目，保持 key 唯一且稳定   |
| `value`             | `readonly string[]`                                                             | —       | 受控值                 |
| `defaultValue`      | `readonly string[]`                                                             | `[]`    | 初始值；非受控表单 reset 时恢复 |
| `onChange`          | [`(keys: string[], info: TransferChangeInfo) => void`](#transferchangeinfo-api) | —       | 值变化回调               |
| `selectedKeys`      | `readonly string[]`                                                             | —       | 待移动的勾选项目            |
| `onSelectionChange` | `(keys: string[]) => void`                                                      | —       | 待移动项目变化             |
| `titles`            | `readonly [ReactNode, ReactNode]`                                               | —       | 左、右标题               |
| `searchable`        | `boolean`                                                                       | `true`  | 显示搜索框               |
| `filterOption`      | [`(query: string, item: TransferItem) => boolean`](#transferitem-api)           | —       | 自定义搜索规则             |
| `renderItem`        | [`(item: TransferItem) => ReactNode`](#transferitem-api)                        | —       | 自定义项目内容             |
| `disabled`          | `boolean`                                                                       | —       | 禁止交互                |
| `height`            | `number`                                                                        | `180`   | 高度，数字按像素计算          |
| `virtual`           | `boolean`                                                                       | `false` | 仅渲染可见项目             |
| `name`              | `string`                                                                        | —       | 表单字段名称              |
| `form`              | `string`                                                                        | —       | 关联表单 ID             |
| `required`          | `boolean`                                                                       | —       | 表单必填验证              |
| `oneWay`            | `boolean`                                                                       | `false` | 只允许向右移入             |