Skip to main content

ion-select

shadow

选择是用于从一组选项中选择一个或多个选项的表单控件。当用户点击选择时,会出现一个对话框,显示所有选项,以大而易选的列表渲染。

🌐 Selects are form controls to select an option, or options, from a set of options. When a user taps the select, a dialog appears with all of the options in a large, easy to select list.

应该使用带有子元素 <ion-select-option> 的 select。如果子选项没有给出 value 属性,则其文本将用作值。

🌐 A select should be used with child <ion-select-option> elements. If the child option is not given a value attribute then its text will be used as the value.

如果在 <ion-select> 上设置了 value,所选的选项将根据该值进行选择。

🌐 If value is set on the <ion-select>, the selected option will be chosen based on that value.

标签

🌐 Labels

标签应用于描述选择框。它们可以用于视觉展示,当用户聚焦于选择框时,屏幕阅读器也会读取它们。这使用户能够轻松理解选择框的意图。选择框有几种方法来分配标签:

🌐 Labels should be used to describe the select. They can be used visually, and they will also be read out by screen readers when the user is focused on the select. This makes it easy for the user to understand the intent of the select. Select has several ways to assign a label:

Select 有多个选项用于为组件提供标签:

🌐 Select has several options for supplying a label for the component:

  • label 属性:用于明文标签
  • label 插槽:用于自定义 HTML 标签
  • aria-label:用于为屏幕阅读器提供标签,但不添加可见标签

标签放置

🌐 Label Placement

标签默认会占据其内容的宽度。开发者可以使用 labelPlacement 属性来控制标签相对于控件的位置。虽然这里使用了 label 属性,但 labelPlacement 也可以与 label 插槽一起使用。

🌐 Labels will take up the width of their content by default. Developers can use the labelPlacement property to control how the label is placed relative to the control. While the label property is used here, labelPlacement can also be used with the label slot.

标签槽

🌐 Label Slot

虽然明文标签应通过 label 属性传入,但如果需要自定义 HTML,则可以通过 label 插槽传入。

🌐 While plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.

无可见标签

🌐 No Visible Label

即使不需要可见标签,开发者仍应提供一个 aria-label,以便选择框对屏幕阅读器可访问。

🌐 If no visible label is needed, developers should still supply an aria-label so the select is accessible to screen readers.

单选

🌐 Single Selection

默认情况下,选择框只允许用户选择一个选项。警报界面向用户显示一个带有单选按钮样式的选项列表。选择组件的值接收所选选项的值。

🌐 By default, the select allows the user to select only one option. The alert interface presents users with a radio button styled list of options. The select component's value receives the value of the selected option's value.

单选的键盘交互在下面的 键盘交互 部分中描述。

🌐 Keyboard interactions for single selection are described in the Keyboard Interactions section below.

多重选择

🌐 Multiple Selection

通过向 select 添加 multiple 属性,用户可以选择多个选项。当可以选择多个选项时,警报、弹出框或模态覆盖会向用户显示一个带有复选框样式的选项列表。select 组件的值会接收所有已选择选项值的数组。

🌐 By adding the multiple attribute to select, users are able to select multiple options. When multiple options can be selected, the alert, popover, or modal overlay presents users with a checkbox styled list of options. The select component's value receives an array of all of the selected option values.

note

action-sheet 接口不支持多选。

🌐 The action-sheet interface is not supported with multiple selection.

多选的键盘交互在下面的 键盘交互 部分中描述。

🌐 Keyboard interactions for multiple selection are described in the Keyboard Interactions section below.

接口

🌐 Interfaces

默认情况下,select 使用 ion-alert 在警告中打开选项覆盖层。可以通过将 action-sheetpopovermodal 分别传递给 interface 属性,将界面更改为使用 ion-action-sheetion-popoverion-modal。请阅读其他部分以了解不同界面的限制。

🌐 By default, select uses ion-alert to open up the overlay of options in an alert. The interface can be changed to use ion-action-sheet, ion-popover, or ion-modal by passing action-sheet, popover, or modal, respectively, to the interface property. Read on to the other sections for the limitations of the different interfaces.

