跳到主要內容
版本：v8

ion-alert

範圍

警告是一個對話方塊，會向使用者呈現資訊或使用輸入從使用者收集資訊。警告會顯示在應用程式內容的上方，並且必須由使用者手動關閉，他們才能恢復與應用程式的互動。它也可以選擇性地具有 header、subHeader 和 message。

可以透過直接在範本中寫入元件來使用 ion-alert。這會減少您需要連線以呈現警告的處理常式數量。

使用 isOpen​

ion-alert 上的 isOpen 屬性可讓開發人員從應用程式狀態控制警告的呈現狀態。這表示當 isOpen 設定為 true 時，將會呈現警告，而當 isOpen 設定為 false 時，將會關閉警告。

isOpen 使用單向資料繫結，這表示當關閉警告時，它不會自動設定為 false。開發人員應該監聽 ionAlertDidDismiss 或 didDismiss 事件，並將 isOpen 設定為 false。這樣做的原因是它可以防止 ion-alert 的內部與應用程式的狀態緊密耦合。使用單向資料繫結，警告只需要關心反應變數提供的布林值。使用雙向資料繫結，警告需要關心布林值以及反應變數本身的存在。這可能會導致非決定性的行為，並使應用程式更難以偵錯。

控制器警告​

當需要更多控制來決定何時呈現和關閉警告時，可以使用 alertController。

按鈕​

在 buttons 陣列中，每個按鈕都包含其 text 的屬性，並且可以選擇性地包含 handler。如果處理常式傳回 false，則在按一下按鈕時，警告將不會自動關閉。所有按鈕都會以它們已新增至 buttons 陣列的順序從左到右顯示。注意：最右邊的按鈕（陣列中的最後一個）是主要按鈕。

可以選擇性地將 role 屬性新增至按鈕，例如 cancel。如果其中一個按鈕上有 cancel 角色，則如果透過點擊背景關閉警告，則會從具有取消角色的按鈕觸發處理常式。

主控台
從上面的範例記錄時，主控台訊息將會顯示在此處。

輸入​

警告也可以包含多種不同的輸入，其資料可以傳回至應用程式。輸入可以用作提示使用者輸入資訊的簡單方式。接受單選按鈕、核取方塊和文字輸入，但它們不能混合。例如，警告可以具有所有單選按鈕輸入，或所有核取方塊輸入，但同一個警告不能混合單選和核取方塊輸入。但是，請注意，不同類型的「文字」輸入可以混合，例如 url、email、text、textarea 等。如果您需要不符合警告指南的複雜表單 UI，則建議您在模式中建置表單。

文字輸入範例​

單選範例​

自訂​

警告使用範圍封裝，這表示它會在執行時間自動透過將每個樣式附加額外的類別來設定其 CSS 的範圍。覆寫 CSS 中的範圍選取器需要具有更高優先順序的選取器。

建議在 create 方法中將自訂類別傳遞給 cssClass，並使用它將自訂樣式新增至主機和內部元素。此屬性也可以接受以空格分隔的多個類別。

