ドキュメントを検索

Toast

ユーザーの操作を妨げることなく、「保存しました」などの短いメッセージを一時的に表示します。

Toastに対応するWAI-ARIA APGパターンはありません。トーストはライブリージョンを通じて読み上げられ、キーボードのホットキーで到達可能なランドマーク内に配置され、ユーザーが読んでいる間は表示されたままになります。

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Toast } from '@leve-ui/toast';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

const MESSAGES = [
  { title: 'Saved', description: 'Your changes were saved.' },
  { title: 'Copied', description: 'The link was copied to the clipboard.' },
  { title: 'Invitation sent', description: 'We emailed the invitation to your teammate.' },
];

// Any component inside the Provider can add toasts
const ShowButton = component$(() => {
  const toaster = Toast.useToaster();
  const count = useSignal(0);

  return (
    <button
      type="button"
      class="toast-default-button"
      onClick$={() => {
        toaster.add$(MESSAGES[count.value % MESSAGES.length]);
        count.value += 1;
      }}
    >
      Show toast
    </button>
  );
});

// Renders the toasts; put it once, usually at the app root
const Toaster = component$(() => {
  const toaster = Toast.useToaster();

  return (
    <Toast.Region class="toast-default-region">
      <Toast.List class="toast-default-list">
        {toaster.toasts.value.map((toast) => (
          <Toast.Root key={toast.id} toast={toast} class="toast-default-toast">
            <Toast.Title class="toast-default-title">{toast.title}</Toast.Title>
            <Toast.Description class="toast-default-description">
              {toast.description}
            </Toast.Description>
            <Toast.Close aria-label="Close" class="toast-default-close">
              <LuX aria-hidden="true" class="toast-default-icon" />
            </Toast.Close>
          </Toast.Root>
        ))}
      </Toast.List>
    </Toast.Region>
  );
});

export default component$(() => {
  useStyles$(styles);

  return (
    <Toast.Provider>
      <ShowButton />
      <Toaster />
    </Toast.Provider>
  );
});

インストール#

個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。

pnpm add @leve-ui/toast

構造#

import { Toast } from '@leve-ui/toast'; // or '@leve-ui/core'

<Toast.Provider>
  {/* Your app: call Toast.useToaster().add$() anywhere inside */}
  <Toast.Region>
    <Toast.List>
      {toaster.toasts.value.map((toast) => (
        <Toast.Root key={toast.id} toast={toast}>
          <Toast.Title />
          <Toast.Description />
          <Toast.Action />
          <Toast.Close />
        </Toast.Root>
      ))}
    </Toast.List>
  </Toast.Region>
</Toast.Provider>
パーツ要素説明
Toast.Providerなしトーストと設定を保持します。アプリをこれでラップしてください。
Toast.Region<section>トーストを保持するランドマークです。ホットキーによってフォーカスがここに移動します。
Toast.List<ol>トーストのリストです。
Toast.Root<li>個々のトーストです。useToaster().toastsからトーストを受け取ります。
Toast.Title<div>タイトルです。
Toast.Description<div>省略可能。詳細です。
Toast.Action<button>省略可能。「元に戻す」などのアクションです。onClick$の実行後にトーストを閉じます。
Toast.Close<button>トーストを閉じます。

トーストの追加#

Toast.useToaster()はトーストとそれらを変更する関数を返します。Provider内の任意のコンポーネントで呼び出してください。

const toaster = Toast.useToaster();

const id = await toaster.add$({ title: 'Uploading', duration: Infinity });
await toaster.update$(id, { title: 'Uploaded', duration: 3000 });
await toaster.dismiss$(id); // or dismiss$() to close all
オプション説明
title / descriptionテキストです。読み上げにも使用されます。
typeユーザー操作の結果で、すぐに読み上げられる'foreground'(デフォルト)。バックグラウンドタスク用で、現在の読み上げの後に読み上げられる'background'。
durationトーストが表示され続ける時間(ミリ秒単位)。Infinityを指定すると閉じられるまで維持されます。デフォルトはProviderのdurationです。
dataレンダリング用独自のデータで、useToaster<T>()で型付けされます。シリアライズ可能である必要があります。

トーストはモジュール変数ではなくProviderのコンテキスト内のシグナルで保持されます。サーバー上の各リクエストが独自のトーストを持ち、サーバーで追加されたトーストがクライアントに表示されます。

スタック#

各トーストは、カードのように重ねて表示し、ポインターがRegion上にあるかフォーカスがある間(data-expanded)に展開するためのCSS変数を出力します。上のデモはその一例を示しています:

.toast {
  position: absolute;
  bottom: 0;
  transform: translateY(calc(var(--leve-toast-index) * -12px))
    scale(calc(1 - var(--leve-toast-index) * 0.05));
}

