メインコンテンツまでスキップ
バージョン: v8

ion-toast

shadow

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

インラインToasts (推奨)​

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

Using isOpen​​

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

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

Controller Toasts​

Dismissing​

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

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

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

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

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

ポジショニング​

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

相対的な位置​

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

Swipe to Dismiss​

swipeGestureプロパティを使用することで、トーストをスワイプして消すことができます。この機能は位置を認識します。つまり、ユーザがスワイプする方向は position プロパティの値に基づいて変化します。さらに、ユーザーがスワイプする距離は positionAnchor プロパティによって影響を受ける可能性があります。

レイアウト​

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

Icons​

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

テーマ​

アクセシビリティ​

フォーカスの管理​

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

スクリーンリーダー​

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

役割​

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

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

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

トーストボタンの説明​

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

const toast = await this.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.

  • If adding buttons to a toast, always provide alternative ways of completing the actions associated with each button. This ensures that even if the toast dismisses before a user can read it, they can still complete the actions shown in the toast.

  • Avoid showing a toast with buttons from inside another overlay such as a modal. Modals and other overlays implement focus trapping that will prevent screen readers from moving focus to the toast to complete the actions. This may be confusing for users since the toast will still be announced by screen readers. This is true even if alternative ways of completing the actions associated with each button are implemented. Consider creating a live region within the focus-trapped modal instead of using a 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​

DescriptionIf true, the toast will animate.
Attributeanimated
Typeboolean
Defaulttrue

buttons​

DescriptionAn array of buttons for the toast.
Attributeundefined
Type(string ｜ ToastButton)[] ｜ undefined
Defaultundefined

color​

DescriptionThe 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.
Attributecolor
Type"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Defaultundefined

cssClass​

DescriptionAdditional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attributecss-class
Typestring ｜ string[] ｜ undefined
Defaultundefined

duration​

DescriptionHow many milliseconds to wait before hiding the toast. By default, it will show until dismiss() is called.
Attributeduration
Typenumber
Defaultconfig.getNumber('toastDuration', 0)

enterAnimation​

DescriptionAnimation to use when the toast is presented.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) ｜ undefined
Defaultundefined
DescriptionHeader to be shown in the toast.
Attributeheader
Typestring ｜ undefined
Defaultundefined

htmlAttributes​

DescriptionAdditional attributes to pass to the toast.
Attributeundefined
Typeundefined ｜ { [key: string]: any; }
Defaultundefined

icon​

DescriptionThe name of the icon to display, or the path to a valid SVG file. See ion-icon. https://ionic.io/ionicons
Attributeicon
Typestring ｜ undefined
Defaultundefined

isOpen​

DescriptionIf true, the toast will open. If false, the toast will close. Use this if you need finer grained control over presentation, otherwise just use the toastController or the trigger property. Note: isOpen will not automatically be set back to false when the toast dismisses. You will need to do that in your code.
Attributeis-open
Typeboolean
Defaultfalse

keyboardClose​

DescriptionIf true, the keyboard will be automatically dismissed when the overlay is presented.
Attributekeyboard-close
Typeboolean
Defaultfalse

layout​

DescriptionDefines how the message and buttons are laid out in the toast. 'baseline': The message and the buttons will appear on the same line. Message text may wrap within the message container. 'stacked': The buttons containers and message will stack on top of each other. Use this if you have long text in your buttons.
Attributelayout
Type"baseline" ｜ "stacked"
Default'baseline'

leaveAnimation​

DescriptionAnimation to use when the toast is dismissed.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) ｜ undefined
Defaultundefined

message​

DescriptionMessage to be shown in the toast. This property accepts custom HTML as a string. Content is parsed as plaintext by default. innerHTMLTemplatesEnabled must be set to true in the Ionic config before custom HTML can be used.
Attributemessage
TypeIonicSafeString ｜ string ｜ undefined
Defaultundefined

mode​

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" ｜ "md"
Defaultundefined

position​

DescriptionThe starting position of the toast on the screen. Can be tweaked further using the positionAnchor property.
Attributeposition
Type"bottom" ｜ "middle" ｜ "top"
Default'bottom'

positionAnchor​

DescriptionThe element to anchor the toast's position to. Can be set as a direct reference or the ID of the element. With position="bottom", the toast will sit above the chosen element. With position="top", the toast will sit below the chosen element. With position="middle", the value of positionAnchor is ignored.
Attributeposition-anchor
TypeHTMLElement ｜ string ｜ undefined
Defaultundefined

swipeGesture​

DescriptionIf set to 'vertical', the Toast can be dismissed with a swipe gesture. The swipe direction is determined by the value of the position property: top: The Toast can be swiped up to dismiss. bottom: The Toast can be swiped down to dismiss. middle: The Toast can be swiped up or down to dismiss.
Attributeswipe-gesture
Type"vertical" ｜ undefined
Defaultundefined

translucent​

DescriptionIf true, the toast will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.
Attributetranslucent
Typeboolean
Defaultfalse

trigger​

DescriptionAn ID corresponding to the trigger element that causes the toast to open when clicked.
Attributetrigger
Typestring ｜ undefined
Defaultundefined

イベント​

NameDescriptionBubbles
didDismissEmitted after the toast has dismissed. Shorthand for ionToastDidDismiss.true
didPresentEmitted after the toast has presented. Shorthand for ionToastWillDismiss.true
ionToastDidDismissEmitted after the toast has dismissed.true
ionToastDidPresentEmitted after the toast has presented.true
ionToastWillDismissEmitted before the toast has dismissed.true
ionToastWillPresentEmitted before the toast has presented.true
willDismissEmitted before the toast has dismissed. Shorthand for ionToastWillDismiss.true
willPresentEmitted before the toast has presented. Shorthand for ionToastWillPresent.true

メソッド​

dismiss​

DescriptionDismiss the toast overlay after it has been presented.
Signaturedismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss​

DescriptionReturns a promise that resolves when the toast did dismiss.
SignatureonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss​

DescriptionReturns a promise that resolves when the toast will dismiss.
SignatureonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present​

DescriptionPresent the toast overlay after it has been created.
Signaturepresent() => Promise<void>

CSS Shadow Parts​

NameDescription
buttonAny button element that is displayed inside of the toast.
button cancelAny button element with role "cancel" that is displayed inside of the toast.
containerThe element that wraps all child elements.
headerThe header text of the toast.
iconThe icon that appears next to the toast content.
messageThe body text of the toast.

CSSカスタムプロパティ​

NameDescription
--backgroundBackground of the toast
--border-colorBorder color of the toast
--border-radiusBorder radius of the toast
--border-styleBorder style of the toast
--border-widthBorder width of the toast
--box-shadowBox shadow of the toast
--button-colorColor of the button text
--colorColor of the toast text
--endPosition from the right if direction is left-to-right, and from the left if direction is right-to-left
--heightHeight of the toast
--max-heightMaximum height of the toast
--max-widthMaximum width of the toast
--min-heightMinimum height of the toast
--min-widthMinimum width of the toast
--startPosition from the left if direction is left-to-right, and from the right if direction is right-to-left
--white-spaceWhite space of the toast message
--widthWidth of the toast

Slots​

No slots available for this component.

Contents

このページを編集