警报

🌐 Alert

动作表

🌐 Action Sheet

弹出窗口

🌐 Popover

🌐 Modal

响应交互

🌐 Responding to Interaction

处理用户与选择控件交互的主要方式是 ionChangeionDismissionCancel 事件。有关这些事件以及选择控件触发的其他事件的更多详细信息,请参见 Events

🌐 The main ways of handling user interaction with the select are the ionChange, ionDismiss, and ionCancel events. See Events for more details on these and other events that select fires.

Console
Console messages will appear here when logged from the example above.

对象值引用

🌐 Object Value References

在使用对象作为选择值时,如果这些对象来自服务器或数据库,其标识可能会发生变化,而所选值的标识保持不变。例如,当将具有所需对象值的现有记录加载到选择框中时,可能会发生这种情况,但新获取的选择项现在具有不同的标识。这将导致选择框看起来没有任何值,即使原来的选择仍然存在。

🌐 When using objects for select values, it is possible for the identities of these objects to change if they are coming from a server or database, while the selected value's identity remains the same. For example, this can occur when an existing record with the desired object value is loaded into the select, but the newly retrieved select options now have different identities. This will result in the select appearing to have no value at all, even though the original selection in still intact.

默认情况下,选择框使用严格相等(===)来确定选项是否被选中。可以通过向 compareWith 属性提供属性名或函数来覆盖这一行为。

🌐 By default, the select uses strict equality (===) to determine if an option is selected. This can be overridden by providing a property name or a function to the compareWith property.

使用比较

🌐 Using compareWith

Console
Console messages will appear here when logged from the example above.

对象值和多重选择

🌐 Object Values and Multiple Selection

Console
Console messages will appear here when logged from the example above.

齐行

🌐 Justification

开发者可以使用 justify 属性来控制标签和控件在一行上的排列方式。

🌐 Developers can use the justify property to control how the label and control are packed on a line.

填充选择

🌐 Filled Selects

Material Design 为选择控件提供了填充样式。选择控件上的 fill 属性可以设置为 "solid""outline"

🌐 Material Design offers filled styles for a select. The fill property on the select can be set to either "solid" or "outline".

通过将选择的 mode 设置为 md,可以在 iOS 上使用填充选择。

🌐 Filled selects can be used on iOS by setting the select's mode to md.

warning

使用 fill 的选择不应在 ion-item 中使用,因为组件之间存在样式冲突。

选择按钮

🌐 Select Buttons

该警报支持两个按钮:CancelOK。每个按钮的文本可以使用 cancelTextokText 属性进行自定义。

🌐 The alert supports two buttons: Cancel and OK. Each button's text can be customized using the cancelText and okText properties.

action-sheetpopover 接口没有 OK 按钮,点击任何选项都会自动关闭覆盖层并选择该值。popover 接口没有 Cancel 按钮,点击背景会关闭覆盖层。

🌐 The action-sheet and popover interfaces do not have an OK button, clicking on any of the options will automatically close the overlay and select that value. The popover interface does not have a Cancel button, clicking on the backdrop will close the overlay.

modal 界面在标题栏中有一个 Close 按钮。这个按钮仅负责关闭模态窗口。任何已做的选择在点击此按钮或使用其他方式关闭模态窗口后都会保留。

🌐 The modal interface has a single Close button in the header. This button is only responsible for dismissing the modal. Any selections made will persist after clicking this button or if the modal is dismissed using an alternative method.

接口选项

🌐 Interface Options

由于 select 使用了 alert、action sheet、popover 和 modal 接口,因此选项可以通过 interfaceOptions 属性传递给这些组件。这可以用于传递自定义标题、副标题、CSS 类等。

🌐 Since select uses the alert, action sheet, popover, and modal interfaces, options can be passed to these components through the interfaceOptions property. This can be used to pass a custom header, subheader, css class, and more.

请参阅 ion-alert 文档ion-action-sheet 文档ion-popover 文档ion-modal 文档 以了解每个接口接受的属性。

🌐 See the ion-alert docs, ion-action-sheet docs, ion-popover docs, and ion-modal docs for the properties that each interface accepts.

