Introducing KickStart —  AI generated FormKit forms in seconds. Generate from a screenshot, edit with drag-and-drop or conversational AI, copy & paste as components or schema!
Try for free

Transfer List

View pricing →

专业安装快速启动 :rocket:

介绍

转移列表概览

1 分钟

转移列表输入非常适合最终用户需要从选项列表中选择和排序多个值的情况。在这个例子中,我们允许最终用户从一组客人中选择,并将他们移动到 VIP 列表:

加载实时示例

入门

在本节中,我们将介绍如何复制上面的“客人 vs VIP”示例的基础知识。

基础输入

下面是一个带有最少必需属性的转移列表输入示例。如您所见,有两个列表框:源列表框和目标列表框。源列表框将包含选项列表,目标列表框将包含所选选项:

加载实时示例

标签

让我们添加一些标签属性,以便清楚地向最终用户说明如何使用转移列表输入。我们将添加一个 label 属性来解释指令给用户,以及 source-labeltarget-label 属性来指示哪个列表框是源,哪个是目标:

加载实时示例

源和目标空消息

在这种状态下,没有传递选项也没有选择值,我们可以通过设置 source-empty-messagetarget-empty-message 属性向用户显示自定义消息:

加载实时示例

定义选项

options 属性可以接受三种不同格式的值:

  • 一个包含 valuelabel 键的对象数组
  • 一个字符串数组 'A', 'B', 'C'
  • 一个键值对的对象字面量 { a: 'A', b: 'B', c: 'C' }
  • 一个返回以上任何一种的函数

让我们继续用一系列客人的名字填充转移列表的选项:

加载实时示例

传输列表输入的 是一个数组。从源列表中选中的选项值将被追加到数组中。为了在下面的示例中显示值的变化,让我们将传输列表输入包裹在一个 FormKit 表单中,将传输列表输入的名称设置为 vips,并在一个 <pre> 标签中显示表单本身的值(如果你不熟悉 FormKit 表单,你可以在这里阅读更多信息):

加载实时示例

初始值

传输列表输入可以通过在 transferlist 本身或包裹的 formgroup 上设置 value 属性来预先填充值。请记住,你传递给 value 属性的值需要与你的选项列表中的值的键匹配:

加载实时示例

可搜索

通过设置 searchable 属性,可以使传输列表输入具有搜索功能。在这个示例中,我们将设置 searchable 属性,并为搜索输入设置一个 placeholder 属性:

加载实时示例
只搜索选项
搜索输入只会搜索源选项列表中的选项。它不会返回已经被转移到目标列表中的选项。

过滤

传输列表输入将使用其自己的内部搜索功能来过滤选项。你可以通过为 filter 属性提供你自己的函数来替换这个搜索功能。你的函数将接收两个参数,正在迭代的选项和当前的搜索值:

加载实时示例

选择后清除

默认情况下,传输列表输入会在选择后清除搜索输入。你可以通过将 clear-on-select 属性设置为 false 来改变这种行为:

最大值

通过设置 max 属性,可以限制传输列表输入的最大选中值数量。就这个示例而言,让我们将 max 属性设置为 2,以限制可以选择的 VIP 数量:

加载实时示例

选择时转移

默认情况下,转移列表输入会在点击时添加或移除选项。你可以通过设置 transfer-on-select 属性为 false 来改变这种行为。现在,转移列表将表现得更像传统的转移列表:

加载实时示例

异步性

异步选项

这里我们有一个转移列表输入,它从一个异步函数加载其选项。该函数在组件挂载时被调用,随后选项被加载到源列表框中:

加载实时示例

分页

现在假设我们的 API 请求没有获取到我们需要的所有选项,而是返回了一个分页响应。转移列表输入可以通过对异步函数进行少量配置来处理分页。

当将 options 属性指定为一个异步函数时,该函数将会被调用,并将 FormKit 上下文对象作为其第一个参数。这个上下文对象包含一个 page 属性(我们尝试加载的当前页面),它由转移列表输入跟踪,并且 hasNextPage,这是一个回调函数,我们可以用它来告诉转移列表还有更多选项需要加载:

加载实时示例

搜索

