lh-ui-plus

한국어

简体中文
English
繁體中文
日本語
Español
العربية
Français
Русский

한국어

简体中文
English
繁體中文
日本語
Español
العربية
Français
Русский

테마

API 风格：

Tooltip 툴팁 ​

마우스를 올렸을 때 추가 정보를 표시하는 텍스트 툴팁 컴포넌트입니다.

기본 사용법 ​

기본 사용법
vue
<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- 기본 사용법 -->
  <LhTooltip content="이것은 툴팁 메시지입니다">
    <LhButton>마우스 올려 툴팁 표시</LhButton>
  </LhTooltip>
</template>
vue
<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- 기본 사용법 -->
  <LhTooltip content="이것은 툴팁 메시지입니다">
    <LhButton>마우스 올려 툴팁 표시</LhButton>
  </LhTooltip>
</template>

다양한 위치 ​

다양한 위치
vue
<script setup lang="ts">
</script>

<template>
  <!-- 위 -->
  <LhTooltip content="위쪽 툴팁" placement="top">
    <LhButton>위</LhButton>
  </LhTooltip>
  <!-- 아래 -->
  <LhTooltip content="아래쪽 툴팁" placement="bottom">
    <LhButton>아래</LhButton>
  </LhTooltip>
  <!-- 왼쪽 -->
  <LhTooltip content="왼쪽 툴팁" placement="left">
    <LhButton>왼쪽</LhButton>
  </LhTooltip>
  <!-- 오른쪽 -->
  <LhTooltip content="오른쪽 툴팁" placement="right">
    <LhButton>오른쪽</LhButton>
  </LhTooltip>
</template>
vue
<script>
export default {}
</script>

<template>
  <!-- 위 -->
  <LhTooltip content="위쪽 툴팁" placement="top">
    <LhButton>위</LhButton>
  </LhTooltip>
  <!-- 아래 -->
  <LhTooltip content="아래쪽 툴팁" placement="bottom">
    <LhButton>아래</LhButton>
  </LhTooltip>
  <!-- 왼쪽 -->
  <LhTooltip content="왼쪽 툴팁" placement="left">
    <LhButton>왼쪽</LhButton>
  </LhTooltip>
  <!-- 오른쪽 -->
  <LhTooltip content="오른쪽 툴팁" placement="right">
    <LhButton>오른쪽</LhButton>
  </LhTooltip>
</template>

사용자 정의 지연 ​

사용자 정의 지연
vue
<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- 1초 지연 표시 -->
  <LhTooltip content="1초 지연 표시" :show-after="1000">
    <LhButton>지연 툴팁</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="진입 300ms 후 표시, 이탈 500ms 후 숨김" :open-delay="300" :close-delay="500">
    <LhButton>open-delay / close-delay</LhButton>
  </LhTooltip>
</template>
vue
<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- 1초 지연 표시 -->
  <LhTooltip content="1초 지연 표시" :show-after="1000">
    <LhButton>지연 툴팁</LhButton>
  </LhTooltip>
  <!-- open-delay / close-delay -->
  <LhTooltip content="진입 300ms 후 표시, 이탈 500ms 후 숨김" :open-delay="300" :close-delay="500">
    <LhButton>open-delay / close-delay</LhButton>
  </LhTooltip>
</template>

국제화 ​

툴팁 텍스트는 LhConfigProvider와 언어 패를 조합해 국제화 전환을 구현할 수 있습니다.

국제화
vue
<script setup lang="ts">
import { ref } from 'vue'
import { LhConfigProvider, LhTooltip, LhButton, enUS } from '@lh-ui/vue3'
import koKR from '@lh-ui/share/locales/lang/ko-KR'

const locale = ref('ko-KR')
</script>

<template>
  <!-- ConfigProvider로 언어 패 전환 -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhTooltip :content="locale === 'zh-CN' ? '中文提示' : 'English Tooltip'">
      <LhButton>Tooltip</LhButton>
    </LhTooltip>
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>
vue
<script>
import { LhConfigProvider, LhTooltip, LhButton, enUS } from '@lh-ui/vue3'
import koKR from '@lh-ui/share/locales/lang/ko-KR'

