版本：v8

ion-select

阴影

选择器是用于从一组选项中选择一个或多个选项的表单控件。当用户点击选择器时，会弹出一个对话框，其中包含所有选项，并以易于选择的列表形式显示。

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

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

单选

默认情况下，选择器只允许用户选择一个选项。警报界面向用户呈现一个带单选按钮样式的选项列表。选择器组件的值接收选定选项的值。

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

多选

通过向选择器添加 multiple 属性，用户可以選擇多個选项。当可以選擇多个选项时，警报、弹出框或模态覆盖层会向用户呈现一个带复选框样式的选项列表。选择器组件的值接收所有选定选项值的数组。

注意

action-sheet 界面不支持多选。

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

界面

默认情况下，选择器使用 ion-alert 在警报中打开选项的覆盖层。可以通过将 action-sheet、popover 或 modal 分别传递给 interface 属性，将界面更改为使用 ion-action-sheet、ion-popover 或 ion-modal。继续阅读其他部分以了解不同界面的限制。

警报

操作表

响应交互

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

控制台

当从上面的示例中记录时，控制台消息将显示在此处。

对象值引用

当使用对象作为选择器值时，如果这些对象来自服务器或数据库，则它们的标识可能会发生变化，而选定值的标识保持不变。例如，这可能发生在将具有所需对象值的现有记录加载到选择器中时，但新检索到的选择器选项现在具有不同的标识。这将导致选择器看起来没有任何值，即使原始选择仍然完好无损。

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

使用 compareWith

控制台

当从上面的示例中记录时，控制台消息将显示在此处。

对象值和多选

控制台

当从上面的示例中记录时，控制台消息将显示在此处。

对齐方式

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

填充选择器

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

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

警告

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

选择器按钮

警报支持两个按钮：取消 和 确定。每个按钮的文本都可以使用 cancelText 和 okText 属性进行自定义。

action-sheet 和 popover 界面没有 确定 按钮，点击任何选项都会自动关闭覆盖层并选择该值。popover 界面没有 取消 按钮，点击遮罩层会关闭覆盖层。

modal 接口的标题中只有一个 关闭 按钮。此按钮仅负责关闭模态框。点击此按钮或使用其他方法关闭模态框后，所有选择都将保留。

接口选项

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

请查看 ion-alert 文档、ion-action-sheet 文档、ion-popover 文档以及 ion-modal 文档，了解每个接口接受的属性。

注意：interfaceOptions 不会覆盖 alert 接口中的 inputs 或 buttons。

开始和结束插槽

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

注意

在大多数情况下，放置在这些插槽中的 Icon 组件应该具有 aria-hidden="true"。有关更多信息，请查看 Icon 可访问性文档。

如果插槽内容旨在进行交互，则应将其包装在交互式元素中，例如 Button。这可以确保内容可以被 Tab 键选中。

自定义

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

设置 Select 元素的样式

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

或者，根据需要的浏览器支持，可以使用 CSS 阴影部件来设置 select 的样式。请注意，使用 ::part，可以定位元素上的任何 CSS 属性。

设置 Select 接口的样式

自定义接口对话框应该通过遵循该接口文档中的样式设置部分（CSS 阴影部件、CSS 自定义属性和插槽）来完成。

但是，Select 选项会设置一个类以简化样式设置，并允许将类传递给叠加选项，请查看 Select 选项文档，了解自定义选项的用法示例。

自定义切换图标

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

图标翻转行为

默认情况下，当 select 打开时，切换图标会在 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;
}

从旧版 Select 语法迁移

Ionic 在 Ionic 7.0 中引入了更简单的 select 语法。此新语法减少了设置 select 所需的样板代码，解决了可访问性问题，并改善了开发人员体验。

开发人员可以一次迁移一个 select。虽然开发人员可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

使用现代语法涉及两个步骤。

删除 ion-label，并在 ion-select 上使用 label 属性。标签的位置可以使用 ion-select 上的 labelPlacement 属性进行配置。
将 ion-item 上 fill 和 shape 的任何用法移动到 ion-select 上。

JavaScript
Angular
React
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>

<!-- 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>

