选择框

QSelect 组件有两种类型的选择框:单选和多选。这个组件可以打开一组可操作的菜单列表。对于较长的列表还可以选择过滤功能。

如果您在找一个下拉按钮而不是输入框,那么使用请使用下拉按钮

QSelect API

Loading QSelect API...

外观设计

Overview

WARNING

您只能给 QSelect 使用一种主要的外观设计款式(filled, outlined, standout, borderless),不能使用多个,因为它们是互相排斥的。




装饰




着色




可清除的

作为辅助,您可以使用 clearable 属性,这样用户可以通过附加的图标将数据重置为 null。下面第二个示例等价于使用 clearable




禁用和只读




插槽中使用 “submit” 类型的 QBtn

WARNING

当将类型为 “submit” 的 QBtn 放置在 QField、QInput 或 QSelect 的 “before”、“after” 、“prepend” 或 “append” 插槽中时,您还应该在有问题的 QBtn 上添加 @click 事件。该事件应调用提交表单的方法。此类插槽中的所有点击事件均不会传播到其父元素。

菜单过渡动画

WARNING

请注意,当使用选项 options-cover 属性时,过渡效果不生效。

在下面的示例中,显示部分过渡效果。有关可用过渡效果的完整列表,请转到 过渡效果页面。




选项列表的展示模式

默认情况下,QSelect 在桌面上使用菜单的方式展示选项列表,在手机上使用对话框展示选项列表。但是您可以使用 behavior 来强制控制使用某种模式。

WARNING

请注意,在 iOS 上,菜单模式可能会产生问题,尤其是与 use-input 属性结合使用时。您可以控制在 IOS 设备上只是用对话框模式,例如::behavior="$q.platform.is.ios === true ? 'dialog' : 'menu'"







The model

WARNING

model 在单选模式下可以是任意类型(String, Object, …),但是在多选模式下只能是一个数组。







model 的内容可能会受到 emit-value 属性的影响,您将在下面的 “选项” 部分中学习。

选项

选项类型







Affecting model

当使用 emit-value 时,model 会明确的绑定到选项中的 value 属性上,而不是整个对象。只有当选项是对象类型时才有意义。




当使用 map-options 时,model 可以只包含 value,并且他会根据选项进行映射以确定其 label。这涉及到性能损失,所以只有在绝对必要的情况下才使用它。例如,如果 model 包含整个 Object (因此包含 label 属性) ,就不需要它。




自定义属性名

默认情况下,QSelect 会寻找并使用每个选项中的 label, value, disablesanitize 属性,但是您也可以重写它们:

WARNING

如果您将函数用于自定义 props,请始终检查该选项是否为 null。这些函数既用于列表中的选项,也用于选定的选项。




自定义菜单选项

WARNING

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




这里是另一个例子,我们为每个选项添加一个 QToggle 。可能性是无穷的。




默认情况下,如果没有选项,则不会出现菜单。但是您可以自定义此情况并指定菜单应显示的内容。




懒加载

下面的示例展示了如何使用懒加载选项。这意味着,第一次渲染时不需要 options 属性。




当滚动到达终点时,您可以动态加载新选项:




覆盖模式




展示的值










过滤和自动补全

use-input 和原生属性

所有给 QSelect 设置的属性,如果未在 API 卡片中的 props 部分列出,那么它将会被传递给底层的原生input 标签(请先检查 use-input 属性描述以了解它的作用)以完成过滤/指定补全/添加新选项。例如: autocomplete,placeholder。

更多信息: native input attributes.



















创建新的值

TIP

以下只是一些示例,帮助您开始创建自己的 QSelect。这不是 QSelect 可以提供的全部可能性。 将此功能与 use-input 属性一起使用是很有意义的。

为了创建新的值,您可以使用new-value-mode 属性,或者监听 @new-value 事件,如果您同时使用两者,那么在您的自定义场景中,@new-value 事件应该只用于覆盖 new-value-mode

new-value-mode 属性

new-value-mode 属性指定创建的新值应该怎么样被添加到数据中,可以有以下三种取值:

  1. add 即使数据中已经存在了相同的值仍然添加;
  2. add-unique 不会添加重复数据;
  3. toggle 如果数据中之前没有此数据那么添加它,否则将其删除。

