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

代码演示

如何引入

基本使用

数据项需传入 value、label、key

分组

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

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

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

禁用

拖拽排序

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

拖拽 + 自定义已选项渲染

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

自定义渲染面板头部信息

Semi 自 2.29.0 版本提供 renderSourceHeader, renderSelectedHeader 参数允许用户自定义渲染左右两个面板的头部信息。
renderSourceHeader: (props: SourceHeaderProps) => ReactNode
renderSelectedHeader: (props: SelectedHeaderProps) => ReactNode
参数类型如下:
使用示例如下

完全自定义渲染

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

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

在完全自定义渲染的场景下,由于拖拽区的渲染也已由你完全接管,因此你不声明 draggable 亦可。 但你需要自行实现拖拽逻辑,你可以借助社区中拖拽类工具库 dnd-kit 或者 react-sortable-hoc,快速实现功能。关于两者选型,这是我们的一些建议
  • 两者均由同一作者维护, dnd-kit 是 react-sortable-hoc 的接任产品
  • react-sortable-hoc 的 API 设计更加高内聚,在简单场景上代码更加简洁。但它强依赖了 findDOMNode API,在未来的 React 版本中会被废弃。同时该库最近两年已经处于不维护的状态。
  • dnd-kit 相对而言,有一定上手门槛,但它的自由度更高,扩展性更强,并且仍处于维护状态。我们更推荐使用
更多 DIff 信息可查阅 react-sortable-hoc 的 Github 主页
另外,要支持拖拽排序,你需要在拖拽排序结束后,将 oldIndex、newIndex 作为入参,调用 onSortEnd
使用 react-sortable-hoc 的示例:
使用 dnd-kit 的示例如下,需要用到的核心依赖有 @dnd-kit/sortable, @dnd-kit/core,其中核心 hooks 为 useSortable,使用说明如下

树穿梭框

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

Accessibility

ARIA

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

API 参考

Transfer 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 时,不展示搜索框,传入函数可自定义搜素逻辑。当 type 为 treeList时,如需要自定义搜索逻辑,需设置 filter 为 true,并通过 treePropsfilterTreeNode 设置自定义的搜索函数。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
renderSelectedHeader自定义右侧面板头部信息的渲染(props: SelectedHeaderProps) => ReactNode2.29.0
renderSelectedItem自定义右侧单个已选项的渲染(item: { onRemove, sortableHandle } & Item) => ReactNode
renderSelectedPanel自定义右侧已选面板的渲染(selectedPanelProps) => ReactNode1.11.0
renderSourceHeader自定义左侧面板头部信息的渲染(props: SourceHeaderProps) => ReactNode2.29.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>

Methods

绑定在组件实例上的方法,可以通过 ref 调用实现某些特殊交互
NameDescription
search(value: string)可通过 ref 调用该方法进行搜索,该搜索值会被置给 Input。

设计变量