ドキュメントを検索

Hover Card

リンクがホバーまたはフォーカスされたときに表示される、リンク先コンテンツのプレビュー。

ホバーカード用のWAI-ARIA APGパターンはありません。ホバーカードはポインターユーザー向けの視覚的なプレビューです。支援技術に対してカードがリンクに関連付けられていないため、リンク先のページにも同じ情報が含まれている必要があります。

Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.

import { component$, useStyles$ } from '@builder.io/qwik';
import { HoverCard } from '@leve-ui/hover-card';
import styles from './default.css?inline';

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

  return (
    <p class="hover-card-default">
      Reviewed by{' '}
      <HoverCard.Root>
        <HoverCard.Trigger href="#ada" class="hover-card-default-trigger">
          @ada
        </HoverCard.Trigger>
        {/* A preview only: the profile page has the same information */}
        <HoverCard.Content sideOffset={8} class="hover-card-default-content">
          {/* Only inline elements (span) inside: the card is in a <p> */}
          <span class="hover-card-default-avatar" aria-hidden="true">
            AL
          </span>
          <span class="hover-card-default-body">
            <span class="hover-card-default-name">Ada Lovelace</span>
            <span class="hover-card-default-bio">Writes the first programs. Joined in 1843.</span>
            <a href="#ada" class="hover-card-default-link">
              View profile
            </a>
          </span>
          <HoverCard.Arrow class="hover-card-default-arrow" />
        </HoverCard.Content>
      </HoverCard.Root>{' '}
      yesterday.
    </p>
  );
});

インストール#

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

pnpm add @leve-ui/hover-card

構造#

import { HoverCard } from '@leve-ui/hover-card'; // or '@leve-ui/core'

<HoverCard.Root>
  <HoverCard.Trigger />
  <HoverCard.Content>
    <HoverCard.Arrow />
  </HoverCard.Content>
</HoverCard.Root>
パーツ要素説明
HoverCard.Root<span>パーツをラップし、開閉状態を保持します。インライン要素であるため、テキスト内に収まります。
HoverCard.Trigger<a>カードを表示するリンク。asを使用して、別の要素またはルーターリンクコンポーネントをレンダリングします。
HoverCard.Content<span>カード本体となる、トップレイヤーのpopover="manual"要素。<span>であるため段落内に配置できます。内部にはインライン要素のみを使用してください。
HoverCard.Arrow<span>任意。CSSで描画される、Triggerを指す矢印。

asを使用して、HoverCard.TriggerをQwik Cityの<Link>などのルーターリンクコンポーネントまたは別の要素としてレンダリングします。asに渡されるコンポーネントは、id、aria-*、data-*、およびon*$イベントハンドラーを含む受け取ったpropsを単一の要素にスプレッドする必要があります。

コンポーネント用途
Tooltipボタンを説明する短いテキスト。
Hover Cardリンク先のリッチなプレビュー。内部にリンクを含めることができます。
Popoverユーザーが意図して開き、キーボードでも操作するパネル。

例#

カスタムTrigger#

ホバーカードの動作を維持しながらクライアントサイドナビゲーションを行うには、Qwik Cityの<Link>などのルーターリンクコンポーネントをHoverCard.Triggerのasに渡します。

Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.

APIリファレンス#

Root#

Propデフォルト型
ids–{ trigger?: string; content?: string }

パーツの要素IDをオーバーライドします。

defaultOpenfalseboolean

初期状態でカードを表示するかどうか(非制御)。

bind:open–Signal<boolean>

開閉状態を保持するシグナル(制御)。

onOpenChange$–QRL<(open: boolean) => void>

ユーザーの操作によってカードが表示または非表示になったときに呼び出されます。

openDelay700number

ポインターがTrigger上に静止するかTriggerがフォーカスされてからカードが開くまでの遅延(ms単位)。

closeDelay300number

ポインターが離れてからカードが閉じるまでの遅延(ms単位)。ポインターをカード上へ移動できるようにします。

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

データ属性値
data-leve-hover-card常に存在
data-state"open" | "closed"

Trigger#

Propデフォルト型
as'a'keyof HTMLElementTagNameMap | Component<any>

<a>の代わりにレンダリングする要素またはコンポーネントです。コンポーネントは受け取ったpropsを1つの要素にスプレッドする必要があります。

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

データ属性値
data-leve-hover-card-trigger常に存在
data-state"open" | "closed"

Content#

Propデフォルト型
side'bottom''top' | 'right' | 'bottom' | 'left'

Triggerに対してカードを配置する側。スペースがない場合は反転します。

align'center''start' | 'center' | 'end'

その側に沿った配置方向。

sideOffset0number

Triggerからの距離(px)。

alignOffset0number

側に沿ったオフセット(px)。

avoidCollisionstrueboolean

カードをビューポート内に収めるために反転およびシフトするかどうか。

collisionPadding0number

衝突を防ぐ際のビューポート端からのパディング(px)。

arrowPadding0number

矢印とカードの角との間のパディング(px単位)。

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

データ属性値
data-leve-hover-card-content常に存在
data-state"open" | "closed"
data-side反転後の最終的な配置側:"top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS変数値
--leve-hover-card-anchor-widthTriggerの幅
--leve-hover-card-anchor-heightTriggerの高さ
--leve-hover-card-available-widthビューポートで利用可能な幅
--leve-hover-card-available-heightビューポートで利用可能な高さ

Contentが開いている間、インラインのposition、top、leftが設定されます。display(例えばflex)は:popover-openにのみ設定してください。Content自体に設定すると、閉じたポップオーバーに対するブラウザのdisplay: noneが上書きされてしまいます。

Arrow#

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

データ属性値
data-leve-hover-card-arrow常に存在
data-sideContentの最終的な配置側

アクセシビリティ#

  • ポインターがリンク上に静止するかリンクがフォーカスされると、カードはopenDelay(700ms)後に開き、ポインターが離れたとき、フォーカスが外れたとき、またはEscapeを押したときにcloseDelay(300ms)後に閉じます。
  • ポインターをカード上に移動すると開いた状態が維持されるため、カード内のリンクをクリックできます(WCAG 1.4.13 Content on Hover or Focus)。
  • カードにはroleがなく、リンクからも参照されず、フォーカスが移動することもありません。情報やアクションをカード内だけに配置しないでください。キーボードやスクリーンリーダーのユーザーはリンク先のページでそれらにアクセスします。
  • HoverCard.Arrowはaria-hidden="true"によって支援技術から隠されます。

キーボード操作#

キー説明
Tabリンクをフォーカスすると遅延後にカードが表示され、フォーカスが外れるとカードが非表示になります。
Escapeカードを非表示にします。フォーカスはリンクにとどまります。