export default {
  components: { LhConfigProvider, LhTooltip, LhButton },
  data() {
    return {
      locale: 'ko-KR',
      koKR: koKR,
      enUS: enUS,
    }
  },
}
</script>

<template>
  <!-- ConfigProvider로 언어 패 전환 -->
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhTooltip :content="locale === 'zh-CN' ? '中文提示' : 'English Tooltip'">
      <LhButton>Tooltip</LhButton>
    </LhTooltip>
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>

sx 빠른 레이아웃 ​

sx 속성으로 트리거 루트 요소의 여백과 크기를 빠르게 조정할 수 있으며, 추가 CSS를 작성할 필요가 없습니다.

sx 여백 레이아웃
vue
<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- sx 여백 레이아웃 -->
  <LhTooltip content="sx는 트리거 루트 요소에 적용됩니다" :sx="{ mt: 2, ml: 2 }">
    <LhButton type="primary">위쪽 여백 2, 왼쪽 여백 2</LhButton>
  </LhTooltip>
</template>
vue
<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- sx 여백 레이아웃 -->
  <LhTooltip content="sx는 트리거 루트 요소에 적용됩니다" :sx="{ mt: 2, ml: 2 }">
    <LhButton type="primary">위쪽 여백 2, 왼쪽 여백 2</LhButton>
  </LhTooltip>
</template>

sx는 8px 기준으로 동작합니다: mt: 2 → marginTop: 16px, ml: 2 → marginLeft: 16px. 전체 속성은 sx 빠른 레이아웃을 참고하세요.

트리거 방식과 상태 ​

trigger로 트리거 방식을 지정합니다. disabled는 툴팁을 비활성화하고, manual과 visible을 함께 사용해 수동으로 표시를 제어하며, hideAfter로 지연 숨김을 제어합니다.

트리거 방식과 상태
vue
<script setup lang="ts">
import { ref } from 'vue'
import { LhTooltip, LhButton } from '@lh-ui/vue3'

const manualVisible = ref(false)
</script>

<template>
  <!-- 클릭 트리거 -->
  <LhTooltip content="클릭하여 트리거" trigger="click">
    <LhButton>클릭 트리거</LhButton>
  </LhTooltip>
  <!-- 포커스 트리거 -->
  <LhTooltip content="포커스로 트리거" trigger="focus">
    <LhButton>포커스 트리거</LhButton>
  </LhTooltip>
  <!-- 비활성화된 툴팁 -->
  <LhTooltip content="비활성화된 툴팁" disabled>
    <LhButton type="info" disabled>비활성화</LhButton>
  </LhTooltip>
  <!-- 수동 제어 -->
  <LhTooltip content="수동 제어" manual :visible="manualVisible">
    <LhButton @click="manualVisible = !manualVisible">수동 전환</LhButton>
  </LhTooltip>
  <!-- 지연 숨김 -->
  <LhTooltip content="1초 지연 숨김" :hide-after="1000">
    <LhButton>지연 숨김</LhButton>
  </LhTooltip>
</template>
vue
<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
  data() {
    return {
      manualVisible: false,
    }
  },
}
</script>

<template>
  <!-- 클릭 트리거 -->
  <LhTooltip content="클릭하여 트리거" trigger="click">
    <LhButton>클릭 트리거</LhButton>
  </LhTooltip>
  <!-- 포커스 트리거 -->
  <LhTooltip content="포커스로 트리거" trigger="focus">
    <LhButton>포커스 트리거</LhButton>
  </LhTooltip>
  <!-- 비활성화된 툴팁 -->
  <LhTooltip content="비활성화된 툴팁" disabled>
    <LhButton type="info" disabled>비활성화</LhButton>
  </LhTooltip>
  <!-- 수동 제어 -->
  <LhTooltip content="수동 제어" manual :visible="manualVisible">
    <LhButton @click="manualVisible = !manualVisible">수동 전환</LhButton>
  </LhTooltip>
  <!-- 지연 숨김 -->
  <LhTooltip content="1초 지연 숨김" :hide-after="1000">
    <LhButton>지연 숨김</LhButton>
  </LhTooltip>
</template>

