컴포넌트/아이콘, 이미지

Avatar (아바타)

VanillaFront 2026. 9. 20. 16:18

Va.Avatar — 사용자 표현 아바타 컴포넌트

사용자를 아이콘, 이니셜, 또는 이미지로 표현하는 아바타 컴포넌트입니다. 원형/사각형 모양, 활성 상태 표시, 뱃지 오버레이 기능을 내장하며 SNS/협업 UI에 최적화되어 있습니다.

 

클래스 정보

Va.Avatar extends Va.Component
tagName: 'avatar' (실제 렌더링은 <span>)
isContainer: false
파일: va_avatar.js (별도 모듈)

기본 사용법

이미지 아바타 (프로필 사진):

{
    tagName: 'avatar',
    image: './assets/img/user.jpg',
    size: 'medium'
}

이니셜 아바타 (사진 없을 때):

{
    tagName: 'avatar',
    initial: 'HG',
    backgroundColor: 'var(--colorPrimary)',
    color: 'white'
}

아이콘 아바타 (익명/시스템):

{
    tagName: 'avatar',
    icon: 'ico_person_fill'
}

세 가지 표시 모드

Avatar는 image → initial → icon 우선순위로 하나만 표시:

모드속성용도

이미지 image 실제 프로필 사진이 있을 때
이니셜 initial 이름 첫 글자로 자동 생성 (사진 없을 때)
아이콘 icon 익명/시스템/봇 사용자 표현

세 속성을 동시에 설정하면 update()에서 우선순위대로 하나만 렌더링됩니다.

속성

속성타입기본값설명

image String — 이미지 URL
initial String — 이니셜 텍스트 (예: 'HG')
icon String — 아이콘 클래스 (예: 'ico_person_fill')
shape String 'circular' 'circular' 또는 'square'
size String — xsmall, small, medium, large, xlarge
color String — 전경색 (텍스트/아이콘 색)
backgroundColor String — 배경색 (컨텐츠 영역)
actived Boolean false 활성 상태 표시 (초록 점 등)
badgeVisible Boolean false 뱃지 오버레이 표시 여부
badge Object — 내부 Va.Badge 옵션
iconSize String — 아이콘 크기 클래스
stopPropagation Boolean true 클릭 이벤트 전파 차단

이벤트

이벤트발생 시점콜백 인자

click 아바타 클릭 (sender, element, evt)
contextmenu 우클릭 (sender, element, evt)
badgeClick 뱃지 클릭 (sender, element, evt)
badgeContextmenu 뱃지 우클릭 (sender, element, evt)
focus 포커스 (sender, element, evt)
blur 포커스 해제 (sender, element, evt)

클릭 시 자동 토글: actived 상태가 클릭마다 자동으로 반전됩니다 (선택/취소).

메서드

  • setImage(image) — 이미지 설정 (다른 모드 초기화)
  • setInitial(initial) — 이니셜 설정
  • setIcon(icon) — 아이콘 설정
  • setColor(color) — 전경색 변경
  • setBackgroundColor(color) — 배경색 변경
  • showBadge() / hideBadge() — 뱃지 토글
  • active() / inactive() — 활성 상태 제어
  • setActived(actived) — 활성 상태 설정
  • isActive() — 활성 여부 반환
  • show() / hide() — 표시/숨김
  • focus() / blur() — 포커스 제어

내부 구조

<span class="va-avatar circular" tabIndex="0">
    <div class="content" elname="content">
        <span class="icon avatar-icon ico_person_fill" elname="icon"></span>
        <!-- 또는 -->
        <span class="char">HG</span>
        <!-- 또는 -->
        <span class="img" style="background-image: url('...')"></span>
    </div>
    <div class="active" elname="active"></div>  <!-- actived 시 표시 -->
    <span class="va-badge">...</span>            <!-- badge -->
</span>

자주 쓰는 조합 예시

프로필 사진 (원형)

{
    tagName: 'avatar',
    image: user.avatarUrl,
    shape: 'circular',
    size: 'medium'
}

이니셜 아바타 + 컬러

{
    tagName: 'avatar',
    initial: 'HG',
    backgroundColor: '#FF6B6B',
    color: 'white',
    size: 'large'
}

활성 표시 (온라인 상태)

