--- id: "transfer" title: "穿梭框" category: "选择组件" document_type: "component-specification" spec_status: "local-current-draft" element_ui: "2.15.6" vue: "2.6.14" page: "../index.html#spec-transfer" source_data: "../component-data.json" official_components: ["transfer"] template_components: ["el-transfer"] scenario_count: 6 verification: "scenario-checklist-not-full-test-pass" --- # 穿梭框 专题 `transfer` · 选择组件 · Element UI 2.15.6 ## 适用范围与组件映射 公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。 官方条目映射：`transfer`。 本页模板直接使用的 Element UI 标签：`el-transfer`。 ## 通用基线 - 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。 - 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。 - 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。 - 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。 - 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。 - 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。 - 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。 - 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。 - 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。 - 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。 - 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。 ## 本页用法与分类 默认用法：需要同时看见可选集合和已选集合、并批量移入移出时，默认使用当前双列穿梭框，保留搜索和两侧计数。 | 区分什么 | 本页内容 | 选用或触发条件 | | --- | --- | --- | | 用途：两集合迁移 | 穿梭框让来源和结果同时可见。 | 需要核对两个集合及批量移动时使用；简单选择少量选项不必引入双列结构。 | | 功能：过滤、排序与内容 | 搜索过滤可见项；标题、按钮文字和目标排序解释移动结果。 | 当前启用搜索并使用可选集合/已选集合标题；接入时只配置确有业务含义的排序或自定义内容，不将其列作不同外观。 | | 自动状态：勾选与可移动性 | 勾选表示准备移动，移入右侧才改变目标集合。 | 部分勾选自动显示半选；无可移动项时方向按钮禁用，禁用项目不能勾选。搜索无结果不清空已迁移集合。 | 使用边界：不把右侧全部项目持续画成蓝色选中行。不把移动完成当作保存成功。 ## 组件规则 - **TRANSFER-R01**：需要同时查看来源与结果并批量移入、移出时使用双列穿梭框；默认保留两侧标题、计数和搜索。标题表达集合含义，不将勾选中与已经迁入目标集合混为一类。 - **TRANSFER-R02**：覆盖搜索、无匹配、全选、部分选择、禁用、批量移入 / 移出；切换搜索不丢已迁移集合。 - **TRANSFER-R03**：迁移不是业务提交，是否保存由宿主决定；大量数据需限定查询范围，不能一次塞入全库。 - **TRANSFER-R04**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。 - **TRANSFER-R05**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。 - **TRANSFER-R06**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。 - **TRANSFER-R07**：穿梭框的搜索框仅在输入聚焦时改变自身边框；搜索无结果不报表单错误。宿主要求至少选择一项且校验失败时，在集合旁给出错误红短提示并关联组名，不给整个双列容器画输入错误框。 - **TRANSFER-R08**：【列表内容】双列白底、边框灰、项目正文深灰；搜索输入按输入框规范，仅聚焦原边框主题蓝。 - **TRANSFER-R09**：【勾选与半选】待移动项复选标记主题蓝、对勾白色；分组只选择部分可选项时头部复选显示白色横线。 - **TRANSFER-R10**：【移动按钮】有可移动项时按按钮规范显示；没有可移动项或方向不允许时浅灰背景、禁用灰并阻止执行。 - **TRANSFER-R11**：【禁用与空结果】禁用项目使用禁用灰且不可勾选；空列表/搜索无结果使用空值灰提示，不显示输入校验红框。 - **TRANSFER-R12**：【焦点与悬停】可操作项目悬停或键盘定位浅灰背景，按钮焦点操作蓝；位置移动不自动表示业务提交成功。 - **TRANSFER-R13**：【组件边界】穿梭框的列表勾选、分组半选和左右移动是不同状态；目标列表中的成员不是一直处于蓝色选中行。 - **TRANSFER-R14**：两侧搜索框各自填满所属面板的内容列，沿用输入框专题；不把普通筛选280px整项规则套到穿梭面板内部。 ## 场景与验收清单 以下为需核对的场景组；`[ ]` 不代表已经测试通过。 - [ ] **TRANSFER-S01**：当前样例：左右集合、搜索、无匹配、全选/部分选择、移入/移出和禁用项。 - [ ] **TRANSFER-S02**：接入验收：按集合含义配置左右标题、计数和移动按钮文字；需要固定目标顺序时再定义目标排序（target-order），需要额外信息时再接入自定义行或底部。这些属于功能与内容配置。 - [ ] **TRANSFER-S03**：过滤不丢失已迁移集合；迁移是本地选择变化，不代表保存成功；无可移动项时按钮禁用。 - [ ] **TRANSFER-S04**：接入验收：远端集合稳定标识与大数据分批查询，不能把当前页全选宣称为全库全选。 - [ ] **TRANSFER-S05**：共用视觉验收：仅核对本组件实际适用的颜色与组合状态；无此能力标为不适用，不给静态内容添加输入错误、半选或按下状态。 - [ ] **TRANSFER-S06**：共用文字验收：正文14px/400、次级操作12px/400、标题600；检查实际子元素与弹出层。输入焦点只改自身边框，按钮和链接保留键盘焦点轮廓。 ### 专题验收重点 搜索后迁移、反向迁移、禁用项不可移动、窄屏不裁按钮。 ## 当前示例模板 以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。 ```html ``` ## 交付与使用边界 - 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。 - 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。 - 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。 ## 来源与关联 - 来源线索：本次补充。 - [打开本专题页面](../index.html#spec-transfer) - [通用基线](FOUNDATIONS.md) - [规范总索引](README.md) - [结构化规范数据](../component-data.json)（记录 id：`transfer`） - [原始历史样板](../original-20260621.html) - [历史规范条目](../spec-notes.json) ## 本组件颜色状态表 | 状态 / 条件 | 统一规则 | | --- | --- | | 列表内容 | 双列白底、边框灰、项目正文深灰；搜索输入按输入框规范，仅聚焦原边框主题蓝。 | | 勾选与半选 | 待移动项复选标记主题蓝、对勾白色；分组只选择部分可选项时头部复选显示白色横线。 | | 移动按钮 | 有可移动项时按按钮规范显示；没有可移动项或方向不允许时浅灰背景、禁用灰并阻止执行。 | | 禁用与空结果 | 禁用项目使用禁用灰且不可勾选；空列表/搜索无结果使用空值灰提示，不显示输入校验红框。 | | 焦点与悬停 | 可操作项目悬停或键盘定位浅灰背景，按钮焦点操作蓝；位置移动不自动表示业务提交成功。 | 穿梭框的列表勾选、分组半选和左右移动是不同状态；目标列表中的成员不是一直处于蓝色选中行。 [公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css) ## 业务落地场景 - [人群标签 · 可选会员 / 已选会员 · 双列穿梭框](../../showcase/index.html#segments) · [场景文档](../../showcase/docs/segments.md)；落地范围：顶部已选人数为当前标签组的已选集合，会员总数为全部可分配会员；左侧可选集合是尚未加入当前组的会员，右侧是已选会员。默认已选6人、会员总数24人，对应左侧18人、右侧6人；两侧勾选计数不等于集合人数。 [竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)