转移列表输入也可以在用户搜索时异步加载选项。在这个例子中,我们将重新添加 searchable 属性,并将 getGuests() 更改为 searchGuests()。当用户搜索时,searchGuests() 现在将被调用,并传入与之前相同的上下文对象,但这次,我们将仅解构 search 属性。此外,我们将修改 getGuests() 以仅在提供搜索值时返回客人:

加载实时示例

选项加载器

重新加载值

转移列表输入还提供了一个 optionLoader 属性,允许你重新加载不在选项列表中的值。在这个例子中,我们将为转移列表提供一个初始值(一个客人 ID),并将 optionLoader 指定为一个函数,该函数将向 API 发出请求以获取单个客人数据:

加载实时示例

请注意,在上面的例子中,optionLoader 函数 getGuest 被传递了两个参数:所选选项的值(在这种情况下,是电影 ID)和 cachedOptioncachedOption 用于防止不必要的查找;如果 cachedOption 不是 null,这意味着所选选项已经被加载,你可以直接返回 cachedOption

获取额外数据

您还可以使用 optionLoader 来获取选定值上未在选项列表中的额外数据。在这个例子中,选择一个选项后,我们将执行查找以加载所选客人的年龄:

加载实时示例

插槽

就像任何其他FormKit输入一样,传输列表输入允许您使用插槽来自定义其标记。

来源和目标选项

现在我们正在加载选定值的额外数据(所选客人的年龄和电子邮件地址),让我们使用 target-option 插槽来自定义所选值的外观:

加载实时示例

示例

排名顺序

传输列表输入可以用来创建一个排名列表,让我们用最伟大的NBA球员来做这件事:

加载实时示例

属性 & 属性

PropType默认描述
debouncenumber200对选项函数的调用进行去抖动的毫秒数。
optionsany[]用户可以从中选择的选项列表。
filterfunctionnull用于对静态选项应用您自己的自定义过滤函数。
option-loaderfunctionnull用于初始化值的水合作用,或执行额外请求以加载所选选项的更多信息。
source-empty-messagestringundefined当没有选项显示时呈现一条消息。
target-empty-messagestringundefined当没有值显示时呈现一条消息。
maxnumberundefined限制可以选择的选项数量。
clear-on-selectbooleantrue选择一个选项后清除搜索输入(仅适用于不通过函数加载的选项)。
searchablebooleanfalse启用搜索输入。
source-labelstringundefined为源列表呈现一个标签。
target-labelstringundefined为目标列表呈现一个标签。
transfer-on-selectbooleantrue自动将选定的选项转移到目标列表。如果设置为false,将呈现向前传输和向后传输按钮。
显示 通用 props
configObject{}提供给 input 的节点和此输入的任何后代节点的配置选项。
delayNumber20在调度 commit hook 前,输入值的去抖动毫秒数。
dirtyBehaviorstringtouched确定此输入的“dirty”标志设置方式。可以设置为 touchedcompare — 默认为 touched,性能更好,但无法检测表单是否再次匹配其初始状态。
errorsArray[]要在此字段上显示的错误消息的字符串数组。
helpString''帮助文本与输入关联的文本。
idStringinput_{n}输入的唯一标识符。提供一个 id 还可以全局访问输入的节点。
ignoreBooleanfalse防止将输入包含在任何父级(组、列表、表单等)中。在仅用于 UI 而不是实际值的情况下非常有用。
indexNumberundefined如果父级是列表,允许在给定索引处插入输入。如果输入的值未定义,它将继承该索引位置的值。如果它有一个值,它将在给定索引处将其插入到列表的值中。
labelString''与输入关联的 label 元素的文本。
nameStringinput_{n}输入的名称,在数据对象中唯一标识。在一组字段中应该是唯一的。
parentFormKitNodecontextual默认情况下,父级是包装组、列表或表单,但此属性允许显式分配父级节点。
prefix-iconString''指定放置在 prefixIcon 部分的 图标
preservebooleanfalse在输入卸载时,在父组、列表或表单上保留输入的值。
preserve-errorsbooleanfalse默认情况下,使用 setErrors 在输入上设置的错误会在输入时自动清除,将此属性设置为 true 可以保留错误,直到明确清除为止。
sections-schemaObject{}一个包含部分键和模式部分值的对象,其中每个模式部分应用于相应的部分。
suffix-iconString''指定放置在 suffixIcon 部分的 图标
typeStringtext要从库中渲染的输入类型。
validationString, Array[]要应用于输入的 验证 规则。
validation-visibilityStringblur确定何时显示输入的验证失败规则。有效值为 blurdirtylive
validation-labelString{label prop}确定在验证错误消息中使用的标签,默认情况下,如果可用,则使用 label 属性,否则使用 name 属性。
validation-rulesObject{}附加的自定义验证规则,可用于验证 prop。
valueAnyundefined为输入和/或其子元素提供初始值。不是响应式的。可以种子 整个组(表单)和列表。

