Image 圖片

帶載入失敗佔位的圖片，可選全螢幕預覽（縮放 / 旋轉 / 多圖切換）。原生 loading="lazy" + decoding="async"。

基礎用法

基礎用法

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

<template>
  <!-- 基礎用法 -->
  <LhImage src="https://picsum.photos/240/140" alt="示例图片" width="240" style="width: 240px" />
</template>

<script>
export default {}
</script>

<template>
  <!-- 基礎用法 -->
  <LhImage src="https://picsum.photos/240/140" alt="示例图片" width="240" style="width: 240px" />
</template>

預覽

點選預覽

<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>

<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>

裁切與 lazy 載入

fit 對應原生 object-fit；lazy 開啟原生 lazy 載入（進入視區才載入）。預覽器 LhImageViewer 可獨立使用，接收 images 與 initial-index。

fit 裁切模式

Lazy 載入

<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"
  />
  <!-- Lazy 載入 -->
  <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>

<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"
  />
  <!-- Lazy 載入 -->
  <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 指定初始圖片。

獨立預覽器

<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>

<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	原生 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[]
  /** 原生 lazy 載入（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