JenniferSoft Design Docs

Appearance

v-tooltip 디렉티브 ​

v-tooltip은 DOM 구조에 제약 없이 툴팁 기능을 손쉽게 추가할 수 있도록 설계된 Vue 디렉티브입니다. CloneTooltip 컴포넌트와 달리, 래퍼(wrapper) 컴포넌트로 감싸지 않고 엘리먼트에 직접 툴팁을 바인딩하여 DOM 구조를 변경하지 않는 장점이 있습니다.

기본 사용법 ​

v-tooltip 디렉티브는 툴팁에 표시할 텍스트와 옵션을 포함하는 객체를 값으로 받습니다.

vue
<template>
    <Btn
        v-tooltip="{ text: 'This is a tooltip', placement: 'top' }"
        type="outlined"
        text="Hover me"
    />
</template>

<script setup lang="ts">
import { Btn, vTooltip } from '@jennifersoft/vue-components-v2';
// main.ts 또는 진입점에서 vTooltip을 전역으로 등록해야 합니다.
// import vTooltip from '...';
// app.directive('tooltip', vTooltip);
</script>

다양한 위치의 툴팁 ​

placement 옵션을 사용하여 툴팁의 위치를 자유롭게 지정할 수 있습니다.

 
 
 
vue
<script setup lang="ts">
import { ref } from 'vue';
import { Btn, vTooltip } from '@jennifersoft/vue-components-v2';
const tooltipMessage = ref('...'); // 툴팁 메시지
</script>
<template>
    <div class="flex flex-col gap-8">
        <div class="flex flex-row gap-8">
            <Btn
                v-tooltip="{ text: tooltipMessage, placement: 'top-left' }"
                type="outlined"
                text="Top-Left"
            />
            <Btn
                v-tooltip="{ text: tooltipMessage, placement: 'top' }"
                type="outlined"
                text="Top"
            />
            <Btn
                v-tooltip="{ text: tooltipMessage, placement: 'top-right' }"
                type="outlined"
                text="Top-Right"
            />
        </div>
        <!-- ... other placements ... -->
    </div>
</template>

API ​

v-tooltip 디렉티브에 전달하는 객체(binding.value)의 속성은 다음과 같습니다.

이름타입기본값설명
textstring-(필수) 툴팁에 표시할 텍스트
placement'top' | 'top-left' | ...'top'툴팁이 표시될 위치
maxWidthnumber264툴팁의 최대 너비(px)
overlayStylePartial<CSSStyleDeclaration>{}툴팁 팝업(레이어) 영역에 적용할 인라인 스타일 객체

상세 설명 ​

  • text: 툴팁에 표시할 문자열입니다. 필수 항목입니다.
  • placement: 툴팁이 표시될 위치를 지정합니다. 총 12가지 위치(top, top-left, top-right, bottom, bottom-left, bottom-right, left, left-top, left-bottom, right, right-top, right-bottom)를 지원합니다.
  • maxWidth: 툴팁의 최대 너비를 픽셀 단위로 지정합니다.
  • overlayStyle: 툴팁 팝업(레이어) 영역에 직접 인라인 스타일을 적용할 수 있는 CSSStyleDeclaration의 부분 집합 객체입니다. 예를 들어, { backgroundColor: 'blue', color: 'white' }와 같이 사용할 수 있습니다.

overlayStyle 사용법 ​

overlayStyle 옵션을 사용하여 툴팁의 배경색, 글자색 등 다양한 스타일을 직접 지정할 수 있습니다.

vue
<template>
    <Btn
        v-tooltip="{
            text: '커스텀 툴팁',
            placement: 'top',
            overlayStyle: {
                backgroundColor: 'skyblue',
                color: 'lightgreen',
                border: '3px solid pink',
                padding: '8px 12px',
            },
        }"
        type="outlined"
        text="Styled Tooltip"
    />
</template>

<script setup>
import { Btn, vTooltip } from '@jennifersoft/vue-components-v2';
</script>

CloneTooltip과의 차이점 ​

구분v-tooltip (디렉티브)CloneTooltip (컴포넌트)
형태Vue 디렉티브Vue 컴포넌트
DOM 구조변경 없음. 대상 엘리먼트에 이벤트 리스너만 추가.자식 요소를 복제(clone)하여 래핑.
사용법<div v-tooltip="{...}"></div><CloneTooltip ...><child/></CloneTooltip>
유연성DOM 구조에 영향을 주지 않아 스타일 충돌 위험이 적고, 어느 엘리먼트에나 쉽게 적용 가능.ref가 이미 사용된 컴포넌트에는 적용이 어려운 등 제약이 있음.

사용 사례 ​

v-tooltip은 다음과 같은 상황에서 특히 유용합니다:

  1. 기존 컴포넌트나 엘리먼트의 DOM 구조를 절대 변경하면 안 되는 경우
  2. CSS selector (e.g., first-child, last-child) 스타일에 영향을 주지 않고 툴팁을 추가해야 하는 경우
  3. 메뉴 아이템, 버튼 등 정교한 스타일링이 적용된 여러 요소에 일관되게 툴팁을 적용할 때