Accordion#

콘텐츠를 접었다 펼 수 있는 아코디언 컴포넌트입니다.

Live Preview#

class AccordionDefaultExample extends StatelessComponent {
  const AccordionDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return CoAccordion(
      items: [
        CoAccordionItem(
          title: 'Is it accessible?',
          content: text('Yes. It adheres to the WAI-ARIA design pattern.'),
          expanded: true,
        ),
        CoAccordionItem(
          title: 'Is it styled?',
          content: text('Yes. It comes with default styles that matches the other components.'),
        ),
        CoAccordionItem(
          title: 'Is it animated?',
          content: text('Yes. It\'s animated by default, but you can disable it if you prefer.'),
        ),
      ],
    );
  }
}

class AccordionDefaultExample extends StatelessWidget {
  const AccordionDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoAccordion(
      items: [
        CoAccordionItem(
          title: 'Is it accessible?',
          content: Text('Yes. It adheres to the WAI-ARIA design pattern.'),
          expanded: true,
        ),
        CoAccordionItem(
          title: 'Is it styled?',
          content: Text(
            'Yes. It comes with default styles that matches the other components.',
          ),
        ),
        CoAccordionItem(
          title: 'Is it animated?',
          content: Text(
            "Yes. It's animated by default, but you can disable it if you prefer.",
          ),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

• FAQ, 도움말 등 질문-답변 형태의 콘텐츠를 표시할 때
• 긴 내용을 섹션별로 접어서 공간을 절약할 때
• 설정 패널의 카테고리별 옵션을 그룹화할 때

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

• Tabs: 관련 콘텐츠를 탭으로 전환할 때 (한 번에 하나만 보여도 될 때)
• Dialog: 추가 정보를 모달로 보여줄 때
• Drawer: 복잡한 콘텐츠를 사이드 패널로 보여줄 때

기본 사용법 (Basic Usage)#

// 기본 아코디언
Accordion(
  items: [
    AccordionItem(
      title: '섹션 1',
      child: Text('섹션 1의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 2',
      child: Text('섹션 2의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 3',
      child: Text('섹션 3의 내용입니다.'),
    ),
  ],
)

// 다중 열기 허용
Accordion(
  allowMultiple: true,
  items: accordionItems,
)

// 초기 열림 상태
Accordion(
  initialOpenIndexes: [0],
  items: accordionItems,
)

// 기본 아코디언
Accordion(
  children: [
    AccordionItem(
      title: '섹션 1',
      content: Component.text('섹션 1의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 2',
      content: Component.text('섹션 2의 내용입니다.'),
    ),
    AccordionItem(
      title: '섹션 3',
      content: Component.text('섹션 3의 내용입니다.'),
    ),
  ],
)

// 다중 열기 허용 (각 항목을 개별적으로 isOpen으로 제어)
Accordion(
  children: [
    AccordionItem(
      title: 'FAQ 1',
      content: Component.text('FAQ 1 답변입니다.'),
      isOpen: true,
    ),
    AccordionItem(
      title: 'FAQ 2',
      content: Component.text('FAQ 2 답변입니다.'),
      isOpen: true,
    ),
  ],
)

// 초기 열림 상태
Accordion(
  children: [
    AccordionItem(
      title: '기본 정보',
      content: Component.text('기본 정보 내용입니다.'),
      isOpen: true, // 초기 열림 상태
    ),
    AccordionItem(
      title: '추가 정보',
      content: Component.text('추가 정보 내용입니다.'),
    ),
  ],
)

Props / Parameters#

Accordion#

스타일 시스템 (Style System)#

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

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (items, allowMultiple)
• chrome / dimensional / 슬롯 스타일: CoreAccordionStyle 한 곳으로 (backgroundColor / borderColor / borderWidth / borderRadius / contentPaddingH / contentPaddingV / itemGap / dividerColor / dividerThickness / triggerStyle / contentTextStyle / chevronIconStyle)

Resolve chain#

design system default for accordion
  → CoreAccordionTheme.style                   // 프로젝트 공통
  → parent component slot override
  → widget.accordionStyle                      // 인스턴스별

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

슬롯 매핑 (CoreAccordionStyle 12 필드)#

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

기존 CoreAccordionTheme 의 평면 필드 (padding / iconGap / dividerHeight / dividerColor / arrowIconColor) 는 호환을 위해 유지되지만, 새 코드는 accordionStyle 슬롯을 사용하세요:

사용 예 (Flutter)#

CoAccordion(
  items: [
    CoAccordionItem(
      title: 'FAQ Question',
      content: Text('Answer'),
    ),
  ],
  accordionStyle: CoreAccordionStyle(
    contentPaddingV: 24,
    dividerColor: Color(0xFFE5E7EB),
    dividerThickness: 1,
    triggerStyle: CoreButtonStyle(
      paddingV: 16,
      labelStyle: CoreTextStyle(fontSize: 16, fontWeight: 600),
    ),
    contentTextStyle: CoreTextStyle(fontSize: 14),
    chevronIconStyle: CoreIconStyle(size: 20),
  ),
)

사용 예 (Web)#

CoAccordion(
  items: [
    CoAccordionItem(
      title: 'FAQ Question',
      content: Component.text('Answer'),
    ),
  ],
  accordionStyle: CoreAccordionStyle<CoreColor>(
    contentPaddingV: 24,
    dividerThickness: 1,
    triggerStyle: CoreButtonStyle<CoreColor>(
      paddingV: 16,
    ),
  ),
)

AccordionItem#

변형 (Variants)#

아이콘 포함#

AccordionItem(
  leading: Icon(Icons.person),
  title: '개인 정보',
  child: PersonalInfoForm(),
)

FAQ 스타일#

Accordion(
  items: faqList.map((faq) => AccordionItem(
    title: faq.question,
    child: Text(faq.answer),
  )).toList(),
)

단일 항목 (접기/펼치기)#

AccordionItem(
  title: '고급 설정',
  initiallyOpen: false,
  child: AdvancedSettingsPanel(),
)

동작 스펙 (Behavior)#

열기/닫기#

• 헤더 클릭 시 해당 섹션이 슬라이드 애니메이션으로 펼쳐짐/접힘
• allowMultiple: false (기본): 하나를 열면 이전에 열린 항목이 자동으로 닫힘
• allowMultiple: true: 여러 항목을 동시에 열 수 있음

애니메이션#

• 기본 200ms, easeIn/easeOut 커브
• AccordionTheme으로 duration, curve, reverseCurve 커스터마이즈 가능

AccordionTheme(
  duration: Duration(milliseconds: 300),
  curve: Curves.easeInOut,
)

화살표 아이콘#

• 헤더 우측에 화살표 아이콘이 열림/닫힘 방향을 표시
• Flutter: AccordionTheme.arrowIcon으로 커스텀 가능
• Web: 고정 chevron 아이콘 (180° 회전 트랜지션)

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

✅ Do#

Accordion(
  items: faqList.map((faq) => AccordionItem(
    title: faq.question,
    child: Text(faq.answer),
  )).toList(),
)

❌ Don't#

Accordion(items: [
  AccordionItem(
    title: '결제 정보',
    child: PaymentForm(), // 반드시 입력해야 하는 폼
  ),
])

✅ Do#

Accordion(
  items: categories.map((cat) => AccordionItem(
    leading: Icon(cat.icon),
    title: cat.name,
    child: cat.settingsPanel,
  )).toList(),
)

❌ Don't#

Accordion(items: [
  AccordionItem(title: '유일한 섹션', child: content),
])

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: 헤더에 "펼침/접힘" 상태가 Semantics로 전달
• Web: <button> 요소로 렌더링되어 네이티브 접근성 자동 적용

터치 타겟#

• 헤더 최소 높이: 48dp

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

관련 컴포넌트 (Related Components)#

• Tabs: 콘텐츠를 탭으로 전환. 아코디언과 달리 한 번에 하나의 패널만 표시
• Card: 콘텐츠 컨테이너. 아코디언 항목 내부에 카드를 배치 가능

조합 예제#

// 설정 페이지 패턴
Accordion(
  allowMultiple: true,
  items: [
    AccordionItem(
      leading: Icon(Icons.person),
      title: '프로필 설정',
      child: ProfileSettingsForm(),
    ),
    AccordionItem(
      leading: Icon(Icons.notifications),
      title: '알림 설정',
      child: NotificationSettingsForm(),
    ),
    AccordionItem(
      leading: Icon(Icons.security),
      title: '보안 설정',
      child: SecuritySettingsForm(),
    ),
  ],
)