Transfer

transfer

穿梭框 · 左右双 listbox 面板 + 移动按钮(选中/全部) + 可选搜索 + 空态(零依赖·复用 Listbox/Empty)

用法

基础用法

勾选左侧条目后用中间箭头移入/移出（›/‹ 移选中，»/« 全部）。非受控时用 defaultTargetKeys 设初始已选。

全部功能模块9

已授权3

tsx

<Transfer
  dataSource={modules}
  defaultTargetKeys={["dashboard", "orders", "goods"]}
  titles={["全部功能模块", "已授权"]}
  onChange={(target) => save(target)}
/>

可搜索

searchable 在两侧面板顶部各放一个搜索框，输入即按 label 过滤。

全部功能模块11

已授权1

tsx

<Transfer
  dataSource={modules}
  defaultTargetKeys={["dashboard"]}
  searchable
  searchPlaceholder="搜索模块名"
  titles={["全部功能模块", "已授权"]}
/>

整体禁用

disabled 让两侧列表与移动按钮全失效。

全部功能模块10

已授权2

tsx

<Transfer dataSource={modules} defaultTargetKeys={["dashboard", "orders"]} disabled />

何时用

权限分配、可见字段、白名单等「从全集里挑一批进目标集」且两侧都要可见可搜的场景用。当候选项有几十上百条、要批量勾选并能两边对照时比多选 Listbox 直观。如果只是单列多选、不需要「已选/未选」分栏对照，用 Listbox multiple 即可。

导入

import { Transfer } from "@hulianui/ui"

Props

名称	类型	默认	说明
dataSource*	`TransferItem[]`	—	全量数据源；每项 `key`/`label`，可带 `description`/`disabled`
targetKeys	`string[]`	—	受控：右侧（目标）面板的键集合
defaultTargetKeys	`string[]`	—	非受控初始目标键
searchable	`boolean`	`false`	每个面板顶部显示搜索框
searchPlaceholder	`string`	`"搜索"`	搜索框占位符
filterOption	`(input: string, item: TransferItem) => boolean`	label 包含匹配	自定义过滤（默认大小写不敏感子串）
disabled	`boolean`	`false`	整体禁用（两侧列表与移动按钮全失效）
className	`string`	—	容器类名

Events

事件	类型	说明
onChange	`(targetKeys: string[], direction: "left" \| "right", movedKeys: string[]) => void`	移动后回调，`direction` 为 `"right"`（入选）/`"left"`（移出）

Slots

插槽	类型	说明
titles	`[ReactNode, ReactNode]`	左右面板标题（默认 `["源列表","已选"]`）

禁忌 / 坑

onChange 首参就是移动后的完整目标键集合，直接 setTarget 即可（无需自己合并 movedKeys）；后两参 direction/movedKeys 用于审计/差量提示。
disabled 的 item 不可勾选、也不随「全部移入/移出」按钮移动——设计如此，用于冻结历史项。
暂无其它已知坑。

Playground

searchabledisabled

全部功能模块9

已授权3

<Transfer
  dataSource={modules}
  targetKeys={target}
  onChange={setTarget}
  titles={["全部功能模块", "已授权"]}
/>

用法

基础用法

勾选左侧条目后用中间箭头移入/移出（›/‹ 移选中，»/« 全部）。非受控时用 defaultTargetKeys 设初始已选。

全部功能模块9

已授权3

tsx

<Transfer
  dataSource={modules}
  defaultTargetKeys={["dashboard", "orders", "goods"]}
  titles={["全部功能模块", "已授权"]}
  onChange={(target) => save(target)}
/>

可搜索

searchable 在两侧面板顶部各放一个搜索框，输入即按 label 过滤。

全部功能模块11

已授权1

tsx

<Transfer
  dataSource={modules}
  defaultTargetKeys={["dashboard"]}
  searchable
  searchPlaceholder="搜索模块名"
  titles={["全部功能模块", "已授权"]}
/>

整体禁用

disabled 让两侧列表与移动按钮全失效。

全部功能模块10

已授权2

tsx

<Transfer dataSource={modules} defaultTargetKeys={["dashboard", "orders"]} disabled />

何时用

Props

名称	类型	默认	说明
dataSource*	`TransferItem[]`	—	全量数据源；每项 `key`/`label`，可带 `description`/`disabled`
targetKeys	`string[]`	—	受控：右侧（目标）面板的键集合
defaultTargetKeys	`string[]`	—	非受控初始目标键
searchable	`boolean`	`false`	每个面板顶部显示搜索框
searchPlaceholder	`string`	`"搜索"`	搜索框占位符
filterOption	`(input: string, item: TransferItem) => boolean`	label 包含匹配	自定义过滤（默认大小写不敏感子串）
disabled	`boolean`	`false`	整体禁用（两侧列表与移动按钮全失效）
className	`string`	—	容器类名

事件

类型

说明

onChange

(targetKeys: string[], direction: "left" | "right", movedKeys: string[]) => void

移动后回调，direction 为 "right"（入选）/"left"（移出）

插槽

类型

说明

titles

[ReactNode, ReactNode]

左右面板标题（默认 ["源列表","已选"]）

禁忌 / 坑

onChange 首参就是移动后的完整目标键集合，直接 setTarget 即可（无需自己合并 movedKeys）；后两参 direction/movedKeys 用于审计/差量提示。

disabled 的 item 不可勾选、也不随「全部移入/移出」按钮移动——设计如此，用于冻结历史项。

暂无其它已知坑。

Playground

searchabledisabled

全部功能模块9

已授权3

<Transfer
  dataSource={modules}
  targetKeys={target}
  onChange={setTarget}
  titles={["全部功能模块", "已授权"]}
/>

Transfer

用法

基础用法

可搜索

整体禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Transfer

用法

基础用法

可搜索

整体禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground