QSelect 组件有两种选择类型：单个或多个。此组件会打开一个菜单，用于选择列表和操作。过滤器也可用于更长的列表。

¥The QSelect component has two types of selection: single or multiple. This component opens up a menu for the selection list and action. A filter can also be used for longer lists.

如果你需要下拉菜单，请使用 “button” 而不是 “input”，而不是 按钮下拉菜单。

¥In case you are looking for a dropdown “button” instead of “input” use Button Dropdown instead.

设计(Design)

¥Design

概述(Overview)

¥Overview

装饰器(Decorators)

¥Decorators

着色(Coloring)

¥Coloring

可清除(Clearable)

¥Clearable

作为辅助，你可以使用 clearable 属性，以便用户可以通过附加图标将模型重置为 null。以下示例中的第二个 QSelect 相当于使用 clearable。

¥As a helper, you can use clearable prop so user can reset model to null through an appended icon. The second QSelect in the example below is the equivalent of using clearable.

禁用并只读(Disable and readonly)

¥Disable and readonly

QBtn 类型为 “submit” 的插槽(Slots with QBtn type “submit”)

¥Slots with QBtn type “submit”

菜单转换(Menu transitions)

¥Menu transitions

在下面的例子中，展示了一些过渡效果。要查看可用的转换的完整列表，请前往 过渡效果。

¥In the example below there’s a few transitions showcased. For a full list of transitions available, go to Transitions.

选项列表显示模式(Options list display mode)

¥Options list display mode

默认情况下，QSelect 在桌面设备上以菜单形式显示选项列表，在移动设备上以对话框形式显示。你可以使用 behavior 属性强制执行某项行为。

¥By default QSelect shows the list of options as a menu on desktop and as a dialog on mobiles. You can force one behavior by using the behavior property.

模型(The model)

¥The model

模型内容可能会受到 emit-value 属性的影响，你将在下面的 “选项” 部分中了解到这一点。

¥The model content can be influenced by emit-value prop as you’ll learn in “The options” section below.

选项(The options)

¥The options

选项类型(Options type)

¥Options type

影响模型(Affecting model)

¥Affecting model

使用 emit-value 时，模型将根据指定的选定选项变为确定的 value。默认为发出整个选项。仅当选项为对象形式时才有意义。

¥When emit-value is used, the model becomes the determined value from the specified selected option. Default is to emit the whole option. It makes sense to use it only when the options are of Object form.

使用 map-options 时，模型只能包含 value，并且它将与选项进行映射以确定其标签。这会导致性能损失，因此仅在绝对必要时才使用它。例如，如果模型包含整个对象（因此包含 label 属性），则不需要这样做。

¥When map-options is used, the model can contain only the value, and it will be mapped against the options to determine its label. There is a performance penalty involved, so use it only if absolutely necessary. It’s not needed, for example, if the model contains the whole Object (so contains the label prop).

自定义属性名称(Custom prop names)

¥Custom prop names

默认情况下，QSelect 从选项数组对象中查看每个选项的 label、value、disable 和 sanitize 属性。但是你可以覆盖这些：

¥By default, QSelect looks at label, value, disable and sanitize props of each option from the options array Objects. But you can override those:

自定义菜单选项(Customizing menu options)

¥Customizing menu options

以下是另一个示例，我们为每个选项添加了一个 QToggle。可能性无穷无尽。

¥Here is another example where we add a QToggle to each option. The possibilities are endless.

默认情况下，当没有选项时，菜单不会显示。但是你可以自定义此场景并指定菜单应显示的内容。

¥By default, when there are no options, the menu won’t appear. But you can customize this scenario and specify what the menu should display.

延迟加载(Lazy loading)

¥Lazy loading

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

¥The following example shows a glimpse of how you can play with lazy loading the options. This means, along with many other things, that options prop is not required on first render.

你可以在滚动到末尾时动态加载新选项：

¥You can dynamically load new options when scroll reaches the end:

封面模式(Cover mode)

¥Cover mode

禁用 TAB 选择(Disable TAB selection)

¥Disable TAB selection

显示值(The display value)

¥The display value

过滤和自动补齐(Filtering and autocomplete)

¥Filtering and autocomplete

“use-input” 原生属性(Native attributes with “use-input”)

¥Native attributes with “use-input”

QSelect 上设置的所有属性，如果 API 中的 props 列表中没有，则将传递到原生输入字段（请先查看 use-input prop 描述以了解其功能），用于过滤/自动补齐/添加新值。一些示例：自动补齐，占位符。

