Version: v7

ion-toast

トーストは、最近のアプリケーションでよく使われる小さな通知です。操作に関するフィードバックを提供したり、システムメッセージを表示したりするために使用されます。トーストは、アプリケーションのコンテンツの上に表示され、アプリケーションによって解除されると、アプリケーションとの対話を再開することができます。

インラインToasts (推奨)

ion-toastは、テンプレートに直接コンポーネントを記述して使用することができます。これにより、トーストを表示するために配線する必要があるハンドラの数を減らすことができます。

<ion-header>
  <ion-toolbar>
    <ion-title>Inline Toast</ion-title>
  </ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
  <ion-button id="open-toast" expand="block">Open</ion-button>
  <p id="message">This toast example uses triggers to automatically open a toast when the button is clicked.</p>
  <ion-toast trigger="open-toast" message="This toast will disappear after 5 seconds" [duration]="5000"></ion-toast>
</ion-content>

Using `isOpen`

ion-toast の isOpen プロパティは、開発者がアプリケーションの状態からトーストの表示状態を制御できるようにするものです。つまり、isOpen を true に設定するとトーストが表示され、isOpen を false に設定するとトーストは破棄されます。

isOpen は一方通行のデータバインディングを使用しているため、トーストが破棄されたときに自動的に false に設定されることはありません。開発者は ionToastDidDismiss または didDismiss イベントをリスニングして isOpen を false に設定する必要があります。この理由は、ion-toast の内部がアプリケーションの状態と密接に結合するのを防ぐためである。一方通行のデータバインディングでは、トーストはリアクティブ変数が提供するブーリアン値だけを気にすればよい。一方通行のデータバインディングでは、トーストはブーリアン値とリアクティブ変数の存在の両方に関心を持つ必要があります。これは、非決定的な動作につながり、アプリケーションのデバッグを困難にします。

src/app/example.component.html
src/app/example.component.ts

<ion-header>
  <ion-toolbar>
    <ion-title>Inline Toast</ion-title>
  </ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
  <ion-button expand="block" (click)="setOpen(true)">Open</ion-button>
  <ion-toast
    [isOpen]="isToastOpen"
    message="This toast will close in 5 seconds"
    [duration]="5000"
    (didDismiss)="setOpen(false)"
  ></ion-toast>
</ion-content>

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  isToastOpen = false;

  setOpen(isOpen: boolean) {
    this.isToastOpen = isOpen;
  }
}

Controller Toasts

src/app/example.component.html
src/app/example.component.ts

<ion-button expand="block" (click)="presentToast('top')">Present Toast At the Top</ion-button>
<ion-button expand="block" (click)="presentToast('middle')">Present Toast At the Middle</ion-button>
<ion-button expand="block" (click)="presentToast('bottom')">Present Toast At the Bottom</ion-button>

import { Component } from '@angular/core';
import { ToastController } from '@ionic/angular';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  constructor(private toastController: ToastController) {}

  async presentToast(position: 'top' | 'middle' | 'bottom') {
    const toast = await this.toastController.create({
      message: 'Hello World!',
      duration: 1500,
      position: position,
    });

    await toast.present();
  }
}

Dismissing

トーストは静かな通知であり、ユーザーの邪魔をしないように意図されています。そのため、トーストを解除するためにユーザーの操作を必要とするべきではありません。

トーストは、トーストオプションの duration に表示するミリ秒数を渡すことで、特定の時間経過後に自動的に解除されるようにすることができます。もし "cancel" という役割を持つボタンが追加された場合、そのボタンがトーストを終了させます。作成後にトーストを破棄するには、インスタンスの dismiss() メソッドを呼び出してください。

ハードウェアの戻るボタンを押しても、トーストはユーザーの邪魔をしないようになっているので、トーストは破棄されません。

次の例では、buttons プロパティを使用して、クリックすると自動的にトーストを解散させるボタンを追加する方法と、解散イベントの role を収集する方法を示しています。

Console

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

src/app/example.component.html
src/app/example.component.ts

<ion-button id="open-toast">Open Toast</ion-button>
<ion-toast
  trigger="open-toast"
  message="Hello World!"
  [duration]="3000"
  [buttons]="toastButtons"
  (didDismiss)="setRoleMessage($event)"
