Version: v6

ion-toast

コンテンツ

ポジション
Dismissing
アイコン
Interfaces
アクセシビリティ
使い方
プロパティ
イベント
メソッド
CSS Shadow Parts
CSSカスタムプロパティ
Slots

Toastは、現代のアプリケーションで一般的に使用される小さな通知です。操作に関するフィードバックを提供したり、システムメッセージを表示したりするために使用できます。Toastはアプリのコンテンツの上に表示され、終了するとアプリとの対話を再開することができます。

ポジション

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

Dismissing

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

アイコン

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

Interfaces

ToastButton

interface ToastButton {
  text?: string;
  icon?: string;
  side?: 'start' | 'end';
  role?: 'cancel' | string;
  cssClass?: string | string[];
  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;
}

アクセシビリティ

フォーカスの管理

トーストはさりげなく通知するものであり、ユーザーの邪魔をするものではありません。トーストを消すためにユーザーの操作が必要であってはなりません。そのため、トーストが表示されても、フォーカスが自動的に移動することはありません。

スクリーンリーダー

ion-toast は、デフォルトで aria-live="polite" と aria-atomic="true" が設定されています。

aria-liveは、スクリーンリーダーがトーストを提示したときに、その内容をアナウンスするようにします。しかし、この属性は 'polite' に設定されているため、スクリーン・リーダーは通常、現在のタスクを中断しません。開発者は htmlAttributes プロパティを使用して aria-live を 'assertive' に設定することで、この動作をカスタマイズすることができます。これにより、スクリーンリーダーはトーストが表示されるとすぐにユーザーに通知し、それまでの更新を中断させる可能性があります。

また、aria-atomic="true"を設定すると、トースト全体を1つのユニットとしてアナウンスすることができます。これはトーストのコンテンツを動的に更新するときに便利で、スクリーン・リーダーが変更されたコンテンツのみをアナウンスすることを防ぎます。

ヒント

これは完全なリストではありませんが、トーストを使用する際に従うべきガイドラインをいくつか紹介します。

トーストの解除にユーザーの操作を必要としないようにします。例えば、トーストに "Dismiss" ボタンがあるのは良いですが、タイムアウト後にトーストが自動的に終了するようにします。通知のためにユーザーの操作が必要な場合は、代わりに ion-alert を使用することを検討してください。
複数のトーストを連続して開くことは避けてください。もし aria-live が 'assertive' に設定されている場合、スクリーンリーダーは新しいトーストをアナウンスするために現在のタスクの読み込みを中断し、前のトーストのコンテキストが失われる可能性があります。
長いメッセージのトーストの場合は、durationプロパティを調整して、ユーザーがトーストの内容を読むのに十分な時間を確保することを検討してください。

使い方

Angular
Javascript
React
Stencil
Vue

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

@Component({
  selector: 'toast-example',
  templateUrl: 'toast-example.html',
  styleUrls: ['./toast-example.css'],
})
export class ToastExample {

  constructor(public toastController: ToastController) {}

  async presentToast() {
    const toast = await this.toastController.create({
      message: 'Your settings have been saved.',
      duration: 2000
    });
    toast.present();
  }

  async presentToastWithOptions() {
    const toast = await this.toastController.create({
      header: 'Toast header',
      message: 'Click to Close',
      icon: 'information-circle',
      position: 'top',
      buttons: [
        {
          side: 'start',
          icon: 'star',
          text: 'Favorite',
          handler: () => {
            console.log('Favorite clicked');
          }
        }, {
          text: 'Done',
          role: 'cancel',
          handler: () => {
            console.log('Cancel clicked');
          }
        }
      ]
    });
    await toast.present();

    const { role } = await toast.onDidDismiss();
    console.log('onDidDismiss resolved with role', role);
  }

}

async function presentToast() {
  const toast = document.createElement('ion-toast');
  toast.message = 'Your settings have been saved.';
  toast.duration = 2000;

  document.body.appendChild(toast);
  return toast.present();
}

async function presentToastWithOptions() {
  const toast = document.createElement('ion-toast');
  toast.header = 'Toast header';
  toast.message = 'Click to Close';
  toast.icon = 'information-circle',
  toast.position = 'top';
  toast.buttons = [
    {
      side: 'start',
      icon: 'star',
      text: 'Favorite',
      handler: () => {
        console.log('Favorite clicked');
      }
    }, {
      text: 'Done',
      role: 'cancel',
      handler: () => {
        console.log('Cancel clicked');
      }
    }
  ];

  document.body.appendChild(toast);
  await toast.present();

  const { role } = await toast.onDidDismiss();
  console.log('onDidDismiss resolved with role', role);
}

