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 可以通过在模板中直接编写组件来使用。这减少了你需要连接的处理程序数量，从而渲染警报。

使用 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 的内部实现与应用状态紧密耦合。使用单向数据绑定时，警报只需关心响应式变量提供的布尔值。使用双向数据绑定时，警报不仅需要关心布尔值，还需要关心响应式变量本身的存在。这可能导致非确定性行为，并使应用更难调试。

控制器警报

🌐 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

提醒也可以包含几种不同的输入，其数据可以传回应用。输入可以作为提示用户提供信息的一种简单方式。接受单选按钮、复选框和文本输入，但它们不能混合使用。例如，一个提醒可以全部为单选按钮输入，或全部为复选框输入，但同一个提醒不能混合单选按钮和复选框输入。不过，请注意，不同类型的“文本”输入可以混合使用，如 url、email、text、textarea 等。如果你需要一个复杂的表单界面，而该表单不符合提醒的指南，我们建议将表单放在模态窗口中构建。

🌐 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;
}

note

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

无障碍

🌐 Accessibility

屏幕阅读器

🌐 Screen Readers

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

🌐 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；如果没有，则设置为 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

如果为 Alert 定义了 header 属性，则 aria-labelledby 属性将自动设置为 header 的 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.

强烈建议你的 Alert 包含 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',
  },
});

所有 ARIA 属性都可以通过在 Alert 的 htmlAttributes 属性中定义自定义值来手动覆盖。

🌐 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. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
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. This is a no-op if the overlay has not been presented yet. If you want to remove an overlay from the DOM that was never presented, use the remove method.
Signature	dismiss(data?: any, role?: string) => Promise<boolean>
Parameters	data: Any data to emit in the dismiss events. role: The role of the element that is dismissing the alert. This can be useful in a button handler for determining which button was clicked to dismiss the alert. Some examples include: "cancel", "destructive", "selected", and "backdrop".

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

iOS

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

MD

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.