部分

您可以使用该部分的“键”来定位输入的特定部分,这样您就可以修改该部分的类、HTML(通过 :sections-schema)或内容(通过插槽)。在这里阅读更多关于部分的信息。

传输列表的包装器

View on a larger screen to see this section diagram.

为派对选择VIP
您最多可以选择3位VIP。
源列表
传输控件
目标列表
抱歉,您不能添加超过3位宾客。

来源

View on a larger screen to see this section diagram.

宾客
97
未找到宾客
John Doe

转移控件

View on a larger screen to see this section diagram.

目标

View on a larger screen to see this section diagram.

VIPs
3
No VIPs selected
John Doe
Section-key描述
fieldset一个作为转移列表输入的根元素的fieldset元素。
legend一个渲染标签的legend元素。
source一个包含sourceHeader、sourceControls和sourceListItems部分的div元素。
sourceHeader一个包含sourceHeaderLabel和sourceHeaderItemCount部分的div元素。
sourceHeaderLabel一个渲染sourceLabel属性的label元素。
sourceHeaderItemCount一个渲染源列表中的项目数量和选中项目数量的span元素。
sourceControls一个包含sourceSearchINput和sourceSearchClear部分的div元素。
sourceSearch一个包含sourceSearchInput和sourceSearchClear部分的div元素。
sourceSearchInput一个用于搜索的文本输入元素。
sourceSearchClear一个清除搜索输入的按钮元素。
closeIcon用于包含清除搜索输入图标的span元素。
sourceListItems一个包含sourceListItems的ul元素。
sourceEmptyMessage一个包含emptyMessageInner部分的li元素。
emptyMessageInner一个渲染提供的空消息文本的span元素。
sourceListItem一个为sourceListItems部分包含sourceOption部分的li元素。
selectIcon当sourceListItem被设置为选中时,一个渲染选中图标的span元素。
sourceOption一个渲染选项标签的div元素。
sourceLoadMore一个包含loadMoreInner部分的li元素。
loadMoreInner一个渲染加载图标的span元素。
loaderIcon当加载发生时,一个输出图标的span元素。
transferControls一个包含transferButtonForwardAll、transferButtonForward、transferButtonBackward和transferButtonBackwardAll部分的div元素。
transferButtonForwardAll一个将所有选项转移到目标列表的按钮元素。
transferButtonForward一个将选中的选项转移到目标列表的按钮元素。
transferButtonBackward一个将选中的选项转移到源列表的按钮元素。
transferButtonBackwardAll一个将所有选项转移到源列表的按钮元素。
controlLabel一个渲染控制标签的span元素。
fastForwardIcon一个渲染快进图标的span元素。
moveRightIcon一个渲染向右移动图标的span元素。
moveLeftIcon一个渲染向左移动图标的span元素。
rewindIcon一个渲染倒带图标的span元素。
target一个包含targetHeader、targetControls和targetListItems部分的div元素。
targetHeader一个包含targetHeaderLabel和targetHeaderItemCount部分的div元素。
targetHeaderLabel一个渲染targetLabel属性的label元素。
targetHeaderItemCount一个渲染目标列表中的项目数量和选中项目数量的span元素。
targetListItems一个包含targetListItems的ul元素。
targetEmptyMessage一个包含emptyMessageInner部分的li元素。
targetListItem一个为targetListItems部分包含targetOption部分的li元素。
targetLoadMore一个包含loadMoreInner部分的li元素。
显示 通用 section keys
outer最外层的包装元素。
wrapper标签和输入周围的包装器。
label输入的标签。
prefix默认情况下没有输出,但允许直接在输入元素之前放置内容。
prefixIcon输出在前缀部分之前放置一个图标的元素。
inner实际输入元素周围的包装器。
suffix默认情况下没有输出,但允许直接在输入元素之后放置内容。
suffixIcon输出在后缀部分之后放置一个图标的元素。
input输入元素本身。
help包含帮助文本的元素。
messages包装所有消息的容器。
message包含消息的元素(或多个元素) - 最常见的是验证和错误消息。

