SepTransfer 穿梭框组件 v1.0.0
双栏穿梭选择 · 搜索过滤 · 分页 · 全选/半选 · 一键全移/全清 · 自定义渲染 · 单向模式 · 拖拽排序/跨面板移动 · 禁用
1. 基础用法
HTML 声明式标签
JS API 初始化
已选值：[]
2. 搜索过滤 showSearch
HTML 声明式标签
JS API 初始化
3. 分页 pagination
HTML 声明式标签
JS API 初始化
4. 自定义渲染 renderItem
HTML 声明式标签（基础版）
JS API 初始化（renderItem 自定义每项 DOM）
5. 禁用 disabled
HTML 声明式标签
JS API 初始化
6. 单向模式 oneWay
HTML 声明式标签
JS API 初始化
7. 拖拽排序 / 跨面板移动 sortable
可直接拖拽项在左右面板间移动；列表内拖拽可调整顺序。支持 Ctrl/Cmd+点击 多选、Shift+点击 范围选择，然后批量拖拽
HTML 声明式标签
JS API 初始化
8. 一键全移 / 全清 showMoveAll / showClear
HTML 声明式标签
JS API 初始化
9. 固定高度 height
height: 320 — 组件高度固定为 320px，移动项目后高度不变
HTML 声明式标签
JS API 初始化
10. 占满父容器 height: 'fill'
height: 'fill' — 组件占满父容器高度（下方容器固定 360px）
HTML 声明式标签
JS API 初始化
11. 自定义字段映射 fieldNames
后端数据用 id/name/inactive 字段，通过 fieldNames 映射无需预处理
HTML 声明式标签
JS API 初始化
12. 自定义操作按钮 operations
通过 operations 配置按钮文字或隐藏部分按钮
HTML 声明式标签
JS API 初始化
13. 自定义空状态 emptyText / renderEmpty
emptyText 自定义文本，或 renderEmpty 完全自定义渲染
HTML 声明式标签（emptyText 文本）
JS API 初始化（renderEmpty 自定义 DOM）
14. 树模式 Tree Transfer
左侧以树形结构展示层级数据，仅允许移动叶子节点到右侧（适用于组织架构、分类层级等场景）
HTML 声明式标签
JS API 初始化
已选值：[]
15. 增强功能（targetOrder / defaultCheckedKeys / showSelectAll / onDragEnd）
targetOrder: 'unshift' — 新移入项出现在目标列表顶部
targetOrder: 'original' — 目标项按数据源原始顺序排列
defaultCheckedKeys — 初始化时预选左侧第 1、2 项
showSelectAll: false — 隐藏左右面板的全选复选框
onDragEnd — 拖拽结束回调（含 dropped 标记）
最近一次拖拽结束：无
16. 虚拟滚动 virtualScroll（大数据量）
5000 条数据，启用虚拟滚动 + 固定 itemHeight=32px
实际渲染 DOM 节点数：- / 数据总数 5000
virtualScroll: 'auto' + virtualListThreshold: 100 — 数据量超过阈值自动启用
当前模式：-
17. 远程搜索 remote / remoteMethod
输入关键词，模拟远程接口返回过滤结果
最近一次远程请求：无
18. 面板宽度 panelWidth / 最大数量 max
panelWidth: 180px — 自定义左右面板宽度
max: 3 — 目标列表最多容纳 3 项
当前目标列表数量：0 / 上限 3
19. rowKey 自定义 key 函数
数据无标准 key 字段时，用 rowKey 函数提取唯一标识
20. format 自定义计数文案
自定义 header 右侧 "已选 X / 共 Y 条" 显示
21. buttonTexts 自定义按钮文字
操作按钮显示文字而非图标
22. footer / renderFooter 自定义底部
左右面板底部自定义内容（与 pagination 互斥）
23. selectedKeys 受控勾选
通过 selectedKeys 受控管理勾选状态，配合 onSelectChange 实现外部状态同步
当前勾选：源 - / 目标 -
24. onScroll 滚动事件（懒加载 / 无限滚动）
监听面板滚动，reachBottom 到达底部时可加载更多数据
滚动信息：未滚动
25. API 速查
配置项 (Props)
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| dataSource | Array | [] | 数据源，每项 { key, label, disabled } |
| value | Array | — | 已选中的 key 数组（受控） |
| defaultValue | Array | [] | 默认选中的 key 数组（非受控） |
| titles | Array | ['源列表','目标列表'] | 左右栏标题 |
| fieldNames | { key, label, disabled, children } | { key:'key', label:'label', disabled:'disabled', children:'children' } | 自定义字段映射，适配后端数据结构 |
| tree | boolean | object | false | 启用树模式，左侧以树形结构展示，仅移动叶子节点 |
| showSearch | boolean | false | 是否显示搜索框（匹配文本自动高亮） |
| searchPlaceholder | string | '请输入搜索' | 搜索框占位文本 |
| filterOption | (kw, item) => boolean | null | 自定义搜索过滤函数 |
| pagination | false | { pageSize } | false | 分页配置 |
| renderItem | (item) => string | Node | null | 自定义项渲染 |
| emptyText | string | '暂无数据' | 空列表提示文本 |
| renderEmpty | (side) => string | Node | null | 自定义空状态渲染 |
| rowKey | (item, index) => string | number | null | 自定义数据项 key 提取函数，优先于 fieldNames.key |
| format | { noChecked?, hasChecked? } | { noChecked: '{total} 项', hasChecked: '{checked}/{total}' } | 自定义 header 计数文案模板，支持 {checked} 和 {total} 占位符 |
| buttonTexts | { toTarget?, toSource?, all?, clear? } | {} | 自定义操作按钮文字，配置后按钮显示文字而非图标 |
| footer | string | Node | null | 左右面板底部自定义内容（与 pagination 互斥，分页优先） |
| renderFooter | (side) => string | Node | null | 左右面板底部自定义渲染函数，参数 side 为 'source' 或 'target' |
| disabled | boolean | false | 是否禁用 |
| oneWay | boolean | false | 单向模式（只能左→右） |
| sortable | boolean | true | 已选列表可拖拽排序；所有项支持左右面板间拖拽移动（不受此选项影响） |
| showMoveAll | boolean | true | 显示一键全移按钮 |
| showClear | boolean | true | 显示一键全清按钮 |
| showSelectAll | boolean | true | 是否显示左右面板的全选复选框 |
| targetOrder | 'push' | 'unshift' | 'original' | 'push' | 新移入目标面板的项的顺序：'push' 追加末尾，'unshift' 插入开头，'original' 按数据源原序 |
| defaultCheckedKeys | { source?: Array, target?: Array } | { source: [], target: [] } | 初始化时默认勾选的 key（左右面板独立，非受控） |
| selectedKeys | { source?: Array, target?: Array } | null | null | 受控勾选状态，优先级高于 defaultCheckedKeys，配合 onSelectChange 同步 |
| operations | { toTarget, toSource, all, clear } | null | 自定义操作按钮：值为 string 显示文字，false 隐藏，省略/true 用默认图标 |
| height | 'auto' | number | string | 'auto' | 组件高度：'auto' 自适应（min 200px / max 360px）；数字如 320 固定 px；'fill' 或 '100%' 占满父容器 |
| panelWidth | number | string | Array | null | 面板宽度：数字=px，字符串=CSS 宽度；单值左右同宽，数组 [左宽, 右宽] 分别设置 |
| virtualScroll | boolean | 'auto' | false | 虚拟滚动：true 强制启用，'auto' 数据量超过 virtualListThreshold 时自动启用（与树模式/分页互斥） |
| virtualListThreshold | number | 100 | virtualScroll 为 'auto' 时自动启用虚拟滚动的数据量阈值 |
| itemHeight | number | 32 | 虚拟滚动单项高度（px） |
| remote | boolean | false | 远程搜索模式，需配合 remoteMethod 使用 |
| remoteMethod | (query, callback, side) => void | null | 远程搜索方法，callback(results) 返回结果数组 |
| max | number | 0 | 目标列表最大数量限制（0 为不限制），达到后禁用移入按钮 |
| onChange | (targetKeys, direction, movedKeys) => void | — | 选中值变化回调 |
| onSearchChange | (direction, keyword) => void | — | 搜索词变化回调 |
| onSelectChange | (sourceChecked, targetChecked) => void | — | 勾选变化回调 |
| onScroll | ({ side, scrollTop, scrollHeight, clientHeight, reachBottom, reachTop }) => void | — | 面板滚动回调，reachBottom 可用于无限滚动加载 |
| onDragStart | ({ from, keys }) => void | — | 拖拽开始回调 |
| onDrop | ({ from, to, keys, dropKey, after }) => void | — | 拖拽放置回调 |
| onDragEnd | ({ from, keys, dropped }) => void | — | 拖拽结束回调；dropped 表示是否成功放置 |
实例方法 (Methods)
| 方法 | 说明 |
|---|---|
| getValue() | 获取已选 key 数组 |
| setValue(keys) | 设置已选 key 数组 |
| getCheckedKeys(side) | 获取某侧勾选的 key（'source' | 'target'） |
| setCheckedKeys(side, keys) | 设置某侧勾选的 key |
| getDataSource() | 获取数据源 |
| setDataSource(data) | 更新数据源 |
| moveToTarget() | 左栏勾选项移到右栏 |
| moveToSource() | 右栏勾选项移到左栏 |
| moveAllToTarget() | 全部移到右栏 |
| clearAll() | 全部移回左栏 |
| getEl() | 获取根元素 |
| getState() / setState() | 获取/设置状态 |
| subscribe(fn) | 订阅状态变化 |
| destroy() | 销毁组件 |