注意:interfaceOptions 不会通过 alert 接口覆盖 inputsbuttons

🌐 Note: interfaceOptions will not override inputs or buttons with the alert interface.

起始槽和结束槽

🌐 Start and End Slots

startend 插槽可以用于在选择框的任一侧放置图标、按钮或前缀/后缀文本。如果点击插槽内容,选择框将不会打开。

🌐 The start and end slots can be used to place icons, buttons, or prefix/suffix text on either side of the select. If the slot content is clicked, the select will not open.

note

在大多数情况下,放置在这些插槽中的 Icon 组件应具有 aria-hidden="true"。有关更多信息,请参阅 图标无障碍文档

如果插槽内容是为了互动的,应将其封装在交互元素中,例如 Button。这确保了内容可以通过 Tab 键跳转。

🌐 If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a Button. This ensures that the content can be tabbed to.

定制化

🌐 Customization

Select 组件由两个单元组成,每个单元都需要单独进行样式设置。ion-select 元素在视图中由选中的值或占位符(如果没有选中值)以及下拉图标表示。该接口在上面的 接口 部分中定义,是点击 ion-select 时打开的对话框。该接口包含通过添加 ion-select-option 元素定义的所有选项。以下部分将讲解为这些单元设置样式的区别。

🌐 There are two units that make up the Select component and each need to be styled separately. The ion-select element is represented on the view by the selected value(s), or placeholder if there is none, and dropdown icon. The interface, which is defined in the Interfaces section above, is the dialog that opens when clicking on the ion-select. The interface contains all of the options defined by adding ion-select-option elements. The following sections will go over the differences between styling these.

设置选择元素的样式

🌐 Styling Select Element

如前所述,ion-select 元素仅由在视图上显示的值(或占位符)和图标组成。要自定义它,可以使用 CSS 与任意 CSS 自定义属性 的组合来进行样式设置。

🌐 As mentioned, the ion-select element consists only of the value(s), or placeholder, and icon that is displayed on the view. To customize this, style using a combination of CSS and any of the CSS custom properties.

或者,根据所需的浏览器支持,可以使用 CSS 阴影部分来为 select 元素设置样式。请注意,通过使用 ::part,可以针对元素上的任何 CSS 属性进行操作。

🌐 Alternatively, depending on the browser support needed, CSS shadow parts can be used to style the select. Notice that by using ::part, any CSS property on the element can be targeted.

样式选择界面

🌐 Styling Select Interface

自定义界面对话框应按照该界面文档中的样式部分(CSS影子部分、CSS自定义属性和插槽)进行:

🌐 Customizing the interface dialog should be done by following the styling sections (CSS shadow parts, CSS custom properties, and slots) in that interface's documentation:

然而,选择选项确实会设置一个类以便于样式设置,并允许将类传递给覆盖选项,请参见 选择选项文档 以获取自定义选项的使用示例。

🌐 However, the Select Option does set a class for easier styling and allows for the ability to pass a class to the overlay option, see the Select Options documentation for usage examples of customizing options.

自定义切换图标

🌐 Custom Toggle Icons

可以使用 toggleIcon 和/或 expandedIcon 属性将显示在选择文本旁边的图标设置为任何 Ionicon

🌐 The icon that displays next to the select text can be set to any Ionicon using the toggleIcon and/or expandedIcon properties.

图标翻转行为

🌐 Icon Flip Behavior

默认情况下,当下拉菜单打开时,切换图标在 md 模式下会自动旋转,而在 ios 模式下保持静止。此行为可以通过 CSS 自定义。

🌐 By default, when the select is open, the toggle icon will automatically rotate on md mode and remain static on ios mode. This behavior can be customized using CSS.

下面的示例还使用了一个 自定义 toggleIcon,以更好地演示 ios 的翻转行为,因为默认图标是垂直对称的。

🌐 The below example also uses a custom toggleIcon to better demonstrate the flip behavior on ios, since the default icon is vertically symmetrical.

预输入组件

🌐 Typeahead Component

