컴포넌트/필드 컴포넌트

InputField (입력필드)

VanillaFront 2026. 9. 9. 17:45

Va.InputField — 라벨 + 입력 + 검증까지 한 세트로 묶은 폼 필드

Va.Input이 순수 입력 자체라면, Va.InputField는 그 위에 라벨·필수 표시·검증 메시지·설명 텍스트·info 툴팁을 얹은 "완성된 폼 필드" 입니다. 실무에서 폼을 만들 때 훨씬 자주 쓰는 컴포넌트.

  • 클래스: Va.InputField — va_component.js:5377
  • short name: inputField
  • 상속: Va.Field (Field 계열의 베이스)
  • 내부 컴포넌트: Va.Input 인스턴스를 자식으로 소유 (fieldComponent)
  • isContainer: true
  • 베이스 CSS: va-field

1. 기본 사용

{
    tagName: 'inputField',
    label: '이름',
    value: '홍길동',
    placeholder: '이름을 입력하세요',
    required: true,
    onChange: 'onNameChange'
}

한 줄로 라벨·필수 별표·입력창·검증 메시지 자리가 모두 세팅됩니다.

2. Field 계열 아키텍처 — 두 계층

VanillaFront의 폼은 PureField(값 관리) + Field(라벨 감쌈) 두 계층입니다.

Va.Component
    ├─ Va.PureField          ← 값·이벤트·마스킹 (라벨 없음)
    │      ├─ Va.Input       ← 텍스트 입력
    │      ├─ Va.Combobox
    │      └─ ...
    │
    └─ Va.Field              ← 라벨·검증·설명 감쌈
           ├─ Va.InputField     ← 내부에 Va.Input 소유
           ├─ Va.ComboboxField  ← 내부에 Va.Combobox 소유
           ├─ Va.TextareaField
           ├─ Va.NumberField
           └─ ...

InputField의 정체: Field 베이스가 라벨 영역·필드 영역·검증 영역을 만들고, 그 필드 영역에 새로 만든 Va.Input을 꽂아 넣는 Composition 구조 (va_component.js:5407).

this.fieldComponent = new Va.Input(optionField);  // ← 내부에 Input 새로 생성

즉, InputField = Field 껍데기 + Va.Input 인스턴스 입니다.

3. Va.Input과의 차이

항목Va.InputVa.InputField

라벨 ✕ ✓ (label)
필수 표시 ✕ ✓ (required → 라벨 옆 별표)
검증 메시지 ✕ ✓ (setValidation(), clearValidation())
설명 텍스트 ✕ ✓ (commentText)
info 툴팁 ✕ ✓ (infoButton)
ARIA 통합 부분 ✓ (aria-label / aria-invalid / aria-errormessage 자동 세팅)
값 관리 ✓ ✓ (내부 Input에 위임)
마스킹/numberComma ✓ ✓ (옵션 통과)

한 줄 요약: "라벨 붙은 폼 안에 넣을 표준 텍스트 입력."

4. 주요 속성

라벨 관련

속성기본값설명

label — 라벨 텍스트 (문자열) 또는 세부 옵션 객체({label, infoButton, ...})
labelPosition 'top' 라벨 위치 — top / bottom / left / right. Va.Config.labelPosition으로 전역 기본값 설정 가능
labelWidth '100%'(top/bottom) 또는 100(px, left/right) 라벨 영역 폭
labelAlign — 라벨 정렬
noLabel false 라벨 영역 자체를 숨김 (자리는 그대로)
seperator (labelPosition에 따라 자동) 라벨과 필드 사이 구분선
infoButton — 라벨 옆 정보 아이콘 (툴팁 트리거)
required false 필수 필드 표시 (라벨 옆 별표)

필드 관련 (Input으로 위임되는 옵션)

속성설명

type HTML input type (기본 'text')
value 필드 값
placeholder 플레이스홀더
readonly / disabled 상태
textAlign 텍스트 정렬
masking 마스킹 패턴 (Input 규약 동일)
numberComma 숫자 콤마 포맷
size 크기 (기본 'medium')
appearance / shape 시각 스타일
fieldWidth 필드 영역 폭 — 'flex'(기본, flex:1) 또는 px 값
valueType 값 타입 힌트
stopPropagation / preventParentFieldEvent 이벤트 제어

검증 관련

속성설명

validation {state, size, message} 객체 통째로
validationState 'success' / 'warning' / 'error' 등
validationMessage 검증 결과 메시지
validationSize 메시지 크기
validType / validRequired / validMax / validMin 검증 규칙
resetValue 리셋 시 되돌아갈 값

설명

속성설명

commentText 필드 위/옆에 표시되는 설명 텍스트

세부 커스터마이즈

{
    tagName: 'inputField',
    label: '이메일',
    input: {                    // ← 내부 Input에 직접 전달할 추가 옵션
        maxLength: 100,
        byteMaxLength: false,
        autocomplete: 'email'
    }
}

input 옵션 객체는 va_component.js:5404에서 내부 Va.Input 생성 시 spread됩니다.

5. 이벤트

Field 베이스가 재정의하는 이벤트 — 내부 Input의 이벤트를 가로채 InputField 자신이 dispatch합니다.

이벤트시그니처발생 시점

