QSelect 组件有两种选择类型:单选或多选。此组件会打开一个菜单,用于选择列表和操作。对于较长的列表,也可以使用筛选器。
如果您正在寻找一个下拉“按钮”而不是“输入”,请使用 按钮下拉。
设计
概述
警告
对于您的 QSelect,您只能使用一种主要设计(filled
、outlined
、standout
、borderless
)。您不能使用多种,因为它们是互斥的。
装饰器
着色
可清除
作为帮助程序,您可以使用 clearable
道具,以便用户可以通过附加的图标将模型重置为 null
。下面示例中的第二个 QSelect 等同于使用 clearable
。
禁用和只读
带有 QBtn 类型“提交”的插槽
警告
当在 QField、QInput 或 QSelect 的 “before”、“after”、“prepend” 或 “append” 插槽中放置类型为 “submit” 的 QBtn 时,您也应该在该 QBtn 上添加 @click
监听器。这个监听器应该调用提交表单的方法。此类插槽中的所有 “click” 事件都不会传播到其父元素。
菜单过渡
警告
请注意,使用 options-cover
属性时,过渡不起作用。
在下面的示例中,展示了一些过渡。有关可用过渡的完整列表,请访问 过渡。
选项列表显示模式
默认情况下,QSelect 在桌面设备上将选项列表显示为菜单,在移动设备上显示为对话框。您可以使用 behavior
属性强制使用一种行为。
警告
请注意,在 iOS 上,菜单行为可能会产生问题,尤其是在与 use-input
属性结合使用时。您可以使用条件 behavior
属性,例如 :behavior="$q.platform.is.ios === true ? 'dialog' : 'menu'"
,以便仅在 iOS 上使用对话框模式。
模型
警告
单选模型可以是任何类型(字符串、对象等),而多选模型必须是数组。
模型内容会受到 emit-value
属性的影响,您将在下面的“选项”部分中了解到。
选项
选项类型
影响模型
当使用 emit-value
时,模型将成为指定选中选项确定的 value
。默认情况下,它会发出整个选项。仅当选项为对象形式时,使用它才有意义。
当使用 map-options
时,模型只能包含 value
,它将与选项进行映射以确定其标签。这样做会造成性能损耗,因此仅在绝对必要时才使用它。例如,如果模型包含整个对象(因此包含标签属性),则不需要它。
自定义属性名称
默认情况下,QSelect 查看选项数组对象中每个选项的 label
、value
、disable
和 sanitize
属性。但您可以覆盖这些属性。
警告
如果您对自定义属性使用函数,请始终检查选项是否为空。这些函数用于列表中的选项和选定选项。
自定义菜单选项
警告
选项列表使用虚拟滚动渲染,因此,如果您为一个选项渲染多个元素,则必须在除第一个元素以外的所有元素上设置 q-virtual-scroll--with-prev
类。
以下是一个示例,我们在每个选项中添加一个 QToggle。可能性是无限的。
默认情况下,如果没有选项,菜单将不会出现。但您可以自定义这种情况,并指定菜单应该显示什么。
延迟加载
以下示例展示了如何使用延迟加载选项。这意味着除了其他许多事情之外,options
属性在首次渲染时不是必需的。
当滚动到达末尾时,您可以动态加载新选项。
覆盖模式
禁用 TAB 选择
显示值
过滤和自动完成
使用 “use-input” 的原生属性
设置在 QSelect 上的所有属性(不在 API 的属性列表中)将传递给使用的原生输入字段(请先查看 use-input
属性描述以了解它的作用),用于过滤/自动完成/添加新值。一些示例:自动完成、占位符。
更多信息:原生输入属性.
创建新值
提示
以下只是一些入门示例,帮助您创建自己的 QSelect 行为。这不是 QSelect 提供的所有可能性的详尽列表。
将此功能与 use-input
属性结合使用很有意义。
为了启用创建新值,您需要 **要么指定** new-value-mode
属性,**要么监听** @new-value
事件。如果您同时使用两者,那么监听 @new-value
的目的只是在您的自定义场景中覆盖 new-value-mode
。
new-value-mode 属性
new-value-mode
属性值指定应如何添加值: add
(添加值,即使是重复值),add-unique
(仅在不重复时添加),或者 toggle
(如果值不存在于模型中,则添加值;否则将其删除)。
通过使用此属性,您无需也监听 @new-value
事件,除非您有一些需要覆盖此行为的特定场景。
@new-value 事件
@new-value 事件将使用要添加的值和一个 done
回调函数发出。 done
回调函数有两个 **可选** 参数
- 要添加的值
- 行为(与
new-value-mode
属性的值相同,以及何时指定它会覆盖该属性——如果使用它)——默认行为(如果未使用new-value-mode
)是添加值,即使它是重复值
调用不带任何参数的 done()
函数只会清空输入框的值,而不会以任何方式篡改模型。
使用菜单和过滤
过滤并将新值添加到菜单
过滤新值(在下面的示例中,要添加的值需要至少 3 个字符才能通过),并且不会添加到菜单
从输入中生成多个值
清理
**默认情况下,所有选项(包括选定的选项)都会被清理。**这意味着禁用以 HTML 格式显示它们。但是,如果您需要在选项中使用 HTML,并且信任其内容,那么您可以通过以下几种方式来实现。
您可以通过以下方法强制使用 HTML 格式的菜单选项
- 将受信任选项的
html
键设置为true
(对于特定受信任选项) - 或者通过设置 QSelect 的
options-html
属性(对于所有选项)
如果设置了以下条件,则 QSelect 的显示值将以 HTML 格式显示
- 设置了 QSelect 的
display-value-html
属性 - 或者您没有使用
display-value
,并且- 设置了 QSelect 的
options-html
属性 - 任何选定选项的
html
键都设置为true
- 设置了 QSelect 的
警告
如果您使用 selected
或 selected-item
插槽,那么您负责清理显示值。 display-value-html
属性将不适用。
渲染性能
渲染性能不受选项数量的影响很大,除非在大型集合中使用 map-options
。请注意,已使用无限滚动,当用户滚动列表时,它会渲染额外的选项。
提示
- (组合式 API)为了在使用大量选项时获得最佳性能,请不要使用 ref()/computed()/reactive()/etc. 将要传递给
options
属性的数组包装起来。这将允许 Vue 忽略使列表对更改“响应”。 - (选项式 API)为了在使用大量选项时获得最佳性能,请使用
Object.freeze(items)
冻结要传递给options
属性的数组。这将允许 Vue 忽略使列表对更改“响应”。
键盘导航
当 QSelect 获得焦点时
- 按下 ENTER、ARROW DOWN(或者如果未设置
use-input
,则按下 SPACE)将打开选项列表 - 如果设置了
use-chips
- 按下 SHIFT + TAB 将在 QChips 中向后导航(如果选中 QChips,则 TAB 将在 QChips 中向前导航)
- 选中 QChips 时按下 ENTER 将从选择中删除该选项
- 按下 BACKSPACE 将从选择中删除最后一个选项(当设置了
use-input
时,输入应为空)
- 按下 BACKSPACE,当设置了
clearable
时,则- 它将使用
null
值清除单选模型 - 它将删除多选的最后一个添加的值
- 它将使用
- 按下 TAB(或如果未设置
use-chips
或者选中了第一个 QChips,则按下 SHIFT + TAB)将导航到页面上的下一个或上一个可聚焦元素 - 如果未设置
use-input
,则输入文本(0 - 9 或 A - Z)将- 创建一个搜索缓冲区(如果 1.5 秒内没有输入新键,它将重置),该缓冲区将用于搜索选项标签
- 如果在缓冲区中第一次键入多次,则选择以该字母开头的下一个选项(在当前焦点选项之后)
- 选择与输入文本匹配的下一个选项(从当前焦点选项开始)(匹配是模糊的——选项标签应以第一个字母开头并包含所有字母)
当打开选项列表时
- 按下 ARROW UP 或 ARROW DOWN 将在选项列表中向上或向下导航
- 按下 PAGE UP 或 PAGE DOWN 将在选项列表中向上或向下导航一页
- 按下 HOME 或 END 将导航到选项列表的开头或结尾(仅当您没有使用
use-input
或者输入为空时) - 当使用箭头键导航时,导航将在到达列表的开头或结尾时循环
- 当选项列表中选中一个选项时按下 ENTER(或者当未设置
use-input
时按下 SPACE,或者当未设置multiple
和disable-tab-selection
时按下 TAB)将- 选择选项并关闭选项列表,如果未设置
multiple
和disable-tab-selection
- 如果设置了
multiple
,则切换选项
- 选择选项并关闭选项列表,如果未设置
原生表单提交
在处理具有 action
和 method
的原生表单时(例如,在 Quasar 与 ASP.NET 控制器一起使用时),您需要在 QSelect 上指定 name
属性,否则 formData 将不会包含它(如果应该包含它)——所有值都将转换为字符串(原生行为,因此不要使用对象值)