ion-select

shadow

选择器（Select）是用于从一组选项中选择一个或多个选项的表单控件。当用户点击选择器时，会出现一个对话框，其中包含一个大型、易于选择的列表中的所有选项。

选择器应与子 <ion-select-option> 元素一起使用。如果子选项没有给出 value 属性，则其文本将用作值。

如果在 <ion-select> 上设置了 value，则将根据该值选择选项。

标签

标签应用于描述选择器。它们可以在视觉上使用，当用户聚焦选择器时，屏幕阅读器也会将其读出。这使用户能够轻松理解选择器的用途。选择器有几种分配标签的方式：

选择器有几种为组件提供标签的选项：

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

标签位置

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

标签插槽

虽然纯文本标签应通过 label 属性传递，但如果需要自定义 HTML，可以通过 label 插槽传递。

无可见标签

如果不需要可见标签，开发者仍应提供 aria-label，以便屏幕阅读器可以访问选择器。

单选

默认情况下，选择器允许用户只选择一个选项。警告框界面会向用户展示一个单选按钮样式的选项列表。选择器组件的值接收所选选项的值。

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

多选

通过向选择器添加 multiple 属性，用户可以选择多个选项。当可以选择多个选项时，警告框或弹出框覆盖层会向用户展示一个复选框样式的选项列表。选择器组件的值接收所有所选选项值的数组。

备注

不支持使用 action-sheet 界面进行多选。

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

界面

默认情况下，选择器使用 ion-alert 在警告框中打开选项列表。可以通过向 interface 属性传递 action-sheet 或 popover 来将界面更改为使用 ion-action-sheet 或 ion-popover。请继续阅读其他部分，了解不同界面的限制。

警告框

操作列表

弹出框

响应交互

处理用户与选择器交互的主要方式是 ionChange、ionDismiss 和 ionCancel 事件。有关这些事件以及选择器触发的其他事件的更多详细信息，请参阅事件。

控制台

控制台消息将在上方示例中调用 console.log 时显示在此处。

对象值引用

对选择值使用对象时，如果这些对象来自服务器或数据库，它们的身份可能会发生变化，而所选值的身份保持不变。例如，当具有所需对象值的现有记录被加载到选择器中，但新检索的选择选项现在具有不同的身份时，可能会发生这种情况。这将导致选择器看起来根本没有值，即使原始选择仍然存在。

默认情况下，选择器使用对象相等（===）来确定是否选择了选项。可以通过为 compareWith 属性提供属性名称或函数来覆盖此行为。

使用 compareWith

控制台

控制台消息将在上方示例中调用 console.log 时显示在此处。

对象值和多选

控制台

控制台消息将在上方示例中调用 console.log 时显示在此处。

排列（Justify）

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

填充样式选择器

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

由于 fill 样式在视觉上定义了选择器容器，使用 fill 的选择器不应在 ion-item 中使用。

选择器按钮

警告框支持两个按钮：Cancel 和 OK。每个按钮的文本可以使用 cancelText 和 okText 属性进行自定义。

action-sheet 和 popover 界面没有 OK 按钮，点击任何选项将自动关闭覆盖层并选择该值。popover 界面没有 Cancel 按钮，点击背景遮罩将关闭覆盖层。

界面选项

由于选择器使用警告框、操作列表和弹出框界面，可以通过 interfaceOptions 属性将选项传递给这些组件。这可用于传递自定义头部、副头部、CSS 类等。

请参阅 ion-alert 文档、ion-action-sheet 文档和 ion-popover 文档了解每个界面接受的属性。

注意：interfaceOptions 不会覆盖 alert 界面的 inputs 或 buttons。

开始和结束插槽

start 和 end 插槽可用于在选择器的任一侧放置图标、按钮或前缀/后缀文本。如果点击插槽内容，选择器不会打开。

备注

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

如果插槽内容需要交互，应将其包裹在交互元素中，如按钮。这确保内容可以通过 Tab 键聚焦。

自定义

有两个单元构成 Select 组件，每个需要单独设置样式。ion-select 元素在视图上由所选值（如果没有则为占位符）和下拉图标表示。界面（在界面部分中定义）是点击 ion-select 时打开的对话框。界面包含通过添加 ion-select-option 元素定义的所有选项。以下部分将详细介绍它们之间的样式差异。

样式化选择器元素

如上所述，ion-select 元素仅由值（或占位符）和视图上显示的图标组成。要自定义，请使用 CSS 和任何 CSS 自定义属性的组合进行样式设置。

或者，根据所需的浏览器支持，CSS 阴影部分可用于样式化选择器。请注意，通过使用 ::part，可以定位元素上的任何 CSS 属性。

样式化选择器界面

