アバター

hc-avatar は、写真アバターには <img> に、画像がないときのイニシャルのフォールバックには <span> に適用します。どちらも同じ円形の面、サイズ、形状バリアントを共有します。

別名: プロフィール画像、ユーザーアイコン。

画像アバター

<img class="hc-avatar" src="/users/ada.jpg" alt="Ada Lovelace">
<img class="hc-avatar" src="/users/john.jpg" alt="John Smith">

コンポーネントは object-fit: cover と overflow: hidden を設定するため、どんなアスペクト比の画像も中央寄せの正方形クロップとして描画されます。(上のプレビューはインラインのプレースホルダー画像です。 src は実際の写真に向けてください。)

イニシャルのフォールバック

画像がないときは、代わりに <span> を描画します。フルネームは aria-label に運ばせてください。見えるイニシャルは短く (1〜2 文字)、グループ内でユーザーを識別できる程度に一意であるべきです。

ALJCHL

<span class="hc-avatar" aria-label="Ada Lovelace">AL</span>

画像のフォールバック

写真がないかもしれないときは、画像とイニシャルのフォールバックを 1 つの .hc-avatar で包みます。installAvatar() ビヘイビアが画像のネイティブな load / error イベントを監視し、ラッパーに data-state を設定するため、画像が失敗するとフォールバックが自動で現れます。素のイニシャルと確実に読み込める画像に JavaScript は不要です — この自動フォールバックだけが必要とします:

import { installAvatar } from '@hypermedia-components/core';
installAvatar(); // idempotent; returns an uninstaller

ゼロ設定の @hypermedia-components/core/behaviors エントリは自動でインストールします。

<!-- installAvatar() writes data-state; the preview above forces
     data-state="error" to show the fallback. -->
<span class="hc-avatar" role="img" aria-label="Ada Lovelace">
  <img class="hc-avatar__image" src="/users/ada.jpg" alt="">
  <span class="hc-avatar__fallback" aria-hidden="true">AL</span>
</span>

アクセシブルな名前はラッパーが運びます(role="img" + aria-label)。画像は装飾(alt="")で、フォールバックはその名前を視覚的に複製するため aria-hidden です。

状態

installAvatar() はラッパーの data-state に次のいずれかを書くため、各フェーズをスタイルできます:

`data-state`	意味
`loading`	画像を取得中。スロットが空にならないようフォールバックを表示。
`pending`	取得中だが `data-delay` が設定されている — フラッシュを避けるため、その時間はフォールバックを隠したまま(下記参照)。
`loaded`	画像がデコードされた。フォールバックは隠れる。
`error`	画像が失敗した(または `src` がない)。フォールバックが表示され、壊れた画像は取り除かれる。

フラッシュの回避(`data-delay`)

高速な接続では画像が数ミリ秒で届くことが多く、先にイニシャルを見せるとフラッシュになります。data-delay="<ms>" を設定すると、その時間はフォールバックを隠したままにします — 画像が先に読み込まれればフォールバックは決して現れず、そうでなければ遅延が過ぎたときに現れます。

<span class="hc-avatar" role="img" aria-label="Ada Lovelace" data-delay="500">
  <img class="hc-avatar__image" src="/users/ada.jpg" alt="">
  <span class="hc-avatar__fallback" aria-hidden="true">AL</span>
</span>

JavaScript なしで

このパターンはプログレッシブです: 画像がフォールバックに重なるため、読み込みに成功すれば installAvatar() がなくてもイニシャルは覆われます。トレードオフは、壊れた画像は JS なしでは取り除かれないことです — ブラウザの壊れた画像インジケーターがフォールバックの上に見えるかもしれません。画像の欠落をサーバサイドで検知できるなら、 <span class="hc-avatar">…</span> のイニシャル形を直接描画してください。

サイズ

data-size は xs、sm、md(デフォルト)、lg、xl を受け付けます。

JSJSJSJSJS

<span class="hc-avatar" data-size="xs" aria-label="Jane Smith">JS</span>
<span class="hc-avatar" data-size="sm" aria-label="Jane Smith">JS</span>
<span class="hc-avatar"                aria-label="Jane Smith">JS</span>
<span class="hc-avatar" data-size="lg" aria-label="Jane Smith">JS</span>
<span class="hc-avatar" data-size="xl" aria-label="Jane Smith">JS</span>

形状

data-shape="square" は、完全な円の代わりに正方形プリセットの角丸にします。

JSJS

<span class="hc-avatar" aria-label="Jane Smith">JS</span>
<span class="hc-avatar" aria-label="Jane Smith" data-shape="square">JS</span>

グループ

アバターの列を .hc-avatar-group で包むと重なります — 最初以外の各アバターは負のマージンで引き戻され、ページ背景に合わせたリングが付くため、重なりがきれいに読めます。

ABCD

<div class="hc-avatar-group">
  <span class="hc-avatar" aria-label="Ada">A</span>
  <span class="hc-avatar" aria-label="Beatrice">B</span>
  <span class="hc-avatar" aria-label="Catalina">C</span>
  <span class="hc-avatar" aria-label="Dorothée">D</span>
</div>

アクセシビリティ

<img class="hc-avatar"> には常に意味のある alt テキストを — 典型的にはユーザーのフルネームです。
イニシャルのフォールバックでは、見えるテキストは短く視覚的です。スクリーンリーダーにフルネームを与えるには aria-label を使ってください。そうしないとユーザーはただの「JS」と読み上げられ、ほとんど役に立ちません。
純粋に装飾のアバター(例: すでに読み上げられる名前の隣のサムネイル)には、二重読み上げを避けるためアバターに aria-hidden="true" を設定してください。

テーマ用トークン

component トークン(component.tokens.json):

トークンパス	用途
`avatar.size`	デフォルトの寸法。
`avatar.radius` / `square-radius`	円と正方形の角丸。
`avatar.bg` / `fg`	フォールバックの面の色。
`avatar.font-size` / `font-weight`	イニシャルのテキストスタイル。
`avatar.xs.` / `sm.` / `lg.` / `xl.`	専用のサイズ上書き。

CSS 変数

生成される CSS 変数を表示

--hc-avatar-size | -radius | -square-radius
--hc-avatar-bg | -fg
--hc-avatar-font-size | -font-weight
--hc-avatar-xs-size | -xs-font-size
--hc-avatar-sm-size | -sm-font-size
--hc-avatar-lg-size | -lg-font-size
--hc-avatar-xl-size | -xl-font-size