{
    tagName: 'avatar',
    image: user.photo,
    actived: user.isOnline
}

뱃지 붙이기 (알림 카운트)

{
    tagName: 'avatar',
    image: user.photo,
    badgeVisible: true,
    badge: {
        text: '3',
        appearance: 'danger'
    },
    onBadgeClick: 'onClickNotifications'
}

사각형 아바타

{
    tagName: 'avatar',
    initial: 'AB',
    shape: 'square',
    backgroundColor: 'var(--colorPrimary)',
    color: 'white'
}

동적으로 이미지 로드 실패 처리

config(){
    return {
        ref: 'refAvatar',
        tagName: 'avatar',
        image: user.photoUrl
    };
}
mounted(){
    let avatar = this.getRef('refAvatar');
    // 이미지 실패 시 이니셜로 폴백
    if (!user.photoUrl) {
        avatar.setInitial(user.name.substring(0, 2));
        avatar.setBackgroundColor('#4A90E2');
    }
}

실전 예시 — 사용자 리스트

config(){
    return {
        tagName: 'section',
        layout: 'ds-flex fd-column gap-s',
        tags: this.users.map(user => ({
            tagName: 'div',
            layout: 'ds-flex fd-row ai-center gap-m',
            style: { padding: '10px' },
            tags: [{
                tagName: 'avatar',
                image: user.photoUrl,
                initial: user.name.substring(0, 2),  // 이미지 없으면 이니셜로 fallback (프레임워크 자동은 아니므로 조건부 처리 권장)
                backgroundColor: user.color,
                color: 'white',
                actived: user.isOnline,
                size: 'medium'
            },{
                tagName: 'div',
                style: { flex: 1 },
                tags: [
                    { tagName: 'title', innerHTML: user.name },
                    { tagName: 'subTitle', innerHTML: user.status }
                ]
            }]
        }))
    };
}

관련 컴포넌트

Va.AvatarGroup — 아바타 그룹

여러 아바타를 겹쳐 표시하며, 지정 개수 초과 시 +N 팝업으로 오버플로우:

let group = new Va.AvatarGroup({
    stackSize: 4,          // 최대 표시 개수
    layout: 'stack'        // 'spread' 또는 'stack'
});
users.forEach(user => {
    group.append(new Va.Avatar({ image: user.photo }));
});
// 5명째부터 자동으로 '+N' 팝업에 들어감

주요 이벤트: expand (팝업 열림), collapse (팝업 닫힘)

Va.Persona — 아바타 + 이름/설명 조합

아바타와 함께 이름·직책·부서 등 텍스트를 조합해 표시:

{
    tagName: 'persona',
    title: '홍길동',
    detail: '개발팀장',
    textPosition: 'right',    // 'top'/'bottom'/'left'/'right'
    avatar: {
        image: user.photo,
        size: 'medium'
    }
}

주요 이벤트: click, avatarClick, badgeClick

주의사항

  • isContainer: false — 자식 태그를 직접 넣을 수 없음
  • 세 모드 중 하나만 표시 — image/initial/icon 우선순위대로 하나만
  • 클릭 시 자동 actived 토글 — 원치 않으면 클릭 핸들러에서 setActived()로 원복 필요
  • 이미지 로드 실패 자동 폴백 없음 — 이미지 URL이 무효할 때 자동으로 이니셜로 넘어가지 않음. 애플리케이션에서 사전 체크 필요
  • 뱃지는 우하단 고정 — position: absolute + right:0% + bottom:0% (커스터마이징 시 style로 override)
  • stopPropagation 기본 true — 아바타 클릭이 부모로 버블링 안 됨. 리스트 아이템 전체 클릭도 필요하면 stopPropagation: false
  • AvatarGroup의 add()는 append() 별칭 — 둘 다 사용 가능
  • AvatarGroup 팝업 위치는 아바타 상단 — 화면 최상단에서 잘리면 popover 스크롤

대안 비교

상황추천

개별 사용자 표시 Va.Avatar
여러 사용자 그룹 표시 Va.AvatarGroup
아바타 + 이름/역할 Va.Persona
단순 이미지 표시 Va.Image
아이콘 표시 Va.I
알림 뱃지만 필요 Va.Badge

참고