Transfer#
数据录入
@rockshin/tao-ui在可选列表和已选列表之间移动记录。
#何时使用
适合同时展示可选与已选内容的多选操作。应用应维护 targetKeys,并为记录提供稳定 key。
#示例
#受控目标列表
勾选记录后通过中间按钮移动;禁用记录不可选择。
TSX
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。
1/12 itemsSource
0 itemsTarget
- No data
TSX
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 接收搜索词、记录和方向。可见标签可以与搜索值不同。
12 itemsSource
0 itemsTarget
- No data
TSX
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 向右移动记录,并允许在目标列表逐条移除。分页分别作用于两侧列表。
10 itemsSource
- /3
2 itemsTarget
- Member 2
- Member 4
- /1
TSX
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 展示勾选数量。
0 / 12 availableSource
Choose team members
0 / 0 selectedTarget
- No data
Members added to this project
TSX
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 状态。
12 itemsSource
0 itemsTarget
TSX
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 可分别设置语义样式。
3 itemsSource
0 itemsTarget
- No data
TSX
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
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| disabled | 是否禁用 | boolean | undefined | - |
| render | Item content; defaults to the title, or the key when the title is omitted. | ((item: T) => RenderResult) | undefined | - |