Transfer List

• 介绍
• 入门
  • 基础输入
  • 标签
  • 定义选项
  • 值
  • 可搜索
  • 最大值
  • 选择时转移
• 异步性
  • 异步选项
  • 选项加载器
• 插槽
  • 来源和目标选项
• 示例
  • 排名顺序
• 属性 & 属性
• 部分
  • 传输列表的包装器
  • 来源
  • 转移控件
  • 目标
• 可访问性
  • 键盘交互

介绍

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

入门

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

基础输入

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

标签

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

源和目标空消息

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

定义选项

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

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

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

值

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

初始值

传输列表输入可以通过在 transferlist 本身或包裹的 form 或 group 上设置 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）和 cachedOption。cachedOption 用于防止不必要的查找；如果 cachedOption 不是 null，这意味着所选选项已经被加载，你可以直接返回 cachedOption。

获取额外数据

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

插槽

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

来源和目标选项

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

示例

排名顺序

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

属性 & 属性

部分

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

传输列表的包装器

来源

转移控件

目标

可访问性

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

键盘交互