使用这个属性时不必监听 @new-value 事件,除非您有特殊的场景需要重写它的行为。




@new-value 事件

@new-value 事件中带有被添加的新数据和一个 done 回调函数。done 函数有两个可选的参数:

  • 被添加的数据
  • 添加数据的行为(与 new-value-mode 可设置的值一样,并且会覆盖它)
    • 默认行为(如果未设置 new-value-mode 的话)是即使数据中已经有重复的数据也会添加

不带参数调用 done() 只会清空输入框的值,而不会以任何方式修改 model。







使用菜单和过滤

过滤和给菜单中添加新的值一起使用:




过滤但不给菜单添加新的值(下面三个示例中,要添加的值至少需要 3 个字符才能通过):




从输入生成多个值:




安全处理

默认情况下,所有选项(包括选定的选项)都是经过安全处理的。这意味着以 HTML 格式显示它们是无效的。然而,如果您需要在您的选项上显示 HTML,并且您信任它们的内容,那么有几种方法可以做到这一点。

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

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

QSelect 的显示值会以 HTML 形式显示,如果:

  • 设置了 QSelect 的 display-value-html属性
  • 或者您不使用 display-value
    • 设置了 QSelect 的 options-html 属性
    • 所有被选定的选项的 html 键都被设置为 true

WARNING

如果您使用了 selectedselected-item 插槽,那么您需要自行对展示的值进行安全处理。display-value-html 属性不会被应用。







渲染性能

渲染性能不会受到选项数量的影响,除非在大的集合中使用 map-options。请注意,当用户在列表中滚动时,虚拟无限滚动将渲染其他选项。

TIP

  • (Composition API) 为了在使用大量选项时获得最佳性能,不要用 ref()/computed()/reactive()/etc来包裹您传递给 options 属性中的数组。这允许 Vue 跳过对列表进行响应式改变。
  • (Options API) 为了在使用大量选项的同时获得最佳性能,请使用 Object.freeze(items) 冻结您传递给 options 属性中的数组。这允许 Vue 跳过对列表进行响应式改变。



键盘导航

当 QSelect 聚焦时:

  • 按下 ENTER, ARROW DOWN (或者 SPACE 如果没有设置 use-input的话) 将会打开选项列表。
  • 如果设置了 use-chips
    • 按下 SHIFT + TAB 将在 QChips 中向后导航 (如果选择了一个 QChip TAB 键将会在 QChips 中向前导航)
    • 当一个 QChip 被选中时,按下 ENTER 会取消选中该选项。
    • 按下 BACKSPACE 会删除选中列表中的最后一个(如果设置了 use-input 输入应该为空)
  • 按下 TAB 将导航至下一个或页面上的上一个可聚焦元素(如果未设置 use-chips 或选择了第一个 QChip,则按 SHIFT + TAB
  • 如果未设置 use-input,则输入文字(0 - 9 or A - Z)将会:
    • 创建一个搜索缓冲区(当在 1.5 秒内未输入新键时将重置),该缓冲区将用于在选项标签中进行搜索
    • 如果多次输入缓冲区中的第一个键,则选择以该字母开头的下一个选项(在当前焦点之后)
    • 选择与键入的文本匹配的下一个选项(从当前的焦点开始)(匹配是模糊的-选项标签应以第一个字母开头并包含所有字母)

当选项列表打开时:

  • 按下 ARROW UPARROW DOWN将在选项列表中向上或向下导航
  • 按下 PAGE UPPAGE DOWN 将在选项列表中向上或向下导航一页
  • 按下 HOMEEND 将导航到选项列表的开头或结尾(仅当您未使用 use-input 或输入为空时)
  • 使用箭头键进行导航时,导航将在到达列表的开头或结尾时结束
  • 选项在列表中被选中时按下 ENTER (如果未设置 use-input,则按 SPACE;如果未设置 multiple,则按 TAB)将会:
    • 选择选项,并且如果未设置 multiple 则关闭选项列表。
    • 如果设置了 multiple,则切换选项。

原生表单提交

当处理一个带有 actionmethod 的原生表单时(如:使用 Quasar 和 ASP.NET 控制器时),您需要为 QSelect 声明 name 属性,否则表单数据中不会包含它:




类型定义

export type QSelectOption<T = string> = {
  label: string;
  value: T;
};