/* Using the useIonToast Hook */

import React from 'react';
import { IonButton, IonContent, IonPage, useIonToast } from '@ionic/react';

const ToastExample: React.FC = () => {
  const [present, dismiss] = useIonToast();

  return (
    <IonPage>
      <IonContent>
        <IonButton
          expand="block"
          onClick={() =>
            present({
              buttons: [{ text: 'hide', handler: () => dismiss() }],
              message: 'toast from hook, click hide to dismiss',
              onDidDismiss: () => console.log('dismissed'),
              onWillDismiss: () => console.log('will dismiss'),
            })
          }
        >
          Show Toast
        </IonButton>
        <IonButton
          expand="block"
          onClick={() => present('hello from hook', 3000)}
        >
          Show Toast using params, closes in 3 secs
        </IonButton>
        <IonButton expand="block" onClick={dismiss}>
          Hide Toast
        </IonButton>
      </IonContent>
    </IonPage>
  );
};

/* Using the IonToast Component */

import React, { useState } from 'react';
import { IonToast, IonContent, IonButton } from '@ionic/react';
import { informationCircle, star } from 'ionicons/icons';

export const ToastExample: React.FC = () => {
  const [showToast1, setShowToast1] = useState(false);
  const [showToast2, setShowToast2] = useState(false);

  return (
    <IonContent>
      <IonButton onClick={() => setShowToast1(true)} expand="block">Show Toast 1</IonButton>
      <IonButton onClick={() => setShowToast2(true)} expand="block">Show Toast 2</IonButton>
      <IonToast
        isOpen={showToast1}
        onDidDismiss={() => setShowToast1(false)}
        message="Your settings have been saved."
        duration={200}
      />

      <IonToast
        isOpen={showToast2}
        onDidDismiss={() => setShowToast2(false)}
        message="Click to Close"
        icon={informationCircle}
        position="top"
        buttons={[
          {
            side: 'start',
            icon: star,
            text: 'Favorite',
            handler: () => {
              console.log('Favorite clicked');
            }
          },
          {
            text: 'Done',
            role: 'cancel',
            handler: () => {
              console.log('Cancel clicked');
            }
          }
        ]}
      />
    </IonContent>
  );
};

import { Component, h } from '@stencil/core';

import { toastController } from '@ionic/core';

@Component({
  tag: 'toast-example',
  styleUrl: 'toast-example.css'
})
export class ToastExample {
  async presentToast() {
    const toast = await toastController.create({
      message: 'Your settings have been saved.',
      duration: 2000
    });
    toast.present();
  }

  async presentToastWithOptions() {
    const toast = await toastController.create({
      header: 'Toast header',
      message: 'Click to Close',
      icon: 'information-circle',
      position: 'top',
      buttons: [
        {
          side: 'start',
          icon: 'star',
          text: 'Favorite',
          handler: () => {
            console.log('Favorite clicked');
          }
        }, {
          text: 'Done',
          role: 'cancel',
          handler: () => {
            console.log('Cancel clicked');
          }
        }
      ]
    });
    await toast.present();

    const { role } = await toast.onDidDismiss();
    console.log('onDidDismiss resolved with role', role);
  }

  render() {
    return [
      <ion-content>
        <ion-button onClick={() => this.presentToast()}>Present Toast</ion-button>
        <ion-button onClick={() => this.presentToastWithOptions()}>Present Toast: Options</ion-button>
      </ion-content>
    ];
  }
}

<template>
  <ion-page>
    <ion-content class="ion-padding">
      <ion-button @click="openToast">Open Toast</ion-button>
      <ion-button @click="openToastOptions">Open Toast: Options</ion-button>
    </ion-content>
  </ion-page>
</template>

<script>
import { IonButton, IonContent, IonPage, toastController } from '@ionic/vue';
import { informationCircle } from 'ionicons/icons';

