Pro installation quickstart 🚀

dropdown 输入允许用户从选项列表中选择一个值。与原生选择元素不同,下拉输入允许您自定义其外观和行为。

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

  • 具有 valuelabel 键的对象数组(参见上面的示例)
  • 字符串数组 ['A', 'B', 'C']
  • 具有键值对的对象字面量 { a: 'A', b: 'B', c: 'C' }
  • 返回上述任何内容的函数
空选项

如果你将选项设置为一个空数组,输入将以禁用状态呈现。

基本示例

单选

下拉输入默认以单选模式呈现。

加载实时示例

多选

设置了 multiple 属性的下拉输入将以多选模式呈现。

加载实时示例
多选输入值

注意在上面的示例中,因为设置了 multiple 属性,所以 value 属性必须是一个数组。

动态选项

而不是将静态列表传递给 options 属性,选项可以动态分配。

在这个例子中,函数 loadHorrorMoviesTMDB 的 API 发出请求,加载恐怖电影列表。将函数分配给 options 属性将在最终用户打开列表框时加载选项。

加载实时示例

总是在打开时加载

默认情况下,下拉菜单只会在列表框展开时(一次)异步加载选项。设置 always-load-on-open 属性将导致下拉菜单每次展开列表框时都加载选项。

加载实时示例

在创建时加载

load-on-created 属性将导致下拉菜单在创建时就加载选项。

加载实时示例

分页

分配给 options prop 的函数将传递两个参数:pagehasNextPage。page 参数表示当前的页码,hasNextPage 是一个回调函数,表示是否还有更多的页面需要加载。

加载实时示例

滚动加载

如果你希望用户在不需要点击选项列表底部的 加载更多 选项的情况下加载更多选项,你可以将 load-on-scroll prop 设置为 true,然后我们的函数 loadCurrentlyPopularMovies 将再次被调用:

加载实时示例

选项加载器

FormKit 的下拉输入还提供了一个 optionLoader prop,允许你重新加载不在选项列表中的值。在这个例子中,下拉菜单提供了一个初始值(两个电影 ID)。对于不在选项列表中的每个值,都会调用 optionLoader 函数。

加载实时示例

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

选项外观

与原生的 select 元素不同,下拉输入可以通过标记进行定制。

选项插槽

下拉输入允许你使用选项插槽来定制每个选项的外观和感觉。在这个例子中,我们使用选项插槽来显示每个选项的资产;logo 和名称:

加载实时示例

选择外观

下拉输入允许你定制选定选项的外观和感觉。

选择外观 prop

当使用下拉输入作为 multi-select 时,你可以通过设置 selection-appearance prop 为 truncate(默认)或 tags 来定制选定选项的外观和感觉。

加载实时示例

选择插槽

如果你只想定制选定选项的显示,使用选择插槽(与上面提到的选项插槽相反):

加载实时示例
仅限单选和标签

选择插槽在选择外观为 truncate 的多选下拉菜单上不存在。

行为属性

以下属性允许您自定义下拉输入的行为。

空消息

默认情况下,如果没有传递选项,下拉输入将以禁用状态呈现。可选地,您可以传递 empty-message 属性一个消息,当没有可用选项时显示:

加载实时示例

超滚动

当使用具有静态选项的下拉菜单时,FormKit 的下拉菜单还带有一个名为 overscroll 的功能:

加载实时示例

可移除选择

如果您希望允许用户移除所选值,将 selection-removable 属性设置为 true。这将在所选值旁边渲染一个关闭图标:

仅限单选

selection-removable 属性不能用于多选。

加载实时示例

移除后打开

默认情况下,当 selection-removable 属性设置为 true 时,移除所选值后,下拉菜单不会打开。您可以通过将 open-on-remove 属性设置为 true 来改变这种行为:

加载实时示例

选择后关闭

默认情况下,当设置了 multiple 属性时,选择一个选项后,下拉菜单不会关闭。您可以通过将 close-on-select 属性设置为 true 来改变这种行为:

加载实时示例

聚焦时打开

如果您希望在下拉输入聚焦时立即展开列表框,您可以使用 open-on-focus 属性:

加载实时示例

最大值

如果您希望限制可以选择的选项数量,您可以使用 max 属性:

加载实时示例

属性和属性

PropType默认描述
optionsany[]用户可以从中选择的选项列表。
load-on-scrollbooleanfalse当设置为 `true` 时,下拉菜单将尝试根据最终用户的滚动位置加载更多选项
option-loaderfunctionnull用于为初始值提供数据,或执行额外的请求以加载所选选项的更多信息。
empty-messagestringundefined当没有选项可显示时,渲染一条消息。
selection-appearancestringtruncate对于多选下拉菜单,此属性允许您自定义所选选项的外观和感觉。可能的值是 `truncate`(默认)或 `tags`。
selection-removablebooleanfalse对于单选下拉菜单,此属性允许您移除所选值。
open-on-removebooleanfalse当 `selection-removable` 属性设置为 `true` 时,移除所选值后,下拉菜单不会打开。您可以通过将 `open-on-remove` 属性设置为 `true` 来改变这种行为。
close-on-selectbooleanfalse当设置了 `multiple` 属性时,选择一个选项后,下拉菜单不会关闭。您可以通过将 `close-on-select` 属性设置为 `true` 来改变这种行为。
open-on-focusbooleanfalse如果您希望在下拉输入聚焦时立即展开列表框,您可以使用 `open-on-focus` 属性。
options-appearancestringundefined对于多选下拉菜单,此属性允许您自定义所选选项的外观和感觉。可能的值是 `default`(默认)或 `checkbox`。
multiplebooleanfalse当设置为 `true` 时,下拉菜单将允许用户选择多个选项。
behaviorstringundefined当设置为 `overscroll` 时,下拉菜单将允许用户选择多个选项。
always-load-on-openbooleanfalse当设置为 `true` 时,下拉菜单将始终在打开列表框时加载选项。
load-on-createdbooleanfalse当设置为 `true` 时,下拉菜单将在节点创建时加载选项。
maxnumber | stringundefined如果您希望限制可以选择的选项数量,您可以使用 `max` 属性(仅适用于多选)。
显示 通用 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为输入和/或其子元素提供初始值。不是响应式的。可以种子 整个组(表单)和列表。

部分

您可以通过使用该部分的"key"来定位输入的特定部分,从而可以修改该部分的类、HTML(通过:sections-schema)或内容(通过插槽))。了解更多关于部分的信息,请点击这里

选择器结构

View on a larger screen to see this section diagram.

选择 T 恤颜色
选择 T 恤颜色
×
打开和关闭声音效果。
发生了一些错误。

列表框结构

View on a larger screen to see this section diagram.

选择结构

单选下拉菜单

View on a larger screen to see this section diagram.

灰色