为什么捐赠
API 资源管理器
选择

QSelect 组件有两种选择类型:单选或多选。此组件会打开一个菜单,用于选择列表和操作。对于较长的列表,也可以使用筛选器。

如果您正在寻找一个下拉“按钮”而不是“输入”,请使用 按钮下拉

正在加载 QSelect API...

设计

概述

警告

对于您的 QSelect,您只能使用一种主要设计(filledoutlinedstandoutborderless)。您不能使用多种,因为它们是互斥的。

设计概述



装饰器

装饰器



着色

着色



可清除

作为帮助程序,您可以使用 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。默认情况下,它会发出整个选项。仅当选项为对象形式时,使用它才有意义。

Emit-value



当使用 map-options 时,模型只能包含 value,它将与选项进行映射以确定其标签。这样做会造成性能损耗,因此仅在绝对必要时才使用它。例如,如果模型包含整个对象(因此包含标签属性),则不需要它。

映射选项



自定义属性名称

默认情况下,QSelect 查看选项数组对象中每个选项的 labelvaluedisablesanitize 属性。但您可以覆盖这些属性。

警告

如果您对自定义属性使用函数,请始终检查选项是否为空。这些函数用于列表中的选项和选定选项。

自定义标签、值和禁用属性



自定义菜单选项

警告

选项列表使用虚拟滚动渲染,因此,如果您为一个选项渲染多个元素,则必须在除第一个元素以外的所有元素上设置 q-virtual-scroll--with-prev 类。

选项插槽



以下是一个示例,我们在每个选项中添加一个 QToggle。可能性是无限的。

对象选项



默认情况下,如果没有选项,菜单将不会出现。但您可以自定义这种情况,并指定菜单应该显示什么。

无选项插槽



延迟加载

以下示例展示了如何使用延迟加载选项。这意味着除了其他许多事情之外,options 属性在首次渲染时不是必需的。

延迟加载选项



当滚动到达末尾时,您可以动态加载新选项。

动态加载选项



覆盖模式

覆盖组件的菜单



禁用 TAB 选择

禁用 Tab 选择



显示值

自定义显示值



使用芯片作为显示值



选定项目插槽



过滤和自动完成

使用 “use-input” 的原生属性

设置在 QSelect 上的所有属性(不在 API 的属性列表中)将传递给使用的原生输入字段(请先查看 use-input 属性描述以了解它的作用),用于过滤/自动完成/添加新值。一些示例:自动完成、占位符。

更多信息:原生输入属性.

过滤选项



基本过滤



过滤超过 2 个字符



文本自动完成



延迟过滤



过滤后选择选项



创建新值

提示

以下只是一些入门示例,帮助您创建自己的 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() 函数只会清空输入框的值,而不会以任何方式篡改模型。

监听 @new-value



仅添加唯一值



使用菜单和过滤

过滤并将新值添加到菜单

过滤并添加到菜单



过滤新值(在下面的示例中,要添加的值需要至少 3 个字符才能通过),并且不会添加到菜单

过滤而不添加到菜单



从输入中生成多个值

生成多个值



清理

**默认情况下,所有选项(包括选定的选项)都会被清理。**这意味着禁用以 HTML 格式显示它们。但是,如果您需要在选项中使用 HTML,并且信任其内容,那么您可以通过以下几种方式来实现。

您可以通过以下方法强制使用 HTML 格式的菜单选项

  • 将受信任选项的 html 键设置为 true(对于特定受信任选项)
  • 或者通过设置 QSelect 的 options-html 属性(对于所有选项)

如果设置了以下条件,则 QSelect 的显示值将以 HTML 格式显示

  • 设置了 QSelect 的 display-value-html 属性
  • 或者您没有使用 display-value,并且
    • 设置了 QSelect 的 options-html 属性
    • 任何选定选项的 html 键都设置为 true

警告

如果您使用 selectedselected-item 插槽,那么您负责清理显示值。 display-value-html 属性将不适用。

以 HTML 格式显示选项



以 HTML 格式显示显示值



渲染性能

渲染性能不受选项数量的影响很大,除非在大型集合中使用 map-options。请注意,已使用无限滚动,当用户滚动列表时,它会渲染额外的选项。

提示

  • (组合式 API)为了在使用大量选项时获得最佳性能,请不要使用 ref()/computed()/reactive()/etc. 将要传递给 options 属性的数组包装起来。这将允许 Vue 忽略使列表对更改“响应”。
  • (选项式 API)为了在使用大量选项时获得最佳性能,请使用 Object.freeze(items) 冻结要传递给 options 属性的数组。这将允许 Vue 忽略使列表对更改“响应”。
10 万个选项



键盘导航

当 QSelect 获得焦点时

  • 按下 ENTERARROW 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 - 9A - Z)将
    • 创建一个搜索缓冲区(如果 1.5 秒内没有输入新键,它将重置),该缓冲区将用于搜索选项标签
    • 如果在缓冲区中第一次键入多次,则选择以该字母开头的下一个选项(在当前焦点选项之后)
    • 选择与输入文本匹配的下一个选项(从当前焦点选项开始)(匹配是模糊的——选项标签应以第一个字母开头并包含所有字母)

当打开选项列表时

  • 按下 ARROW UPARROW DOWN 将在选项列表中向上或向下导航
  • 按下 PAGE UPPAGE DOWN 将在选项列表中向上或向下导航一页
  • 按下 HOMEEND 将导航到选项列表的开头或结尾(仅当您没有使用 use-input 或者输入为空时)
  • 当使用箭头键导航时,导航将在到达列表的开头或结尾时循环
  • 当选项列表中选中一个选项时按下 ENTER(或者当未设置 use-input 时按下 SPACE,或者当未设置 multipledisable-tab-selection 时按下 TAB)将
    • 选择选项并关闭选项列表,如果未设置 multipledisable-tab-selection
    • 如果设置了 multiple,则切换选项

原生表单提交

在处理具有 actionmethod 的原生表单时(例如,在 Quasar 与 ASP.NET 控制器一起使用时),您需要在 QSelect 上指定 name 属性,否则 formData 将不会包含它(如果应该包含它)——所有值都将转换为字符串(原生行为,因此不要使用对象值)

原生表单