版本：v8

ion-toast

快顯通知是現代應用程式中常用的細微通知。它可以用來提供有關操作的回饋或顯示系統訊息。快顯通知會顯示在應用程式內容之上，並且可以由應用程式關閉，以恢復使用者與應用程式的互動。

內聯快顯通知（建議）

可以直接在您的範本中編寫元件來使用 ion-toast。這減少了為了呈現快顯通知而需要連接的處理常式數量。

使用 `isOpen`

ion-toast 上的 isOpen 屬性允許開發人員從應用程式狀態控制快顯通知的呈現狀態。這表示當 isOpen 設定為 true 時，將會呈現快顯通知；而當 isOpen 設定為 false 時，將會關閉快顯通知。

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

控制器快顯通知

關閉

快顯通知旨在作為細微的通知，不應打斷使用者。因此，不應要求使用者互動來關閉快顯通知。

快顯通知可以在特定的時間量後自動關閉，方法是在快顯通知選項的 duration 中傳遞要顯示的毫秒數。如果新增了角色為 "cancel" 的按鈕，則該按鈕將關閉快顯通知。若要在建立後關閉快顯通知，請在執行個體上呼叫 dismiss() 方法。

按下硬體返回按鈕不會關閉快顯通知，因為它們不應打斷使用者。

以下範例示範如何使用 buttons 屬性來新增一個按鈕，該按鈕在按一下時會自動關閉快顯通知，以及如何收集關閉事件的 role。

主控台

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

定位

快顯通知可以定位在視窗的頂部、底部或中間。位置可以在建立時傳遞。可能的值為 top、bottom 和 middle。如果未指定位置，快顯通知將顯示在視窗的底部。

相對定位

如果快顯通知與導覽元素（例如頁首、頁尾或 FAB）一起呈現，則快顯通知預設可能會重疊這些元素。這可以使用 positionAnchor 屬性來修正，該屬性採用元素參考或 ID。快顯通知將相對於所選元素定位，當使用 position="top" 時會顯示在其下方，或當使用 position="bottom" 時會顯示在其上方。當使用 position="middle" 時，會忽略 positionAnchor 屬性。

滑動以關閉

可以使用 swipeGesture 屬性滑動以關閉快顯通知。此功能會感知位置，這表示使用者需要滑動的方向將根據 position 屬性的值而變更。此外，使用者需要滑動的距離可能會受到 positionAnchor 屬性的影響。

版面配置

快顯通知內的按鈕容器可以使用 layout 屬性顯示在與訊息相同的行上，或是堆疊在不同的行上。堆疊的版面配置應與具有長文字值的按鈕一起使用。此外，堆疊的快顯通知版面配置中的按鈕可以使用 side 值 start 或 end，但不能同時使用兩者。

圖示

可以在快顯通知內內容的旁邊新增圖示。一般而言，快顯通知中的圖示應用於新增其他樣式或內容，而不是為了吸引使用者的注意或提高快顯通知的優先順序。如果您希望向使用者傳達更高優先順序的訊息或保證回應，我們建議改為使用警示。

主題設定

協助工具

焦點管理

快顯通知旨在作為細微的通知，不應打斷使用者。不應要求使用者互動來關閉快顯通知。因此，當呈現快顯通知時，焦點不會自動移至快顯通知。

螢幕閱讀器

快顯通知會設定 aria 屬性，以便對螢幕閱讀器可存取，但如果這些屬性不夠描述性或與快顯通知在應用程式中的使用方式不一致，則可以覆寫這些屬性。

角色

ion-toast 內部 .toast-content 元素設定了 role="status" 和 aria-live="polite"。這會導致螢幕閱讀器僅宣告 toast 訊息和標頭。當 toast 顯示時，按鈕和圖示不會被宣告。

aria-live 會讓螢幕閱讀器在 toast 內容更新時宣告該內容。然而，由於屬性設定為 'polite'，螢幕閱讀器不應中斷當前任務。

由於 toast 的目的是作為不顯眼的通知，因此 aria-live 絕不應設定為 "assertive"。如果開發人員需要使用重要訊息中斷使用者，建議使用警示框。

Toast 按鈕說明

當螢幕閱讀器與包含文字的按鈕互動時，螢幕閱讀器會讀取這些按鈕。如果按鈕僅包含圖示，或需要與現有文字不同的描述，則應將標籤分配給按鈕，方法是將 aria-label 傳遞給按鈕的 htmlAttributes 屬性。

Angular
Javascript
React
Vue

const toast = await this.toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const toast = await this.toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

