카테고리 없음

FilterboxField (필터박스필드)

VanillaFront 2026. 9. 10. 15:34

Va.FilterboxField — 라벨 + 실시간 필터링 드롭다운 + 검증

Va.Filterbox가 순수 필터박스라면, Va.FilterboxField는 그 위에 라벨·필수 표시·검증 메시지를 얹은 완성 폼 필드입니다. Field 계열 아키텍처 그대로, 내부에 Va.Filterbox를 소유하는 Composition 구조. ComboboxField의 사촌.

  • 클래스: Va.FilterboxField — va_component.js:5797
  • short name: filterboxField
  • 상속: Va.Field (ComboboxField·TagField 등과 형제)
  • 내부 컴포넌트: Va.Filterbox 인스턴스 (fieldComponent)
  • isContainer: true
  • 베이스 CSS: va-combobox-field (ComboboxField와 동일 CSS 클래스 재사용)

1. 기본 사용

{
    tagName: 'filterboxField',
    label: '국가',
    filterKeys: ['display'],
    data: [
        { key: 'US', display: 'United States' },
        { key: 'KR', display: 'South Korea' },
        { key: 'JP', display: 'Japan' }
        // ... 200개국
    ],
    value: 'KR',
    required: true,
    onSelect: 'onCountrySelect'
}

라벨 + 검증 + 팝업 드롭다운 + 타이핑 필터가 한 번에 세팅.

2. Field 계열에서의 위치

Va.Field
   ├─ Va.InputField          ← Va.Input
   ├─ Va.SearchField         ← Va.Search
   ├─ Va.NumberField         ← Va.Number
   ├─ Va.ComboboxField       ← Va.Combobox
   ├─ Va.FilterboxField      ← Va.Filterbox        ← 이 문서
   ├─ Va.TagField            ← Va.Tag
   └─ ...

FilterboxField의 정체: Field 베이스 + 내부에 Va.Filterbox 인스턴스.

3. Va.Filterbox / Va.ComboboxField와의 차이

항목Va.FilterboxVa.FilterboxFieldVa.ComboboxField

라벨 ✕ ✓ ✓
검증 메시지 ✕ ✓ ✓
필드 자유 입력 ✓ ✓ (내부 Filterbox 동작) ✕
filterKeys 지원 ✓ ✓ ✕
실시간 필터 ✓ ✓ ✕
바인딩 옵션 ✕ (Filterbox엔 별도 없음) ✕ (ComboboxField와 달리 안 넘김) ✓
filterKeys 기본값 ['display'] ['key', 'display'] (2개로 확장) —

한 줄 요약: "옵션이 많고 라벨이 필요한 폼에서 타이핑으로 찾는 필드."

4. 주요 속성 — Filterbox 옵션 + Field 옵션

필터 관련 (Filterbox 전용)

속성기본값설명

filterKeys ['key', 'display'] 필터링 대상 필드명 배열. ComboboxField에는 없는 속성
filterType — 필터 방식 힌트 (properties에 선언은 있으나 실질 동작은 Filterbox 로직에 위임)

⚠️ isFilterRuntime(실시간 필터 여부)이 optionField에 명시 통과되지 않음 (va_component.js:5816-5842). 필요하면 combobox 옵션 통해 전달.

데이터 관련 (Filterbox 계승)

속성기본값설명

data — 항목 배열
key 'key' 값 필드명
display 'display' 표시 필드명
displayType 'display' key / display / both
template 자동 생성 팝업 항목 렌더 템플릿

선택 동작

속성기본값설명

value — 선택 값
multiSelect false 다중 선택
clickToSelect true 클릭 선택
editable — 자유 입력 허용

팝업

속성기본값설명

expanded false 팝업 초기 상태
popWidth 자동 팝업 폭
popMaxHeight (Filterbox 기본) 팝업 최대 높이

라벨 (Field 상속)

속성설명

label 라벨 텍스트 또는 객체
labelPosition top / bottom / left / right
labelWidth 라벨 폭
noLabel 라벨 숨김
infoButton info 아이콘
required 필수 표시

검증

속성설명

validation {state, size, message}
validationState success / warning / error
validationMessage 메시지

세부 커스터마이즈 (combobox 옵션 키 — 주의)

{
    tagName: 'filterboxField',
    label: '국가',
    combobox: {                     // ← 옵션 키가 'combobox' (filterbox 아님!)
        isFilterRuntime: true,      // 실시간 필터 활성화
        rowHeight: 40
    }
}