openDelay / closeDelay는 각각 showAfter / hideAfter의 별칭이므로, 선호에 따라 선택해 사용할 수 있습니다.

테마와 외관 ​

effect로 라이트/다크 테마를 전환하고, bgColor로 배경색을 지정하며, maxWidth로 최대 너비를 제한하고, teleportTarget으로 팝업 레이어의 마운트 위치를 지정할 수 있습니다.

테마와 외관
vue
<script setup lang="ts">
import { LhTooltip, LhButton } from '@lh-ui/vue3'
</script>

<template>
  <!-- 다크 테마 -->
  <LhTooltip content="다크 테마" effect="dark">
    <LhButton>다크 테마</LhButton>
  </LhTooltip>
  <!-- 라이트 테마 -->
  <LhTooltip content="라이트 테마" effect="light">
    <LhButton>라이트 테마</LhButton>
  </LhTooltip>
  <!-- 사용자 정의 배경색 -->
  <LhTooltip content="사용자 정의 배경색" bg-color="#5a3fa8">
    <LhButton>사용자 정의 배경색</LhButton>
  </LhTooltip>
  <!-- 최대 너비 -->
  <LhTooltip content="이 텍스트는 길어서 maxWidth에 의해 160px 내에서 자동으로 줄바꿈되어 표시됩니다" :max-width="160">
    <LhButton>최대 너비 160px</LhButton>
  </LhTooltip>
  <!-- 사용자 정의 마운트 지점 -->
  <LhTooltip content="#app에 마운트되는 팝업 레이어" teleport-target="#app">
    <LhButton>사용자 정의 마운트 지점</LhButton>
  </LhTooltip>
</template>
vue
<script>
import { LhTooltip, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhTooltip, LhButton },
}
</script>

<template>
  <!-- 다크 테마 -->
  <LhTooltip content="다크 테마" effect="dark">
    <LhButton>다크 테마</LhButton>
  </LhTooltip>
  <!-- 라이트 테마 -->
  <LhTooltip content="라이트 테마" effect="light">
    <LhButton>라이트 테마</LhButton>
  </LhTooltip>
  <!-- 사용자 정의 배경색 -->
  <LhTooltip content="사용자 정의 배경색" bg-color="#5a3fa8">
    <LhButton>사용자 정의 배경색</LhButton>
  </LhTooltip>
  <!-- 최대 너비 -->
  <LhTooltip content="이 텍스트는 길어서 maxWidth에 의해 160px 내에서 자동으로 줄바꿈되어 표시됩니다" :max-width="160">
    <LhButton>최대 너비 160px</LhButton>
  </LhTooltip>
  <!-- 사용자 정의 마운트 지점 -->
  <LhTooltip content="#app에 마운트되는 팝업 레이어" teleport-target="#app">
    <LhButton>사용자 정의 마운트 지점</LhButton>
  </LhTooltip>
</template>

Tooltip API ​

Props ​

속성명설명타입기본값
content툴팁 내용string''
placement툴팁 위치"top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end"'top'
trigger트리거 방식"hover" | "click" | "focus"'hover'
disabled비활성화 여부booleanfalse
manual수동 표시 제어 여부booleanfalse
visible수동 제어 시 표시 상태boolean—
showAfter표시 지연 시간(ms)number0
hideAfter숨김 지연 시간(ms)number0
openDelay표시 지연 시간(ms), showAfter의 별칭number—
closeDelay닫기 지연number—
effect테마"dark" | "light"'dark'
type내장 테마 색상 타입 (effect의 배경색을 덮어씁니다)"primary" | "success" | "warning" | "danger" | "info"—
bgColor사용자 정의 배경색 (effect와 type의 배경색을 덮어씁니다)string—
maxWidth최대 너비string | number'200px'
teleportTargetTeleport 대상 (선택자 또는 요소, 기본값 body)string | HTMLElement'body'
themeVars컴포넌트 수준 테마 변수, ConfigProvider 설정을 덮어씁니다{ [x: string]: string; }—
bgPattern컴포넌트 수준 배경 문양, ConfigProvider 설정을 덮어씁니다string—
sxsx 빠른 레이아웃 속성 (트리거 루트 요소에 적용)LhSxProps—