{/* 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>

<!-- 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 使用启发式方法来检测应用程序是否使用现代 select 语法。在某些情况下，可能更愿意继续使用旧版语法。开发人员可以在 ion-select 上设置 legacy 属性为 true，以强制该输入实例使用旧版语法。

可访问性

键盘交互

Ionic 的键盘交互遵循网络的实现模式，而不是原生 iOS select，以确保所有平台上的一致体验。

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

select 已关闭。
select 已获得焦点。
select 未禁用。

键	描述
`Enter`	打开叠加层，并将焦点设置到第一个选定选项。如果没有选定选项，则将焦点设置到第一个选项。
`空格`	打开叠加层，并将焦点设置到第一个选定选项。如果没有选定选项，则将焦点设置到第一个选项。

单选

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

这些键盘交互适用于 ion-action-sheet、ion-alert、ion-popover 和 ion-modal 元素，当叠加层显示并获得焦点时。

键	描述
`向下箭头`	将焦点设置到列表中的下一个选项，并选择它。如果没有下一个选项，则选择将循环到第一个选项。
`向左箭头`	将焦点设置到列表中的上一个选项，并选择它。如果没有上一个选项，则选择将循环到最后一个选项。
`向右箭头`	将焦点设置到列表中的下一个选项，并选择它。如果没有下一个选项，则选择将循环到第一个选项。
`向上箭头`	将焦点设置到列表中的上一个选项，并选择它。如果没有上一个选项，则选择将循环到最后一个选项。
`Enter`	如果选项获得焦点，则会选择该选项。没有 “确定” 按钮的叠加层会立即提交值，关闭叠加层并将焦点返回到 `ion-select` 元素。如果 “确定” 按钮获得焦点，则会保存用户的选择，关闭叠加层并将焦点返回到 `ion-select` 元素。
`Escape`	关闭叠加层，不更改提交的选项。将焦点返回到 `ion-select` 元素。
`空格`	如果获得焦点的单选按钮未选中，则取消选中当前选中的单选按钮，并选中获得焦点的单选按钮。否则，不执行任何操作。如果叠加层没有 “确定” 按钮，则会立即提交值，叠加层会关闭。
`Tab`	将焦点移动到叠加层上的下一个可聚焦元素（取消按钮、“确定” 按钮，或选择或第一个选项）。如果下一个可聚焦元素是选项，则会将焦点设置到选定选项，否则会将焦点设置到第一个选项。

多选

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

这些键盘交互适用于 ion-alert、ion-popover 和 ion-modal 元素，当叠加层显示并启用多选时。

键	描述
`Enter`	当 “确定” 按钮获得焦点时，它会保存用户的选择，关闭叠加层并将焦点返回到 `ion-select` 元素。
`Escape`	关闭叠加层，不更改提交的选项。将焦点返回到 `ion-select` 元素。
`空格`	选中或取消选中当前获得焦点的选项。这不会取消选中其他选定选项。如果叠加层没有 “确定” 按钮，则会立即提交值。
`Tab`	将焦点移动到叠加层上的下一个可聚焦元素（取消按钮、“确定” 按钮，或任何选项）。如果下一个可聚焦元素是选项列表，则它应该迭代每个选项。

属性

cancelText

描述	在取消按钮上显示的文本。
属性	`cancel-text`
类型	`string`
默认值	`'Cancel'`

color

描述	从应用程序调色板中使用的颜色。默认选项为：`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"` 和 `"dark"`。有关颜色的更多信息，请查看主题。此属性仅在使用现代 select 语法时可用。
属性	`color`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
默认值	`undefined`

compareWith

描述	此属性允许开发者在确定 ion-select 中选定选项时，为比较对象指定自定义函数或属性名称。如果未指定，则默认行为将使用严格相等 (===) 进行比较。
属性	`compare-with`
类型	`((currentValue: any, compareValue: any) => boolean) ｜ null ｜ string ｜ undefined`
默认值	`undefined`

disabled

描述	如果为 `true`，则用户无法与 select 交互。
属性	`disabled`
类型	`boolean`
默认值	`false`

expandedIcon

描述	select 打开时显示的切换图标。如果已定义，则在 `md` 模式下的图标旋转行为将被禁用。如果未定义，则 `toggleIcon` 将用于 select 打开和关闭时的图标。
属性	`expanded-icon`
类型	`string ｜ undefined`
默认值	`undefined`

fill

描述	项目的填充。如果为 `"solid"`，则项目将有背景。如果为 `"outline"`，则项目将为透明且带有边框。仅在 `md` 模式下可用。
属性	`fill`
类型	`"outline" ｜ "solid" ｜ undefined`
默认值	`undefined`

interface

描述	select 应使用的界面：`action-sheet`、`popover`、`alert` 或 `modal`。
属性	`interface`
类型	`"action-sheet" ｜ "alert" ｜ "modal" ｜ "popover"`
默认值	`'alert'`

interfaceOptions

描述	`alert`、`action-sheet` 或 `popover` 界面可以接受的任何其他选项。请参阅 ion-alert 文档、ion-action-sheet 文档、ion-popover 文档以及 ion-modal 文档，了解每个界面的创建选项。注意：`interfaceOptions` 不会覆盖 `alert` 接口中的 `inputs` 或 `buttons`。
属性	`interface-options`
类型	`any`
默认值	`{}`

justify

描述	如何在同一行中排列标签和 select。当 `labelPlacement` 设置为 `"floating"` 或 `"stacked"` 时，`justify` 不适用于标签和 select 在不同行上的情况。`"start"`：标签和 select 将在 LTR 中显示在左侧，在 RTL 中显示在右侧。`"end"`：标签和 select 将在 LTR 中显示在右侧，在 RTL 中显示在左侧。`"space-between"`：标签和 select 将显示在行的两端，两元素之间留有间距。
属性	`justify`
类型	`"end" ｜ "space-between" ｜ "start" ｜ undefined`
默认值	`undefined`

label

描述	与 select 关联的可见标签。如果您需要呈现纯文本标签，请使用此属性。如果同时使用 `label` 属性和 `label` 插槽，则 `label` 属性将优先于 `label` 插槽。
属性	`label`
类型	`string ｜ undefined`
默认值	`undefined`

labelPlacement

描述	标签相对于 select 的放置位置。`"start"`：标签将在 LTR 中显示在 select 的左侧，在 RTL 中显示在右侧。`"end"`：标签将在 LTR 中显示在 select 的右侧，在 RTL 中显示在左侧。`"floating"`：当 select 获得焦点或具有值时，标签将显示得更小并在 select 上方显示。否则，它将显示在 select 的顶部。`"stacked"`：无论 select 是否处于模糊状态或没有值，标签都将显示得更小并在 select 上方显示。`"fixed"`：标签的行为与 `"start"` 相同，但它还具有固定宽度。长文本将用省略号 ("...") 截断。当使用 `"floating"` 或 `"stacked"` 时，我们建议使用 `value` 或 `placeholder` 初始化 select。
属性	`label-placement`
类型	`"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" ｜ undefined`
默认值	`'start'`

mode

描述	模式决定使用哪种平台样式。
属性	`mode`
类型	`"ios" ｜ "md"`
默认值	`undefined`

multiple

描述	如果为 `true`，则 select 可以接受多个值。
属性	`multiple`
类型	`boolean`
默认值	`false`

name

描述	控件的名称，与表单数据一起提交。
属性	`name`
类型	`string`
默认值	`this.inputId`

okText

描述	要在确定按钮上显示的文本。
属性	`ok-text`
类型	`string`
默认值	`'OK'`

placeholder

描述	select 为空时显示的文本。
属性	`placeholder`
类型	`string ｜ undefined`
默认值	`undefined`

selectedText

描述	要显示的文本，而不是选定选项的值。
属性	`selected-text`
类型	`null ｜ string ｜ undefined`
默认值	`undefined`

shape

描述	select 的形状。如果为 "round"，则将具有更大的边框半径。
属性	`shape`
类型	`"round" ｜ undefined`
默认值	`undefined`

toggleIcon

描述	要使用的切换图标。对于 `ios` 模式默认为 `chevronExpand`，对于 `md` 模式默认为 `caretDownSharp`。
属性	`toggle-icon`
类型	`string ｜ undefined`
默认值	`undefined`

value

描述	select 的值。
属性	`value`
类型	`any`
默认值	`undefined`

Events

Name	描述	Bubbles
`ionBlur`	select 失去焦点时发出。	`true`
`ionCancel`	选择取消时发出。	`true`
`ionChange`	值更改时发出。以编程方式设置 `value` 属性时，此事件不会发出。	`true`
`ionDismiss`	覆盖层关闭时发出。	`true`
`ionFocus`	select 获得焦点时发出。	`true`

Methods

open

描述	打开 select 覆盖层。覆盖层是警报、操作表或弹出窗口，具体取决于 `ion-select` 上的 `interface` 属性。
Signature	`open(event?: UIEvent) => Promise<any>`

CSS Shadow Parts

Name	描述
`container`	选定文本或占位符的容器。
`icon`	select 图标容器。
`label`	描述 select 的标签文本。
`placeholder`	没有值时在 select 中显示的文本。
`text`	select 的显示值。

CSS Custom Properties

Name	描述
`--background`	select 的背景
`--border-color`	select 边框的颜色
`--border-radius`	select 边框的半径。当使用 fill="outline" 时，较大的半径可能显示不均匀；如果需要，请改用 shape="round" 或增加 --padding-start。
`--border-style`	select 边框的样式
`--border-width`	select 边框的宽度
`--highlight-color-focused`	select 获得焦点时高亮的颜色
`--highlight-color-invalid`	select 无效时高亮的颜色
`--highlight-color-valid`	select 有效时高亮的颜色
`--highlight-height`	select 高亮的高度。仅适用于 md 模式。
`--padding-bottom`	select 底部填充
`--padding-end`	如果方向为从左到右，则为 select 的右侧填充；如果方向为从右到左，则为左侧填充
`--padding-start`	如果方向为从左到右，则为 select 的左侧填充；如果方向为从右到左，则为右侧填充
`--padding-top`	select 顶部填充
`--placeholder-color`	select 占位符文本的颜色
`--placeholder-opacity`	select 占位符文本的不透明度
`--ripple-color`	MD 模式下波纹效果的颜色。

Name	描述
`--background`	select 的背景
`--border-color`	select 边框的颜色
`--border-radius`	select 边框的半径。当使用 fill="outline" 时，较大的半径可能显示不均匀；如果需要，请改用 shape="round" 或增加 --padding-start。
`--border-style`	select 边框的样式
`--border-width`	select 边框的宽度
`--highlight-color-focused`	select 获得焦点时高亮的颜色
`--highlight-color-invalid`	select 无效时高亮的颜色
`--highlight-color-valid`	select 有效时高亮的颜色
`--highlight-height`	select 高亮的高度。仅适用于 md 模式。
`--padding-bottom`	select 底部填充
`--padding-end`	如果方向为从左到右，则为 select 的右侧填充；如果方向为从右到左，则为左侧填充
`--padding-start`	如果方向为从左到右，则为 select 的左侧填充；如果方向为从右到左，则为右侧填充
`--padding-top`	select 顶部填充
`--placeholder-color`	select 占位符文本的颜色
`--placeholder-opacity`	select 占位符文本的不透明度
`--ripple-color`	MD 模式下波纹效果的颜色。

Slots

Name	描述
`end`	在 select 的尾部边缘显示的内容。
`label`	与 select 关联的标签文本。使用 `labelPlacement` 属性来控制标签相对于 select 的放置位置。如果您需要呈现带有自定义 HTML 的标签，请使用此属性。
`start`	在 select 的头部边缘显示的内容。

标签​

标签位置​

标签槽​

无可见标签​

单选​

多选​

界面​

警报​

操作表​

弹出框​

模态​

响应交互​

对象值引用​

使用 compareWith​

对象值和多选​

对齐方式​

填充选择器​

选择器按钮​

接口选项​

开始和结束插槽​

自定义​

设置 Select 元素的样式​

设置 Select 接口的样式​

自定义切换图标​

图标翻转行为​

联想输入组件​

接口​

SelectChangeEventDetail​

SelectCustomEvent​

从旧版 Select 语法迁移​

使用现代语法​

使用旧版语法​

可访问性​

键盘交互​

单选​

多选​

属性​

cancelText​

color​

compareWith​

disabled​

expandedIcon​

fill​

interface​

interfaceOptions​

justify​

label​

labelPlacement​

mode​

multiple​

name​

okText​

placeholder​

selectedText​

shape​

toggleIcon​

value​

Events​

Methods​

open​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

标签

标签位置

标签槽

无可见标签

单选

多选

界面

警报

操作表

弹出框

模态

响应交互

对象值引用

使用 compareWith

对象值和多选

对齐方式

填充选择器

选择器按钮

接口选项

开始和结束插槽

自定义

设置 Select 元素的样式

设置 Select 接口的样式

自定义切换图标

图标翻转行为

联想输入组件

接口

SelectChangeEventDetail

SelectCustomEvent

从旧版 Select 语法迁移

使用现代语法

使用旧版语法

可访问性

键盘交互

单选

多选

属性

cancelText

color

compareWith

disabled

expandedIcon

fill

interface

interfaceOptions

justify

label

labelPlacement

mode

multiple

name

okText

placeholder

selectedText

shape

toggleIcon

value

Events

Methods

open

CSS Shadow Parts

CSS Custom Properties

Slots