自定义界面对话框应按照该界面文档中的自定义部分进行：

• 警告框自定义
• 操作列表自定义
• 弹出框自定义

但是，Select Option 确实设置了一个类以便于样式化，并允许将类传递给覆盖层选项，有关自定义选项的用法示例，请参阅选择选项文档。

自定义切换图标

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

图标翻转行为

默认情况下，当选择器打开时，切换图标在 md 模式下会自动旋转，在 ios 模式下保持静态。此行为可以通过 CSS 自定义。

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

输入预测组件

可以使用现有的 Ionic 组件构建输入预测或自动完成功能。我们建议使用 ion-modal 以充分利用可用屏幕空间。

接口

SelectChangeEventDetail

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

SelectCustomEvent

虽然不是必需的，但此接口可以替代 CustomEvent 接口，为此组件发出的 Ionic 事件提供更强的类型支持。

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

从旧版选择器语法迁移

Ionic 7.0 引入了更简单的选择器语法。这种新语法减少了设置选择器所需的样板代码，解决了无障碍访问问题，并改善了开发者体验。

开发者可以逐个迁移每个选择器。虽然开发者可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

使用现代语法包括两个步骤：

1. 移除 ion-label，改用在 ion-select 上使用 label 属性。标签的位置可以使用 ion-select 上的 labelPlacement 属性配置。
2. 将任何 fill 和 shape 的使用从 ion-item 移到 ion-select 上。

JavaScript

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>

Angular

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</ion-select>

React

{/* Label and Label Position */}

{/* Before */}
<IonItem>
  <IonLabel position="floating">Favorite Fruit:</IonLabel>
  <IonSelect>...</IonSelect>
</IonItem>

{/* After */}
<IonItem>
  <IonSelect label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
</IonItem>


{/* Fill */}

{/* Before */}
<IonItem fill="outline" shape="round">
  <IonLabel position="floating">Favorite Fruit:</IonLabel>
  <IonSelect>...</IonSelect>
</IonItem>

{/* After */}

{/* Inputs using `fill` should not be placed in IonItem */}
<IonSelect fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>

Vue

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>

使用旧版语法

Ionic 使用启发式方法检测应用是否在使用现代选择器语法。在某些情况下，继续使用旧版语法可能更可取。开发者可以将 ion-select 上的 legacy 属性设置为 true，以强制该输入实例使用旧版语法。

无障碍访问

键盘交互

Ionic 的键盘交互遵循 web 的实现模式，而不是原生 iOS 选择器，以在所有平台上提供一致的体验。

这些键盘交互适用于满足以下条件的所有 ion-select 元素：

• 选择器已关闭。
• 选择器已聚焦。
• 选择器未禁用。

键	描述
Enter	打开覆盖层并聚焦第一个选中的选项。如果没有选中的选项，则聚焦第一个选项。
Space	打开覆盖层并聚焦第一个选中的选项。如果没有选中的选项，则聚焦第一个选项。

单选

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

这些键盘交互适用于当覆盖层呈现并聚焦时的 ion-action-sheet、ion-alert 和 ion-popover 元素。

键	描述
下箭头	聚焦并选择列表中的下一个选项。如果没有下一个选项，选择将循环到第一个选项。
左箭头	聚焦并选择列表中的上一个选项。如果没有上一个选项，选择将循环到最后一个选项。
右箭头	聚焦并选择列表中的下一个选项。如果没有下一个选项，选择将循环到第一个选项。
上箭头	聚焦并选择列表中的上一个选项。如果没有上一个选项，选择将循环到最后一个选项。
Enter	如果某个选项被聚焦，将选择该选项。没有"OK"按钮的覆盖层将立即提交值，关闭覆盖层并将焦点返回到 ion-select 元素。 如果"OK"按钮被聚焦，将保存用户的选择，关闭覆盖层并将焦点返回到 ion-select 元素。
Escape	关闭覆盖层而不更改已提交的选项。将焦点返回到 ion-select 元素。
Space	如果聚焦的单选按钮未被选中，则取消选中当前选中的单选按钮并选中聚焦的单选按钮。否则，不做任何操作。如果覆盖层没有"OK"按钮，将立即提交值并关闭覆盖层。
Tab	将焦点移动到覆盖层上的下一个可聚焦元素（取消按钮、"OK"按钮、或选择或第一个选项）。如果下一个可聚焦元素是选项，将聚焦选中的选项，否则聚焦第一个选项。

多选

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

这些键盘交互适用于当覆盖层呈现并启用多选时的 ion-alert 和 ion-popover 元素。