⚠️ 옵션 키가 combobox — FilterboxField의 세부 커스터마이즈 옵션 키가 예상과 달리 filterbox가 아니라 combobox 입니다 (va_component.js:5841). ComboboxField 소스에서 복사되며 남은 흔적. 실무에서 헷갈리기 쉽습니다.

각 Field 계열 옵션 키:

  • InputField → input
  • SearchField → search
  • NumberField → number
  • ColorField → colorPicker
  • ComboboxField → combobox
  • TagField → tag
  • FilterboxField → combobox (!)

5. 바인딩 옵션 부재 — ComboboxField와 결정적 차이

ComboboxField에는 있는 이 옵션들이 FilterboxField에는 없습니다:

  • bindParams (부모 필드 값 자동 수집)
  • bindRequired (바인딩 필드 비면 팝업 안 열림)
  • bindCallbackKeys (선택 후 다른 필드 자동 채움)
  • bindCallbackClearKeys (선택 후 다른 필드 자동 비움)
  • commonCode / dynamicCode (공통 코드 마스터)

함의: 부모-자식 폼 필드 연쇄 로직이 필요하면 FilterboxField가 아니라 ComboboxField를 쓰거나, Filterbox의 내부 로직에 의존해서 수동으로 이벤트 처리해야 합니다.

6. 이벤트

Filterbox의 이벤트를 재발화:

이벤트시그니처발생 시점

select (component, element, listItem, data, key, display, evt) 항목 선택 시
expand / collapse 팝업 확장/축소  
focus / blur 표준  
change / keydown Field 표준 (검증 자동 리셋)  

⚠️ select 이벤트 dispatch가 두 번 — 소스 va_component.js:5851과 va_component.js:5884에서 각각. 콜백 중복 실행 위험. 첫 번째는 (this, this.element, evt) 짧은 인자, 두 번째는 (this, this.element, listItem, data, keyValue, displayValue, evt) 긴 인자. 콜백에서 인자 방어 필요.

⚠️ beforePop / afterPop / hidePop 이벤트 재발화 없음 — ComboboxField·TagField에는 있는데 FilterboxField에는 명시적 재발화 코드가 빠져 있음. 필요하면 fieldComponent에 직접 리스너.

7. 메서드

Filterbox의 메서드에 위임:

값

메서드설명

getValue() Field 상속 (내부 Filterbox getValue() 위임)
setValue(value) Field 상속
getSelectedData() 선택된 데이터 객체 반환

데이터 (Filterbox 위임)

메서드설명

setData(data) 데이터 교체
getData() 데이터 반환
addData(data) / insertData(data, baseData) 추가/삽입
modifyData(data, cls) 수정
removeData(data) / removeDataByKey(key) 제거
select(data) 프로그램적 선택
getDataById(vaDataId) / getDataByListItem(listItem) / getListItemByData(data) 조회

⚠️ moveData, applyData, selectFirstData, focusFirstData, getDisplay, getDisplayAsText는 위임 메서드 없음 — ComboboxField에는 있는데 FilterboxField에는 빠져 있음. 필요하면 component.fieldComponent.xxx()로 직접 호출.

상태 (Field 상속)

메서드설명

setDisabled(bool) / getDisabled() 비활성화
setReadOnly(bool) / setReadonly(bool) 읽기 전용
setLabel(label) 라벨 변경
setPlaceholder(text) 플레이스홀더

검증

메서드설명

setValidation(state, message) 검증 표시 + aria
clearValidation() 검증 해제

포커스

메서드설명

focus() / blur() 내부 Filterbox의 fieldElement에 위임

8. 내부 구조

<div elname="element" class="va-field va-combobox-field [vertical|horizontal]" field="true">
  <div elname="inner" class="field-inner">
    <div elname="labelDiv" class="label-div">
      <label cpname="label">국가 <span class="required">*</span></label>
    </div>
    <div elname="comment" class="field-comment"></div>
    <div elname="fieldDiv" class="field-div">
      <div cpname="field" class="va-filterbox">              ← 내부 Va.Filterbox
        <div class="field-wrapper" role="combobox">
          <input type="text">                                 ← 자유 입력 가능
          <div class="focus-line"></div>
          <div class="va-combobox-dropdown">▼</div>
        </div>
        <!-- 팝업은 hiddenArea로 이동 -->
      </div>
    </div>
  </div>
  <div elname="validationDiv" style="display:none">
    <div class="va-validation">...</div>
  </div>
</div>

주목: 클래스 이름이 va-combobox-field — ComboboxField와 동일한 CSS 클래스를 재사용하므로 시각 스타일이 완전 통일됨.

