컴포넌트/배지

Badge (배지)

VanillaFront 2026. 9. 20. 16:29

Va.Badge — 알림·상태 표시 뱃지 컴포넌트

숫자, 짧은 텍스트, 아이콘, 또는 상태 점을 표시하는 뱃지 컴포넌트입니다. 알림 카운트, 상태 표시, 카테고리 라벨 등에 사용되며, Va.Avatar·Va.Button 등 다른 컴포넌트에 오버레이로 붙기도 합니다.

 

클래스 정보

Va.Badge extends Va.Component
tagName: 'badge' (실제 렌더링은 <span>)
isContainer: false

기본 사용법

숫자 뱃지 (알림 카운트):

{
    tagName: 'badge',
    text: '3',
    color: 'danger'
}

상태 점 (텍스트 없음):

{
    tagName: 'badge',
    color: 'success'
}

아이콘 뱃지:

{
    tagName: 'badge',
    icon: 'ico_checkmark',
    color: 'success'
}

코드로:

let badge = new Va.Badge({ text: 'NEW', color: 'primary' });
parent.append(badge);

속성

속성타입기본값설명

text String — 뱃지 텍스트 (자동 이스케이프)
innerHTML String — HTML 문자열
icon String — 아이콘 클래스 ('ico_xxx')
appearance String 'filled' 외형: 'filled', 'outline'
color String — 시맨틱 색상 or 커스텀 색상 (아래 참조)
backgroundColor String — 커스텀 배경색
iconColor String — 아이콘 색상
shape String 'circular' 모양
size String — xsmall, small, medium, large
actived Boolean false 활성 상태 표시
disabled Boolean false 비활성 (회색 처리)
stopPropagation Boolean true 이벤트 전파 차단

color — 시맨틱 색상 6종

값이 시맨틱 키워드면 테마 색상 자동 적용:

color용도대표 색

'primary' 강조 파랑 계열
'danger' 위험/에러 빨강
'important' 중요 주황
'info' 정보 하늘색
'success' 성공 초록
'warning' 경고 노랑

시맨틱 키워드가 아니면 커스텀 색상으로 처리:

{ tagName: 'badge', text: 'HOT', color: '#FF00FF' }  // 자유 색

appearance 두 가지

값결과

'filled' (기본) 배경색 채움
'outline' 테두리만 (배경 투명)

이벤트

이벤트발생 시점콜백 인자

click 클릭 시 (sender, element, evt)
contextmenu 우클릭 시 (sender, element, evt)

disabled: true이면 클릭 이벤트 dispatch 안 됨.
stopPropagation: true(기본)이면 부모로 이벤트 안 올라감.

메서드

  • setText(text) — 텍스트 변경
  • setInnerHTML(html) — HTML 변경
  • setIcon(icon) — 아이콘 변경
  • setBackgroundColor(color) — 배경색 변경
  • setActive(actived) — 활성 상태 변경

내부 구조

<span class="va-badge filled danger">
    <div class="badge-inner" elname="inner">
        <span class="icon" elname="icon"></span>  <!-- icon 지정 시 -->
        <span elname="text">3</span>              <!-- text 지정 시 -->
    </div>
</span>

사용 시점 — 언제 쓰나

  • 알림 카운트 — 메시지 3건, 알림 5건 등
  • 상태 표시 점 — 온라인/오프라인, 활성/비활성
  • 카테고리 라벨 — "NEW", "HOT", "SALE"
  • 다른 컴포넌트 오버레이 — Avatar 우하단, Button 상단
  • 폴더/파일 카운트 — 트리에서 "문서 (12)" 표시

사용하지 말아야 할 때

  • 긴 텍스트/설명 → Va.Tag 또는 Va.Label
  • 버튼 역할 → Va.Button
  • 아이콘만 → Va.I
  • 상태 배너 → Va.SearchPanel 상단 배너 등

자주 쓰는 조합 예시

알림 카운트 (단독)

{
    tagName: 'div',
    layout: 'ds-flex fd-row ai-center gap-s',
    tags: [
        { tagName: 'i', icon: 'ico_bell', size: 'large' },
        { tagName: 'span', text: '알림' },
        { tagName: 'badge', text: '3', color: 'danger' }
    ]
}

상태 점

{
    tagName: 'div',
    layout: 'ds-flex fd-row ai-center gap-xs',
    tags: [
        { tagName: 'badge', color: 'success' },   // 초록 점 (온라인)
        { tagName: 'span', text: user.name }
    ]
}