键	描述
Enter	当"OK"按钮被聚焦时，将保存用户的选择，关闭覆盖层，并将焦点返回到 ion-select 元素。
Escape	关闭覆盖层而不更改已提交的选项。将焦点返回到 ion-select 元素。
Space	选中或取消选中当前聚焦的选项。这不会取消选中其他选中的选项。如果覆盖层没有"OK"按钮，将立即提交值。
Tab	将焦点移动到覆盖层上的下一个可聚焦元素（取消按钮、"OK"按钮或任何选项）。如果下一个可聚焦元素是选项列表，则应遍历每个选项。

属性

cancelText

说明	The text to display on the cancel button.
属性	cancel-text
类型	string
默认值	'Cancel'

color

说明	The 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.
属性	color
类型	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认值	undefined

compareWith

说明	This 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.
属性	compare-with
类型	((currentValue: any, compareValue: any) => boolean) ｜ null ｜ string ｜ undefined
默认值	undefined

disabled

说明	If true, the user cannot interact with the select.
属性	disabled
类型	boolean
默认值	false

expandedIcon

说明	The 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.
属性	expanded-icon
类型	string ｜ undefined
默认值	undefined

fill

说明	The 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.
属性	fill
类型	"outline" ｜ "solid" ｜ undefined
默认值	undefined

interface

说明	The interface the select should use: action-sheet, popover or alert.
属性	interface
类型	"action-sheet" ｜ "alert" ｜ "popover"
默认值	'alert'

interfaceOptions

说明	Any additional options that the alert, action-sheet or popover interface can take. See the ion-alert docs, the ion-action-sheet docs and the ion-popover docs for the create options for each interface. Note: interfaceOptions will not override inputs or buttons with the alert interface.
属性	interface-options
类型	any
默认值	{}

justify

说明	How 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.
属性	justify
类型	"end" ｜ "space-between" ｜ "start"
默认值	'space-between'

label

说明	The 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.
属性	label
类型	string ｜ undefined
默认值	undefined

labelPlacement

说明	Where 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.
属性	label-placement
类型	"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" ｜ undefined
默认值	'start'

legacy

说明	Set the legacy property to true to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the aria-label attribute or the label property. As a result, the legacy property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
属性	legacy
类型	boolean ｜ undefined
默认值	undefined

mode

说明	The mode determines which platform styles to use. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	mode
类型	"ios" ｜ "md"
默认值	undefined

multiple

说明	If true, the select can accept multiple values.
属性	multiple
类型	boolean
默认值	false

name

说明	The name of the control, which is submitted with the form data.
属性	name
类型	string
默认值	this.inputId

okText

说明	The text to display on the ok button.
属性	ok-text
类型	string
默认值	'OK'

placeholder

说明	The text to display when the select is empty.
属性	placeholder
类型	string ｜ undefined
默认值	undefined

selectedText

说明	The text to display instead of the selected option's value.
属性	selected-text
类型	null ｜ string ｜ undefined
默认值	undefined

shape

说明	The shape of the select. If "round" it will have an increased border radius.
属性	shape
类型	"round" ｜ undefined
默认值	undefined

toggleIcon

说明	The toggle icon to use. Defaults to chevronExpand for ios mode, or caretDownSharp for md mode.
属性	toggle-icon
类型	string ｜ undefined
默认值	undefined

value

说明	The value of the select.
属性	value
类型	any
默认值	undefined

事件

Name	说明	冒泡
ionBlur	Emitted when the select loses focus.	true
ionCancel	Emitted when the selection is cancelled.	true
ionChange	Emitted when the value has changed.	true
ionDismiss	Emitted when the overlay is dismissed.	true
ionFocus	Emitted when the select has focus.	true

方法

open

说明	Open the select overlay. The overlay is either an alert, action sheet, or popover, depending on the interface property on the ion-select.
签名	open(event?: UIEvent) => Promise<any>
参数	event: The user interface event that called the open.

CSS 阴影部分

Name	说明
container	The container for the selected text or placeholder.
icon	The select icon container.
label	The label text describing the select.
placeholder	The text displayed in the select when there is no value.
text	The displayed value of the select.

CSS 自定义属性

Name	说明
--background	Background of the select
--border-color	Color of the select border
--border-radius	Radius 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-style	Style of the select border
--border-width	Width of the select border
--highlight-color-focused	The color of the highlight on the select when focused
--highlight-color-invalid	The color of the highlight on the select when invalid
--highlight-color-valid	The color of the highlight on the select when valid
--padding-bottom	Bottom padding of the select
--padding-end	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the select
--padding-start	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the select
--padding-top	Top padding of the select
--placeholder-color	Color of the select placeholder text
--placeholder-opacity	Opacity of the select placeholder text
--ripple-color	The color of the ripple effect on MD mode.

插槽

Name	说明
end	Content to display at the trailing edge of the select.
label	The 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.
start	Content to display at the leading edge of the select.