></ion-toast>

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  public toastButtons = [
    {
      text: 'More Info',
      role: 'info',
      handler: () => {
        console.log('More Info clicked');
      },
    },
    {
      text: 'Dismiss',
      role: 'cancel',
      handler: () => {
        console.log('Dismiss clicked');
      },
    },
  ];

  setRoleMessage(ev) {
    const { role } = ev.detail;
    console.log(`Dismissed with role: ${role}`);
  }
}

ポジショニング

トーストは、ビューポートの上部、下部、中部に配置することができます。位置は作成時に渡すことができます。指定できる値は top, bottom, middle です。位置が指定されない場合、トーストはビューポートの一番下に表示されます。

相対的な位置

トーストがヘッダー、フッター、FABのようなナビゲーション要素と一緒に表示される場合、デフォルトではトーストはこれらの要素と重なるかもしれません。これは positionAnchor プロパティを使って修正することができます。position="top"を使用するとトーストは選択した要素に対して相対的な位置になり、position="bottom"を使用するとその下に、position="bottom"を使用するとその上に表示されます。position="middle"を使用する場合、positionAnchorプロパティは無視されます。

<ion-header id="header">
  <ion-toolbar>
    <ion-title>Header</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-button id="headerAnchor">Anchor to Header</ion-button>
  <ion-button id="footerAnchor">Anchor to Footer</ion-button>

  <ion-toast
    trigger="headerAnchor"
    position="top"
    positionAnchor="header"
    message="Hello World!"
    duration="2000"
  ></ion-toast>
  <ion-toast
    trigger="footerAnchor"
    position="bottom"
    positionAnchor="footer"
    message="Hello World!"
    duration="2000"
  ></ion-toast>
</ion-content>

<ion-footer id="footer">
  <ion-toolbar>
    <ion-title>Footer</ion-title>
  </ion-toolbar>
</ion-footer>

レイアウト

トースト内のボタンコンテナは、layoutプロパティを使用して、メッセージと同じ行に表示するか、別々の行に積み重ねて表示することができます。スタックレイアウトは、長いテキスト値を持つボタンで使用する必要があります。さらに、スタックトーストレイアウトのボタンは side の値として start または end のどちらかを使用できますが、両方を使用することはできません。

src/app/example.component.html
src/app/example.component.ts

<ion-button id="open-inline-toast">Open Baseline Layout Toast</ion-button>
<ion-button id="open-stacked-toast">Open Stacked Layout Toast</ion-button>
<ion-toast
  trigger="open-inline-toast"
  [duration]="3000"
  [buttons]="toastButtons"
  message="This is a toast with a long message and a button that appears on the same line."
></ion-toast>
<ion-toast
  trigger="open-stacked-toast"
  [duration]="3000"
  [buttons]="toastButtons"
  message="This is a toast with a long message and a button that appears on the next line."
  layout="stacked"
></ion-toast>

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  toastButtons = [
    {
      text: 'Action With Long Text',
    },
  ];
}

Icons

トースト内のコンテンツの横にアイコンを追加することができます。一般的に、トーストのアイコンはスタイルやコンテキストを追加するために使用されるべきで、ユーザーの注意を引いたり、トーストの優先順位を上げたりするために使用すべきではありません。より優先順位の高いメッセージをユーザーに伝えたい場合や、応答を保証したい場合は、代わりに Alert を使用することをお勧めします。

<ion-button id="open-toast">Open Toast</ion-button>
<ion-toast trigger="open-toast" message="Hello World!" [duration]="3000" icon="globe"></ion-toast>

テーマ

src/app/example.component.html
src/app/example.component.ts
src/global.css

<ion-button id="open-toast">Open Toast</ion-button>
<ion-toast
  trigger="open-toast"
  [duration]="3000"
  message="Hello Styled World!"
  class="custom-toast"
  [buttons]="toastButtons"
></ion-toast>

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
})
export class ExampleComponent {
  public toastButtons = [
    {
      text: 'Dismiss',
      role: 'cancel',
    },
  ];

  constructor() {}
}

ion-toast.custom-toast {
  --background: #f4f4fa;
  --box-shadow: 3px 3px 10px 0 rgba(0, 0, 0, 0.2);
  --color: #4b4a50;
}

ion-toast.custom-toast::part(message) {
  font-style: italic;
}

ion-toast.custom-toast::part(button) {
  border-left: 1px solid #d2d2d2;
  color: #030207;
  font-size: 15px;
}

アクセシビリティ

