Avatar アバター

LhAvatar はユーザーや事物のアバターを表示するために使用します。画像・アイコン・テキストの 3 つの形態をサポートし、画像の読み込み失敗時には自動的にフォールバックします。

基本的な使い方

画像アバター

fit が切り抜きモード（ネイティブの object-fit）を制御し、alt が代替テキストを提供します。

<script setup lang="ts">
</script>

<template>
  <!-- 画像アバター -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit による切り抜き + alt による代替テキスト -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="ユーザーアバター"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- 画像アバター -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit による切り抜き + alt による代替テキスト -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="ユーザーアバター"
  />
</template>

形状とサイズ

丸と四角、4 つのサイズ

小中大丸

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="小"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="中"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="大"
    />
    <LhAvatar
      size="large"
      text="丸"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="小"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="中"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="大"
    />
    <LhAvatar
      size="large"
      text="丸"
    />
  </div>
</template>

テキストとアイコンのフォールバック

画像がない場合は icon、text の順にフォールバック

水A

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="水墨" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="水墨" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

テキストアバターは自動的に先頭の文字を表示します（中国語は最初の 1 字、英語は最初の文字を大文字にして表示）。

画像の読み込み失敗

失敗後に text へフォールバックし error イベントを発火

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="予"
    @error="onError"
  />
</template>

<script setup lang="ts">
function onError(e: Event) {
  console.log('avatar load error', e)
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="予"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onError(e) {
      console.log('avatar load error', e)
    },
  },
}
</script>

API

Props

プロパティ	説明	型	デフォルト値
src	画像のアドレス。空の場合はアイコン／テキストにフォールバックします	string	—
alt	代替テキスト	string	—
icon	アイコン名（内蔵の LhIcon アイコン。src がない場合に表示）	LhIconName	—
text	テキスト内容（src と icon がない場合は先頭の文字を表示）	string	—
shape	アバターの形状	"circle" | "square"	'circle'
size	アバターのサイズ	"small" | "medium" | "large" | "mini" | "x-large"	'medium'
fit	画像の読み込みモード：fill / contain / cover	"fill" | "contain" | "cover" | "none" | "scale-down"	'cover'
sx	sx クイックレイアウトプロパティ	LhSxProps	—

Events

イベント名	説明	コールバック
error	画像の読み込み失敗時に発火します	(e: Event)

アクセシビリティ

• 画像モードでは <img alt> 自体が代替テキストを提供します。alt 未指定時は text に、さらに avatar にフォールバックします
• アイコン／テキストモードではルート要素が role="img" を担います。alt が指定された場合はアクセシブルネームとして使用し、アイコン自体には aria-hidden を付けます

型定義

このコンポーネントが外部にエクスポートする TypeScript の型構造を以下に示します（packages/components/avatar/src/types.ts および @lh-ui/share/core/* のソースから自動抽出。各エントリーをクリックすると完全な定義が表示されます。プロパティの説明は上の Props 表を参照してください）：

LhAvatarProps

export interface LhAvatarProps {
  src?: string
  alt?: string
  icon?: LhIconName
  text?: string
  shape?: LhAvatarComponentShape
  size?: LhAvatarSize
  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
  sx?: LhSxProps
}

LhAvatarSize

export type LhAvatarSize = LhComponentSize

LhAvatarShape

export type LhAvatarShape = LhAvatarComponentShape

LhAvatarComponentShape _{（@lh-ui/share/core/avatar より）}

export type LhAvatarShape = 'circle' | 'square'

LhIconName _{（@lh-ui/share/core/icon (svgs.ts) より）}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

LhComponentSize _{（@lh-ui/share/core/shared より）}

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]