/* 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 自訂屬性來設定警告的樣式，而無需針對個別元素。

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

如果您正在建置 Ionic Angular 應用程式，則樣式需要新增至全域樣式表檔案。

協助工具​

螢幕助讀程式​

警告會設定 aria 屬性，以便對螢幕助讀程式提供協助工具，但是如果這些屬性的描述性不足或與應用程式中使用警告的方式不一致，則可以覆寫這些屬性。

角色​

如果包含任何輸入或按鈕，則 Ionic 會自動將警告的 role 設定為alertdialog，如果沒有，則會設定為alert。

警告描述​

如果為警告定義了 header 屬性，則 aria-labelledby 屬性將會自動設定為標頭的 ID。如果未定義 header，則 subHeader 元素將會用作後備。同樣地，如果已定義該屬性，則 aria-describedby 屬性將會自動設定為 message 元素的 ID。

強烈建議您的警告具有 message 以及 header 或 subHeader，以便與 ARIA 規範一致。如果您選擇不包含 header 或 subHeader，則另一種方法是使用 htmlAttributes 屬性提供描述性的 aria-label。

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

所有 ARIA 屬性都可以透過在警告的 htmlAttributes 屬性中定義自訂值來手動覆寫。

警告按鈕描述​

螢幕助讀程式會讀取包含文字的按鈕。如果需要文字以外的描述，可以透過將 aria-label 傳遞給按鈕上的 htmlAttributes 屬性，在按鈕上設定標籤。

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

介面​

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

屬性​

animated​

描述若為 true，則警示視窗會有動畫效果。
屬性animated
類型boolean
預設值true

backdropDismiss​

描述若為 true，當點擊背景幕時，警示視窗會關閉。
屬性backdrop-dismiss
類型boolean
預設值true

buttons​

描述要添加到警示視窗的按鈕陣列。
屬性undefined
類型(string ｜ AlertButton)[]
預設值[]

cssClass​

描述要套用的額外 CSS 類別。如果提供多個類別，它們應該以空格分隔。
屬性css-class
類型string ｜ string[] ｜ undefined
預設值undefined

enterAnimation​

描述警示視窗顯示時使用的動畫。
屬性undefined
類型((baseEl: any, opts?: any) => Animation) ｜ undefined
預設值undefined
描述警示視窗標頭中的主要標題。
屬性header
類型string ｜ undefined
預設值undefined

htmlAttributes​

描述要傳遞給警示視窗的額外屬性。
屬性undefined
類型undefined ｜ { [key: string]: any; }
預設值undefined

inputs​

描述要顯示在警示視窗中的輸入欄位陣列。
屬性undefined
類型AlertInput[]
預設值[]

isOpen​

描述若為 true，則警示視窗將開啟。若為 false，則警示視窗將關閉。如果您需要對呈現進行更精細的控制，請使用此屬性，否則只需使用警示控制器或 trigger 屬性。請注意：當警示視窗關閉時，isOpen 不會自動設定回 false。您需要在程式碼中執行此操作。
屬性is-open
類型boolean
預設值false

keyboardClose​

描述若為 true，當覆蓋層顯示時，鍵盤將自動關閉。
屬性keyboard-close
類型boolean
預設值true

leaveAnimation​

描述警示視窗關閉時使用的動畫。
屬性undefined
類型((baseEl: any, opts?: any) => Animation) ｜ undefined
預設值undefined

message​

描述要在警示視窗中顯示的主要訊息。message 可以接受純文字或 HTML 字串。要顯示 HTML 中通常保留的字元，必須進行跳脫。例如，<Ionic> 將變成 &lt;Ionic&gt;

如需更多資訊：安全性文件

此屬性接受自訂 HTML 字串。預設情況下，內容會被解析為純文字。必須在 Ionic 設定中將 innerHTMLTemplatesEnabled 設定為 true，才能使用自訂 HTML。
屬性message
類型IonicSafeString ｜ string ｜ undefined
預設值undefined

mode​

描述模式決定要使用的平台樣式。
屬性mode
類型"ios" ｜ "md"
預設值undefined

subHeader​

描述警示視窗標頭中的副標題。顯示在標題下方。
屬性sub-header
類型string ｜ undefined
預設值undefined

translucent​

描述若為 true，則警示視窗將為半透明。僅在模式為 "ios" 且裝置支援 backdrop-filter 時適用。
屬性translucent
類型boolean
預設值false

trigger​

描述與觸發元素對應的 ID，當點擊該元素時會導致警示視窗開啟。
屬性trigger
類型string ｜ undefined
預設值undefined

事件​

名稱描述冒泡
didDismiss在警示視窗關閉後發出。是 ionAlertDidDismiss 的簡寫。true
didPresent在警示視窗顯示後發出。是 ionAlertWillDismiss 的簡寫。true
ionAlertDidDismiss在警示視窗關閉後發出。true
ionAlertDidPresent在警示視窗顯示後發出。true
ionAlertWillDismiss在警示視窗關閉前發出。true
ionAlertWillPresent在警示視窗顯示前發出。true
willDismiss在警示視窗關閉前發出。是 ionAlertWillDismiss 的簡寫。true
willPresent在警示視窗顯示前發出。是 ionAlertWillPresent 的簡寫。true

方法​

dismiss​

描述在警示視窗顯示後關閉它。
簽名dismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss​

描述返回一個在警示視窗關閉後解析的 Promise。
簽名onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss​

描述返回一個在警示視窗即將關閉時解析的 Promise。
簽名onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present​

描述在建立警示視窗後顯示它。
簽名present() => Promise<void>

CSS 陰影部分​

此元件沒有可用的 CSS 陰影部分。

CSS 自訂屬性​

名稱描述
--backdrop-opacity背景幕的不透明度
--background警示視窗的背景
--height警示視窗的高度
--max-height警示視窗的最大高度
--max-width警示視窗的最大寬度
--min-height警示視窗的最小高度
--min-width警示視窗的最小寬度
--width警示視窗的寬度

插槽​

此元件沒有可用的插槽。

目錄

編輯此頁面