> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Transfer

数据录入`@rockshin/tao-ui`

[API](#api)

在可选列表和已选列表之间移动记录。

## 何时使用

适合同时展示可选与已选内容的多选操作。应用应维护 targetKeys，并为记录提供稳定 key。

## 示例


### 受控目标列表
勾选记录后通过中间按钮移动；禁用记录不可选择。
```tsx preview="iframe-follow"
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>(['1', '4']);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      titles={['Available', 'Selected']}
      render={(item) => item.title}
    />
  );
}
```

### 受控勾选与事件
selectedKeys 独立控制勾选状态；onChange 同时返回移动方向和记录 key。
```tsx preview
import { useState } from 'react';
import { Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  const [selected, setSelected] = useState<TransferKey[]>(['0']);
  const [event, setEvent] = useState('No records moved');
  return (
    <Stack gap="md">
      <Transfer
        dataSource={data}
        targetKeys={keys}
        selectedKeys={selected}
        onSelectChange={(source, target) => setSelected([...source, ...target])}
        onChange={(next, direction, moved) => {
          setKeys(next);
          setEvent(`${moved.length} record(s) moved ${direction}`);
        }}
        render={(item) => item.title}
      />
      <output>{event}</output>
    </Stack>
  );
}
```

### 多字段搜索
filterOption 接收搜索词、记录和方向。可见标签可以与搜索值不同。
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      showSearch={{ placeholder: 'Name or team' }}
      filterOption={(query, item) =>
        `${item.title} ${item.description}`
          .toLowerCase()
          .includes(query.toLowerCase())
      }
      render={(item) => ({
        label: (
          <span>
            {item.title} · {item.description}
          </span>
        ),
        value: `${item.title} ${item.description}`,
      })}
    />
  );
}
```

### 单向穿梭与分页
oneWay 向右移动记录，并允许在目标列表逐条移除。分页分别作用于两侧列表。
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>(['1', '3']);
  return (
    <Transfer
      oneWay
      pagination={{ pageSize: 4 }}
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      render={(item) => item.title}
    />
  );
}
```

### 页脚与选择说明
为两侧分别提供页脚，并通过 selectAllLabels 展示勾选数量。
```tsx preview
import { useState } from 'react';
import { Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      render={(item) => item.title}
      selectAllLabels={[
        ({ selectedCount, totalCount }) =>
          `${selectedCount} / ${totalCount} available`,
        ({ selectedCount, totalCount }) =>
          `${selectedCount} / ${totalCount} selected`,
      ]}
      footer={(_, info) => (
        <small style={{ display: 'block', padding: 8 }}>
          {info?.direction === 'left'
            ? 'Choose team members'
            : 'Members added to this project'}
        </small>
      )}
    />
  );
}
```

### 自定义列表内容
渲染函数提供 filteredItems、selectedKeys 和选择回调；自定义控件需遵循 disabled 状态。
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';
const data = Array.from({ length: 12 }, (_, index) => ({
  key: String(index),
  title: `Member ${index + 1}`,
  description: index % 2 ? 'Design' : 'Engineering',
  disabled: index === 2,
}));

export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  return (
    <Transfer
      dataSource={data}
      targetKeys={keys}
      onChange={setKeys}
      showSearch
      render={(item) => item.title}
    >
      {({ filteredItems, selectedKeys, onItemSelect, disabled }) => (
        <Stack gap="sm" style={{ padding: 12 }}>
          {filteredItems.map((item) => (
            <Checkbox
              key={item.key}
              disabled={disabled || item.disabled}
              checked={selectedKeys.includes(item.key)}
              onChange={(event) =>
                onItemSelect(item.key, event.currentTarget.checked)
              }
            >
              {item.title} <small>({item.description})</small>
            </Checkbox>
          ))}
        </Stack>
      )}
    </Transfer>
  );
}
```

### 自定义 key、状态与禁用
标识字段不叫 key 时可使用 rowKey；source 和 target 可分别设置语义样式。
```tsx preview
import { useState } from 'react';
import { Button, Stack, Transfer } from '@rockshin/tao-ui';
import type { TransferKey } from '@rockshin/tao-ui';

const data = [
  { id: 1, title: 'Design' },
  { id: 2, title: 'Engineering' },
  { id: 3, title: 'Operations' },
];
export default function Example() {
  const [keys, setKeys] = useState<TransferKey[]>([]);
  const [disabled, setDisabled] = useState(false);
  return (
    <Stack gap="md">
      <Button
        variant="secondary"
        onClick={() => setDisabled((value) => !value)}
      >
        {disabled ? 'Enable' : 'Disable'}
      </Button>
      <Transfer
        dataSource={data}
        rowKey={(item) => item.id}
        targetKeys={keys}
        onChange={setKeys}
        disabled={disabled}
        status={keys.length ? undefined : 'warning'}
        render={(item) => item.title}
        styles={{
          target: { header: { background: 'var(--tao-color-bg-container)' } },
        }}
      />
      <small>Select at least one team.</small>
    </Stack>
  );
}
```

## API


### [#](#transfer)Transfer



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| render | Item content; defaults to the title, or the key when the title is omitted. | `((item: T) => RenderResult) | undefined` | `-` |

