输入类 · Transfer
穿梭框
一个更直观高效的多选选择器,可以露出更多选项的信息,支持搜索功能,缺点是占据更多空间

代码演示

如何引入

基本使用

数据项需传入 value、label、key

分组

将 type 设为 groupList
分组的 dataSource,一级子元素必须拥有 title 以及 children 属性,结构参考 <GroupItem>
暂不支持多层嵌套

自定义筛选逻辑,自定义选项数据渲染

使用filter自定义搜索逻辑,返回 true 时表示当前项符合筛选规则,保留当前项在列表中的显示,返回 false 则表示不符合,当前项会被隐藏
使用renderSourceItem,你可以自定义左侧每一条源数据的渲染结构
使用renderSelectedItem 你可以自定义右侧每一条已选项的渲染结构

禁用

拖拽排序

draggable设为 true,开启拖拽排序功能。v1.11.0 后支持

拖拽 + 自定义已选项渲染

draggable设为 true,开启拖拽排序功能;使用 renderSelectedItem 自定义右侧已选项渲染;
你可以将触发器定义为任意你想要的ReactNode,并且添加样式。将拖拽触发器,使用 sortableHandle 进行包裹即可(sortableHandle于 v 1.22.0 后提供),

完全自定义渲染

Semi 提供了 renderSourcePanelrenderSelectedPanel 入参,允许你完全自定义左右侧两个面板的渲染结构
通过该功能,你可以直接复用 Transfer 内部的逻辑能力,实现高度自定义样式结构的Transfer组件 renderSourcePanel: (sourcePanelProps: SourcePanelProps) => ReactNode
SourcePanelProps包含以下参数,你可以从中获取数据来渲染出你的 Panel 结构
renderSelectedPanel: (selectedPanelProps: SelectedPanelProps) => ReactNode
SelectedPanelProps包含以下参数

完全自定义渲染 、 拖拽排序

在完全自定义渲染的场景下,由于拖拽区的渲染也已由你完全接管,因此你不声明 draggable 亦可。
但你需要自行实现拖拽逻辑,我们推荐直接使用react-sortable-hoc
要支持拖拽排序,你需要在拖拽排序结束后,将 oldIndex、newIndex 作为入参,调用 onSortEnd

树穿梭框

传入 type 为treeList,使用Tree组件作为自定义渲染列表。v1.20.0 提供
可通过treeProps(TreeProps)来覆盖默认树的属性,左侧树默认属性为

Accessibility

ARIA

  • 搜索框添加 role search
  • 右侧选中列表添加 role list,选中项添加 role listitem

API 参考

Trasnfer Props

属性说明类型默认值版本
className样式类名string
dataSource数据源Array<Item>|Array<GroupItem>|Array<TreeItem>[]
defaultValue默认已选中值Array<string|number>
disabled是否禁用booleanfalse
draggable是否开启拖拽排序booleanfalse
emptyContent自定义空状态的提示文本,search 为无搜索结果时展示的文本,left 为左侧无源数据时的文本,right 为无勾选数据时的提示文本{left: ReactNode; right: ReactNode; search: ReactNode;}
filter自定义筛选逻辑, 当为 false 时,不展示搜索框boolean | (input:string, item: Item) => booleantrue
inputProps可用于自定义搜索框 Input,可配置属性参考 Input 组件,其中 value 和 onChange 参数在 Transfer 内部会被使用,用户请勿使用,如需通过外部数据进行搜索,可调用 Transfer 的 search 方法InputProps
loading是否正在加载左侧选项boolean-
onChange选中值发生变化时触发的回调, 拖拽排序变化后也会触发该回调(values: Array<string|number>, items: Array<Item>) => void
onDeselect取消勾选时的回调(item: Item) => void
onSearch搜索框输入内容变化时调用(inputValue: string) => void
onSelect勾选时的回调(item: Item) => void
renderSelectedItem自定义右侧单个已选项的渲染(item: { onRemove, sortableHandle } & Item) => ReactNode
renderSelectedPanel自定义右侧已选面板的渲染(selectedPanelProps) => ReactNode1.11.0
renderSourceItem自定义左侧单个候选项的渲染(item: { onChange, checked } & Item) => ReactNode
renderSourcePanel自定义左侧候选面板的渲染(sourcePanelProps) => ReactNode1.11.0
showPath当 type 为treeList时,控制右侧选中项是否显示选择路径booleanfalse1.20.0
style内联样式CSSProperties
treeProps当 type 为treeList时,可作为 TreeProps 传入左侧的 Tree 组件TreeProps1.20.0
typeTransfer 类型,可选listgroupListtreeListstring'list'1.20.0
value已选中值,传入该项时,将作为受控组件使用Array<string|number>

Item Interface

属性说明类型默认值
className样式类名string
disabled是否禁用booleanfalse
key必填,每个选项的唯一标识,不允许重复string | number
label选项展示内容ReactNode
style内联样式CSSProperties
value选项代表的值string | number

GroupItem Interface

GroupItem继承Item的所有属性
属性说明类型默认值
children该分组的元素Array<Item>
title分组名称string

TreeItem Interface

TreeItem 继承 Item 的所有属性
属性说明类型默认值
children子元素Array<TreeItem>

Method

  • search(value: string):可通过 ref 调用该方法进行搜索,该搜索值会被置给 Input。

设计变量