ion-alert

scoped

警报是一个向用户提供信息或使用输入从用户那里收集信息的对话框。应用内容顶部会显示警报，用户必须手动将其关闭，然后才能恢复与应用的交互。它还可以选择具有 header、subHeader 和 message。

¥An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a header, subHeader and message.

内联警报（推荐）

¥Inline Alerts (Recommended)

可以通过直接在模板中编写组件来使用 ion-alert。这减少了为了显示警报而需要连接的处理程序的数量。

¥ion-alert can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Alert.

使用 isOpen

¥Using isOpen

ion-alert 上的 isOpen 属性允许开发者从其应用状态控制警报的渲染状态。这意味着当 isOpen 设置为 true 时，将显示警报，而当 isOpen 设置为 false 时，将消除警报。

¥The isOpen property on ion-alert allows developers to control the presentation state of the Alert from their application state. This means when isOpen is set to true the Alert will be presented, and when isOpen is set to false the Alert will be dismissed.

isOpen 使用单向数据绑定，这意味着当警报解除时，它不会自动设置为 false。开发者应该监听 ionAlertDidDismiss 或 didDismiss 事件并将 isOpen 设置为 false。这样做的原因是它阻止了 ion-alert 的内部与应用的状态紧密耦合。通过单向数据绑定，警报只需要关注反应变量提供的布尔值。对于双向数据绑定，警报需要关注布尔值以及反应变量本身的存在。这可能会导致不确定的行为并使应用更难以调试。

¥isOpen uses a one-way data binding, meaning it will not automatically be set to false when the Alert is dismissed. Developers should listen for the ionAlertDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-alert from being tightly coupled with the state of the application. With a one way data binding, the Alert only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Alert needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.

控制器警报

¥Controller Alerts

alertController 可用于需要对何时显示和消除警报进行更多控制的情况。

¥The alertController can be used in situations where more control is needed over when the Alert is presented and dismissed.

按钮

¥Buttons

在 buttons 数组中，每个按钮都包含其 text 的属性，以及可选的 handler。如果处理程序返回 false，则单击按钮时警报不会自动消失。所有按钮都将按照添加到 buttons 数组的顺序从左到右显示。注意：最右边的按钮（数组中的最后一个）是主按钮。

¥In the array of buttons, each button includes properties for its text, and optionally a handler. If a handler returns false then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the buttons array from left to right. Note: The right most button (the last one in the array) is the main button.

或者，可以将 role 属性添加到按钮，例如 cancel。如果 cancel 角色位于其中一个按钮上，那么如果通过点击背景解除警报，那么它将通过具有取消角色的按钮触发处理程序。

¥Optionally, a role property can be added to a button, such as cancel. If a cancel role is on one of the buttons, then if the alert is dismissed by tapping the backdrop, then it will fire the handler from the button with a cancel role.

Console

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

输入

¥Inputs

警报还可以包括多个不同的输入，其数据可以传回应用。输入可以用作提示用户信息的简单方法。单选框、复选框和文本输入都可以接受，但不能混合使用。例如，警报可以具有所有单选按钮输入或所有复选框输入，但同一警报不能混合单选按钮输入和复选框输入。但请注意，不同类型的 "text" 输入可以混合使用，例如 url、email、text、textarea 等。如果你需要不符合警报准则的复杂表单 UI，那么我们建议在 改为模态。

¥Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as url, email, text, textarea etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead.

文本输入示例

¥Text Inputs Example

单选框示例

¥Radio Example

定制化

¥Customization

Alert 使用范围封装，这意味着它将通过在运行时为每个样式附加一个附加类来自动确定其 CSS 范围。覆盖 CSS 中的作用域选择器需要 更高的特异性 选择器。

¥Alert uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector.

我们建议在 create 方法中将自定义类传递给 cssClass，并使用它向宿主元素和内部元素添加自定义样式。此属性还可以接受用空格分隔的多个类。

¥We recommend passing a custom class to cssClass in the create method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces.

/* DOES NOT WORK - not specific enough */
.alert-wrapper {
  background: #e5e5e5;
}

/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .alert-wrapper {
  background: #e5e5e5;
}

任何定义的 CSS 自定义属性 都可用于设置警报样式，而无需针对单个元素：

