카테고리 없음

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. 알아두면 좋을 주의사항

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

12. FilterboxField vs ComboboxField 선택 기준

상황추천

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

현재글FilterboxField (필터박스필드)

VanillaFront

VanillaFront 입니다. Vanilla Js를 이용하여 SPA기반 UI Framework를 구현합니다. 홈페이지: vanillafront.com

button, splitButton, import css, FileButton, ButtonGroup, colorField, liveserver port root, datetimepicker, numberfield, ColorPicker, responsiveMenuButton, ES6, filterboxField, VanillaJS, menuButton, inputField, FormField, DatePicker, tagField, UI Framework, copy-webpack-plugin #webpack, expandButton, dateField, comboboxField, combobox, vanillafront.com, spa, VanillaFront, filterbox, ToggleButton,

Today :
Yesterday :

일	월	화	수	목	금	토
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30

VanillaFront

FilterboxField (필터박스필드)

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

1. 기본 사용

2. Field 계열에서의 위치

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

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

필터 관련 (Filterbox 전용)

데이터 관련 (Filterbox 계승)

선택 동작

팝업

라벨 (Field 상속)

검증

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

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

6. 이벤트

7. 메서드

값

데이터 (Filterbox 위임)

상태 (Field 상속)

검증

포커스

8. 내부 구조

9. 언제 쓰나

10. 흔한 조합 예시

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

12. FilterboxField vs ComboboxField 선택 기준

'카테고리 없음'의 다른글

티스토리툴바