Va.ButtonGroup — 상호 배타적 선택을 자동화하는 버튼 컨테이너
여러 버튼을 나란히 담고, 하나가 선택되면 나머지는 자동으로 해제되는 라디오형 컨테이너입니다. Va.Div를 상속해 레이아웃 컨테이너 특성을 그대로 갖고, 그 위에 그룹 배타 선택 로직만 얹은 얇은 확장.
- 클래스: Va.ButtonGroup — va_component.js:17484
- short name: buttonGroup
- 상속: Va.Div (다른 버튼 계열과 달리 Component 직속 아님)
- isContainer: true
- 베이스 CSS: va-div (Div의 것을 그대로 씀 — 자체 va-button-group 클래스 없음)
1. 기본 사용
{
tagName: 'buttonGroup',
layout: 'ds-flex fd-row ai-center gap-s',
tags: [
{ tagName: 'toggleButton', text: '왼쪽 정렬' },
{ tagName: 'toggleButton', text: '가운데 정렬' },
{ tagName: 'toggleButton', text: '오른쪽 정렬' }
]
}
사용자가 어떤 버튼을 클릭하면:
- 그룹 안 모든 자식이 unselect() 호출됨
- toggleButton이면 unpress()까지 호출됨
- 클릭된 버튼만 select() (+toggleButton이면 press()) 됨
결과 — 언제나 하나만 선택된 라디오 UI가 자동으로 완성.
2. 다른 버튼/컨테이너와의 차이
항목Va.DivVa.ButtonGroup개별 Va.ToggleButton 나열
| 레이아웃 | ✓ | ✓ (Div 상속) | ✕ (부모가 제공해야) |
| 배타 선택 자동 | ✕ | ✓ | ✕ (수동 처리 필요) |
| toggleButton press/unpress 자동 처리 | ✕ | ✓ | ✕ |
| 이벤트 발화 | 없음 | 없음 (개별 버튼이 발화) | ✓ |
| 자체 상태 | 없음 | 없음 | pressed |
한 줄 요약: "여러 버튼을 라디오처럼 만드는 얇은 마법 컨테이너".
3. 속성
독자적 속성이 없습니다 — va_component.js:17489-17491에서 properties, events를 배열 spread만 하고 아무것도 추가하지 않습니다.
Va.Div의 모든 속성이 그대로 유효:
속성설명
| layout | Flex/Grid 레이아웃 (예: 'ds-flex fd-row ai-center gap-s') |
| mobileLayout | 모바일 전용 레이아웃 |
| style / mobileStyle | 인라인 스타일 |
| mediaQuery | 반응형 속성 |
| border, padding, margin 등 | Div 공통 |
그룹 자체가 어떻게 정렬될지(가로/세로/gap)는 전적으로 layout 속성에 달려 있습니다.
4. 이벤트
독자 이벤트 없음. 그룹 자체는 이벤트를 dispatch하지 않고, 개별 자식 버튼의 이벤트에 의존합니다.
{
tagName: 'buttonGroup',
tags: [
{
tagName: 'toggleButton',
text: '옵션 1',
onClick: 'onOption1' // ← 각 버튼이 자기 이벤트 처리
},
{
tagName: 'toggleButton',
text: '옵션 2',
onClick: 'onOption2'
}
]
}
⚠️ "어떤 게 선택됐는지" 이벤트가 없음 — Combobox처럼 change(selectedIndex) 같은 통합 이벤트가 그룹에서 발화되지 않습니다. 필요하면 개별 버튼 onClick에서 처리하거나, getChildComponents()로 순회해서 selected/pressed 상태를 조회해야 합니다.
5. 메서드
커스텀 메서드 없음 — Va.Div의 것을 그대로 씁니다.
메서드설명
| append(button) | 오버라이드됨 — 자식 추가 시 자동으로 배타 선택 클릭 핸들러 바인딩 |
| getChildComponents() | 자식 버튼 조회 (Component 공통) |
| removeChild(child) | 자식 제거 |
append의 특별한 동작
동적으로 버튼을 추가할 때도 배타 선택이 유지됩니다 (va_component.js:17521-17536):
onAppend() {
const btn = new Va.Button({ text: '동적 추가' });
this.getRef('refButtonGroup').append(btn);
// ← 여기 시점부터 이 새 버튼도 그룹의 배타 선택에 참여
}
Demo의 onAppend가 정확히 이 패턴을 보여줍니다 → DemoButtonGroup.js:13-23
6. 어떻게 동작하나 (내부 로직)
두 곳에서 배타 선택 핸들러를 바인딩합니다:
mounted() — 초기 자식들 (va_component.js:17504-17520)
mounted(){
let buttons = this.getChildComponents();
for(let i=0; i < buttons.length; i++){
this._bindEvent(buttons[i].element, 'click', (evt) => {
for(let j=0; j < buttons.length; j++){
buttons[j].unselect();
if(buttons[j].tagName == 'toggleButton'){
buttons[j].unpress();
}
}
buttons[i].select();
if(buttons[i].tagName == 'toggleButton'){
buttons[i].press();
}
})
}
}
append(button) — 동적으로 추가되는 자식 (va_component.js:17521-17536)
동일한 로직을 새 버튼에도 붙임.
주목할 점:
- unselect() / select()는 모든 자식에게 호출되지만, 이 메서드가 없는 컴포넌트를 넣으면 크래시합니다. 자식은 반드시 select/unselect를 가진 버튼 계열이어야 합니다.
- toggleButton만 press/unpress가 추가로 호출됨 — 다른 종류 버튼과 섞으면 시각 상태가 서로 어긋날 수 있습니다.
7. 내부 구조
<div elname="element" class="va-div [layout classes]">
<!-- 자식 버튼들이 여기 flex/grid 레이아웃대로 나열됨 -->
<button class="va-button">…</button>
<button class="va-button">…</button>
...
</div>
전용 CSS 클래스 없음 — _beginClassBuild('va-button-group') 같은 호출이 없습니다. CSS만으로 그룹 시각 표현(붙어있는 세그먼트 버튼 같은 look)을 강조하려면 style/layout에 직접 규칙을 넣거나 커스텀 클래스를 추가해야 합니다.
8. 언제 쓰나
ButtonGroup이 맞을 때
- 라디오형 옵션 선택을 버튼 UI로 표현할 때 (텍스트 정렬 L/C/R, 뷰 모드 List/Grid, 기간 필터 Day/Week/Month)
- 세그먼트 컨트롤 (iOS Segmented Control 유사)
- 툴바에서 상호 배타적 모드 전환 (편집/보기/디자인)
- 동적으로 버튼이 추가돼도 배타 선택을 유지해야 하는 상황
다른 걸 쓸 때
- 다중 선택 필터 (여러 개 동시 선택 가능) → 단순 Div 안에 ToggleButton 여러 개, 배타 로직 안 씀
- 단순한 여러 버튼 나열 (선택 개념 없음) → Va.Rows / Va.Div
- 값이 있는 폼 필드 → Va.RadioGroup / Va.RadioGroupField
- 드롭다운 형태의 옵션 선택 → Va.Combobox / Va.SegmentedControl