¥Any of the defined CSS Custom Properties can be used to style the Alert without needing to target individual elements:

.my-custom-class {
  --background: #e5e5e5;
}

注意

如果你正在构建 Ionic Angular 应用，则需要将样式添加到全局样式表文件中。

¥If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

无障碍

¥Accessibility

屏幕阅读器

¥Screen Readers

警报设置 aria 属性，以便对屏幕阅读器来说是 accessible，但如果这些属性描述性不够，或者与警报在应用中的使用方式不一致，则可以覆盖这些属性。

¥Alerts set aria properties in order to be accessible to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the alert is being used in an app.

角色

¥Role

如果包含任何输入或按钮，Ionic 会自动将警报的 role 设置为 alertdialog；如果没有，则自动将警报的 role 设置为 alert。

¥Ionic automatically sets the Alert's role to either alertdialog if there are any inputs or buttons included, or alert if there are none.

警报说明

¥Alert Description

如果为警报定义了 header 属性，则 aria-labelledby 属性将自动设置为标头的 ID。如果未定义 header，则 subHeader 元素将用作后备元素。同样，如果定义了该属性，则 aria-describedby 属性将自动设置为 message 元素的 ID。

¥If the header property is defined for the Alert, the aria-labelledby attribute will be automatically set to the header's ID. The subHeader element will be used as a fallback if header is not defined. Similarly, the aria-describedby attribute will be automatically set to the ID of the message element if that property is defined.

强烈建议你的警报具有 message，以及 header 或 subHeader，以便与 ARIA 规范保持一致。如果你选择不包含 header 或 subHeader，另一种方法是使用 htmlAttributes 属性提供描述性 aria-label。

¥It is strongly recommended that your Alert have a message, as well as either a header or subHeader, in order to align with the ARIA spec. If you choose not to include a header or subHeader, an alternative is to provide a descriptive aria-label using the htmlAttributes property.

Angular

const alert = await this.alertController.create({
  message: 'This is an alert with custom aria attributes.',
  htmlAttributes: {
    'aria-label': 'alert dialog',
  },
});

Javascript

const alert = await this.alertController.create({
  message: 'This is an alert with custom aria attributes.',
  htmlAttributes: {
    'aria-label': 'alert dialog',
  },
});

React

useIonAlert({
  message: 'This is an alert with custom aria attributes.',
  htmlAttributes: {
    'aria-label': 'alert dialog',
  },
});

Vue

const alert = await alertController.create({
  message: 'This is an alert with custom aria attributes.',
  htmlAttributes: {
    'aria-label': 'alert dialog',
  },
});

通过在警报的 htmlAttributes 属性中定义自定义值，可以手动覆盖所有 ARIA 属性。

¥All ARIA attributes can be manually overwritten by defining custom values in the htmlAttributes property of the Alert.

警报按钮说明

¥Alert Buttons Description

包含文本的按钮将由屏幕阅读器读取。如果需要现有文本以外的描述，可以通过将 aria-label 传递到按钮上的 htmlAttributes 属性来在按钮上设置标签。

¥Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be set on the button by passing aria-label to the htmlAttributes property on the button.

Angular

