컴포넌트/패널 외 영역 (Div, Span)

TitleBar (타이틀바)

VanillaFront 2026. 9. 18. 20:29

Va.TitleBar — 제목과 액션을 함께 놓는 상단 바 컨테이너

제목 텍스트와 액션 버튼을 한 줄에 나란히 배치하는 상단 바 전용 컨테이너입니다. Va.Div를 상속받으며 va-title-bar 클래스가 부여되어 flex row 레이아웃 + 타이틀 바 전용 padding이 자동 적용됩니다.

클래스 정보

Va.TitleBar extends Va.Div extends Va.Component
tagName: 'titleBar' (실제 렌더링은 <div>)
isContainer: true

기본 사용법

{
    tagName: 'titleBar',
    tags: [
        { tagName: 'title', innerHTML: '사용자 목록' },
        { tagName: 'div', style: { flex: 1 } },
        { tagName: 'button', text: '저장', appearance: 'primary' }
    ]
}

CSS로 정의된 실체

Va.TitleBar는 매우 얇은 컨테이너로, CSS만으로 다음이 자동 적용됩니다:

.va-title-bar {
    display: flex;
    flex-direction: row;
    align-items: center;
    padding: var(--sizeTitleBarPaddingTop) var(--sizeTitleBarPaddingLeft)
             var(--sizeTitleBarPaddingBottom) var(--sizeTitleBarPaddingRight);
}

즉 flex 가로 배치 + 세로 중앙 정렬 + 테마별 타이틀 바 패딩만 하고, 내용은 자식 컴포넌트가 담당합니다.

자체 title 속성이 없음 — 주의

Va.TitleBar에는 자체적으로 렌더링하는 title 속성이 없습니다. Va.Panel과 달리 title:'...'을 넘겨도 화면에 표시되지 않습니다.

제목 텍스트는 자식으로 Va.Title을 명시적으로 넣어야 합니다:

{
    tagName: 'titleBar',
    tags: [
        { tagName: 'title', innerHTML: '이 텍스트가 실제 제목' },  // 이것이 표시됨
        { tagName: 'button', text: 'Action' }
    ]
}

속성

Va.Div로부터 상속받는 모든 속성:

속성타입설명

layout String flex/grid 레이아웃 (기본은 CSS로 flex-row 적용됨)
style, class, hidden, attributes — 공통 속성
text, innerHTML String Div로부터 상속

이벤트

Va.Div로부터 상속:

  • click — 클릭 시
  • contextmenu — 우클릭 시

메서드

Va.Div / Va.Component 공통 메서드.

내부 구조

<div class="va-title-bar" tag-name="titleBar">
    <!-- 자식: Title + spacer + Button 등 -->
</div>

사용 시점 — 언제 쓰나

  • 패널·카드 상단 제목 + 액션 조합 — 왼쪽 제목, 오른쪽 액션 버튼
  • 다이얼로그 상단 바 — 제목 + 닫기 버튼
  • 섹션 헤더 — 섹션 제목 + 편집/삭제 액션

사용하지 말아야 할 때

  • 페이지 최상단 로고+글로벌 메뉴 → Va.Header
  • 제목만 필요할 때 → Va.Title (혼자 사용)
  • 액션 버튼 그룹만 필요할 때 → Va.ActionBar
  • 패널 자체의 헤더 → Va.Panel의 title 속성 사용 (Panel 내장)

자주 쓰는 조합 예시

제목 + 우측 액션 (기본 패턴)

{
    tagName: 'titleBar',
    tags: [
        { tagName: 'title', innerHTML: '회원 목록' },
        { tagName: 'div', style: { flex: 1 } },
        { tagName: 'button', text: '신규 등록', appearance: 'primary', icon: 'ico_add' }
    ]
}

제목 + 여러 액션 (편집 모드 툴바)

{
    tagName: 'titleBar',
    tags: [
        { tagName: 'title', innerHTML: '게시글 수정' },
        { tagName: 'div', style: { flex: 1 } },
        { tagName: 'button', text: 'Edit', icon: 'ico_pen_fill' },
        { tagName: 'button', text: 'Save', appearance: 'primary', icon: 'ico_checkmark' }
    ]
}

Title + SubTitle 조합

{
    tagName: 'titleBar',
    tags: [
        {
            tagName: 'div',
            tags: [
                { tagName: 'title', innerHTML: '월간 매출 리포트' },
                { tagName: 'subTitle', innerHTML: '2026년 3월' }
            ]
        },
        { tagName: 'div', style: { flex: 1 } },
        { tagName: 'button', text: '내보내기', icon: 'ico_download' }
    ]
}

Panel 내부 상단 바

{
    tagName: 'panel',
    tags: [{
        tagName: 'titleBar',
        tags: [
            { tagName: 'title', innerHTML: '데이터 조회' },
            { tagName: 'div', style: { flex: 1 } },
            { tagName: 'button', text: '새로고침', icon: 'ico_refresh' }
        ]
    },{
        ref: 'refGrid',
        tagName: 'grid'
    }]
}

다이얼로그 상단 바

{
    tagName: 'dialog',
    tags: [{
        tagName: 'titleBar',
        tags: [
            { tagName: 'title', innerHTML: '설정' },
            { tagName: 'div', style: { flex: 1 } },
            { tagName: 'button', iconOnly: true, icon: 'ico_close', appearance: 'transparent', onClick: 'onClose' }
        ]
    },{
        tagName: 'section',
        tags: [ /* 다이얼로그 본문 */ ]
    }]
}

실전 예시 — CRUD 화면 상단

config(){
    return {
        tagName: 'page',
        tags: [{
            tagName: 'panel',
            tags: [{
                tagName: 'titleBar',
                tags: [
                    {
                        tagName: 'div',
                        tags: [
                            { tagName: 'title', innerHTML: '사용자 관리' },
                            { tagName: 'subTitle', innerHTML: '전체 234명' }
                        ]
                    },
                    { tagName: 'div', style: { flex: 1 } },
                    { tagName: 'button', text: '신규', icon: 'ico_add', appearance: 'primary', onClick: 'onClickNew' },
                    { tagName: 'button', text: '삭제', icon: 'ico_delete_fill', appearance: 'danger', onClick: 'onClickDelete' }
                ]
            },{
                ref: 'refGrid',
                tagName: 'grid',
                columns: [ /* ... */ ]
            }]
        }]
    };
}

주의사항

  • title 속성은 렌더링되지 않음 — 자식으로 Va.Title을 반드시 넣어야 함
  • 자동으로 flex-row + ai-center 적용 — 별도 layout 지정 불필요
  • spacer 패턴 — 제목과 액션을 좌우로 분리하려면 중간에 { tagName: 'div', style: { flex: 1 } } 삽입
  • 테마 대응 — padding은 var(--sizeTitleBarPadding*) 변수로 테마별 자동 조정
  • Va.ActionBar와 조합 지양 — 이미 flex-row 컨테이너이므로 안에 또 ActionBar를 넣으면 중첩 구조. 액션 버튼은 TitleBar에 직접 자식으로

대안 비교

상황추천

제목 + 액션 조합 Va.TitleBar
액션 버튼 그룹만 Va.ActionBar
제목 단독 Va.Title
페이지 최상단 (로고+글로벌 메뉴) Va.Header
패널 자체 헤더 Va.Panel의 title 속성
다이얼로그 상단 Va.Dialog 내장 헤더 또는 TitleBar

참고