컴포넌트/필드 컴포넌트

ColorField (색상필드)

VanillaFront 2026. 9. 10. 15:06

Va.ColorField — 라벨 + 컬러 스와치 + 팝업 팔레트

Va.ColorPicker가 순수 색상 입력이라면, Va.ColorField는 그 위에 라벨·필수 표시·검증 메시지를 얹은 완성 폼 필드입니다. Field 계열 아키텍처 그대로, 내부에 Va.ColorPicker를 소유하는 Composition 구조.

  • 클래스: Va.ColorField — va_colorpicker.js:446
  • short name: colorField
  • 상속: Va.Field (InputField·NumberField 등과 형제)
  • 파일: va_colorpicker.js (import 필요)
  • 내부 컴포넌트: Va.ColorPicker 인스턴스 (fieldComponent)
  • isContainer: true
  • 베이스 CSS: va-field

1. 기본 사용

import '../../lib/va_colorpicker.js';  // ← 필수 (colorPicker + colorField 둘 다 이 파일에)

// config 안에서
{
    tagName: 'colorField',
    label: '카테고리 색상',
    value: '#FF6600',
    required: true,
    onSelect: 'onColorPicked'
}

2. Field 계열 아키텍처에서의 위치

Va.Field
   ├─ Va.InputField      ← Va.Input (text)
   ├─ Va.SearchField     ← Va.Search (search)
   ├─ Va.NumberField     ← Va.Number (number)
   ├─ Va.TextareaField
   ├─ Va.ComboboxField
   ├─ Va.ColorField      ← Va.ColorPicker    ← 이 문서
   └─ ...

ColorField의 정체: Field 베이스가 라벨/필드/검증 영역을 만들고, 필드 영역에 새로 만든 Va.ColorPicker를 꽂아 넣는 표준 Composition (va_colorpicker.js:479):

this.fieldComponent = new Va.ColorPicker(optionField);

즉, ColorField = Field 껍데기 + Va.ColorPicker 인스턴스.

3. Va.ColorPicker / 다른 Field와의 차이

항목Va.ColorPickerVa.ColorFieldVa.InputField

라벨 ✕ ✓ ✓
검증 메시지 ✕ ✓ ✓
필수 표시 ✕ ✓ ✓
info 툴팁 ✕ ✓ ✓
팝업 팔레트 ✓ ✓ (내부 위임) ✕
스와치 미리보기 ✓ ✓ (내부 위임) ✕
파일 va_colorpicker.js va_colorpicker.js va_component.js
popWidth 기본값 270 280 (미묘하게 다름) —
이벤트 재발화 로직 없음 beforePop/afterPop/hidePop/select/expand/collapse 모두 리렌더 없음

4. 주요 속성

ColorField 전용 / ColorPicker에서 전달

속성기본값설명

popWidth 280 팝업 너비. ColorPicker의 270과 다르니 주의
expanded false 팝업 초기 상태
min / max — properties 배열에 있으나 색상 필드에선 사용 안 됨 (Number에서 복사된 잔재)

라벨 관련 (Field 상속)

속성기본값설명

label — 라벨 텍스트 또는 옵션 객체
labelPosition 'top' top / bottom / left / right
labelWidth 자동 라벨 영역 폭
labelAlign — 라벨 정렬
noLabel false 라벨 영역 숨김
infoButton — 라벨 옆 info 아이콘
required false 필수 표시

필드 관련 (ColorPicker로 위임)

속성설명

value 색상 hex 문자열 ('#FF0000')
placeholder 플레이스홀더
readonly / disabled 상태
size / appearance / shape 시각 스타일
textAlign 텍스트 필드 정렬
stopPropagation 이벤트 버블링

⚠️ showText 옵션이 명시적으로 통과되지 않음 — ColorPicker의 showText(hex 텍스트 표시)는 ColorField의 optionField 목록에 없습니다 (va_colorpicker.js:460-478). 필요하면 colorPicker 옵션 객체 통해서 넘겨야 합니다.

세부 커스터마이즈 (colorPicker 옵션 키)

{
    tagName: 'colorField',
    label: '태그 색상',
    value: '#3366CC',
    colorPicker: {                // ← 내부 ColorPicker에 직접 전달
        showText: false,          // 스와치만 표시
        popWidth: 320
    }
}

각 Field 계열 옵션 키:

  • InputField → input
  • SearchField → search
  • NumberField → number
  • ColorField → colorPicker

검증

속성설명

validation {state, size, message} 객체
validationState success / warning / error
validationMessage 메시지 텍스트

5. 이벤트

ColorPicker의 이벤트를 모두 재발화합니다 (va_colorpicker.js:489-535):

이벤트시그니처발생 시점

select (component, element, value, evt) 팝업에서 색상 클릭. value는 hex 문자열. 발생 시 검증 자동 리셋
beforePop (component, element, evt) 팝업 열리기 직전
afterPop (component, element, evt) 팝업 열린 직후
hidePop (component, element, evt) 팝업 닫힘 요청 시
expand / collapse 팝업 확장/축소  
focus / blur 필드 포커스 진입/이탈  
keydown 키다운 (검증 자동 리셋)  