フォーカスの管理

トーストはさりげない通知であり、ユーザーを中断させるものではありません。トーストを解除するためにユーザが操作する必要はありません。そのため、トーストが表示されたときにフォーカスが自動的にトーストに移動することはありません。

スクリーンリーダー

トーストは、スクリーンリーダーからaccessibleであるためにariaプロパティを設定しますが、これらのプロパティは、十分な説明がない場合や、トーストがアプリでどのように使用されているかに合っていない場合は、上書きすることができます。

役割

ion-toastは、内側の .toast-content 要素に role="status" と aria-live="polite" を設定している。これにより、スクリーンリーダーはトーストメッセージとヘッダーのみをアナウンスします。ボタンとアイコンは、トーストが表示されてもアナウンスされません。

aria-liveは、トーストの内容が更新されたときに、スクリーンリーダーにトーストの内容をアナウンスさせます。しかし、この属性は 'polite' に設定されているので、スクリーンリーダーは現在のタスクを中断すべきではありません。

トーストはさりげなく通知することを意図しているので、aria-liveを"assertive"に設定すべきではありません。開発者が重要なメッセージでユーザーを中断させる必要がある場合は、alertを使用することをお勧めします。

トーストボタンの説明

テキストを含むボタンは、スクリーンリーダーによって読み取られます。ボタンがアイコンのみを含んでいる場合、または既存のテキスト以外の説明が必要な場合は、ボタンの htmlAttributes プロパティに aria-label を渡すことで、ボタンにラベルを割り当てる必要があります。

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',
      },
    },
  ],
});

Tips

While this is not a complete list, here are some guidelines to follow when using toasts.

Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an alert instead.
For toasts with long messages, consider adjusting the duration property to allow users enough time to read the content of the toast.

Interfaces

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

Description	`true`の場合、トーストはアニメーションします。
Attribute	`animated`
Type	`boolean`
Default	`true`

buttons

Description	トースト用のボタンがずらり。
Attribute	`undefined`
Type	`(string ｜ ToastButton)[] ｜ undefined`
Default	`undefined`

color

Description	アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, と `"dark"` です．色に関する詳しい情報は theming を参照してください。
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
Default	`undefined`

cssClass

Description	カスタムCSSに適用する追加のクラス。複数のクラスを指定する場合は、スペースで区切る必要があります。
Attribute	`css-class`
Type	`string ｜ string[] ｜ undefined`
Default	`undefined`

duration

Description	トーストを隠すまでに何ミリ秒待つかを指定します。デフォルトでは、`dismiss()`が呼ばれるまで表示されます。
Attribute	`duration`
Type	`number`
Default	`config.getNumber('toastDuration', 0)`

enterAnimation

Description	乾杯の音頭をとるときに使うアニメーションです。
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

Description	トーストに表示されるヘッダー。
Attribute	`header`
Type	`string ｜ undefined`
Default	`undefined`

htmlAttributes

Description	トーストに渡す追加の属性。
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

icon

Description	表示するアイコンの名前、または有効なSVGファイルへのパスを指定します。ion-icon`を参照。https://ionic.io/ionicons
Attribute	`icon`
Type	`string ｜ undefined`
Default	`undefined`

isOpen

Description	もし `true` ならば、トーストは表示されます。もし `false` ならば、トーストは閉じます。プレゼンテーションの細かい制御が必要な場合はこれを使用し、そうでない場合は toastController または `trigger` プロパティを使用してください。注意: トーストが終了しても `isOpen` は自動的に `false` に戻りません。あなたのコードでそれを行う必要があります。
Attribute	`is-open`
Type	`boolean`
Default	`false`

keyboardClose

Description	`true`の場合、オーバーレイが表示されたときにキーボードが自動的に解除されます。
Attribute	`keyboard-close`
Type	`boolean`
Default	`false`

layout

Description	トーストのメッセージやボタンの配置を定義します。'baseline'を指定します。メッセージとボタンは同じ行に表示されます。メッセージテキストはメッセージコンテナ内で折り返すことができます。'stacked':ボタンコンテナとメッセージが重なるように表示されます。ボタンに長いテキストがある場合に使用します。
Attribute	`layout`
Type	`"baseline" ｜ "stacked"`
Default	`'baseline'`

leaveAnimation

Description	トーストの解散時に使用するアニメーションです。
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

message

Description	トーストに表示するメッセージ。このプロパティは、文字列としてカスタムHTMLを受け入れます。デフォルトではコンテンツはプレーンテキストとしてパースされます。カスタムHTMLを使用するには、Ionicの設定で `innerHTMLTemplatesEnabled` を `true` に設定する必要があります。
Attribute	`message`
Type	`IonicSafeString ｜ string ｜ undefined`
Default	`undefined`

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

position

Description	画面上のトーストの開始位置。 `positionAnchor`プロパティを使ってさらに微調整できます。
Attribute	`position`
Type	`"bottom" ｜ "middle" ｜ "top"`
Default	`'bottom'`

positionAnchor

Description	トーストの位置を固定する要素。直接参照するか、要素のIDを指定します。position="bottom"`の場合、トーストは選択した要素の上に表示されます。position="top"`の場合、トーストは選択した要素の下に位置します。position="middle"`の場合、`positionAnchor`の値は無視される。
Attribute	`position-anchor`
Type	`HTMLElement ｜ string ｜ undefined`
Default	`undefined`

