Message 전역 메시지

전역 가벼운 피드백으로, 주로 조작 결과를 일회성으로 알립니다. 명령형 서비스 API가 중심(LhMessage.success(...)), 큐는 독립 컨테이너에 렌더링되어 컴포넌트 트리에 의존하지 않으며, 한도를 초과하면 가장 오래된 메시지가 자동으로 제거됩니다.

기본 사용법

vue

<script setup lang="ts">
import { LhMessage } from '@lh-ui/vue3'

const showBasic = () => {
  LhMessage('메시지 알림입니다')
}
</script>

<template>
  <LhButton @click="showBasic">알림 표시</LhButton>
</template>

vue

<script>
import { LhMessage } from '@lh-ui/vue3'

export default {
  methods: {
    showBasic() {
      LhMessage('메시지 알림입니다')
    },
  },
}
</script>

<template>
  <LhButton @click="showBasic">알림 표시</LhButton>
</template>

시맨틱 유형

네 가지 시맨틱 + loading; warning / danger / error는 role="alert"로 즉시 읽히고, 나머지는 부드럽게 읽힙니다.

vue

<script setup lang="ts">
import { LhMessage } from '@lh-ui/vue3'

const showInfo = () => LhMessage.info('정보 알림')
const showSuccess = () => LhMessage.success('저장 성공')
const showWarning = () => LhMessage.warning('위험에 주의하세요')
const showDanger = () => LhMessage.danger('작업 실패')
// loading은 기본적으로 자동으로 닫히지 않으므로 반환된 핸들로 직접 닫습니다
const showLoading = () => {
  const handle = LhMessage.loading('동기화 중…')
  setTimeout(() => handle.close(), 2000)
}
</script>

<template>
  <div class="demo-message-row">
    <LhButton @click="showInfo">정보</LhButton>
    <LhButton @click="showSuccess">성공</LhButton>
    <LhButton @click="showWarning">경고</LhButton>
    <LhButton @click="showDanger">위험</LhButton>
    <LhButton @click="showLoading">로딩 중(수동으로 닫기)</LhButton>
  </div>
</template>

vue

<script>
import { LhMessage } from '@lh-ui/vue3'

export default {
  methods: {
    showInfo() {
      LhMessage.info('정보 알림')
    },
    showSuccess() {
      LhMessage.success('저장 성공')
    },
    showWarning() {
      LhMessage.warning('위험에 주의하세요')
    },
    showDanger() {
      LhMessage.danger('작업 실패')
    },
    // loading은 기본적으로 자동으로 닫히지 않으므로 반환된 핸들로 직접 닫습니다
    showLoading() {
      const handle = LhMessage.loading('동기화 중…')
      setTimeout(() => handle.close(), 2000)
    },
  },
}
</script>

<template>
  <div class="demo-message-row">
    <LhButton @click="showInfo">정보</LhButton>
    <LhButton @click="showSuccess">성공</LhButton>
    <LhButton @click="showWarning">경고</LhButton>
    <LhButton @click="showDanger">위험</LhButton>
    <LhButton @click="showLoading">로딩 중(수동으로 닫기)</LhButton>
  </div>
</template>

닫기와 큐 상한

showClose로 닫기 버튼을 표시합니다; 큐는 기본적으로 최대 5개까지(LhMessage.config({ max })로 조정)이며, 초과 시 가장 오래된 것부터 제거됩니다.

vue

<script setup lang="ts">
import { LhMessage } from '@lh-ui/vue3'

const showClosable = () => LhMessage.success('저장 성공', { showClose: true })
// closeLabel은 닫기 버튼의 접근성 이름을 커스터마이징합니다
const showCloseLabel = () => LhMessage.info('확인해 주세요', { showClose: true, closeLabel: '확인했습니다, 닫기' })
</script>

<template>
  <LhButton @click="showClosable">수동으로 닫기</LhButton>
  <LhButton @click="showCloseLabel">커스텀 닫기 문구</LhButton>
</template>

vue

<script>
import { LhMessage } from '@lh-ui/vue3'

export default {
  methods: {
    showClosable() {
      LhMessage.success('저장 성공', { showClose: true })
    },
    // closeLabel은 닫기 버튼의 접근성 이름을 커스터마이징합니다
    showCloseLabel() {
      LhMessage.info('확인해 주세요', { showClose: true, closeLabel: '확인했습니다, 닫기' })
    },
  },
}
</script>

<template>
  <LhButton @click="showClosable">수동으로 닫기</LhButton>
  <LhButton @click="showCloseLabel">커스텀 닫기 문구</LhButton>
</template>

전역 설정

import { LhMessage } from '@lh-ui/vue3'

LhMessage.config({
  duration: 3000, // 자동으로 닫히는 시간(ms, 0은 자동 닫힘 없음)
  max: 5,         // 큐에 동시에 표시되는 최대 항목 수
  offset: 20,     // 뷰포트 상단으로부터의 오프셋(px)
  appendTo: 'body', // 마운트 컨테이너(선택자 또는 요소)
})

API

LhMessage Props

프로퍼티	설명	타입	기본값
content	메시지 내용	`string`	—
type	시맨틱 유형	`"success" \| "warning" \| "error" \| "info" \| "danger" \| "loading"`	`'info'`
showClose	닫기 버튼 표시 여부	`boolean`	`false`
closeLabel	닫기 버튼의 접근성 이름(넘기지 않으면 언어 팩 `message.close` 사용)	`string`	—
sx	sx 빠른 레이아웃 속성	`LhSxProps`	—

서비스 메서드: LhMessage(options) / LhMessage.success/info/warning/danger/loading(content, options?), { close } 핸들을 반환합니다; 그 외에 LhMessage.close(id), LhMessage.closeAll(), LhMessage.config(options)가 있습니다.

