컴포넌트/시멘틱태그

Details (디테일스)

VanillaFront 2026. 9. 16. 18:59

Va.Details — 접고 펼치는 HTML5 <details> 컴포넌트

타이틀을 클릭하면 본문이 접혔다 펼쳐지는 아코디언형 시맨틱 컴포넌트입니다. HTML5 <details> + <summary> 태그를 기반으로 하며, 열림/닫힘 아이콘과 커스텀 헤더 위치를 지원합니다.

클래스 정보

Va.Details extends Va.Semantic extends Va.Component
tagName: 'details'
isContainer: true

기본 사용법

{
    tagName: 'details',
    title: '더 알아보기',
    open: false,
    tags: [{
        tagName: 'div',
        innerHTML: '숨겨진 상세 내용이 여기에 표시됩니다.'
    }]
}

또는 코드로:

let details = new Va.Details({
    title: '자세히',
    open: true,
    innerHTML: '펼쳐진 상세 내용'
});
parent.append(details);

HTML5 <details>의 의미

<details>는 HTML5 시맨틱 태그로, 필요할 때만 펼쳐 보는 부가 정보를 감쌉니다. <summary> 자식이 항상 보이는 헤더 역할을 하며, 사용자가 클릭하면 나머지 자식이 노출됩니다.

VanillaFront의 Va.Details는 여기에 아이콘 토글 버튼, 헤더 위치(top/bottom), keyboard(Enter/Space) 지원, 커스텀 이벤트를 얹은 확장판입니다.

속성

속성타입기본값설명

title String — 헤더에 표시되는 타이틀 텍스트
open Boolean false 초기 펼침 상태
headerPosition String 'top' 'top' 또는 'bottom' — 헤더 위치
openIcon String 'ico_add_square' 접힌 상태 아이콘
closeIcon String 'ico_subtract_square' 펼친 상태 아이콘
innerHTML String — 본문 HTML
text String — 본문 순수 텍스트
focused Boolean — 포커스 상태 (readonly로 활용)

이벤트

이벤트발생 시점콜백 인자

expand 펼쳐질 때 (sender, element, evt)
collapse 접힐 때 (sender, element, evt)
click 헤더 클릭 시 (sender, element, evt)

메서드

  • expand() — 펼치기
  • collapse() — 접기
  • setTitle(text) — 타이틀 변경
  • setText(text) / setInnerHTML(html) — 본문 변경
  • focus() / blur() — 헤더 포커스 제어

내부 구조

<details class="va-detail" va-role="va-detail">
    <summary class="header" tabindex="0" elname="header">
        <div elname="title">타이틀 텍스트</div>
        <button cpname="headerButton"><!-- +/- 토글 아이콘 --></button>
    </summary>
    <div class="body" elname="detail">
        <div class="detail-inner" elname="detailInner" style="overflow:auto">
            <!-- containerElement — 자식 컴포넌트 위치 -->
        </div>
    </div>
</details>

headerPosition: 'bottom'이면 summary가 아래로 이동합니다.

사용 시점 — 언제 쓰나

  • FAQ / 도움말 — 질문 목록에서 각 질문을 클릭하면 답변이 펼쳐지는 UI
  • 부가 설정 — 기본은 숨겨두고 "고급 옵션" 등을 눌러야 보이는 영역
  • 긴 텍스트 요약 — 미리보기만 보이고 "더보기"로 전체 노출
  • 디버그/로그 뷰어 — 각 로그 엔트리를 접었다 펼쳤다

사용하지 말아야 할 때

  • 여러 항목 중 하나만 열리는 아코디언 → 각 Details를 그룹으로 묶고 이벤트로 제어하거나, 별도 아코디언 컴포넌트 사용
  • 탭 인터페이스 → Va.Tab 사용
  • 다이얼로그/모달 → Va.Dialog 사용
  • 필수로 항상 보여야 할 정보 → 일반 section 사용

자주 쓰는 조합 예시

FAQ 리스트

{
    tagName: 'section',
    layout: 'ds-flex fd-column gap-s',
    tags: [{
        tagName: 'details',
        title: 'VanillaFront는 무엇인가요?',
        innerHTML: 'B2B용 UI Framework로, Vanilla JS ES6 모듈만으로 동작합니다.'
    },{
        tagName: 'details',
        title: '별도 빌드가 필요한가요?',
        innerHTML: '아니요. 브라우저가 ES6 모듈을 직접 로드하므로 No-Build로 동작합니다.'
    },{
        tagName: 'details',
        title: '어떤 컴포넌트가 있나요?',
        innerHTML: '약 120종의 UI 컴포넌트를 제공합니다.'
    }]
}

고급 옵션 접기

{
    tagName: 'form',
    tags: [
        { tagName: 'inputField', label: '이름' },
        { tagName: 'inputField', label: '이메일' },
        {
            tagName: 'details',
            title: '고급 설정',
            open: false,
            tags: [
                { tagName: 'checkboxField', label: '뉴스레터 수신' },
                { tagName: 'checkboxField', label: '알림 수신' }
            ]
        }
    ]
}

이벤트로 상태 감시

{
    tagName: 'details',
    title: '이력 보기',
    onExpand: 'onExpandHistory',
    onCollapse: 'onCollapseHistory',
    tags: [ /* 이력 목록 */ ]
}

// View 안:
onExpandHistory(sender){
    console.log('펼쳐짐');
    this.loadHistory();
}
onCollapseHistory(sender){
    console.log('접힘');
}

실전 예시 — 커스텀 아이콘 + 헤더 위치

{
    tagName: 'details',
    title: '오늘의 팁',
    open: true,
    headerPosition: 'top',
    openIcon: 'ico_chevron_right',
    closeIcon: 'ico_chevron_down',
    style: {
        border: '1px solid var(--colorNeutralStroke)',
        borderRadius: 'var(--sizeRadiusM)',
        padding: 'var(--sizeSpacingM)'
    },
    innerHTML: '<code>Ctrl+Shift+R</code>로 하드 새로고침이 가능합니다.'
}

주의사항

  • open() 메서드와 open 속성 이름 충돌 — 소스에 open(open){...} 메서드가 있으나 사실상 속성 대입으로 덮어써지므로 실사용은 expand() / collapse()를 쓰는 것이 안전
  • 키보드 지원 — 헤더가 tabindex=0이고 Enter/Space로 토글 가능 (접근성)
  • 자식은 detail-inner에 붙음 — containerElement가 detailInner로 설정되어 있어 tags로 넣은 자식은 스크롤 가능한 안쪽 영역에 들어감
  • text와 innerHTML 동시 설정 금지 — 텍스트가 우선. 둘 중 하나만 사용
  • 여러 개를 그룹으로 쓸 때 아코디언 효과 원하면 각 Details의 expand 이벤트에서 다른 형제 Details를 collapse() 호출해야 함 (기본은 독립적으로 열림)

대안 비교

상황추천

접었다 펼치는 상세 영역 Va.Details
여러 탭 중 하나만 표시 Va.Tab
모달 창 Va.Dialog
항상 보여야 하는 섹션 section / Va.Panel
툴팁 Va.Tooltip

참고