const alert = await this.alertController.create({
  header: 'Header',
  buttons: [
    {
      text: 'Exit',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

Javascript

const alert = await this.alertController.create({
  header: 'Header',
  buttons: [
    {
      text: 'Exit',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

React

useIonAlert({
  header: 'Header',
  buttons: [
    {
      text: 'Exit',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

Vue

const alert = await alertController.create({
  header: 'Header',
  buttons: [
    {
      text: 'Exit',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

接口

¥Interfaces

AlertButton

type AlertButtonOverlayHandler = boolean | void | { [key: string]: any };

interface AlertButton {
  text: string;
  role?: 'cancel' | 'destructive' | string;
  cssClass?: string | string[];
  id?: string;
  htmlAttributes?: { [key: string]: any };
  handler?: (value: any) => AlertButtonOverlayHandler | Promise<AlertButtonOverlayHandler>;
}

AlertInput

interface AlertInput {
  type?: TextFieldTypes | 'checkbox' | 'radio' | 'textarea';
  name?: string;
  placeholder?: string;
  value?: any;
  /**

   * The label text to display next to the input, if the input type is `radio` or `checkbox`.
   */
  label?: string;
  checked?: boolean;
  disabled?: boolean;
  id?: string;
  handler?: (input: AlertInput) => void;
  min?: string | number;
  max?: string | number;
  cssClass?: string | string[];
  attributes?: { [key: string]: any };
  tabindex?: number;
}

AlertOptions

interface AlertOptions {
  header?: string;
  subHeader?: string;
  message?: string | IonicSafeString;
  cssClass?: string | string[];
  inputs?: AlertInput[];
  buttons?: (AlertButton | string)[];
  backdropDismiss?: boolean;
  translucent?: boolean;
  animated?: boolean;
  htmlAttributes?: { [key: string]: any };

  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

属性

¥Properties

animated

Description	If true, the alert will animate.
Attribute	animated
Type	boolean
Default	true

backdropDismiss

Description	If true, the alert will be dismissed when the backdrop is clicked.
Attribute	backdrop-dismiss
Type	boolean
Default	true

buttons

Description	Array of buttons to be added to the alert.
Attribute	undefined
Type	(string ｜ AlertButton)[]
Default	[]

cssClass

Description	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attribute	css-class
Type	string ｜ string[] ｜ undefined
Default	undefined

enterAnimation

Description	Animation to use when the alert is presented.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

header

Description	The main title in the heading of the alert.
Attribute	header
Type	string ｜ undefined
Default	undefined

htmlAttributes

Description	Additional attributes to pass to the alert.
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

inputs

Description	Array of input to show in the alert.
Attribute	undefined
Type	AlertInput[]
Default	[]

isOpen

Description	If true, the alert will open. If false, the alert will close. Use this if you need finer grained control over presentation, otherwise just use the alertController or the trigger property. Note: isOpen will not automatically be set back to false when the alert dismisses. You will need to do that in your code.
Attribute	is-open
Type	boolean
Default	false

keyboardClose

Description	If true, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	keyboard-close
Type	boolean
Default	true

leaveAnimation

Description	Animation to use when the alert is dismissed.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

message

Description	The main message to be displayed in the alert. message can accept either plaintext or HTML as a string. To display characters normally reserved for HTML, they must be escaped. For example <Ionic> would become &lt;Ionic&gt; For more information: Security Documentation This property accepts custom HTML as a string. Content is parsed as plaintext by default. innerHTMLTemplatesEnabled must be set to true in the Ionic config before custom HTML can be used.
Attribute	message
Type	IonicSafeString ｜ string ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

subHeader

Description	The subtitle in the heading of the alert. Displayed under the title.
Attribute	sub-header
Type	string ｜ undefined
Default	undefined

translucent

Description	If true, the alert will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.
Attribute	translucent
Type	boolean
Default	false

trigger

Description	An ID corresponding to the trigger element that causes the alert to open when clicked.
Attribute	trigger
Type	string ｜ undefined
Default	undefined

事件

¥Events

Name	Description	Bubbles
didDismiss	Emitted after the alert has dismissed. Shorthand for ionAlertDidDismiss.	true
didPresent	Emitted after the alert has presented. Shorthand for ionAlertWillDismiss.	true
ionAlertDidDismiss	Emitted after the alert has dismissed.	true
ionAlertDidPresent	Emitted after the alert has presented.	true
ionAlertWillDismiss	Emitted before the alert has dismissed.	true
ionAlertWillPresent	Emitted before the alert has presented.	true
willDismiss	Emitted before the alert has dismissed. Shorthand for ionAlertWillDismiss.	true
willPresent	Emitted before the alert has presented. Shorthand for ionAlertWillPresent.	true

方法

¥Methods

dismiss

Description	Dismiss the alert overlay after it has been presented.
Signature	dismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss

Description	Returns a promise that resolves when the alert did dismiss.
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	Returns a promise that resolves when the alert will dismiss.
Signature	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description	Present the alert overlay after it has been created.
Signature	present() => Promise<void>

CSS 阴影部分

¥CSS Shadow Parts

No CSS shadow parts available for this component.

CSS 自定义属性

¥CSS Custom Properties

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the alert
--height	Height of the alert
--max-height	Maximum height of the alert
--max-width	Maximum width of the alert
--min-height	Minimum height of the alert
--min-width	Minimum width of the alert
--width	Width of the alert

插槽

¥Slots

No slots available for this component.