Va.StarSliderField — 라벨 + 별점 입력
Va.StarSlider가 순수 별점 입력이라면, Va.StarSliderField는 그 위에 폼 라벨·필수 표시·검증 메시지를 얹은 완성 폼 필드입니다. Field 계열 아키텍처 그대로, 내부에 Va.StarSlider를 소유하는 Composition 구조. 리뷰 폼에 라벨 붙일 때 정석.
- 클래스: Va.StarSliderField — va_slider.js:1039
- short name: starSliderField
- 상속: Va.Field (다른 Field 형제들과 같음)
- 파일: va_slider.js (별도 파일 — import 필요)
- 내부 컴포넌트: Va.StarSlider 인스턴스 (fieldComponent)
- isContainer: true
1. 시작하기 전 — 별도 파일 import
import Va from '../../lib/va.js';
import '../../lib/va_slider.js'; // ← Slider 계열 모두 이 파일에
2. 기본 사용
{
tagName: 'starSliderField',
label: '만족도',
value: 3,
starCount: 5,
required: true,
onChange: 'onRatingChange'
}
라벨 + 검증 + 별점 아이콘이 한 번에 세팅.
3. StarSlider / SliderField와의 차이
항목Va.StarSliderVa.StarSliderFieldVa.SliderField
| 폼 라벨 | ✕ | ✓ | ✓ |
| 검증 메시지 | ✕ | ✓ | ✓ |
| 필수 표시(별표) | ✕ | ✓ | ✓ |
| UI 형태 | 별 아이콘 | 별 아이콘 | rail + thumb |
| 입력 방식 | 클릭 | 클릭 | 드래그 |
| starCount/starColor | ✓ | ✓ | ✕ |
한 줄 요약: "폼 안 라벨 붙은 별점 입력 — 리뷰·평점 폼에 정석."
4. 주요 속성
별 관련 (StarSlider 계승)
속성기본값설명
| value | 0 | 현재 별점 값 |
| starCount | 5 | 표시할 별 개수 |
| starColor | 'orange' | 채워진 별 색상 |
| starDisabledColor | 'var(--colorNeutralForegroundDisabled)' | 비활성 별 색상 |
| visibleValue | — | 별 옆에 값 숫자 표시 |
| max | — | 최댓값 매핑 (별 개수와 값 스케일 분리) |
| steps | — | 세분화 단계 (반쪽 별 등, 실제 동작 확인 필요) |
⚠️ StarSliderField의 starDisabledColor 기본값이 StarSlider와 다름 — var(--colorNeutralForegroundDisabled) (Field는 폼 관점 색상). StarSlider는 var(--colorStrokeDisabled). 프로젝트 테마에 따라 미묘한 차이.
라벨 관련 (Field 상속)
속성설명
| label | 폼 라벨 |
| labelPosition | top / bottom / left / right |
| labelWidth | 라벨 폭 |
| noLabel | 폼 라벨 숨김 |
| infoButton | info 아이콘 |
| required | 필수 표시 |
검증
속성설명
| validation | {state, size, message} |
| validationState | success / warning / error |
| validationMessage | 메시지 |
세부 커스터마이즈 (starSlider 옵션 키)
{
tagName: 'starSliderField',
label: '평점',
starSlider: { // ← 내부 StarSlider에 직접 전달
starColor: '#f8b400'
}
}
각 Field 계열 옵션 키:
- SliderField → slider
- StarSliderField → starSlider
5. 이벤트
StarSlider의 이벤트를 재발화:
이벤트시그니처발생 시점
| change | (component, element, value, evt) | 별 클릭으로 값 변경 시. value는 새 별점. 내부적으로 this.value도 자동 갱신됨 |
| click | (component, element, evt) | 클릭 |
| focus / blur | (component, element, evt) | 포커스 진입/이탈 |
| contextmenu | (component, element, evt) | 우클릭 |
주목: change 리스너 내부에서 this.value = value 자동 세팅 (va_slider.js:1105)합니다. SliderField에서는 없던 명시 세팅으로, Field 컴포넌트 자체가 값을 인지하도록 처리.
change 콜백 예시
onRatingChange(comp, el, value, evt) {
console.log('별점:', value); // 3
// this.value도 자동으로 3이 되어 있음
}
6. 메서드
값 관리 (Field 상속)
메서드설명
| getValue() | 내부 StarSlider의 getValue() 위임 |
| setValue(value) | Field 상속 |
주의: StarSliderField는 setValue/getValue를 오버라이드하지 않습니다. 값은 Field 베이스가 관리.
상태 (Field 상속)
메서드설명
| setDisabled(bool) / getDisabled() | 비활성화 |
| setReadOnly(bool) / setReadonly(bool) | 읽기 전용 |
| setLabel(label) | 폼 라벨 변경 |
| setSize(size) | 크기 |
검증
메서드설명
| setValidation(state, message) | 검증 표시 |
| clearValidation() | 검증 해제 |
포커스
메서드설명
| focus() / blur() | 위임 (내부 StarSlider엔 focus()가 없어 실효 제한적) |
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-star-slider"> ← 내부 Va.StarSlider
<div class="field-wrapper">
<div class="star-div">
<span class="icon ico_star_fill">★</span>
<span class="icon ico_star_fill">★</span>
<span class="icon ico_star_fill">★</span>
<span class="icon ico_star">☆</span>
<span class="icon ico_star">☆</span>
</div>
<div class="value-div" style="display:none">3</div>
</div>
</div>
</div>
</div>
<div elname="validationDiv" style="display:none">
<div class="va-validation">...</div>
</div>
</div>
8. 언제 쓰나
StarSliderField가 맞을 때
- 폼 안 리뷰·평점 입력 (숙소, 상품, 콘텐츠)
- 만족도 조사 폼
- 품질 평가 (내부 관리 화면)
- 라벨·검증이 필요한 별점 UI
- 필수 별점 입력 (required: true)
다른 걸 쓸 때
- 라벨 없이 인라인 → Va.StarSlider
- 감각적 슬라이더 → Va.SliderField
- 정확한 수치 입력 → Va.NumberField
- 배타 선택 (매우 나쁨~매우 좋음) → Va.RadioGroupField
- 하트/좋아요 → Va.ToggleButton (커스텀 아이콘)
9. 흔한 조합 예시
// 표준
{
tagName: 'starSliderField',
label: '만족도',
value: 0,
starCount: 5,
required: true
}
// 값 표시 포함
{
tagName: 'starSliderField',
label: '평점',
value: 3,
visibleValue: true
}
// 10개 별
{
tagName: 'starSliderField',
label: '점수',
starCount: 10,
value: 7
}
// 100점 만점 매핑
{
tagName: 'starSliderField',
label: '평가',
starCount: 5,
max: 100,
value: 80 // → 4번째 별까지
}
// 브랜드 컬러
{
tagName: 'starSliderField',
label: '별점',
starColor: '#f8b400',
value: 4
}
// 좌측 라벨
{
tagName: 'starSliderField',
label: '만족도',
labelPosition: 'left',
labelWidth: 100,
starCount: 5
}
// 읽기 전용 (평점 표시)
{
tagName: 'starSliderField',
label: '평균 평점',
value: 4.5,
readonly: true,
starColor: '#f8b400',
visibleValue: true
}
// info 툴팁
{
tagName: 'starSliderField',
label: '전체 만족도',
infoButton: {
tooltip: '전반적인 서비스 만족도를 평가해주세요'
},
starCount: 5
}
10. 실전 예 — 리뷰 등록 폼
class ReviewForm extends Va.View {
onRatingChange(comp, el, value, evt) {
// 별점에 따라 라벨 자동 갱신
const labels = { 1: '나빠요', 2: '별로', 3: '보통', 4: '좋아요', 5: '최고!' };
this.getRef('label').setValue(labels[value] || '');
}
onSubmit(btn, el, evt) {
const service = this.getRef('serviceRating').getValue();
const quality = this.getRef('qualityRating').getValue();
const comment = this.getRef('comment').getValue();
if (service === 0 || quality === 0) {
new Va.Alert({ title: '알림', message: '별점을 모두 선택하세요' }).show(this);
return;
}
ReviewService.save(this, { service, quality, comment }, (view, ok) => {
if (ok) new Va.Alert({ title: '완료', message: '리뷰가 등록되었습니다' }).show(view);
});
}
config() {
return {
tagName: 'page',
tags: [{
tagName: 'panel',
tags: [
{ tagName: 'h2', innerHTML: '리뷰 작성' },
{
tagName: 'starSliderField',
ref: 'serviceRating',
label: '서비스 만족도',
starCount: 5,
starColor: '#f8b400',
required: true,
onChange: 'onRatingChange'
},
{
tagName: 'starSliderField',
ref: 'qualityRating',
label: '품질',
starCount: 5,
starColor: '#f8b400',
required: true
},
{ tagName: 'div', ref: 'label', innerHTML: '' },
{
tagName: 'textareaField',
ref: 'comment',
label: '의견',
placeholder: '자세한 의견을 남겨주세요'
},
{
tagName: 'button',
text: '등록',
appearance: 'primary',
onClick: 'onSubmit'
}
]
}]
};
}
}
흐름:
- 두 개의 별점 필드로 서비스·품질 각각 평가
- 별점 변경 시 라벨 텍스트 자동 갱신
- 두 별점 모두 필수 검증 후 제출
11. 알아두면 좋을 주의사항
- va_slider.js import 필수 — 없으면 인식 못 함.
- starDisabledColor 기본값이 StarSlider와 다름 — Field는 --colorNeutralForegroundDisabled, Slider는 --colorStrokeDisabled. 프로젝트 테마에서 두 변수 값 확인.
- change 시 this.value 자동 세팅 — 값 관리가 자동으로 됨.
- 옵션 키 starSlider — 세부 커스터마이즈용.
- focus() 실효 미미 — 내부 StarSlider의 focus()가 없어서.
- 별 아이콘 하드코딩 — ico_star / ico_star_fill. 다른 아이콘 원하면 커스터마이즈 필요.
- starColor 인라인 style로 세팅 — CSS 오버라이드보다 우선.
- 초기 value: 0 — 아무 별도 안 채워진 상태. 명시 지정 권장.
- readonly: true도 클릭 반응 없음 — StarSlider의 동작 그대로.
- getValue() 반환은 숫자 — Slider 계열 중 그나마 사용 편함.
- max 매핑 시 소수점 발생 가능 — starCount: 5, max: 7 → 별 3개 = 4.2. 정수만 원하면 max를 starCount의 배수로.
- 필수 검증 자동화 없음 — required: true는 별표 표시만. 실제 값 검증은 콜백에서.
12. starSliderField vs radioGroupField vs sliderField 선택
상황추천
| 리뷰·평점 (직관적) | starSliderField |
| 매우 나쁨~매우 좋음 5단계 | radioGroupField |
| 연속 수치 조절 | sliderField |
| 정확한 점수 입력 | numberField |
| 좋아요/싫어요 | toggleButton (하트 아이콘) |
"별로 표현하는 게 자연스러우면 starSliderField" — 명확한 사용처.
참고
- API 문서 페이지: https://vanillafront.com/docs.html?theme=light#main#apistarsliderfield
- 연관: Va.StarSlider(내부), Va.SliderField(형제 슬라이더 계열)
'컴포넌트 > 필드 컴포넌트' 카테고리의 다른 글
| SwitchField (스위치필드) (0) | 2026.09.13 |
|---|---|
| Switch (스위치) (0) | 2026.09.13 |
| StarSlider (스타슬라이더) (0) | 2026.09.13 |
| DoubleSlider (더블슬라이더) (0) | 2026.09.13 |
| SliderField (슬라이더 필드) (0) | 2026.09.12 |