9. 언제 쓰나

FilterboxField가 맞을 때

  • 폼 안 옵션이 많은 필드 — 국가·도시·부서·제품 등
  • 사용자가 대략적인 이름만 알 때 (타이핑으로 좁힘)
  • 라벨·검증 메시지 필요
  • 부모-자식 바인딩이 필요 없을 때 (있다면 ComboboxField 사용)

다른 걸 쓸 때

  • 옵션 10개 이하 → Va.ComboboxField (스크롤로 충분)
  • 라벨 없이 인라인 → Va.Filterbox
  • 부모-자식 폼 바인딩 필요 → Va.ComboboxField (바인딩 옵션 있음)
  • 다중 선택 + 칩 UI → Va.TagField
  • 자유 텍스트 입력 → Va.InputField

10. 흔한 조합 예시

// 국가 선택
{
    tagName: 'filterboxField',
    label: '국가',
    filterKeys: ['display'],
    data: countries    // 200+개국
}

// 사원 조회 (여러 필드 매칭)
{
    tagName: 'filterboxField',
    label: '담당자',
    filterKeys: ['name', 'employeeId', 'email'],
    template: {
        tagName: 'listItem',
        layout: 'ds-flex fd-column',
        tags: [
            { tagName: 'div', innerHTML: '{name}' },
            { tagName: 'div', innerHTML: '{email}', style: 'color:gray; font-size:12px' }
        ]
    },
    data: employees
}

// 실시간 필터 (combobox 옵션 통해서)
{
    tagName: 'filterboxField',
    label: '분류',
    filterKeys: ['display'],
    combobox: {
        isFilterRuntime: true    // Filterbox의 실시간 옵션
    },
    data: categories
}

// 좌측 라벨 + 필수
{
    tagName: 'filterboxField',
    label: '지역',
    labelPosition: 'left',
    labelWidth: 100,
    required: true,
    filterKeys: ['display'],
    data: regions
}

// 다중 선택 필터
{
    tagName: 'filterboxField',
    label: '카테고리',
    multiSelect: true,
    filterKeys: ['display'],
    data: [...]
}

11. 알아두면 좋을 주의사항

  1. 옵션 키가 combobox — FilterboxField 세부 커스터마이즈는 combobox 키. 헷갈리기 쉬움.
  2. select 이벤트 두 번 dispatch — 인자 개수 다름. 방어 코드 필요.
  3. beforePop/afterPop/hidePop 재발화 없음 — 필요하면 fieldComponent에 직접.
  4. 바인딩 옵션 없음 — 부모-자식 폼 연쇄 필요하면 ComboboxField 사용.
  5. 일부 메서드 위임 누락 — moveData, applyData, selectFirstData, getDisplay 등. fieldComponent로 직접 호출.
  6. filterKeys 기본이 ['key', 'display'] — Filterbox(['display'])보다 확장됨.
  7. isFilterRuntime을 명시적 전달 없음 — combobox 옵션으로 우회.
  8. filterType 속성 선언만 있음 — 실제 사용은 Filterbox 내부 로직에 의존.
  9. filterKey (단수) vs filterKeys (복수) 혼용 코드 — va_component.js:5901에서 _syncProperties에 filterKey(단수)로 들어 있음. 실제 사용은 filterKeys(복수)라 이 동기화는 무효 코드일 가능성.
  10. CSS 클래스가 va-combobox-field — ComboboxField와 시각 통일.
  11. 필터 데이터에 null 값 있으면 크래시 위험 — Filterbox의 indexOf 호출이 null에서 실패. 데이터 방어 필요.
  12. 한글 초성·대소문자 무시 필터 없음 — Filterbox 내부 로직 그대로. 필요하면 데이터 가공 또는 필터 오버라이드.
  13. focus()는 fieldElement에 포커스 — 팝업 자동 열림 아님. 팝업 원하면 component.fieldComponent.showFilterboxPop() 직접.

12. FilterboxField vs ComboboxField 선택 기준

상황추천

옵션 10개 이하, 부모-자식 바인딩 필요 ComboboxField
옵션 10개 이하, 단순 선택 ComboboxField
옵션 50개 이상, 부모-자식 바인딩 필요 ComboboxField (바인딩 필요 시 필터 못 써도 감수)
옵션 50개 이상, 바인딩 불필요 FilterboxField
옵션 수백 개 이상, 성능 중요 FilterboxField + isFilterRuntime: false
서버에서 검색어 던져 데이터 받기 ComboboxField + 커스텀 이벤트로 서버 호출