export default {
  components: { IonButton, IonContent, IonPage },
  methods: {
    async openToast() {
      const toast = await toastController
        .create({
          message: 'Your settings have been saved.',
          duration: 2000
        })
      return toast.present();
    },
    async openToastOptions() {
      const toast = await toastController
        .create({
          header: 'Toast header',
          message: 'Click to Close',
          icon: informationCircle,
          position: 'top',
          buttons: [
            {
              side: 'start',
              icon: 'star',
              text: 'Favorite',
              handler: () => {
                console.log('Favorite clicked');
              }
            }, {
              text: 'Done',
              role: 'cancel',
              handler: () => {
                console.log('Cancel clicked');
              }
            }
          ]
        })
      await toast.present();

      const { role } = await toast.onDidDismiss();
      console.log('onDidDismiss resolved with role', role);
    },
  },
}
</script>

Developers can also use this component directly in their template:

<template>
  <ion-button @click="setOpen(true)">Show Toast</ion-button>
  <ion-toast
    :is-open="isOpenRef"
    message="Your settings have been saved."
    :duration="2000"
    @didDismiss="setOpen(false)"
  >
  </ion-toast>
</template>

<script>
import { IonToast, IonButton } from '@ionic/vue';
import { defineComponent, ref } from 'vue';

export default defineComponent({
  components: { IonToast, IonButton },
  setup() {
    const isOpenRef = ref(false);
    const setOpen = (state: boolean) => isOpenRef.value = state;

    return { isOpenRef, setOpen }
  }
});
</script>

プロパティ

animated

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

buttons

Description	An array of buttons for the toast.
Attribute	`undefined`
Type	`(string ｜ ToastButton)[] ｜ undefined`
Default	`undefined`

color

Description	The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see theming.
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string & Record<never, never> ｜ undefined`
Default	`undefined`

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`

duration

Description	How many milliseconds to wait before hiding the toast. By default, it will show until `dismiss()` is called.
Attribute	`duration`
Type	`number`
Default	`0`

enterAnimation

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

Description	Header to be shown in the toast.
Attribute	`header`
Type	`string ｜ undefined`
Default	`undefined`

htmlAttributes

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

icon

Description	The name of the icon to display, or the path to a valid SVG file. See `ion-icon`. https://ionic.io/ionicons
Attribute	`icon`
Type	`string ｜ undefined`
Default	`undefined`

keyboardClose

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

leaveAnimation

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

message

Description	Message to be shown in the toast.
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`

position

Description	The position of the toast on the screen.
Attribute	`position`
Type	`"bottom" ｜ "middle" ｜ "top"`
Default	`'bottom'`

translucent

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

イベント

Name	Description
`ionToastDidDismiss`	Emitted after the toast has dismissed.
`ionToastDidPresent`	Emitted after the toast has presented.
`ionToastWillDismiss`	Emitted before the toast has dismissed.
`ionToastWillPresent`	Emitted before the toast has presented.

メソッド

dismiss

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

onDidDismiss

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

onWillDismiss

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

present

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

CSS Shadow Parts

Name	Description
`button`	Any button element that is displayed inside of the toast.
`container`	The element that wraps all child elements.
`header`	The header text of the toast.
`icon`	The icon that appears next to the toast content.
`message`	The body text of the toast.

CSSカスタムプロパティ

Name	Description
`--background`	Background of the toast
`--border-color`	Border color of the toast
`--border-radius`	Border radius of the toast
`--border-style`	Border style of the toast
`--border-width`	Border width of the toast
`--box-shadow`	Box shadow of the toast
`--button-color`	Color of the button text
`--color`	Color of the toast text
`--end`	Position from the right if direction is left-to-right, and from the left if direction is right-to-left
`--height`	Height of the toast
`--max-height`	Maximum height of the toast
`--max-width`	Maximum width of the toast
`--min-height`	Minimum height of the toast
`--min-width`	Minimum width of the toast
`--start`	Position from the left if direction is left-to-right, and from the right if direction is right-to-left
`--white-space`	White space of the toast message
`--width`	Width of the toast

Slots

No slots available for this component.

コンテンツ

ポジション​

Dismissing​

アイコン​

Interfaces​

ToastButton​

ToastOptions​

アクセシビリティ​

フォーカスの管理​

スクリーンリーダー​

ヒント​

使い方​

プロパティ​

animated​

buttons​

color​

cssClass​

duration​

enterAnimation​

header​

htmlAttributes​

icon​

keyboardClose​

leaveAnimation​

message​

mode​

position​

translucent​

イベント​

メソッド​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​