참고: trigger의 'click' 값은 아직 구현되지 않았습니다 (동작은 'hover'와 동일). 클릭 전환은 향후 버전에서 제공될 예정입니다.

Slots ​

슬롯명설명
default툴팁을 트리거하는 요소 (툴팁 본문은 content 속성으로 설정)

Methods ​

ref를 통해 컴포넌트가 노출하는 메서드를 호출할 수 있습니다:

메서드명설명
show즉시 툴팁을 표시합니다
hide즉시 툴팁을 숨깁니다
toggle툴팁 표시 상태를 전환합니다

접근성 ​

  • 팝업 레이어에는 role="tooltip"이 부여됩니다. 표시 시 트리거 루트 요소에 팝업 레이어를 가리키는 aria-describedby가 자동으로 설정되고, 숨김 시 자동으로 제거되어 빈 참조가 남지 않습니다
  • 키보드 접근성: hover / focus 트리거 방식에서는 키보드 포커스가 트리거에 들어올 때(focusin) 툴팁이 표시되고, 포커스가 벗어나면 자동으로 숨겨져 WAI-ARIA APG의 툴팁 패턴에 부합합니다. click 트리거 방식은 포커스에 반응하지 않습니다
  • 트리거 안에는 포커스 가능한 요소(버튼, 링크 등)를 배치해야 합니다. 순수 텍스트는 키보드로 포커스할 수 없어 키보드 사용자가 툴팁에 도달할 수 없습니다

타입 정의 ​

이 컴포넌트가 외부로 내보내는 TypeScript 타입 구조는 다음과 같습니다 (packages/components/tooltip/src/types.ts와 @lh-ui/share/core/* 소스에서 자동 추출되었습니다. 각 항목을 클릭하여 펼쳐 보세요. 속성 설명은 위쪽 Props 표를 참고하세요):

LhTooltipPlacement
ts
/**
 * Tooltip 타입
 */
export type LhTooltipPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'
LhTooltipTrigger
ts
export type LhTooltipTrigger = 'hover' | 'click' | 'focus'
LhTooltipEffect
ts
export type LhTooltipEffect = 'dark' | 'light'
LhTooltipType
ts
export type LhTooltipType = 'primary' | 'success' | 'warning' | 'danger' | 'info'
LhTooltipProps
ts
/**
 * Tooltip 컴포넌트 Props
 */
export interface LhTooltipProps {
  /** 툴팁 텍스트 내용 */
  content?: string
  /** 표시 위치 */
  placement?: LhTooltipPlacement
  /** 트리거 방식 */
  trigger?: LhTooltipTrigger
  /** 비활성화 여부 */
  disabled?: boolean
  /** 수동 표시 제어 여부 */
  manual?: boolean
  /** 수동 제어 시 표시 상태 */
  visible?: boolean
  /** 표시 지연 시간(ms) */
  showAfter?: number
  /** 숨김 지연 시간(ms) */
  hideAfter?: number
  /** 표시 지연 시간(ms), showAfter의 별칭 */
  openDelay?: number
  /** 닫기 지연 */
  closeDelay?: number
  /** 테마 */
  effect?: LhTooltipEffect
  /** 내장 테마 색상 타입 (effect의 배경색을 덮어씀) */
  type?: LhTooltipType
  /** 사용자 정의 배경색 (effect와 type의 배경색을 덮어씀) */
  bgColor?: string
  /** 최대 너비 */
  maxWidth?: string | number
  /** Teleport 대상 (선택자 또는 요소, 기본값 body) */
  teleportTarget?: string | HTMLElement
  /** 컴포넌트 수준 테마 변수, ConfigProvider 설정을 덮어씀 */
  themeVars?: Record<string, string>
  /** 컴포넌트 수준 배경 문양, ConfigProvider 설정을 덮어씀 */
  bgPattern?: string
  /** sx 빠른 레이아웃 속성 (트리거 루트 요소에 적용) */
  sx?: LhSxProps
}

국풍의 아름다움으로 코드의 토대를 세웁니다

Copyright © 2024-2026 FengMo WenXue