Avatar#

사용자 프로필 이미지 또는 이니셜을 표시하는 아바타 컴포넌트입니다.

Live Preview#

class AvatarDefaultExample extends StatefulComponent {
  const AvatarDefaultExample({super.key});

  @override
  State<AvatarDefaultExample> createState() => _AvatarDefaultExampleState();
}

class _AvatarDefaultExampleState extends State<AvatarDefaultExample> {
  @override
  Component build(BuildContext context) {
    return CoAvatar(
      initials: 'AB',
    );
  }
}

class AvatarDefaultExample extends StatefulWidget {
  const AvatarDefaultExample({super.key});

  @override
  State<AvatarDefaultExample> createState() => _AvatarDefaultExampleState();
}

class _AvatarDefaultExampleState extends State<AvatarDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return const CoAvatar(
      initials: 'AB',
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 사용자 프로필 이미지 또는 이니셜을 표시할 때
• 댓글, 채팅, 팀 멤버 목록에서 사용자를 시각적으로 식별할 때
• 온라인/오프라인 상태를 함께 표시해야 할 때

대신 다른 컴포넌트를 사용하세요:

• Icon: 사용자가 아닌 일반 아이콘을 표시할 때
• Badge: 텍스트 레이블이 필요한 상태 표시일 때
• Image: 프로필이 아닌 일반 이미지를 표시할 때

기본 사용법 (Basic Usage)#

// 이미지 아바타
CoAvatar(
  imageUrl: 'https://example.com/photo.jpg',
  size: CoreComponentSize.md,
)

// 이니셜 아바타
CoAvatar(
  initials: '홍',
  size: CoreComponentSize.lg,
)

// 링 효과
CoAvatar(
  imageUrl: user.photoUrl,
  ring: true,
)

// 커스텀 child
CoAvatar(
  size: CoreComponentSize.sm,
  child: Icon(Icons.person),
)

// 이미지 아바타
CoAvatar(
  imageUrl: 'https://example.com/photo.jpg',
  size: CoreComponentSize.md,
)

// 이니셜 아바타
CoAvatar(
  initials: '홍',
  size: CoreComponentSize.lg,
)

// 링 효과
CoAvatar(
  imageUrl: 'https://example.com/photo.jpg',
  size: CoreComponentSize.md,
  ring: true,
)

// 커스텀 child
CoAvatar(
  size: CoreComponentSize.sm,
  child: text('JD'),
)

Props / Parameters#

스타일 시스템 (Style System)#

Avatar 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreAvatarStyle<Clr> 단일 슬롯으로 흐릅니다 (Epic #1302 원칙 6/7/8). 시맨틱 enum (size) 과 behaviour (ring / badge / imageUrl / initials) 는 위젯 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯 파라미터로 직접 (size, ring, imageUrl, initials, child, badge, badgeAlignment, badgeGap)
• chrome / dimensional / 슬롯 스타일: CoreAvatarStyle 한 곳으로 (backgroundColor / foregroundColor / borderRadius / ringColor / ringWidth / fallbackTextStyle)

Resolve chain#

design system default for avatar
  → CoreAvatarTheme.style                  // 프로젝트 공통
  → parent component slot override
  → widget.avatarStyle                     // 인스턴스별

fallbackTextStyle 슬롯은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

슬롯 매핑 (CoreAvatarStyle 6 필드)#

Migration — 옛 평면 chrome → 새 위치 매핑#

backgroundColor prop 은 호환을 위해 유지되지만 새 코드에서는 avatarStyle.backgroundColor 사용을 권장합니다.

사용 예 (Flutter)#

CoAvatar(
  initials: 'JD',
  ring: true,
  avatarStyle: CoreAvatarStyle(
    backgroundColor: Color(0xFF3B82F6),
    foregroundColor: Colors.white,
    ringColor: Color(0xFFE11D48),
    ringWidth: 3,
    fallbackTextStyle: CoreTextStyle(fontWeight: 700),
  ),
)

사용 예 (Web)#

CoAvatar(
  initials: 'JD',
  ring: true,
  avatarStyle: CoreAvatarStyle<CoreColor>(
    backgroundColor: CoreColor.fromHex('#3B82F6'),
    fallbackTextStyle: CoreTextStyle<CoreColor>(fontWeight: 700),
  ),
)

변형 (Variants)#

크기#

링 효과#

CoAvatar(imageUrl: url, ring: true)
CoAvatar(imageUrl: url, ring: false)

배경색 커스텀#

CoAvatar(initials: 'AB', backgroundColor: Colors.blue)
CoAvatar(initials: 'CD', backgroundColor: Colors.green)

동작 스펙 (Behavior)#

이미지 로딩#

• ImageProvider(Flutter) 또는 <img> 태그(Web)로 이미지 표시
• 이미지 로드 실패 시 자동으로 initials 텍스트로 폴백
• Flutter: Avatar.network() 생성자에서 cacheWidth/cacheHeight로 메모리 최적화
• Web: <img> 태그에 alt 속성 자동 적용

Ring 효과#

• Flutter: 2px gap + 1px stroke, ring: true로 활성화
• Web: CSS ring-2 ring-primary ring-offset-2 클래스, ring: true로 활성화

CoAvatar(
  imageUrl: 'https://example.com/photo.jpg',
  ring: true,
)

이미지 폴백#

• imageUrl과 initials를 함께 제공하면 이미지 로드 실패 시 이니셜로 폴백
• child가 있으면 imageUrl/initials보다 우선

CoAvatar(
  imageUrl: 'https://example.com/photo.jpg',
  initials: 'JD',
  size: CoreComponentSize.md,
)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

CoAvatar(
  imageUrl: user.photoUrl,
  initials: 'JD',
)

❌ Don't#

✅ Do#

Row(
  children: teamMembers.take(5).map((m) => CoAvatar(
    imageUrl: m.photo,
    size: CoreComponentSize.sm,
  )).toList(),
)

❌ Don't#

✅ Do#

CoAvatar(
  imageUrl: user.photoUrl,
  ring: user.isOnline,
)

❌ Don't#

접근성 (Accessibility)#

스크린 리더#

• Flutter: 이미지 아바타에 사용자 이름 시맨틱 제공. 이니셜 텍스트가 읽힘
• Web: <img> 태그의 alt 속성으로 사용자 이름 전달. 폴백은 텍스트가 직접 읽힘

최소 크기#

• 인터랙티브 아바타(클릭 가능): 최소 44×44dp 터치 영역 확보
• XS(24px) 아바타는 표시 전용으로만 사용

색상 대비#

• 이니셜 텍스트와 배경색의 대비 WCAG AA 준수
• Ring 효과는 색상 이외의 시각적 구분(간격)도 제공

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Badge: 상태 텍스트 레이블. Avatar의 badge 대신 텍스트 기반 상태 표시
• Icon: 아이콘 시스템. Avatar의 커스텀 child로 아이콘 배치 가능
• HoverCard: 호버 미리보기. Avatar에 호버하면 프로필 카드 표시

조합 예제#

// 댓글 목록 패턴
ListView.builder(
  itemBuilder: (context, index) {
    final comment = comments[index];
    return Row(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        HoverCard(
          hoverBuilder: (context) => UserProfileCard(user: comment.author),
          child: Avatar(
            imageUrl: comment.author.photoUrl,
            initials: Avatar.getInitials(comment.author.name),
            size: AvatarSize.sm,
            status: comment.author.isOnline
              ? AvatarStatus.online
              : null,
          ),
        ),
        SizedBox(width: 12),
        Expanded(child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(comment.author.name,
              style: TextStyle(fontWeight: FontWeight.bold)),
            Text(comment.body),
          ],
        )),
      ],
    );
  },
)