.toast[data-expanded] {
  transform: translateY(calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px));
}

例#

アクション#

Toast.Actionを持つトーストは閉じられるまで表示されたままになるため、ユーザーが到達する時間を確保できます。トーストはやがて消えるため、同じアクションをページ内の別の場所にも用意してください。

  • report.pdf
  • photo.png
  • notes.txt

APIリファレンス#

Provider#

Propデフォルト型
duration5000number

トーストが表示され続ける時間(ミリ秒単位)。Actionを持つトーストは、閉じられるまで表示され続けます。

placement'bottom-end''top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end'

Regionを配置する位置。Regionおよびトーストにdata-placementとして出力されます。

swipeDirection–'up' | 'down' | 'left' | 'right'

トーストをスワイプして閉じる方向。デフォルトは配置位置の最も近い端です。

swipeThreshold50number

トーストを閉じるために必要なスワイプ距離(ピクセル単位)。

hotkey['F8']string[]

Regionにフォーカスを移動するキー。KeyboardEvent.codeの値、および修飾キーとしてのaltKey、ctrlKey、metaKey、shiftKey。

Region#

Propデフォルト型
label'Notifications ({hotkey})'string

リージョンの名前。{hotkey}はF8などのホットキーに置き換えられます。

すべての<section>属性も受け入れます。

データ属性値
data-leve-toast-region常に存在
data-placementProviderのplacement
data-expandedポインターがRegion上にあるか、Region内にフォーカスがある場合に存在

ライブラリはRegionを配置しません。data-placementまたは独自のクラスを使用して配置してください。

List#

独自のpropはありません。 すべての<ol>属性を受け入れます。

データ属性値
data-leve-toast-list常に存在
data-placementProviderのplacement
data-expandedポインターがRegion上にあるか、Region内にフォーカスがある場合に存在

Root#

Propデフォルト型
toast (必須)–ToastData

useToaster().toastsから取得した、レンダリング対象のトースト。

すべての<li>属性も受け入れます。

データ属性値
data-leve-toast常に存在
data-state"open" | "closed"
data-type"foreground" | "background"
data-placementProviderのplacement
data-front最新の開いているトーストに存在
data-expandedポインターがRegion上にあるか、Region内にフォーカスがある場合に存在
data-swipeスワイプ中またはスワイプ後の"move" | "cancel" | "end"
data-swipe-direction"up" | "down" | "left" | "right"
CSS変数値
--leve-toast-index前面からの位置:0が最新の開いているトースト
--leve-toast-count開いているトーストの数
--leve-toast-front-offsetスタックを展開するための、より新しいトーストの合計の高さ
--leve-toast-heightこのトーストの高さ
--leve-toast-front-height最前面のトーストの高さ(例:背面のトーストの高さを揃えるため)
--leve-toast-swipe-move-x / -ydata-swipe="move"時の、ここまでのスワイプ移動距離
--leve-toast-swipe-end-x / -ydata-swipe="end"時の、スワイプ移動距離

閉じられると、トーストはdata-state="closed"を取得し、CSSアニメーションおよびトランジションが完了した後に削除されるため、終了アニメーションを適用できます。

タイトル#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-toast-title常に存在

説明#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-toast-description常に存在

アクション#

独自のpropはありません。 すべての<button>属性を受け入れます。

データ属性値
data-leve-toast-action常に存在

閉じる#

独自のpropはありません。 すべての<button>属性を受け入れます。

データ属性値
data-leve-toast-close常に存在

アクセシビリティ#

  • トーストが追加されると、そのタイトルと説明文は常にページ上に存在するライブリージョンを通じて通知されます。foregroundにはassertive、backgroundにはpoliteが使用されます。後からページに追加されたライブリージョンは確実に読み上げられない場合があるため、トースト自体はライブリージョンではありません。
  • Toast.Regionは、「Notifications (F8)」という名前の<section>ランドマークです。labelで名前を変更でき、{hotkey}はホットキーに置き換えられます。
  • トーストは、ユーザーが操作していない間のみ自動的に閉じます。ポインターがRegion上にある、フォーカスがRegion内にある、ウィンドウがバックグラウンドにある、またはトーストがスワイプされている間はタイマーが一時停止します。Actionを持つトーストは自動的に閉じることはありません。
  • アイコンのみを表示する場合は、Toast.Closeにaria-labelを指定してください。

キーボード操作#

キー説明
F8フォーカスをRegionに移動します。Providerのhotkeyで変更できます。
Tabトーストおよびそのボタン間を移動します。
Escapeトースト上で実行すると、そのトーストを閉じて次のトーストまたはRegionにフォーカスを移動します。