Image 画像

読み込み失敗時のプレースホルダーを備えた画像コンポーネントです。全画面プレビュー（拡大・縮小 / 回転 / 複数画像の切り替え）をオプションで利用できます。ネイティブの loading="lazy" + decoding="async" を使用します。

基本的な使い方

vue

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

<template>
  <!-- 基本的な使い方 -->
  <LhImage src="https://picsum.photos/240/140" alt="サンプル画像" width="240" style="width: 240px" />
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- 基本的な使い方 -->
  <LhImage src="https://picsum.photos/240/140" alt="サンプル画像" width="240" style="width: 240px" />
</template>

プレビュー

vue

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

<template>
  <!-- クリックでプレビュー -->
  <LhImage
    src="https://picsum.photos/240/140?random=2"
    alt="プレビュー可能な画像"
    preview
    :preview-src-list="['https://picsum.photos/600/400?random=2', 'https://picsum.photos/600/400?random=3']"
    style="width: 240px"
  />
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- クリックでプレビュー -->
  <LhImage
    src="https://picsum.photos/240/140?random=2"
    alt="プレビュー可能な画像"
    preview
    :preview-src-list="['https://picsum.photos/600/400?random=2', 'https://picsum.photos/600/400?random=3']"
    style="width: 240px"
  />
</template>

クロップと遅延読み込み

fit はネイティブの object-fit に対応します。lazy はネイティブの遅延読み込みを有効にします（ビューポートに入ってから読み込みます）。プレビューア LhImageViewer は独立して使用でき、images と initial-index を受け取ります。

vue

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

<template>
  <!-- fit クロップモード -->
  <LhImage
    v-for="f in ['fill', 'contain', 'cover', 'none', 'scale-down']"
    :key="f"
    src="https://picsum.photos/240/140"
    :alt="`fit=${f}`"
    :fit="f"
    style="width: 110px; height: 80px"
  />
  <!-- 遅延読み込み -->
  <div style="max-height: 120px; overflow-y: auto; width: 100%">
    <LhImage
      v-for="i in 4"
      :key="i"
      :src="`https://picsum.photos/240/120?random=${i}`"
      :alt="`遅延読み込み画像 ${i}`"
      lazy
      style="width: 240px; display: block; margin-bottom: 8px"
    />
  </div>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- fit クロップモード -->
  <LhImage
    v-for="f in ['fill', 'contain', 'cover', 'none', 'scale-down']"
    :key="f"
    src="https://picsum.photos/240/140"
    :alt="`fit=${f}`"
    :fit="f"
    style="width: 110px; height: 80px"
  />
  <!-- 遅延読み込み -->
  <div style="max-height: 120px; overflow-y: auto; width: 100%">
    <LhImage
      v-for="i in 4"
      :key="i"
      :src="`https://picsum.photos/240/120?random=${i}`"
      :alt="`遅延読み込み画像 ${i}`"
      lazy
      style="width: 240px; display: block; margin-bottom: 8px"
    />
  </div>
</template>

スタンドアローンプレビューア

LhImageViewer は LhImage から独立して使用できます。images に画像リストを渡し、initial-index で初期画像を指定します。

vue

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

<template>
  <!-- スタンドアローンプレビューア -->
  <LhImageViewer
    :images="['https://picsum.photos/600/400?random=11', 'https://picsum.photos/600/400?random=12']"
    :initial-index="1"
  >
    <LhButton>画像ギャラリーを開く（2 枚目から）</LhButton>
  </LhImageViewer>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- スタンドアローンプレビューア -->
  <LhImageViewer
    :images="['https://picsum.photos/600/400?random=11', 'https://picsum.photos/600/400?random=12']"
    :initial-index="1"
  >
    <LhButton>画像ギャラリーを開く（2 枚目から）</LhButton>
  </LhImageViewer>
</template>

API

LhImage Props

