Transfer 穿梭框
在可用与已选两个列表之间批量移动一组离散项目。
使用概览
适合使用
- 用户需要从较长候选集合中构建明确的已选集合时。
不建议使用
- 只选择一两项，或候选数量极大需要搜索和服务端查询时。
真实示例
项目成员穿梭框
在候选成员与项目成员列表之间移动人员。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/transfer.json基础用法
导入
import { Transfer } from "@richardqiu/quartz/transfer";JSX
<Transfer availableLabel="可用成员" selectedLabel="项目成员" addLabel="添加成员" removeLabel="移除成员" items={[{ id: "lin", label: "林晨" }, { id: "zhou", label: "周宁" }]} defaultValue={["lin"]} />状态与控制摘要
默认
键盘焦点可见
已选择
空状态
已禁用
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | readonly TransferItem[] | 必填 | 提供可移动项目的稳定标识、标签与禁用状态。 |
value | readonly string[] | [] | 受控指定当前位于已选列表中的项目标识。 |
组合结构
- 01
Transfer
键盘约定
- Tab 访问原生复选框和移动操作，空格键切换或激活当前控件。
可访问性契约
- 两个集合和移动操作都需要由使用方命名。
- 禁用项即使被勾选也不会移动。