选择框

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, disable 和 sanitize 属性,但是您也可以重写它们:

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

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

原生表单提交

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




类型定义

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