可以使用现有的 Ionic 组件来构建类型预测或自动补齐功能。我们建议使用 ion-modal 来充分利用可用的屏幕空间。

🌐 Typeahead or autocomplete functionality can be built using existing Ionic components. We recommend using an ion-modal to make the best use of the available screen space.

辅助程序和错误文本

🌐 Helper & Error Text

帮助文本和错误文本可以在使用 helperTexterrorText 属性的选择框中使用。除非将 ion-invalidion-touched 类添加到 ion-select 中,否则错误文本不会显示。这可确保在用户有机会输入数据之前不会显示错误。

🌐 Helper and error text can be used inside of a select with the helperText and errorText property. The error text will not be displayed unless the ion-invalid and ion-touched classes are added to the ion-select. This ensures errors are not shown before the user has a chance to enter data.

在 Angular 中,这通过表单验证自动补齐。在 JavaScript、React 和 Vue 中,需要根据你自己的验证手动添加类。

🌐 In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.

接口

🌐 Interfaces

SelectChangeEventDetail

interface SelectChangeEventDetail<T = any> {
value: T;
}

SelectCustomEvent

虽然不是必需的,但可以使用此接口替代 CustomEvent 接口,以便对从此组件发出的 Ionic 事件进行更强类型的处理。

🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.

interface SelectCustomEvent<T = any> extends CustomEvent {
detail: SelectChangeEventDetail<T>;
target: HTMLIonSelectElement;
}

无障碍

🌐 Accessibility

键盘交互

🌐 Keyboard Interactions

Ionic 的键盘交互遵循 Web 的实现模式,而不是原生 iOS 选择,以在所有平台上获得一致的体验。

🌐 Ionic's keyboard interactions follow the implementation patterns of the web instead of the native iOS select for a consistent experience across all platforms.

当满足以下条件时,这些键盘交互适用于所有 ion-select 元素:

🌐 These keyboard interactions apply to all ion-select elements when the following conditions are met:

  • 选择已关闭。
  • 选择是集中的。
  • 该选择未被禁用。
描述
回车打开覆盖层并将焦点放在第一个选定的选项上。如果没有选定的选项,则焦点放在第一个选项上。
空格打开覆盖层并将焦点放在第一个选定的选项上。如果没有选定的选项,则焦点放在第一个选项上。

单选

🌐 Single Selection

单选键盘交互遵循 ARIA 单选按钮的实现模式

🌐 Single selection keyboard interaction follows the ARIA implementation patterns of a radio.

当覆盖层显示并获得焦点时,这些键盘交互适用于 ion-action-sheetion-alertion-popoverion-modal 元素。

🌐 These keyboard interactions apply to ion-action-sheet, ion-alert, ion-popover, and ion-modal elements when the overlay is presented and focused.

| 键 | 描述 |

| --- | --- |

| 向下箭头 | 聚焦并选择列表中的下一个选项。如果没有下一个选项,选择将循环到第一个选项。 |

| ArrowLeft | 将焦点移至列表中的上一个选项并进行选择。如果没有上一个选项,选择将循环到最后一个选项。 |

| ArrowRight | 将焦点移至列表中的下一个选项并进行选择。如果没有下一个选项,选择将循环到第一个选项。 |

| ArrowUp | 将焦点移至列表中的上一个选项并选择它。如果没有上一个选项,选择将循环到最后一个选项。 |

| 输入 | 如果一个选项被聚焦,它将选择该选项。没有“确定”按钮的覆盖层会立即提交值,关闭覆盖层并将焦点返回到 ion-select 元素。

如果“确定”按钮被聚焦,它将保存用户的选择,关闭覆盖层并将焦点返回到 ion-select 元素。 |

| 退出 | 在不更改已提交选项的情况下关闭覆盖层。将焦点返回到 ion-select 元素。 |

| 空格 | 如果聚焦的单选按钮未被选中,则取消当前选中的单选按钮并选中聚焦的单选按钮。否则,不执行任何操作。如果覆盖层没有“确定”按钮,值将立即提交并关闭覆盖层。|