¥All the attributes set on QSelect that are not in the list of props in the API will be passed to the native input field used (please check use-input prop description first to understand what it does) for filtering / autocomplete / adding new value. Some examples: autocomplete, placeholder.

更多信息：原生输入属性。

¥More information: native input attributes.

创建新值(Create new values)

¥Create new values

为了启用新值的创建，你需要指定 new-value-mode 属性和/或监听 @new-value 事件。如果你同时使用两者，则监听 @new-value 的目的仅在于在自定义场景中覆盖 new-value-mode。

¥In order to enable the creation of new values, you need to either specify the new-value-mode prop and/or listen for @new-value event. If you use both, then the purpose of listening to @new-value would be only to override the new-value-mode in your custom scenarios.

新的-value-mode 属性(The new-value-mode prop)

¥The new-value-mode prop

new-value-mode 属性值指定应如何添加值：add（即使重复也会添加值）、add-unique（仅在不重复时添加）或 toggle（如果值不在模型中则添加，否则删除）。

¥The new-value-mode prop value specifies how the value should be added: add (adds a value, even if duplicate), add-unique (add only if NOT duplicate) or toggle (adds value if it’s not already in model, otherwise it removes it).

使用此属性，你无需再监听 @new-value 事件，除非你在某些特定场景下需要覆盖该行为。

¥By using this prop you don’t need to also listen for @new-value event, unless you have some specific scenarios for which you want to override the behavior.

@new-value 事件(The @new-value event)

¥The @new-value event

@new-value 事件会发出要添加的值和 done 回调。done 回调有两个可选参数：

¥The @new-value event is emitted with the value to be added and a done callback. The done callback has two optional parameters:

• 要添加的值

  ¥the value to be added

• 行为（与 new-value-mode 属性的值相同，并且当指定该属性时，如果使用了该属性，则会覆盖该属性） - 默认行为（如果不使用 new-value-mode）是添加该值，即使它会重复。

  ¥the behavior (same values of new-value-mode prop, and when it is specified it overrides that prop – if it is used) – default behavior (if not using new-value-mode) is to add the value even if it would be a duplicate

不带参数调用 done() 只会清空输入框的值，而不会以任何方式篡改模型。

¥Calling done() with no parameters simply empties the input box value, without tampering with the model in any way.

使用菜单和过滤(Using menu and filtering)

¥Using menu and filtering

过滤新值并将其添加到菜单：

¥Filtering and adding the new values to menu:

过滤新值（在下面的示例中，要添加的值至少需要 3 个字符），并且不会添加到菜单：

¥Filters new values (in the example below the value to be added requires at least 3 characters to pass), and does not add to menu:

从输入生成多个值：

¥Generating multiple values from input:

清理(Sanitization)

¥Sanitization

默认情况下，所有选项（包括选定的选项）都会被清理。这意味着以 HTML 格式显示它们已被禁用。但是，如果你要求选项包含 HTML 代码并且你信任其内容，则有几种方法可以实现。

¥By default, all options (included selected ones) are sanitized. This means that displaying them in HTML format is disabled. However, if you require HTML on your options and you trust their content, then there are a few ways to do this.

你可以通过以下方式强制菜单选项采用 HTML 格式：

¥You can force the HTML form of the menu options by:

• 将受信任选项的 html 键设置为 true（针对特定的受信任选项）

  ¥setting html key of the trusted option to true (for specific trusted options)

• 或者设置 QSelect 的 options-html 属性（适用于所有选项）

  ¥or by setting options-html prop of QSelect (for all options)

如果满足以下条件，QSelect 的显示值将以 HTML 格式显示：

¥The displayed value of QSelect is displayed as HTML if:

• QSelect 的 display-value-html 属性已设置。

  ¥the display-value-html prop of QSelect is set

• 或者你未使用 display-value 并且

  ¥or you are not using display-value and

  • QSelect 的 options-html 属性已设置。

    ¥the options-html prop of QSelect is set

  • 任何选定的选项都将 html 键设置为 true

    ¥any selected option has html key set to true

渲染性能(Render performance)

¥Render performance

渲染性能不会受到选项数量的太大影响，除非 map-options 的使用范围很广。注意无限滚动，当用户滚动列表时，它会渲染更多选项。

¥The render performance is NOT affected much by the number of options, unless map-options is used on a large set. Notice the infinite scroll in place which renders additional options as the user scrolls through the list.

键盘导航(Keyboard navigation)

¥Keyboard navigation

当 QSelect 获得焦点时：

¥When QSelect is focused:

• 按 ENTER、ARROW DOWN（如果未设置 use-input，则按 SPACE）将打开选项列表

  ¥pressing ENTER, ARROW DOWN (or SPACE if use-input is not set) will open the list of options

• 如果设置了 use-chips：

  ¥if use-chips is set:

  • 按下 SHIFT + TAB 将在 QChip 中向后导航（如果选择了 QChip，则 TAB 将在 QChip 中向前导航）

    ¥pressing SHIFT + TAB will navigate backwards through the QChips (if a QChip is selected TAB will navigate forward through the QChips)

  • 在选择 QChip 时按下 ENTER 将从选择中移除该选项

    ¥pressing ENTER when a QChip is selected will remove that option from the selection

  • 按下 BACKSPACE 将从选择中移除最后一个选项（设置 use-input 时，输入应为（空）

    ¥pressing BACKSPACE will remove the last option from the selection (when use-input is set the input should be empty)

• 在设置 clearable 的情况下按下 BACKSPACE 则：

  ¥pressing BACKSPACE when clearable is set then:

  • 它会清除模型（使用 null 值）以进行单选

    ¥it clears the model (with null value) for single selection

  • 它删除多选时最后添加的值

    ¥it removes the last added value for multiple selection

• 按下 TAB（如果 use-chips 未设置或选择了第一个 QChip，则按下 SHIFT + TAB）将导航到页面上的下一个或上一个可聚焦元素

  ¥pressing TAB (or SHIFT + TAB if use-chips is not set or the first QChip is selected) will navigate to the next or previous focusable element on page

• 如果未设置 use-input，则输入文本（0 - 9 或 A - Z）将：

  ¥typing text (0 - 9 or A - Z) if use-input is not set will:

  • 创建一个搜索缓冲区（当 1.5 秒内未输入新键时将重置），用于在选项标签中搜索

    ¥create a search buffer (will be reset when a new key is not typed for 1.5 seconds) that will be used to search in the options labels

  • 如果缓冲区中的第一个键被多次输入，则选择下一个以该字母开头的选项（在当前焦点之后）。

    ¥select the next option starting with that letter (after the current focused one) if the first key in buffer is typed multiple times

  • 选择下一个与输入文本匹配的选项（从当前焦点开始）（匹配模糊） - 选项标签应以首字母开头并包含所有字母）

    ¥select the next option (starting with the current focused one) that matches the typed text (the match is fuzzy - the option label should start with the first letter and contain all the letters)

打开选项列表时：

¥When the list of options is opened:

• 按下 ARROW UP 或 ARROW DOWN 将在选项列表中向上或向下导航

  ¥pressing ARROW UP or ARROW DOWN will navigate up or down in the list of options

• 按下 PAGE UP 或 PAGE DOWN 将在选项列表中向上或向下导航一页

  ¥pressing PAGE UP or PAGE DOWN will navigate one page up or down in the list of options

• 按下 HOME 或 END 将在选项列表中导航到开头或结尾（仅当你未使用 use-input 或输入为空时）

  ¥pressing HOME or END will navigate to the start or end of the list of options (only if you are not using use-input, or the input is empty)

• 使用箭头键导航时，导航会在到达列表的开头或结尾时换行。

  ¥when navigating using arrow keys, navigation will wrap when reaching the start or end of the list

• 按下 ENTER（如果 use-input 未设置，则按下 SPACE，或（如果未设置 multiple 和 disable-tab-selection，则 TAB 会跳转到 QChip 列表）当列表中选择一个选项时，将执行以下操作：

  ¥pressing ENTER (or SPACE when use-input is not set, or TAB when multiple and disable-tab-selection are not set) when an option is selected in the list will:

  • 如果未设置 multiple 和 disable-tab-selection，则选择该选项并关闭选项列表。

    ¥select the option and close the list of options if multiple and disable-tab-selection are not set

  • 如果设置了 multiple，则切换该选项

    ¥toggle the option if multiple is set

原生表单提交(Native form submit)

¥Native form submit

当处理具有 action 和 method 的原生表单时（例如，将 Quasar 与 ASP.NET 控制器结合使用时），你需要在 QSelect 上指定 name 属性，否则 formData 将不会包含该属性包含它（如果应该包含的话） - 所有值都将转换为字符串（原生行为，因此请勿使用对象值）：

¥When dealing with a native form which has an action and a method (eg. when using Quasar with ASP.NET controllers), you need to specify the name property on QSelect, otherwise formData will not contain it (if it should) - all value are converted to string (native behaviour, so do not use Object values):