컴포넌트/유효성
Validation (유효성)
VanillaFront
2026. 9. 14. 18:24
Va.Validation — 상태 아이콘 + 메시지 표시
폼 필드 아래 표시되는 검증/상태 메시지 컴포넌트. error/warning/success 상태를 상태별 색상·아이콘과 함께 표시합니다. 대개 개발자가 직접 배치하기보다 Field 계열이 내부에서 자동으로 사용하는 컴포넌트.
- 클래스: Va.Validation — va_component.js:167
- short name: validation
- 상속: Va.Component
- isContainer: false
- 베이스 CSS: va-validation
1. 기본 사용
{
tagName: 'validation',
state: 'error',
text: '필수 항목입니다'
}
- 상태에 따라 CSS 클래스가 붙어 색·아이콘이 결정됨
- error — 빨강, warning — 노랑, success — 초록
2. Validation의 역할
VanillaFront에서 폼 검증 결과를 사용자에게 표시하는 표준 UI 요소. 다른 프레임워크의 "에러 메시지 컴포넌트"에 해당합니다.
항목Va.Validation
| 주 용도 | 필드 아래 검증 결과 표시 |
| 상태 | error / warning / success |
| 구조 | 아이콘 + 텍스트 |
| 직접 사용 빈도 | 낮음 (Field가 자동 관리) |
한 줄 요약: "폼 검증 결과를 상태별 아이콘·색으로 표시하는 컴포넌트."
3. 주요 속성
상태
속성설명
| state | 'error' / 'warning' / 'success' — CSS 클래스로 반영 |
텍스트
속성설명
| text | 순수 텍스트 메시지 |
| innerHTML | HTML 메시지 (_sanitize 적용) |
우선순위: text > innerHTML.
이벤트 제어
속성기본값설명
| stopPropagation | true | 이벤트 버블링 차단 |
4. 이벤트
이벤트시그니처발생 시점
| click | (component, element, evt) | 메시지 클릭 |
| iconClick | (component, element, evt) | 상태 아이콘 클릭 |
| contextmenu | (component, element, evt) | 우클릭 |
| iconContextmenu | (component, element, evt) | 아이콘 우클릭 |
| focus / blur | (component, element, evt) | 포커스 진입/이탈 |
아이콘과 콘텐츠의 클릭 이벤트가 분리 — 아이콘 클릭 시 도움말 팝업을 띄우고, 콘텐츠 클릭은 다른 동작을 하는 UX가 가능.
5. 메서드
메서드설명
| setStateText(state, text) | 상태 + 텍스트를 한 번에 세팅 (가장 자주 씀) |
| setState(state) | 상태만 변경 |
| setText(text) | 텍스트만 변경 |
| setInnerHTML(html) | HTML 메시지 변경 |
| setSize(size) | 크기 변경 |
6. 내부 구조
<div elname="element" class="va-validation [error|warning|success]"
tag-name="validation">
<div elname="inner" class="validation-inner">
<span elname="icon" class="icon"></span> ← 상태 아이콘
<span elname="content" class="content [error|warning|success]">
필수 항목입니다
</span>
</div>
</div>
핵심:
- state CSS 클래스가 element와 content 모두에 적용됨
- 아이콘 자체는 element 안에 span으로 있고, CSS가 상태별로 아이콘 이미지 결정 (예: .va-validation.error .icon)
- 실제 아이콘 이미지는 테마 CSS에서 정의
7. Field 계열에서의 역할
Va.Validation은 거의 항상 Field 계열이 내부에서 사용합니다.
// Va.Field 내부에서
this.validationComponent = new Va.Validation({
state: this.validationState,
size: this.validationSize,
message: this.validationMessage
});
this.validationDivElement.appendChild(this.validationComponent.element);
그리고 Field의 setValidation(state, text) 메서드가 이 인스턴스의 setStateText()를 호출합니다:
// Va.Field.setValidation
setValidation(status, text){
this.fieldComponent.element.classList.add('error');
this.validationDivElement.style.display = 'block';
this.validationComponent.setStateText(status, text); // ← 여기
// ...
}
즉, component.setValidation('error', '메시지') 한 번 호출로 Field 하단에 자동으로 이 Validation이 표시됩니다.
8. 언제 직접 쓰나
Va.Validation을 직접 쓸 때
- 폼 필드 밖에서 상태 메시지 표시 (전체 폼 에러 요약 등)
- 알림/상태 배지 형태로 활용
- 프로세스 진행 결과 표시
대부분의 경우 Field의 setValidation()으로 자동 처리하는 게 정석. 직접 사용은 드묾.
9. 흔한 조합 예시
폼 필드 검증 (직접 사용 아님, Field 자동 관리)
// InputField에 검증 표시
this.getRef('email').setValidation('error', '올바른 이메일 형식이 아닙니다');
this.getRef('name').setValidation('warning', '이름이 너무 깁니다');
this.getRef('phone').setValidation('success', '사용 가능');
// 해제
this.getRef('email').clearValidation();
직접 사용 — 폼 전체 에러 요약
{
tagName: 'div',
layout: 'ds-flex fd-column gap-s',
tags: [
{
tagName: 'validation',
ref: 'formError',
state: 'error',
text: '',
style: { display: 'none' }
},
// ... 폼 필드들
]
}
onSubmit() {
if (invalidCount > 0) {
this.getRef('formError').setStateText('error', `${invalidCount}개 항목을 확인하세요`);
this.getRef('formError').element.style.display = 'block';
}
}
직접 사용 — 저장 결과 알림
{
tagName: 'validation',
ref: 'saveResult',
state: 'success',
text: '',
style: { display: 'none' }
}
onSaved(view, ok, res) {
if (ok) {
view.getRef('saveResult').setStateText('success', '저장되었습니다');
} else {
view.getRef('saveResult').setStateText('error', '저장 실패');
}
view.getRef('saveResult').element.style.display = 'block';
}
10. 실전 예 — Field와 함께 (표준)
class Signup extends Va.View {
onSubmit(btn, el, evt) {
const email = this.getRef('email').getValue();
const pw = this.getRef('password').getValue();
// 검증 후 Validation 자동 표시
if (!email.includes('@')) {
this.getRef('email').setValidation('error', '올바른 이메일 형식이 아닙니다');
return;
}
this.getRef('email').clearValidation();
if (pw.length < 8) {
this.getRef('password').setValidation('error', '8자 이상 입력하세요');
return;
}
if (pw.length >= 12) {
this.getRef('password').setValidation('success', '안전한 비밀번호');
}
// 서버 저장
SignupService.save(this, { email, password: pw });
}
config() {
return {
tagName: 'page',
tags: [{
tagName: 'panel',
tags: [
{
tagName: 'inputField',
ref: 'email',
label: '이메일',
required: true
},
{
tagName: 'inputField',
ref: 'password',
label: '비밀번호',
required: true
},
{
tagName: 'button',
text: '가입',
appearance: 'primary',
onClick: 'onSubmit'
}
]
}]
};
}
}
핵심:
- Va.Validation을 직접 배치하지 않아도 Field가 자동으로 하나씩 소유
- setValidation(state, text) 호출로 즉시 메시지 표시
- clearValidation()으로 해제
11. 알아두면 좋을 주의사항
- state CSS 클래스 필수 — CSS가 상태별 색·아이콘을 정의. 지정 안 하면 시각적 구분 없음.
- text vs innerHTML — text가 우선. XSS 조심.
- setStateText(state, text) 가장 편리 — 한 번에 두 값 세팅.
- Field의 setValidation() 활용 — 대부분의 경우 직접 사용 안 함. Field 내장 메서드 사용.
- state가 클래스로 element와 content 모두에 부여 — 스타일링 시 두 선택자 모두 활용 가능.
- 자체 표시 로직 없음 — 처음엔 표시되나 개발자가 display: none으로 숨겨두었다가 조건부로 노출하는 게 관행.
- 아이콘은 CSS로 결정 — 인라인 옵션으로 아이콘 변경 불가. CSS 오버라이드 필요.
- 접근성 — role="alert"이나 aria-live 자동 세팅 없음. 중요 알림은 별도 처리 권장.
- stopPropagation: true 기본 — 상위로 이벤트 안 올라감.
- isContainer: false — 자식 담기 없음.
- focus/blur 이벤트 있음 — 자체 tabindex 없어 실질적으로 잘 안 발생.
- Field 계열은 검증 자동 리셋 로직 포함 — 사용자가 필드 편집하면 이전 에러 자동 사라짐 (Field 쪽 로직).
12. validation vs Va.Alert vs 인라인 메시지 선택
상황추천
| 폼 필드 아래 검증 메시지 | Field 내장 (자동 Va.Validation) |
| 폼 전체 에러 요약 | Va.Validation 직접 배치 |
| 저장/조회 결과 알림 | Va.Validation 또는 Va.Alert |
| 모달형 알림 | Va.Alert / Va.Confirm |
| 토스트형 짧은 알림 | Va.Toast |
| 상태 아이콘 + 짧은 텍스트 | Va.Validation |
참고
- API 문서 페이지: https://vanillafront.com/docs.html?theme=light#main#apivalidation
- 연관: Va.Field(내부에서 자동 사용), Va.Alert(모달형 알림 대체)