Transfer
在两个集合之间移动条目。中文惯用名：穿梭框。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.transfer |
| 名称 | Transfer |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 在两个集合之间移动条目 |
| 描述 | 中文惯用名：穿梭框。 |
预览
静态结构：Transfer 根节点 data-slot="transfer"，左右两个面板（data-slot 分别为 transfer-left-panel / transfer-right-panel）加中间竖排两个移动按钮（「移到右侧」「移到左侧」，无勾选时禁用）。每个面板：列头为全选 checkbox（仅作用于该列可用项）+ 标题 + 计数（「N 项」），列体为 checkbox 列表（禁用项半透明不可勾）。勾选后点移动按钮批量迁移并清空该侧勾选；disabled 的选项不参与移动。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "Transfer",
"props": {
"name": "owners",
"titles": [
"候选成员",
"已选成员"
],
"options": [
{
"label": "陈晨",
"value": "u-01"
},
{
"label": "林晚",
"value": "u-02"
},
{
"label": "苏叶",
"value": "u-03"
},
{
"label": "周屿",
"value": "u-04"
}
]
}
}何时用
何时使用
- 在两个集合之间移动条目：从候选集挑选成员、权限项、字段子集。
- 候选数量较多且需要直观对照「已选 / 未选」两栏，批量勾选移动。
何时不用
- 少量选项（十几个以内）的多选：使用 Checkbox 组或 Select 多选，Transfer 的双栏结构过重。
- 需要排序已选集合：当前实现不含排序能力，仅维护目标侧集合。
- 层级数据选择：使用 TreeSelect / Cascader。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 基础穿梭 | 左右两栏 + 中间移动按钮，titles 缺省「列表 1 / 列表 2」 | 通用候选 → 目标集合挑选 |
| titles 自定义标题 | 列头标题按业务命名 | 语义化双栏（如「可选权限 / 已授权限」） |
| 选项级 disabled | 单个选项半透明不可勾选、不参与移动 | 必备项 / 无权限项锁定在某侧 |
| disabled 整体禁用 | 全部勾选与移动按钮禁用 | 只读回显已选集合 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
options | TransferOption[] | [] | 全部选项（{ label, value, disabled? }；左列 = 未进目标侧的项，右列 = 目标侧的项） |
value | `Array<string | number>` | — |
titles | [string, string] | ['列表 1', '列表 2'] | 左右两列标题 |
disabled | boolean | false | 整体禁用（勾选与移动均不可用） |
onChange | `(value: Array<string | number>) => void` | — |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为控件根节点） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- 值与 onChange 只表达目标侧（右列）value 数组；左列由 options 减去目标侧推导，不要单独维护。
- titles 按业务语义命名（如「候选成员 / 已选成员」），不要沿用缺省「列表 1 / 列表 2」上线。
- 勾选是中间态，点移动按钮才提交 onChange；移动后该侧勾选自动清空。
- 选项级 disabled 用于锁定必备项；整体 disabled 用于只读回显。
- 候选少量时不要上 Transfer：双栏结构在十几个选项内反而降低效率，用 Checkbox 组。
正例
- ✓ 权限配置：options 为全部权限点，titles ["未授权", "已授权"]，批量勾选后点箭头移动。
- ✓ 报表字段挑选：几十个字段中选展示列，Form 内 name + 至少选一项 rules。
- ✓ 必备项锁定：核心字段选项 disabled，始终留在目标侧不可移出。
反例
- ✕ 8 个选项的多选也上 Transfer（应使用 Checkbox 组）。
- ✕ 用缺省标题「列表 1 / 列表 2」直接上线，用户不理解两栏语义。
- ✕ 试图用 Transfer 对已选集合排序（实现不含排序能力）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。