change (component, element, evt) 값 변경 확정. 발생 시 검증 상태 자동 리셋
focus (component, element, evt) 필드 포커스 진입
blur (component, element, evt) 포커스 이탈 (200ms debounce)
click (component, element, evt) 필드 클릭
keydown (component, element, keyCode, evt) 키다운. 발생 시 검증 상태 자동 리셋
keyup (component, element, evt) 키업
keypress (component, element, evt) 키프레스
contextmenu (component, element, evt) 우클릭
mousedown (component, element, evt) 마우스 다운

주목: change / keydown이 발생하면 자동으로 검증 표시가 리셋됩니다 (va_component.js:5006-5013) — 사용자가 값을 수정하기 시작하면 이전 에러 메시지가 자연스럽게 사라지는 UX.

6. 메서드

값

메서드설명

getValue() 내부 Input의 getValue() 위임 (numberComma/masking 규약 그대로)
setValue(value) 값 세팅 + 검증 상태 자동 리셋

상태

메서드설명

setDisabled(bool) / getDisabled() 비활성화
setReadOnly(bool) / setReadonly(bool) / getReadOnly() / getReadonly() 읽기 전용 (camelCase/lowercase 두 시그니처)
setLabel(label) 라벨 변경
setPlaceholder(text) 플레이스홀더 변경
setSize(size) 크기 변경

검증 (핵심)

메서드설명

setValidation(state, message) 검증 표시 활성화. error 클래스 + aria-invalid + aria-errormessage 자동 세팅
clearValidation() 검증 표시 제거 + aria 속성 정리

포커스

메서드설명

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

7. 내부 구조

<div elname="element" class="va-field va-input [horizontal|vertical] [disabled]" field="true">
  <div elname="inner" class="field-inner">
    <!-- labelPosition에 따라 순서 결정 -->
    <div elname="labelDiv" class="label-div [top|left|right|bottom]" style="width: ...">
      <label cpname="label" class="va-label">
        이메일 <span class="required">*</span>
      </label>
    </div>
    <div elname="comment" class="field-comment">
      <span elname="commentText" class="field-comment-text">부가 설명</span>
    </div>
    <div elname="fieldDiv" class="field-div" style="flex: 1">
      <div cpname="field" class="va-input">          ← 내부 Va.Input
        <div class="field-wrapper">
          <input elname="field" type="text" style="border:0">
          <div class="focus-line"></div>
        </div>
      </div>
    </div>
  </div>
  <div elname="validationDiv" style="display: none">
    <div class="va-validation">검증 메시지</div>    ← setValidation() 시 표시
  </div>
</div>

구조의 핵심:

  • inner div가 label / comment / field 순서를 labelPosition에 따라 재배치
  • validationDiv는 inner 밖에 위치 — 라벨 아래가 아니라 필드 아래에 별도로 붙음
  • fieldWidth: 'flex' → field-div가 flex: 1로 남는 폭을 채움. 숫자면 고정 폭.

8. labelPosition 4가지

시각적으로 크게 다른 4가지 배치:

labelPosition라벨 위치라벨 폭 기본vertical/horizontal 클래스

'top' (기본) 필드 위 '100%' vertical
'bottom' 필드 아래 '100%' vertical
'left' 필드 왼쪽 100(px) horizontal
'right' 필드 오른쪽 100(px) horizontal

전역 기본값을 Va.Config.set('labelPosition', 'left')로 지정할 수도 있습니다 (va_component.js:4869-4871).

9. 검증 사용 패턴

onSubmit() {
    const emailField = this.getRef('email');
    const value = emailField.getValue();

    if (!value) {
        emailField.setValidation('error', '이메일을 입력하세요');
        emailField.focus();
        return;
    }
    if (!value.includes('@')) {
        emailField.setValidation('error', '올바른 이메일 형식이 아닙니다');
        return;
    }
    emailField.clearValidation();
    // ... 서버 전송
}

자동 리셋: 사용자가 필드에 뭔가 입력하기 시작하면(keydown 또는 change) setValidation()으로 표시했던 에러 메시지가 자동으로 사라집니다 — 별도로 clearValidation() 안 불러도 됨.

접근성: setValidation()은 aria-invalid="true", aria-errormessage="…"를 자동 세팅해 스크린리더가 에러를 읽어줍니다.

10. input 옵션으로 내부 Input 세밀 제어

라벨 옵션과 필드 옵션이 이름이 겹치거나, Input에만 있는 옵션(예: maxLength, byteMaxLength)을 넘길 때 유용합니다.

{
    tagName: 'inputField',
    label: '주민등록번호',
    input: {
        masking: '000000-*******',   // 뒷자리 숨김
        maxLength: 14,
        autocomplete: 'off'
    }
}

input 안의 속성이 밖의 동명 속성보다 우선 적용됩니다 (spread 순서상, va_component.js:5389-5406).

11. 언제 어떤 걸 쓰나

상황컴포넌트

일반 폼 안의 텍스트 필드 (라벨 필요) Va.InputField
툴바·검색바·인라인 편집 (라벨 없음) Va.Input
숫자 전용 입력 (스피너 등) Va.NumberField
여러 줄 입력 Va.TextareaField
옵션 선택 Va.ComboboxField / Va.FilterboxField
라벨만 있고 편집은 안 함 Va.LabelField (Display 표시용)