| Tab | 将焦点移动到覆盖层上的下一个可聚焦元素(取消按钮、“确定”按钮,或选择项或第一个选项)。如果下一个可聚焦元素是选项,则焦点将移到已选择的选项,否则将聚焦到第一个选项。 |

多重选择

🌐 Multiple Selection

多选键盘交互遵循复选框的ARIA实现模式

🌐 Multiple selection keyboard interaction follows the ARIA implementation patterns of a checkbox.

当覆盖层显示且启用多重选择时,这些键盘交互适用于 ion-alertion-popoverion-modal 元素。

🌐 These keyboard interactions apply to ion-alert, ion-popover, and ion-modal elements when the overlay is presented and multiple selection is enabled.

描述
Enter当“确定”按钮获得焦点时,它会保存用户的选择,关闭覆盖层,并将焦点返回到 ion-select 元素。
Escape关闭覆盖层而不更改已提交的选项。焦点返回到 ion-select 元素。
Space选择或取消选择当前聚焦的选项。这不会取消选择其他已选的选项。如果覆盖层没有“确定”按钮,将立即提交该值。
Tab将焦点移到覆盖层上的下一个可聚焦元素(取消按钮、“确定”按钮或任何选项)。如果下一个可聚焦元素是选项列表,则应遍历每个选项。

属性

🌐 Properties

cancelText

DescriptionThe text to display on the cancel button.
Attributecancel-text
Typestring
Default'Cancel'

color

DescriptionThe color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.

This property is only available when using the modern select syntax.
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined
Defaultundefined

compareWith

DescriptionThis property allows developers to specify a custom function or property name for comparing objects when determining the selected option in the ion-select. When not specified, the default behavior will use strict equality (===) for comparison.
Attributecompare-with
Type((currentValue: any, compareValue: any) => boolean) | null | string | undefined
Defaultundefined

disabled

DescriptionIf true, the user cannot interact with the select.
Attributedisabled
Typeboolean
Defaultfalse

errorText

DescriptionText that is placed under the select and displayed when an error is detected.
Attributeerror-text
Typestring | undefined
Defaultundefined

expandedIcon

DescriptionThe toggle icon to show when the select is open. If defined, the icon rotation behavior in md mode will be disabled. If undefined, toggleIcon will be used for when the select is both open and closed.
Attributeexpanded-icon
Typestring | undefined
Defaultundefined

fill

DescriptionThe fill for the item. If "solid" the item will have a background. If "outline" the item will be transparent with a border. Only available in md mode.
Attributefill
Type"outline" | "solid" | undefined
Defaultundefined

helperText

DescriptionText that is placed under the select and displayed when no error is detected.
Attributehelper-text
Typestring | undefined
Defaultundefined

interface

DescriptionThe interface the select should use: action-sheet, popover, alert, or modal.
Attributeinterface
Type"action-sheet" | "alert" | "modal" | "popover"
Default'alert'

interfaceOptions

DescriptionAny additional options that the alert, action-sheet or popover interface can take. See the ion-alert docs, the ion-action-sheet docs, the ion-popover docs, and the ion-modal docs for the create options for each interface.

Note: interfaceOptions will not override inputs or buttons with the alert interface.
Attributeinterface-options
Typeany
Default{}

justify

DescriptionHow to pack the label and select within a line. justify does not apply when the label and select are on different lines when labelPlacement is set to "floating" or "stacked". "start": The label and select will appear on the left in LTR and on the right in RTL. "end": The label and select will appear on the right in LTR and on the left in RTL. "space-between": The label and select will appear on opposite ends of the line with space between the two elements.
Attributejustify
Type"end" | "space-between" | "start" | undefined
Defaultundefined

label

DescriptionThe visible label associated with the select.

Use this if you need to render a plaintext label.

The label property will take priority over the label slot if both are used.
Attributelabel
Typestring | undefined
Defaultundefined

labelPlacement

DescriptionWhere to place the label relative to the select. "start": The label will appear to the left of the select in LTR and to the right in RTL. "end": The label will appear to the right of the select in LTR and to the left in RTL. "floating": The label will appear smaller and above the select when the select is focused or it has a value. Otherwise it will appear on top of the select. "stacked": The label will appear smaller and above the select regardless even when the select is blurred or has no value. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). When using "floating" or "stacked" we recommend initializing the select with either a value or a placeholder.
Attributelabel-placement
Type"end" | "fixed" | "floating" | "stacked" | "start" | undefined
Default'start'