Events

이벤트	설명	콜백 매개변수
close	항목의 닫기 버튼을 클릭할 때 발생	—

명령형 사용에서는 닫기(자동 닫힘과 수동 닫기 포함)를 Options의 onClose 콜백으로 감지합니다.

Options

프로퍼티	설명	타입	기본값
content	메시지 내용	`string`	—
type	시맨틱 유형	`'info' \| 'success' \| 'warning' \| 'danger' \| 'error' \| 'loading'`	`'info'`
duration	자동으로 닫히는 시간(ms), `0`이면 자동 닫힘 없음(loading은 기본 `0`)	`number`	`3000`
showClose	닫기 버튼 표시 여부	`boolean`	`false`
offset	뷰포트 상단으로부터의 오프셋(px)	`number`	`20`
sx	sx 빠른 레이아웃 속성	`LhSxProps`	—
onClose	닫은 이후의 콜백	`() => void`	—

접근성

컨테이너와 항목은 live region입니다: info / success / loading은 role="status"로 부드럽게 읽히고, warning / danger / error는 role="alert"로 즉시 읽힙니다
비차단 설계: 포커스를 옮기지 않고 키보드 흐름을 가리지 않습니다
닫기 버튼에 aria-label이 있습니다(언어 팩 message.close, closeLabel로 덮어쓰기 가능)
애니메이션은 prefers-reduced-motion을 존중합니다

타입 정의

이 컴포넌트가 외부로 노출하는 TypeScript 타입 구조는 다음과 같습니다(packages/components/message/src/types.ts와 @lh-ui/share/core/* 소스에서 자동 추출, 각 항목을 클릭하여 전체 정의를 펼쳐 볼 수 있습니다; 프로퍼티 설명은 위쪽 Props 표를 참고하세요):

LhMessageOptions

/** 서비스 옵션: 문자열 내용 + 표시와 콜백 */
export interface LhMessageOptions {
  /** 메시지 내용 */
  content: string
  /** 시맨틱 유형, 기본값 info */
  type?: LhMessageType
  /** 자동으로 닫히는 시간(ms), 0이면 자동 닫힘 없음(loading은 기본 0, 나머지는 기본 3000) */
  duration?: number
  /** 닫기 버튼 표시 여부 */
  showClose?: boolean
  /** 뷰포트 상단으로부터의 오프셋 px(기본 20) */
  offset?: number
  /** 빠른 레이아웃 속성 */
  sx?: LhSxProps
  /** 닫은 이후(자동 닫힘과 수동 닫기 포함)의 콜백 */
  onClose?: () => void
}

LhMessageHandle

/** 서비스 핸들 */
export interface LhMessageHandle {
  close: () => void
}

LhMessageProps

/** 항목 컴포넌트 props(서비스 내부 렌더링; 선언형으로 단독 사용도 가능) */
export interface LhMessageProps {
  content: string
  type?: LhMessageType
  showClose?: boolean
  /** 닫기 버튼의 접근성 이름(넘기지 않으면 언어 팩 message.close 사용) */
  closeLabel?: string
  sx?: LhSxProps
}

LhMessageConfig

/** 전역 기본 설정 항목(LhMessage.config) */
export interface LhMessageConfig {
  duration?: number
  max?: number
  offset?: number
  /** 마운트 컨테이너(기본값 body) */
  appendTo?: string | HTMLElement
}

LhMessageType _{(출처: @lh-ui/share/core/message)}

/** 메시지 시맨틱 유형(네 가지 시맨틱 + loading) */
export type LhMessageType =
  | (typeof LH_MESSAGE_TYPE_CONST)[keyof typeof LH_MESSAGE_TYPE_CONST]

LhMessageRecord _{(출처: @lh-ui/share/core/message)}

/** 서비스 큐에서 단일 메시지의 레코드 형태 */
export interface LhMessageRecord {
  id: number
  type: LhMessageType
  content: string
  /** 자동으로 닫히는 시간(ms), 0이면 자동 닫힘 없음 */
  duration: number
  showClose: boolean
  /** 뷰포트 상단으로부터의 오프셋 px */
  offset: number
  sx?: LhSxProps
  onClose?: () => void
}

상수

이 컴포넌트에서 사용하는 공개 상수는 다음과 같습니다(Props 표의 타입/기본값 열에서 같은 이름의 항목을 클릭하면 이곳으로 이동합니다):

LH_MESSAGE_TYPE_CONST _{(출처: @lh-ui/share/core/message)}

/** 유형 상수(공통 시맨틱 상수에 loading을 보충) */
export const LH_MESSAGE_TYPE_CONST = {
  ...LH_TYPES_CONST,
  /** @alias 로딩 */
  loading: 'loading',
} as const

LH_MESSAGE_DURATION_DEFAULT _{(출처: @lh-ui/share/core/message)}

/** 기본 자동 닫힘 시간(loading 시맨틱은 자동으로 닫히지 않음) */
export const LH_MESSAGE_DURATION_DEFAULT = 3000

LH_MESSAGE_MAX_DEFAULT _{(출처: @lh-ui/share/core/message)}

/** 큐에 동시에 표시되는 최대 항목 수, 초과 시 가장 오래된 것 제거 */
export const LH_MESSAGE_MAX_DEFAULT = 5

LH_MESSAGE_OFFSET_DEFAULT _{(출처: @lh-ui/share/core/message)}

/** 뷰포트 상단으로부터의 기본 오프셋 px */
export const LH_MESSAGE_OFFSET_DEFAULT = 20

Message 전역 메시지 ​

기본 사용법 ​

시맨틱 유형 ​

닫기와 큐 상한 ​

전역 설정 ​

API ​

LhMessage Props ​

Events ​

Options ​

접근성 ​

타입 정의 ​

상수 ​