translucent

Description	`true`の場合、トーストは半透明になります。modeが `"ios"` で、デバイスが `backdrop-filter` をサポートしている場合にのみ適用されます。
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	クリックされたときにトーストを開かせるトリガー要素に対応するID。
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

イベント

Name	Description
`didDismiss`	トーストが終了した後に発行されます。ionToastDidDismissの略記。
`didPresent`	トーストがはじまった後に発行されます。ionToastWillDismissの略語。
`ionToastDidDismiss`	トーストが解散した後に発行されます。
`ionToastDidPresent`	トーストが提示された後に発行されます。
`ionToastWillDismiss`	乾杯が解散する前に発行されます。
`ionToastWillPresent`	トーストが提示される前に発行されます。
`willDismiss`	トーストが終了する前に発行されます。ionToastWillDismissの略語です。
`willPresent`	トーストが表示される前に発行されます。ionToastWillPresentの略記。

メソッド

dismiss

Description	トーストのオーバーレイが提示された後、それを解除します。
Signature	`dismiss(data?: any, role?: string) => Promise<boolean>`

onDidDismiss

Description	トーストが解散したことを解決するPromiseを返します。
Signature	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

Description	トーストが解散するタイミングを解決するPromiseを返します。
Signature	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

Description	トーストのオーバーレイを作成した後に提示します。
Signature	`present() => Promise<void>`

CSS Shadow Parts

Name	Description
`button`	トーストの内側に表示される任意のボタン要素。
`button cancel`	トーストの内側に表示される、"cancel "というロールを持つボタン要素。
`container`	すべての子要素を包む要素。
`header`	乾杯のヘッダーテキストです。
`icon`	トーストの内容の横に表示されるアイコンです。
`message`	乾杯の音頭の本文です。

CSSカスタムプロパティ

Name	Description
`--background`	乾杯の背景
`--border-color`	トーストのボーダーカラー
`--border-radius`	トーストのボーダー半径
`--border-style`	トーストのボーダースタイル
`--border-width`	トーストのボーダー幅
`--box-shadow`	乾杯の箱影
`--button-color`	ボタンテキストの色
`--color`	トーストの文字色
`--end`	方向が左から右の場合は右から、方向が右から左の場合は左から位置すること
`--height`	トーストの高さ
`--max-height`	トーストの最大の高さ
`--max-width`	トーストの最大幅
`--min-height`	トーストの最小の高さ
`--min-width`	トーストの最小幅
`--start`	方向が左から右の場合は左から、方向が右から左の場合は右から位置すること
`--white-space`	乾杯メッセージのホワイトスペース
`--width`	トーストの幅

Slots

No slots available for this component.

インラインToasts (推奨)​

Using isOpen​​

Controller Toasts​

Dismissing​

ポジショニング​

相対的な位置​

レイアウト​

Icons​

テーマ​

アクセシビリティ​

フォーカスの管理​

スクリーンリーダー​

役割​

トーストボタンの説明​

Tips​

Interfaces​

ToastButton​

ToastOptions​

プロパティ​

animated​

buttons​

color​

cssClass​

duration​

enterAnimation​

header​

htmlAttributes​

icon​

isOpen​

keyboardClose​

layout​

leaveAnimation​

message​

mode​

position​

positionAnchor​

translucent​

trigger​

イベント​

メソッド​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents