컴포넌트/필드 컴포넌트
SliderField (슬라이더 필드)
VanillaFront
2026. 9. 12. 20:16
Va.SliderField — 라벨 + 드래그 슬라이더
Va.Slider가 순수 슬라이더라면, Va.SliderField는 그 위에 폼 라벨·필수 표시·검증 메시지를 얹은 완성 폼 필드입니다. Field 계열 아키텍처 그대로, 내부에 Va.Slider를 소유하는 Composition 구조.
- 클래스: Va.SliderField — va_slider.js:941
- short name: sliderField
- 상속: Va.Field (다른 Field 형제들과 같음)
- 파일: va_slider.js (별도 파일 — import 필요)
- 내부 컴포넌트: Va.Slider 인스턴스 (fieldComponent)
- isContainer: true
1. 시작하기 전 — 별도 파일 import
Slider와 마찬가지로 va_slider.js를 먼저 import.
import Va from '../../lib/va.js';
import '../../lib/va_slider.js'; // ← 필수
2. 기본 사용
{
tagName: 'sliderField',
label: '볼륨',
value: 50,
min: 0,
max: 100,
step: 1,
visibleCurrentValue: true,
required: true,
onChange: 'onVolumeChange'
}
라벨 + 검증 + 슬라이더가 한 번에 세팅.
3. Slider / 다른 Field와의 차이
항목Va.SliderVa.SliderFieldVa.NumberField
| 폼 라벨 | ✕ | ✓ | ✓ |
| 검증 메시지 | ✕ | ✓ | ✓ |
| 필수 표시(별표) | ✕ | ✓ | ✓ |
| 입력 방식 | 드래그 | 드래그 | 숫자 타이핑 + 스피너 |
| 진행 바 색상 커스텀 | ✓ | ✓ | ✕ |
| min/max 기본값 | — | min=0, max=100, step=1 | — |
| 파일 | va_slider.js | va_slider.js | va_component.js |
한 줄 요약: "폼 안 라벨 붙은 드래그 슬라이더 — 볼륨·평점·필터에 최적."
4. 주요 속성
슬라이더 전용 (Slider 계승)
속성기본값설명
| min | 0 | 최솟값 (Field에서 기본값 설정) |
| max | 100 | 최댓값 (Field에서 기본값 설정) |
| step | 1 | 증감 단위 (Field에서 기본값 설정) |
| value | 0 | 초기 값 |
| visibleCurrentValue | — | 우측에 숫자 입력창 표시 |
| visibleMinMax | — | min/max 라벨 표시 |
| thumbText | — | thumb 위 값 표시 |
| progressColor | — | 채워진 진행 바 색 |
| railColor | — | 빈 rail 색 |
| inputWidth | 80 | 숫자 입력창 폭 |
주목: SliderField는 min=0, max=100, step=1 기본값을 스스로 설정합니다 (va_slider.js:953-955). Slider 단독은 이 기본값이 없어 명시해야 했지만, Field는 편의를 위해 세팅.
라벨 관련 (Field 상속)
속성설명
| label | 폼 라벨 |
| labelPosition | top / bottom / left / right |
| labelWidth | 라벨 폭 |
| noLabel | 폼 라벨 숨김 |
| infoButton | info 아이콘 |
| required | 필수 표시 |
검증
속성설명
| validation | {state, size, message} |
| validationState | success / warning / error |
| validationMessage | 메시지 |
세부 커스터마이즈 (slider 옵션 키)
{
tagName: 'sliderField',
label: '평점',
slider: { // ← 내부 Slider에 직접 전달
thumbText: true
}
}
각 Field 계열 옵션 키:
- InputField → input
- NumberField → number
- SliderField → slider
5. 이벤트
Slider의 이벤트를 재발화:
이벤트시그니처발생 시점
| change | (component, element, value, evt) | thumb 드래그 또는 값 확정 시 |
| click | (component, element, evt) | 클릭 |
| focus / blur | (component, element, evt) | 포커스 진입/이탈 |
| contextmenu | (component, element, evt) | 우클릭 |
keydown 등 Slider의 일부 이벤트는 재발화 목록에 없음 — 필요하면 component.fieldComponent에 직접 리스너 부착.
change 콜백 예시
onVolumeChange(comp, el, value, evt) {
console.log('현재 값:', value); // 문자열 (input type=range 특성)
audio.volume = Number(value) / 100;
}
⚠️ value는 문자열 — Number() 변환 필요.
6. 메서드
값 관리
메서드설명
| setValue(value) | 값 세팅 + 슬라이더에 위임 |
| getValue() | Slider의 getValue() 위임 (문자열 반환) |
상태 (Field 상속)
메서드설명
| setDisabled(bool) / getDisabled() | 비활성화 |
| setReadOnly(bool) / setReadonly(bool) | 읽기 전용 |
| setLabel(label) | 폼 라벨 변경 |
| setSize(size) | 크기 |
검증
메서드설명
| setValidation(state, message) | 검증 표시 |
| clearValidation() | 검증 해제 |
포커스
메서드설명
| focus() / blur() | 내부 Slider에 위임 (thumb에 포커스) |
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-slider"> ← 내부 Va.Slider
<div class="field-wrapper" role="slider">
<div class="slider-div" style="--progress-value: 50%">
<input type="range" tabindex="-1">
<div class="slider-rail"></div>
<div class="slider-thumb" tabindex="0">
<div class="slider-thumb-text">50</div>
</div>
</div>
<div class="va-number">…</div> ← visibleCurrentValue일 때
</div>
</div>
</div>
</div>
<div elname="validationDiv" style="display:none">
<div class="va-validation">...</div>
</div>
</div>
8. 언제 쓰나
SliderField가 맞을 때
- 폼 안 볼륨·밝기·투명도 조절
- 가격·나이 필터 (라벨과 함께)
- 평점·비율 입력
- 라벨·검증이 필요한 감각적 값 조절
다른 걸 쓸 때
- 라벨 없이 인라인 → Va.Slider
- 정확한 숫자 입력 → Va.NumberField
- 범위(from-to) → Va.DoubleSliderField (있다면)
- 별점 → Va.StarSliderField
9. 흔한 조합 예시
// 표준
{
tagName: 'sliderField',
label: '볼륨',
value: 50,
visibleCurrentValue: true
}
// 소수점 단위 (평점)
{
tagName: 'sliderField',
label: '평점',
value: 3.5,
min: 0,
max: 5,
step: 0.1,
visibleCurrentValue: true,
inputWidth: 60
}
// 색상 커스텀
{
tagName: 'sliderField',
label: '진행률',
value: 60,
progressColor: '#0f6cbd',
railColor: '#e0e0e0',
visibleMinMax: true
}
// 좌측 라벨
{
tagName: 'sliderField',
label: '밝기',
labelPosition: 'left',
labelWidth: 100,
value: 70
}
// info 툴팁
{
tagName: 'sliderField',
label: '알림 볼륨',
infoButton: {
tooltip: '0~100 사이 값'
},
value: 50
}
// 읽기 전용 (진행률 표시)
{
tagName: 'sliderField',
label: '진행 상태',
value: 45,
readonly: true,
thumbText: true
}
10. 알아두면 좋을 주의사항
- va_slider.js import 필수 — 없으면 인식 못 함.
- getValue() 반환은 문자열 — 계산 시 Number() 변환.
- min=0/max=100/step=1 기본값 있음 — Slider 단독과 달리 편의값 세팅.
- 옵션 키 slider — 세부 커스터마이즈용.
- 일부 이벤트 재발화 안 됨 — keydown 등은 fieldComponent 직접 접근.
- focus()는 thumb에 포커스 — 실제 <input>이 아님. 키보드 화살표로 조절.
- change가 드래그 중 계속 발생 — 성능 걱정되면 debounce.
- visibleCurrentValue: true면 폭이 늘어남 — 부모 layout에서 폭 고려.
- thumb 하위 요소 elname="thumb" 추가 노출 — component.thumbElement로 접근 가능.
- 접근성 — role="slider" 자동. aria-valuemin/max/now는 명시 세팅 필요.
11. sliderField vs numberField 선택
상황추천
| 감각적 값 조절 (볼륨, 밝기) | sliderField |
| 정확한 숫자 입력 | numberField |
| 범위 선택 | doubleSliderField |
| 별점 | starSliderField |
| 큰 숫자 정밀 | numberField + numberComma |
참고
- API 문서 페이지: https://vanillafront.com/docs.html?theme=light#main#apisliderfield
- 연관: Va.Slider(내부), Va.NumberField(대체 가능한 정밀 숫자 입력)