카테고리 라벨 (NEW/HOT)

{
    tagName: 'div',
    layout: 'ds-flex fd-row ai-center gap-s',
    tags: [
        { tagName: 'title', innerHTML: '신규 상품' },
        { tagName: 'badge', text: 'NEW', color: 'primary' },
        { tagName: 'badge', text: 'HOT', color: 'danger' }
    ]
}

Avatar 위 오버레이 뱃지 (Avatar 내장 사용)

{
    tagName: 'avatar',
    image: user.photo,
    badgeVisible: true,
    badge: {
        text: '3',
        color: 'danger',
        size: 'xsmall'
    }
}

Button의 badge 속성 (Button 내장 사용)

{
    tagName: 'button',
    text: '메시지',
    icon: 'ico_message',
    badge: {
        text: '5',
        color: 'danger'
    }
}

Outline 스타일 (강조 낮춤)

{
    tagName: 'badge',
    text: 'BETA',
    color: 'info',
    appearance: 'outline'
}

아이콘 뱃지 (완료 표시)

{
    tagName: 'badge',
    icon: 'ico_checkmark',
    color: 'success'
}

커스텀 색상

{
    tagName: 'badge',
    text: 'PREMIUM',
    color: '#FFD700',
    backgroundColor: '#8B4513'
}

클릭 가능한 뱃지 (필터)

{
    tagName: 'div',
    layout: 'ds-flex fd-row gap-xs',
    tags: categories.map(cat => ({
        tagName: 'badge',
        text: cat.name,
        color: this.selected === cat.id ? 'primary' : undefined,
        appearance: this.selected === cat.id ? 'filled' : 'outline',
        key: cat.id,
        onClick: 'onClickCategory',
        style: { cursor: 'pointer' }
    }))
}

비활성 뱃지 (회색)

{
    tagName: 'badge',
    text: '5',
    color: 'danger',
    disabled: true
}

실전 예시 — 메뉴 아이템 카운트

config(){
    return {
        tagName: 'menu',
        tags: [{
            tagName: 'menuItem',
            text: '받은편지함',
            icon: 'ico_inbox',
            tags: [{
                tagName: 'badge',
                text: String(this.unreadCount),
                color: this.unreadCount > 0 ? 'danger' : 'info',
                size: 'small'
            }]
        },{
            tagName: 'menuItem',
            text: '알림',
            icon: 'ico_bell',
            tags: [{
                tagName: 'badge',
                color: 'success'  // 상태 점만 (텍스트 없음)
            }]
        },{
            tagName: 'menuItem',
            text: '설정',
            icon: 'ico_settings'
        }]
    };
}

주의사항

  • isContainer: false — 자식 태그를 직접 넣을 수 없음
  • 텍스트 없이 색상만 — 상태 점 UI로 활용 가능 (text 생략)
  • 아이콘 우선순위 — icon 지정 시 padding 자동 0 (아이콘이 뱃지 전체 채움)
  • 시맨틱 color 6종은 CSS 클래스로 처리 — 그 외 값은 style로 직접 설정
  • stopPropagation 기본 true — 리스트 아이템 위 뱃지 클릭 시 부모 클릭 안 발생. 필요하면 false
  • 크기가 매우 작음 — 시맨틱 색상만 사용할 땐 폰트 색 대비 확인 (특히 warning 노란색)
  • 뱃지 여러 개 나열 시 gap 주기 — 기본 간격 없음, layout: 'ds-flex fd-row gap-xs' 명시
  • Avatar/Button 내장 badge 옵션과 구분 — 이 컴포넌트들은 내부적으로 Va.Badge를 생성해 오버레이. 개별 배치 원하면 별도 Va.Badge 사용
  • 긴 텍스트 부적합 — 3~5자 이내가 시각적으로 자연스러움. 긴 텍스트는 Va.Tag

Badge vs Tag vs Label 비교

컴포넌트용도특징

Va.Badge 알림 카운트, 상태 점, 짧은 라벨 작고 원형/타원, 색상 강조
Va.Tag 카테고리, 필터 태그 중간 크기, 편집/삭제 가능
Va.Label 필드 라벨, 일반 텍스트 순수 텍스트, 스타일 최소

대안 비교

상황추천

알림 카운트/상태 점 Va.Badge
카테고리 필터 태그 Va.Tag
필드 라벨 Va.Label
상세 안내 배너 Va.SearchPanel 상단
강조 텍스트 (문장 내) Va.Span + style
아이콘만 Va.I

참고