useIonToast({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const toast = await toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

提示

雖然這不是完整的列表，但以下是一些使用 toast 時應遵循的準則。

不需要使用者互動來關閉 toast。例如，在 toast 中有一個「關閉」按鈕是可以的，但 toast 也應在逾時一段時間後自動關閉。如果通知需要使用者互動，請考慮改用警示框。
對於包含長訊息的 toast，請考慮調整 duration 屬性，讓使用者有足夠的時間閱讀 toast 的內容。
如果要在 toast 中新增按鈕，請務必提供其他方法來完成與每個按鈕相關聯的動作。這可確保即使 toast 在使用者讀取之前關閉，他們仍然可以完成 toast 中顯示的動作。
避免從另一個覆蓋層（例如模式視窗）內部顯示帶有按鈕的 toast。模式視窗和其他覆蓋層會實作焦點捕獲，這會阻止螢幕閱讀器將焦點移動到 toast 以完成動作。這可能會讓使用者感到困惑，因為螢幕閱讀器仍然會宣告 toast。即使實作了與每個按鈕相關聯的動作的其他完成方式，也是如此。請考慮在焦點捕獲的模式視窗中建立一個即時區域，而不是使用 toast。

介面

ToastButton

interface ToastButton {
  text?: string;
  icon?: string;
  side?: 'start' | 'end';
  role?: 'cancel' | string;
  cssClass?: string | string[];
  htmlAttributes?: { [key: string]: any };
  handler?: () => boolean | void | Promise<boolean | void>;
}

ToastOptions

interface ToastOptions {
  header?: string;
  message?: string | IonicSafeString;
  cssClass?: string | string[];
  duration?: number;
  buttons?: (ToastButton | string)[];
  position?: 'top' | 'bottom' | 'middle';
  translucent?: boolean;
  animated?: boolean;
  icon?: string;
  htmlAttributes?: { [key: string]: any };

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

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

屬性

animated

說明	如果為 `true`，則 toast 將會動態顯示。
屬性	`animated`
類型	`boolean`
預設值	`true`

buttons

說明	toast 的按鈕陣列。
屬性	`undefined`
類型	`(string ｜ ToastButton)[] ｜ undefined`
預設值	`undefined`

color

說明	要從應用程式的調色盤中使用的顏色。預設選項為：`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"` 和 `"dark"`。有關顏色的詳細資訊，請參閱主題。
屬性	`color`
類型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
預設值	`undefined`

cssClass

說明	要應用於自訂 CSS 的其他類別。如果提供多個類別，則應以空格分隔。
屬性	`css-class`
類型	`string ｜ string[] ｜ undefined`
預設值	`undefined`

duration

說明	在隱藏 toast 之前要等待的毫秒數。預設情況下，它會顯示直到呼叫 `dismiss()` 為止。
屬性	`duration`
類型	`number`
預設值	`config.getNumber('toastDuration', 0)`

enterAnimation

說明	在顯示 toast 時使用的動畫。
屬性	`undefined`
類型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
預設值	`undefined`

說明	要在 toast 中顯示的標頭。
屬性	`header`
類型	`string ｜ undefined`
預設值	`undefined`

htmlAttributes

說明	要傳遞給 toast 的其他屬性。
屬性	`undefined`
類型	`undefined ｜ { [key: string]: any; }`
預設值	`undefined`

icon

說明	要顯示的圖示名稱，或有效 SVG 檔案的路徑。請參閱 `ion-icon`。https://ionic.io/ionicons
屬性	`icon`
類型	`string ｜ undefined`
預設值	`undefined`

isOpen

說明	如果為 `true`，則會開啟 toast。如果為 `false`，則會關閉 toast。如果需要更精細地控制顯示，請使用此屬性，否則只需使用 toastController 或 `trigger` 屬性。注意：當 toast 關閉時，`isOpen` 不會自動設回 `false`。您需要在程式碼中執行此操作。
屬性	`is-open`
類型	`boolean`
預設值	`false`

keyboardClose

說明	如果為 `true`，則會在顯示覆蓋層時自動關閉鍵盤。
屬性	`keyboard-close`
類型	`boolean`
預設值	`false`

layout

說明	定義訊息和按鈕在 toast 中的版面配置方式。「baseline」：訊息和按鈕將會顯示在同一行上。訊息文字可能會在訊息容器內換行。「stacked」：按鈕容器和訊息將會堆疊在一起。如果按鈕中有長文字，請使用此選項。
屬性	`layout`
類型	`"baseline" ｜ "stacked"`
預設值	`'baseline'`

leaveAnimation

說明	在關閉 toast 時使用的動畫。
屬性	`undefined`
類型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
預設值	`undefined`

message

說明	要在 toast 中顯示的訊息。此屬性接受自訂 HTML 作為字串。預設情況下，內容會剖析為純文字。必須先在 Ionic 設定中將 `innerHTMLTemplatesEnabled` 設定為 `true`，才能使用自訂 HTML。
屬性	`message`
類型	`IonicSafeString ｜ string ｜ undefined`
預設值	`undefined`

mode

說明	模式決定要使用哪個平台樣式。
屬性	`mode`
類型	`"ios" ｜ "md"`
預設值	`undefined`

position

說明	toast 在螢幕上的起始位置。可以使用 `positionAnchor` 屬性進一步調整。
屬性	`position`
類型	`"bottom" ｜ "middle" ｜ "top"`
預設值	`'bottom'`

positionAnchor

說明	要將 toast 位置錨定到的元素。可以設定為直接參考或元素的 ID。使用 `position="bottom"` 時，toast 會位於所選元素的上方。使用 `position="top"` 時，toast 會位於所選元素的下方。使用 `position="middle"` 時，會忽略 `positionAnchor` 的值。
屬性	`position-anchor`
類型	`HTMLElement ｜ string ｜ undefined`
預設值	`undefined`

swipeGesture

說明	如果設定為 'vertical'，則可以使用滑動手勢關閉 Toast。滑動方向由 `position` 屬性的值決定：`top`：可以向上滑動以關閉 Toast。`bottom`：可以向下滑動以關閉 Toast。`middle`：可以向上或向下滑動以關閉 Toast。
屬性	`swipe-gesture`
類型	`"vertical" ｜ undefined`
預設值	`undefined`

translucent

說明	如果為 `true`，則 toast 將會是半透明的。僅適用於模式為 `"ios"` 且裝置支援`backdrop-filter`時。
屬性	`translucent`
類型	`boolean`
預設值	`false`

trigger

說明	對應於觸發元素的 ID，當點擊時會導致開啟 toast。
屬性	`trigger`
類型	`string ｜ undefined`
預設值	`undefined`

事件

名稱	說明	冒泡
`didDismiss`	在 toast 關閉後發出。`ionToastDidDismiss` 的簡寫。	`true`
`didPresent`	在 toast 顯示後發出。`ionToastWillDismiss` 的簡寫。	`true`
`ionToastDidDismiss`	在 toast 關閉後發出。	`true`
`ionToastDidPresent`	在 toast 顯示後發出。	`true`
`ionToastWillDismiss`	在 toast 關閉之前發出。	`true`
`ionToastWillPresent`	在 toast 顯示之前發出。	`true`
`willDismiss`	在 toast 關閉之前發出。`ionToastWillDismiss` 的簡寫。	`true`
`willPresent`	在 toast 顯示之前發出。`ionToastWillPresent` 的簡寫。	`true`

方法

dismiss

說明	在顯示 toast 覆蓋層後將其關閉。
簽名	`dismiss(data?: any, role?: string) => Promise<boolean>`

onDidDismiss

說明	傳回在 toast 關閉時解析的 Promise。
簽名	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

說明	傳回在 toast 即將關閉時解析的 Promise。
簽名	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

說明	在建立 toast 覆蓋層後將其顯示。
簽名	`present() => Promise<void>`

CSS 陰影部分

名稱	說明
`button`	顯示在 toast 內部的任何按鈕元素。
`button cancel`	顯示在 toast 內部的任何具有角色「cancel」的按鈕元素。
`container`	包裝所有子元素的元素。
`header`	toast 的標頭文字。
`icon`	顯示在 toast 內容旁邊的圖示。
`message`	toast 的主體文字。

CSS 自訂屬性

名稱	說明
`--background`	toast 的背景
`--border-color`	toast 的邊框顏色
`--border-radius`	toast 的邊框圓角
`--border-style`	toast 的邊框樣式
`--border-width`	toast 的邊框寬度
`--box-shadow`	toast 的陰影
`--button-color`	按鈕文字的顏色
`--color`	toast 文字的顏色
`--end`	如果方向為從左到右，則為從右邊開始的位置，如果方向為從右到左，則為從左邊開始的位置
`--height`	toast 的高度
`--max-height`	toast 的最大高度
`--max-width`	toast 的最大寬度
`--min-height`	Toast 的最小高度
`--min-width`	Toast 的最小寬度
`--start`	如果方向是從左到右，則為從左側開始的位置；如果方向是從右到左，則為從右側開始的位置
`--white-space`	Toast 訊息的空白處理
`--width`	Toast 的寬度

名稱	說明
`--background`	toast 的背景
`--border-color`	toast 的邊框顏色
`--border-radius`	toast 的邊框圓角
`--border-style`	toast 的邊框樣式
`--border-width`	toast 的邊框寬度
`--box-shadow`	toast 的陰影
`--button-color`	按鈕文字的顏色
`--color`	toast 文字的顏色
`--end`	如果方向為從左到右，則為從右邊開始的位置，如果方向為從右到左，則為從左邊開始的位置
`--height`	toast 的高度
`--max-height`	toast 的最大高度
`--max-width`	toast 的最大寬度
`--min-height`	Toast 的最小高度
`--min-width`	Toast 的最小寬度
`--start`	如果方向是從左到右，則為從左側開始的位置；如果方向是從右到左，則為從右側開始的位置
`--white-space`	Toast 訊息的空白處理
`--width`	Toast 的寬度

插槽

此元件沒有可用的插槽。

內聯快顯通知（建議）​

使用 isOpen​

控制器快顯通知​

關閉​

定位​

相對定位​

滑動以關閉​

版面配置​

圖示​

主題設定​

協助工具​

焦點管理​

螢幕閱讀器​

角色​

Toast 按鈕說明​

提示​

介面​

ToastButton​

ToastOptions​

屬性​

animated​

buttons​

color​

cssClass​

duration​

enterAnimation​

header​

htmlAttributes​

icon​

isOpen​

keyboardClose​

layout​

leaveAnimation​

message​

mode​

position​

positionAnchor​

swipeGesture​

translucent​

trigger​

事件​

方法​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS 陰影部分​

CSS 自訂屬性​

插槽​

目錄