mode

DescriptionThe mode determines which platform styles to use.

This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attributemode
Type"ios" | "md"
Defaultundefined

multiple

DescriptionIf true, the select can accept multiple values.
Attributemultiple
Typeboolean
Defaultfalse

name

DescriptionThe name of the control, which is submitted with the form data.
Attributename
Typestring
Defaultthis.inputId

okText

DescriptionThe text to display on the ok button.
Attributeok-text
Typestring
Default'OK'

placeholder

DescriptionThe text to display when the select is empty.
Attributeplaceholder
Typestring | undefined
Defaultundefined

required

DescriptionIf true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
Attributerequired
Typeboolean
Defaultfalse

selectedText

DescriptionThe text to display instead of the selected option's value.
Attributeselected-text
Typenull | string | undefined
Defaultundefined

shape

DescriptionThe shape of the select. If "round" it will have an increased border radius.
Attributeshape
Type"round" | undefined
Defaultundefined

toggleIcon

DescriptionThe toggle icon to use. Defaults to chevronExpand for ios mode, or caretDownSharp for md mode.
Attributetoggle-icon
Typestring | undefined
Defaultundefined

value

DescriptionThe value of the select.
Attributevalue
Typeany
Defaultundefined

事件

🌐 Events

NameDescriptionBubbles
ionBlurEmitted when the select loses focus.true
ionCancelEmitted when the selection is cancelled.true
ionChangeEmitted when the value has changed.

This event will not emit when programmatically setting the value property.
true
ionDismissEmitted when the overlay is dismissed.true
ionFocusEmitted when the select has focus.true

方法

🌐 Methods

open

DescriptionOpen the select overlay. The overlay is either an alert, action sheet, or popover, depending on the interface property on the ion-select.
Signatureopen(event?: UIEvent) => Promise<any>
Parametersevent: The user interface event that called the open.

CSS 阴影部分

🌐 CSS Shadow Parts

NameDescription
bottomThe container element for helper text, error text, and counter.
containerThe container for the selected text or placeholder.
error-textSupporting text displayed beneath the select when the select is invalid and touched.
helper-textSupporting text displayed beneath the select when the select is valid.
iconThe select icon container.
innerThe inner element of the wrapper that manages the slots, selected values or placeholder, and toggle icons.
labelThe label text describing the select.
placeholderThe text displayed in the select when there is no value.
supporting-textSupporting text displayed beneath the select.
textThe displayed value of the select.
wrapperThe clickable label element that wraps the entire form field (label text, slots, selected values or placeholder, and toggle icons).

CSS 自定义属性

🌐 CSS Custom Properties

NameDescription
--backgroundBackground of the select
--border-colorColor of the select border
--border-radiusRadius of the select border. A large radius may display unevenly when using fill="outline"; if needed, use shape="round" instead or increase --padding-start.
--border-styleStyle of the select border
--border-widthWidth of the select border
--highlight-color-focusedThe color of the highlight on the select when focused
--highlight-color-invalidThe color of the highlight on the select when invalid
--highlight-color-validThe color of the highlight on the select when valid
--highlight-heightThe height of the highlight on the select. Only applies to md mode.
--padding-bottomBottom padding of the select
--padding-endRight padding if direction is left-to-right, and left padding if direction is right-to-left of the select
--padding-startLeft padding if direction is left-to-right, and right padding if direction is right-to-left of the select
--padding-topTop padding of the select
--placeholder-colorColor of the select placeholder text
--placeholder-opacityOpacity of the select placeholder text
--ripple-colorThe color of the ripple effect on MD mode.

插槽

🌐 Slots

NameDescription
endContent to display at the trailing edge of the select.
labelThe label text to associate with the select. Use the labelPlacement property to control where the label is placed relative to the select. Use this if you need to render a label with custom HTML.
startContent to display at the leading edge of the select.