可访问性

所有 FormKit 输入都是考虑到以下可访问性因素而设计的。通过在此处提交可访问性问题,帮助我们不断改进所有人的可访问性:

语义标记Aria 属性可通过键盘访问焦点指示器与提供的主题的颜色对比可访问标签、帮助文本和错误
部分键属性默认描述
fieldsetrolepresentation向辅助技术表明此元素的功能为展示。
aria-describedby将元素与描述关联起来,帮助屏幕阅读器。
sourceHeaderrolepresentation向辅助技术表明此元素的功能为展示。
sourceHeaderLabelfor将标签与输入元素关联。用户可以点击标签来聚焦输入或切换状态。
sourceHeaderItemCountrolepresentation向辅助技术表明此元素的功能为展示。
aria-label提供一个可访问的名称。
sourceSearchInputrolesearchbox向辅助技术表明此元素的功能为搜索框。
aria-label提供一个可访问的名称。
sourceSearchCleararia-label提供一个可访问的名称。
sourceListItemstabindex-1 or 0通过将其设置为-1(当可搜索或没有源选项时)或0(其他情况时)来优先考虑键盘焦点顺序。
aria-activedescendant管理焦点到当前活动的后代元素。
rolelistbox向辅助技术表明此元素的功能为列表框。
aria-multiselectabletrue表明它允许同时选择多个项目。
aria-roledescription提供此元素角色的描述。
sourceListItemaria-selected表明此元素当前被选中。
roleoption向辅助技术表明此元素的功能为选项。
sourceLoadMoretabindex-1通过将其设置为-1来优先考虑键盘焦点顺序。
aria-selectedfalse表明此元素从未被选中。
sourceEmptyMessagerolepresentation向辅助技术表明此元素的功能为展示。
targetHeaderrolepresentation向辅助技术表明此元素的功能为展示。
targetHeaderLabelfor将标签与输入元素关联。用户可以点击标签来聚焦输入或切换状态。
targetHeaderItemCountrolepresentation向辅助技术表明此元素的功能为展示。
aria-label提供一个可访问的名称。
targetListItemstabindex-1 or 0通过将其设置为-1(当可搜索或没有源选项时)或0(其他情况时)来优先考虑键盘焦点顺序。
aria-activedescendant管理焦点到当前活动的后代元素。
rolelistbox向辅助技术表明此元素的功能为列表框。
aria-multiselectabletrue表明它允许同时选择多个项目。
aria-roledescription提供此元素角色的描述。
targetListItemaria-selected表明此元素当前被选中。
roleoption向辅助技术表明此元素的功能为选项。
targetLoadMoretabindex-1通过将其设置为-1来优先考虑键盘焦点顺序。
aria-selectedfalse表明此元素从未被选中。
targetEmptyMessagerolepresentation向辅助技术表明此元素的功能为展示。
transferButtonForwardaria-label提供一个可访问的名称。
transferButtonForwardAllaria-label提供一个可访问的名称。
transferButtonBackwardaria-label提供一个可访问的名称。
transferButtonBackwardAllaria-label提供一个可访问的名称。
显示 通用 部分键
labellabelfor将其与输入元素关联,提高可访问性和用户体验
inputinputdisabled禁用 HTML 元素,阻止用户交互并指示非交互状态
aria-describedby通过将元素与描述关联,增强可访问性,帮助屏幕阅读器
aria-required当需要验证时,添加所需的状态
iconiconfor每当将图标定义为标签时,将其与输入元素关联,增强可访问性和用户体验

键盘交互

键盘事件描述
Tab将焦点移动到页面上的下一个可聚焦输入。
Shift + Tab将焦点移动到页面上的上一个可聚焦输入。