⚠️ select 이벤트 리스너가 두 번 등록됨 — va_colorpicker.js:489와 va_colorpicker.js:519에서 각각 dispatch. 콜백이 두 번 호출될 수 있으니 주의(첫 번째는 evt만, 두 번째는 value, evt).

⚠️ change 이벤트가 없음 — 다른 Field 계열은 setFieldComponentEvent() 호출로 change/click 등 기본 이벤트가 걸리는데, ColorField는 그 호출이 주석 처리되어 있음 (va_colorpicker.js:488). hex 텍스트 직접 입력 후 change를 잡으려면 component.fieldComponent에 직접 리스너 필요.

색상 선택 콜백 예시

onColorPicked(component, element, value, evt) {
    console.log('선택된 색:', value);   // 예: "#0066CC"
    // 검증 표시는 자동으로 사라짐
}

6. 메서드 (Field 상속)

InputField·NumberField와 동일한 세트:

값

메서드설명

getValue() 내부 ColorPicker의 getValue() 위임 (hex 문자열)
setValue(value) 값 세팅 + 검증 자동 리셋. 스와치 배경색도 자동 반영

상태

메서드설명

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

검증

메서드설명

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

포커스

메서드설명

focus() / blur() 내부 ColorPicker에 위임

주의: ColorPicker 전용 메서드(showColorPickerPop, hideColorPickerPop)는 ColorField에 직접 없음. 필요하면 component.fieldComponent.showColorPickerPop()로 접근.

7. 내부 구조

<div elname="element" class="va-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-colorpicker" style="flex:1">    ← 내부 Va.ColorPicker
        <div class="field-wrapper">
          <div class="color-div" style="background:#FF6600"></div>  ← 스와치
          <input type="text" value="#FF6600">                        ← hex 입력
          <div class="focus-line"></div>
        </div>
        <!-- 팝업은 열릴 때 hiddenArea로 이동 -->
      </div>
    </div>
  </div>
  <div elname="validationDiv" style="display:none">
    <div class="va-validation">...</div>
  </div>
</div>

핵심 스타일 조정: 내부 ColorPicker 옵션에 style: 'flex:1'이 강제로 들어감 (va_colorpicker.js:477) — Field 영역을 꽉 채우게.

8. 언제 쓰나

ColorField가 맞을 때

  • 폼 안에 라벨 붙은 색상 선택 필드
  • 검증 메시지("색상을 선택하세요")를 표시해야 할 때
  • 관리자 설정 페이지의 카테고리·태그 색상
  • 사용자 프로필 강조 색상 지정

다른 걸 쓸 때

  • 라벨 없는 인라인 색상 선택 → Va.ColorPicker
  • 툴바 아이콘형 → Va.ColorPicker + showText:false
  • 미리 정의된 몇 개 색만 → Va.ComboboxField + 각 옵션에 스와치 렌더링

9. 흔한 조합 예시

// 폼 안 표준 사용
{
    tagName: 'colorField',
    label: '배경색',
    value: '#FFFFFF',
    onSelect: 'onBgColor'
}

// 세로 폼에 스와치만
{
    tagName: 'colorField',
    label: '강조색',
    value: '#FF0000',
    colorPicker: { showText: false },
    style: 'width:60px'
}

// 좌측 라벨 + 필수
{
    tagName: 'colorField',
    label: '태그 색상',
    labelPosition: 'left',
    labelWidth: 100,
    required: true,
    value: '#3366CC'
}

// 팝업 폭 크게
{
    tagName: 'colorField',
    label: '테마 색상',
    popWidth: 400,
    value: '#333333'
}

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

  1. va_colorpicker.js import 필수 — ColorPicker와 ColorField가 같이 들어 있음. import 없으면 둘 다 인식 안 됨.
  2. select 이벤트 두 번 발화 위험 — 소스에 dispatch 코드가 중복되어 있음. 콜백 로직이 idempotent하지 않으면 가드 필요.
  3. change 이벤트 없음 — hex 텍스트 직접 편집 감지 필요하면 fieldComponent에 직접 리스너.
  4. showText는 colorPicker 옵션 키로만 — 직접 속성으론 안 됨. {colorPicker: {showText: false}} 형태.
  5. popWidth 기본값 차이 — ColorPicker는 270, ColorField는 280. 통일해서 쓰려면 명시 지정.
  6. min/max 속성은 무의미 — Number에서 복사된 잔재로 properties 배열에 있으나 사용 안 됨.
  7. 팝업 상태머신 참여 — 다른 팝업(Combobox, DatePicker 등)과 자동 상호 배타.
  8. hex 값 대소문자 — 팝업 선택 시 대문자로 반환. 서버 규약이 소문자면 변환 필요.
  9. 투명도(alpha) 미지원 — RGBA 형식 안 됨. 순수 RGB hex만.
  10. 접근성 취약 — 색상 팝업 UI에 ARIA/키보드 네비 부족. 색맹 사용자 대비 텍스트 라벨 병기 권장.
  11. focus() 위임 — Field의 focus()는 내부 ColorPicker의 hex 텍스트 input에 포커스. 팝업 자동 열기는 아님.
  12. 팝업이 hiddenArea로 이동 — 열릴 때 부모 컨테이너의 overflow/z-index 영향 없음. 닫히면 원위치.