dropdown
输入允许用户从选项列表中选择一个值。与原生选择元素不同,下拉输入允许您自定义其外观和行为。
options
属性可以接受三种不同格式的值:
value
和 label
键的对象数组(参见上面的示例)['A', 'B', 'C']
{ a: 'A', b: 'B', c: 'C' }
如果你将选项设置为一个空数组,输入将以禁用状态呈现。
下拉输入默认以单选模式呈现。
设置了 multiple
属性的下拉输入将以多选模式呈现。
注意在上面的示例中,因为设置了 multiple
属性,所以 value
属性必须是一个数组。
而不是将静态列表传递给 options
属性,选项可以动态分配。
在这个例子中,函数 loadHorrorMovies
向 TMDB 的 API 发出请求,加载恐怖电影列表。将函数分配给 options
属性将在最终用户打开列表框时加载选项。
默认情况下,下拉菜单只会在列表框展开时(一次)异步加载选项。设置 always-load-on-open
属性将导致下拉菜单每次展开列表框时都加载选项。
load-on-created
属性将导致下拉菜单在创建时就加载选项。
分配给 options prop 的函数将传递两个参数:page
和 hasNextPage
。page 参数表示当前的页码,hasNextPage 是一个回调函数,表示是否还有更多的页面需要加载。
如果你希望用户在不需要点击选项列表底部的 加载更多 选项的情况下加载更多选项,你可以将 load-on-scroll
prop 设置为 true,然后我们的函数 loadCurrentlyPopularMovies
将再次被调用:
FormKit 的下拉输入还提供了一个 optionLoader
prop,允许你重新加载不在选项列表中的值。在这个例子中,下拉菜单提供了一个初始值(两个电影 ID)。对于不在选项列表中的每个值,都会调用 optionLoader
函数。
注意在上面的例子中,optionLoader 函数传递了两个参数:选定选项的 value
(在这种情况下,是电影 ID)和 cachedOption
。cachedOption prop 用于防止不必要的查找。如果 cachedOption 不是 null
,那么意味着已经加载了选定的选项,你可以直接返回 cachedOption。
与原生的 select 元素不同,下拉输入可以通过标记进行定制。
下拉输入允许你使用选项插槽来定制每个选项的外观和感觉。在这个例子中,我们使用选项插槽来显示每个选项的资产;logo 和名称:
下拉输入允许你定制选定选项的外观和感觉。
当使用下拉输入作为 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
属性:
Prop | Type | 默认 | 描述 |
---|---|---|---|
options | any | [] | 用户可以从中选择的选项列表。 |
load-on-scroll | boolean | false | 当设置为 `true` 时,下拉菜单将尝试根据最终用户的滚动位置加载更多选项 |
option-loader | function | null | 用于为初始值提供数据,或执行额外的请求以加载所选选项的更多信息。 |
empty-message | string | undefined | 当没有选项可显示时,渲染一条消息。 |
selection-appearance | string | truncate | 对于多选下拉菜单,此属性允许您自定义所选选项的外观和感觉。可能的值是 `truncate`(默认)或 `tags`。 |
selection-removable | boolean | false | 对于单选下拉菜单,此属性允许您移除所选值。 |
open-on-remove | boolean | false | 当 `selection-removable` 属性设置为 `true` 时,移除所选值后,下拉菜单不会打开。您可以通过将 `open-on-remove` 属性设置为 `true` 来改变这种行为。 |
close-on-select | boolean | false | 当设置了 `multiple` 属性时,选择一个选项后,下拉菜单不会关闭。您可以通过将 `close-on-select` 属性设置为 `true` 来改变这种行为。 |
open-on-focus | boolean | false | 如果您希望在下拉输入聚焦时立即展开列表框,您可以使用 `open-on-focus` 属性。 |
options-appearance | string | undefined | 对于多选下拉菜单,此属性允许您自定义所选选项的外观和感觉。可能的值是 `default`(默认)或 `checkbox`。 |
multiple | boolean | false | 当设置为 `true` 时,下拉菜单将允许用户选择多个选项。 |
behavior | string | undefined | 当设置为 `overscroll` 时,下拉菜单将允许用户选择多个选项。 |
always-load-on-open | boolean | false | 当设置为 `true` 时,下拉菜单将始终在打开列表框时加载选项。 |
load-on-created | boolean | false | 当设置为 `true` 时,下拉菜单将在节点创建时加载选项。 |
max | number | string | undefined | 如果您希望限制可以选择的选项数量,您可以使用 `max` 属性(仅适用于多选)。 |
显示 通用 props | |||
config | Object | {} | 提供给 input 的节点和此输入的任何后代节点的配置选项。 |
delay | Number | 20 | 在调度 commit hook 前,输入值的去抖动毫秒数。 |
dirtyBehavior | string | touched | 确定此输入的“dirty”标志设置方式。可以设置为 touched 或 compare — 默认为 touched ,性能更好,但无法检测表单是否再次匹配其初始状态。 |
errors | Array | [] | 要在此字段上显示的错误消息的字符串数组。 |
help | String | '' | 帮助文本与输入关联的文本。 |
id | String | input_{n} | 输入的唯一标识符。提供一个 id 还可以全局访问输入的节点。 |
ignore | Boolean | false | 防止将输入包含在任何父级(组、列表、表单等)中。在仅用于 UI 而不是实际值的情况下非常有用。 |
index | Number | undefined | 如果父级是列表,允许在给定索引处插入输入。如果输入的值未定义,它将继承该索引位置的值。如果它有一个值,它将在给定索引处将其插入到列表的值中。 |
label | String | '' | 与输入关联的 label 元素的文本。 |
name | String | input_{n} | 输入的名称,在数据对象中唯一标识。在一组字段中应该是唯一的。 |
parent | FormKitNode | contextual | 默认情况下,父级是包装组、列表或表单,但此属性允许显式分配父级节点。 |
prefix-icon | String | '' | 指定放置在 prefixIcon 部分的 图标。 |
preserve | boolean | false | 在输入卸载时,在父组、列表或表单上保留输入的值。 |
preserve-errors | boolean | false | 默认情况下,使用 setErrors 在输入上设置的错误会在输入时自动清除,将此属性设置为 true 可以保留错误,直到明确清除为止。 |
sections-schema | Object | {} | 一个包含部分键和模式部分值的对象,其中每个模式部分应用于相应的部分。 |
suffix-icon | String | '' | 指定放置在 suffixIcon 部分的 图标。 |
type | String | text | 要从库中渲染的输入类型。 |
validation | String, Array | [] | 要应用于输入的 验证 规则。 |
validation-visibility | String | blur | 确定何时显示输入的验证失败规则。有效值为 blur 、dirty 和 live 。 |
validation-label | String | {label prop} | 确定在验证错误消息中使用的标签,默认情况下,如果可用,则使用 label 属性,否则使用 name 属性。 |
validation-rules | Object | {} | 附加的自定义验证规则,可用于验证 prop。 |
value | Any | undefined | 为输入和/或其子元素提供初始值。不是响应式的。可以种子 整个组(表单)和列表。 |
您可以通过使用该部分的"key"来定位输入的特定部分,从而可以修改该部分的类、HTML(通过:sections-schema
)或内容(通过插槽))。了解更多关于部分的信息,请点击这里。