Banner#

페이지 상단에 중요한 정보, 경고, 오류 등을 표시하는 배너 컴포넌트입니다. Banner는 Flutter와 Web에서 동일한 named properties API를 제공하며, default/info/success/warning/destructive 5개 variant를 지원합니다.

Live Preview#

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

  @override
  State<BannerInfoExample> createState() => _BannerInfoExampleState();
}

class _BannerInfoExampleState extends State<BannerInfoExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Banner.info(
        message: const Text('새로운 업데이트가 준비되었습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerInfoExample> createState() => _BannerInfoExampleState();
}

class _BannerInfoExampleState extends State<BannerInfoExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Banner.info(
        message: const Text('새로운 업데이트가 준비되었습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerWarningExample> createState() => _BannerWarningExampleState();
}

class _BannerWarningExampleState extends State<BannerWarningExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Banner.warning(
        message: const Text('세션이 5분 후에 만료됩니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerWarningExample> createState() => _BannerWarningExampleState();
}

class _BannerWarningExampleState extends State<BannerWarningExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Banner.warning(
        message: const Text('세션이 5분 후에 만료됩니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerDestructiveExample> createState() =>
      _BannerDestructiveExampleState();
}

class _BannerDestructiveExampleState extends State<BannerDestructiveExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Banner.destructive(
        message: const Text('요청을 처리하는 중 문제가 발생했습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerDestructiveExample> createState() =>
      _BannerDestructiveExampleState();
}

class _BannerDestructiveExampleState extends State<BannerDestructiveExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Banner.destructive(
        message: const Text('요청을 처리하는 중 문제가 발생했습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerSuccessExample> createState() => _BannerSuccessExampleState();
}

class _BannerSuccessExampleState extends State<BannerSuccessExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Banner.success(
        message: const Text('변경 사항이 성공적으로 저장되었습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

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

  @override
  State<BannerSuccessExample> createState() => _BannerSuccessExampleState();
}

class _BannerSuccessExampleState extends State<BannerSuccessExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Banner.success(
        message: const Text('변경 사항이 성공적으로 저장되었습니다.'),
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show banner'),
    );
  }
}

사용 시기 (When to Use)#

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

• 페이지 전체에 영향을 미치는 시스템 상태 메시지를 표시할 때 (점검 공지, 서비스 알림)
• 사용자가 취해야 할 중요한 액션을 안내할 때 (세션 만료 경고, 구독 만료 알림)
• 사용자가 방금 완료한 작업의 결과를 페이지 상단에 지속적으로 표시할 때

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

• Toast: 일시적으로 나타났다가 자동으로 사라지는 알림이 필요할 때
• Alert: 특정 콘텐츠 영역 내에 인라인으로 표시하는 경고 메시지가 필요할 때
• Dialog: 사용자의 즉각적인 응답이 필요한 중요한 알림에는 모달 다이얼로그 사용

기본 사용법 (Basic Usage)#

CoUI는 Flutter와 Web에서 동일한 API를 제공합니다. 아래 예제 코드는 양쪽 플랫폼에서 그대로 사용할 수 있습니다.

// 정보 배너
Banner.info(
  message: Text('시스템 점검이 예정되어 있습니다.'),
)

// 성공 배너 (해제 버튼 포함)
Banner.success(
  message: Text('저장이 완료되었습니다.'),
  onDismiss: handleDismiss,
)

// 경고 배너 (액션 포함)
Banner.warning(
  message: Text('세션이 곧 만료됩니다.'),
  description: Text('지금 연장하면 작업을 이어서 할 수 있습니다.'),
  action: Button(
    variant: CoreButtonVariant.outline,
    onPressed: handleExtendSession,
    child: Text('연장하기'),
  ),
  onDismiss: handleDismiss,
)

// 오류 배너
Banner.destructive(
  message: Text('요청을 처리하는 중 오류가 발생했습니다.'),
  onDismiss: handleDismiss,
)

Props / Parameters#

스타일 시스템 (Style System)#

Banner 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreBannerStyle 단일 슬롯으로 흐릅니다 (Epic #1302 원칙 6/7/8, Phase 6f 팬텀 generic 제거). 시맨틱 enum (variant) 과 behaviour (message / description / action / onDismiss / showIcon) 는 위젯 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (variant, message, description, action, onDismiss, showIcon)
• chrome / dimensional / 슬롯 스타일: CoreBannerStyle 한 곳으로 (backgroundColor / foregroundColor / borderColor / borderWidth / borderRadius / padding / iconContentGapStyle / contentDismissGapStyle / titleDescriptionGapStyle / titleStyle / descriptionStyle / iconStyle / actionButtonStyle / closeButtonStyle — 닫기 버튼의 패딩·모서리·아이콘·hover 전환은 전부 nested closeButtonStyle 슬롯)

Resolve chain#

design system default for banner
  → CoreBannerTheme.style                  // 프로젝트 공통
  → parent component slot override
  → widget.bannerStyle                     // 인스턴스별

각 nested 슬롯 스타일 (titleStyle / descriptionStyle / iconStyle / actionButtonStyle / closeButtonStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

슬롯 매핑 (CoreBannerStyle 필드)#

Epic #1696 Phase 3 에서 옛 CoreBannerTokens (raw double 보관 holder) 가 폐기되고, 모든 chrome 이 CoreBannerStyle 슬롯 + static const default* 로 흡수됨.

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

기존 CoreBannerTheme 의 평면 chrome (backgroundColor / borderColor / borderRadius) 은 호환을 위해 유지되지만, 새 코드는 bannerStyle 슬롯을 사용하세요:

사용 예 (Flutter)#

Banner.warning(
  message: Text('세션이 곧 만료됩니다.'),
  description: Text('지금 연장하면 작업을 이어서 할 수 있습니다.'),
  bannerStyle: CoreBannerStyle(
    padding: CoreEdgeInsets.symmetric(horizontal: 24, vertical: 16),
    borderRadius: CoreBorderRadius.all(12),
    titleStyle: CoreTextStyle(fontSize: 14, fontWeight: 600),
    descriptionStyle: CoreTextStyle(fontSize: 12),
    iconStyle: CoreIconStyle(size: 20),
  ),
  onDismiss: handleDismiss,
)

사용 예 (Web)#

Banner.warning(
  message: text('세션이 곧 만료됩니다.'),
  description: text('지금 연장하면 작업을 이어서 할 수 있습니다.'),
  bannerStyle: CoreBannerStyle(
    padding: CoreEdgeInsets.symmetric(horizontal: 24, vertical: 16),
    borderRadius: CoreBorderRadius.all(12),
  ),
  onDismiss: handleDismiss,
)

변형 (Variants)#

Info#

일반적인 정보 전달에 사용합니다.

Banner.info(
  message: Text('새로운 업데이트가 있습니다.'),
)

Success#

성공적인 작업 완료를 알릴 때 사용합니다.

Banner.success(
  message: Text('변경 사항이 저장되었습니다.'),
)

Warning#

사용자의 주의가 필요한 상황에 사용합니다.

Banner.warning(
  message: Text('구독이 7일 후 만료됩니다.'),
)

Destructive (Error)#

오류 또는 실패 상태를 알릴 때 사용합니다.

Banner.destructive(
  message: Text('네트워크 연결에 실패했습니다.'),
)

동작 스펙 (Behavior)#

인터랙션#

• 닫기 버튼 클릭: onDismiss 콜백 실행. 배너 숨김 처리는 부모 위젯에서 상태로 관리
• 액션 버튼 클릭: action 위젯에 정의된 콜백 실행
• 호버: 닫기 버튼 opacity 상승

상태 전환#

• 배너 표시: 슬라이드 다운 또는 페이드인 (부모에서 AnimatedSwitcher 사용 권장)
• 배너 닫기: onDismiss 호출 후 부모에서 상태를 변경하여 제거

테마 오버라이드#

프로젝트 레벨에서 CoreComponentTheme.banner로 기본값을 재정의할 수 있습니다.

CoreComponentTheme(
  banner: CoreBannerTheme(
    style: CoreBannerStyle(
      backgroundColor: CoreColor(0xFFF8F9FA),
      borderColor: CoreColor(0xFF6366F1),
      borderRadius: CoreBorderRadius.all(12),
    ),
  ),
)

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

✅ Do#

// 시스템 점검 공지: info
Banner.info(
  message: Text('2026-03-15 02:00~04:00 시스템 점검이 예정되어 있습니다.'),
)

// 보안 경고: warning
Banner.warning(
  message: Text('비밀번호를 90일 이상 변경하지 않았습니다.'),
  action: TextButton(
    onPressed: handleChangePassword,
    child: Text('변경하기'),
  ),
)

❌ Don't#

// ❌ 여러 배너 동시 표시
Column(
  children: [
    Banner.info(message: Text('점검 예정')),
    Banner.success(message: Text('저장 완료')),
    Banner.warning(message: Text('세션 만료')),
  ],
)

✅ Do#

Banner.info(
  message: Text('새로운 기능이 추가되었습니다. 지금 확인해보세요!'),
  onDismiss: handleDismissBanner,
  action: TextButton(
    onPressed: handleLearnMore,
    child: Text('자세히 보기'),
  ),
)

❌ Don't#

// ❌ 단순 안내에 destructive variant 사용
Banner.destructive(
  message: Text('이 기능은 프리미엄 회원 전용입니다.'),
)

✅ Do#

Banner.warning(
  message: Text('구독이 3일 후 만료됩니다.'),
  action: TextButton(
    onPressed: handleRenewSubscription,
    child: Text('갱신하기'),
  ),
  onDismiss: handleDismiss,
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics(container: true, label: 'Banner') 적용
• Web: role="banner" 속성 자동 적용

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

Banner는 Flutter와 Web에서 동일한 named properties API를 사용합니다. 플랫폼별로 타입이 다른 부분만 차이가 있습니다.

관련 컴포넌트 (Related Components)#

• Toast: 자동으로 사라지는 일시적 알림에 사용
• Alert: 특정 섹션 내 인라인 메시지에 사용
• Status: 시스템이나 사용자 상태 표시에 사용