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 ​

접근성 ​

타입 정의 ​

상수 ​