プロパティ	説明	型	デフォルト値
src	画像のアドレス	`string`	—
alt	代替テキスト（a11y の強い制約。TS 層で必須）	`string`	—
fit	クロップモード（ネイティブの object-fit）	`"contain" \| "cover" \| "fill" \| "none" \| "scale-down"`	`'cover'`
preview	クリックしてプレビュー可能にするかどうか	`boolean`	`false`
previewSrcList	プレビュー画像のリスト（未指定時は [src] に退化）	`string[]`	—
lazy	ネイティブの遅延読み込み（loading="lazy"）	`boolean`	`false`
sx	sx クイックレイアウトプロパティ	`LhSxProps`	—

LhImageViewer Props

プロパティ	説明	型	デフォルト値
images	プレビュー画像のリスト	`string[]`	—
initialIndex	初期にプレビューする画像のインデックス	`number`	`0`
sx	sx クイックレイアウトプロパティ（プレビュー画像に作用）	`LhSxProps`	—

Events

イベント名	説明	コールバック引数
load	画像の読み込み成功時にトリガー	`(event: Event)`
error	画像の読み込み失敗時にトリガー（失敗プレースホルダーに切り替え）	`(event: Event)`

スロット：error（失敗時のプレースホルダー）、placeholder。

LhImageViewer は単独でエクスポートされており、さらに close（プレビューを閉じる。Esc でもトリガー）と switch（画像の切り替え。方向キーを含む）イベントを監視できます。

アクセシビリティ

alt は TS 層で必須とし、代替テキストのない画像を排除します
プレビューアは role="dialog" + aria-modal="true"、フォーカスのトラップ、Esc でのクローズ、方向キーによる画像切り替えに対応します。ツールボタンにはすべて名前が付いています（拡大 / 縮小 / 回転 / 前の画像 / 次の画像 / 閉じる）
回転・拡大縮小のトランジションは prefers-reduced-motion を尊重します

型定義

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

LhImageProps

export interface LhImageProps {
  /** 画像のアドレス */
  src: string
  /** 代替テキスト（a11y の強い制約。TS 層で必須） */
  alt: string
  /** クロップモード（ネイティブの object-fit） */
  fit?: LhImageFit
  /** クリックしてプレビュー可能にするかどうか */
  preview?: boolean
  /** プレビュー画像のリスト（未指定時は [src] に退化） */
  previewSrcList?: string[]
  /** ネイティブの遅延読み込み（loading="lazy"） */
  lazy?: boolean
  /** sx クイックレイアウトプロパティ */
  sx?: LhSxProps
}

LhImageViewerProps

/** プレビューアの props（LhImageViewer は単独でエクスポート） */
export interface LhImageViewerProps {
  /** プレビュー画像のリスト */
  images: string[]
  /** 初期インデックス */
  initialIndex?: number
  /** sx クイックレイアウトプロパティ（プレビュー画像に作用） */
  sx?: LhSxProps
}

LhImageFit _{（@lh-ui/share/core/image より）}

/** 画像のクロップモード（ネイティブの object-fit） */
export type LhImageFit = 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

定数

このコンポーネントで使用される公開定数は以下のとおりです（Props 表の「型 / デフォルト値」列から同名のエントリーをクリックするとここへジャンプします）：

LH_IMAGE_ZOOM_MIN _{（@lh-ui/share/core/image より）}

/** 拡大・縮小の境界 */
export const LH_IMAGE_ZOOM_MIN = 0.25

LH_IMAGE_ZOOM_MAX _{（@lh-ui/share/core/image より）}

export const LH_IMAGE_ZOOM_MAX = 4

LH_IMAGE_ZOOM_STEP _{（@lh-ui/share/core/image より）}

export const LH_IMAGE_ZOOM_STEP = 0.25

Image 画像 ​

基本的な使い方 ​

プレビュー ​

クロップと遅延読み込み ​

スタンドアローンプレビューア ​

API ​

LhImage Props ​

LhImageViewer Props ​

Events ​

アクセシビリティ ​

型定義 ​

定数 ​