ion-toast
コンテンツ
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 |
header
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 | undefined) => 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.