유효성 검사(validate) 사용법 (syn.$v)

개요

syn.$v는 폼 컨트롤(input 등)에 대한 클라이언트 사이드 유효성 검사 기능을 제공합니다. 필수 입력(required), 정규식 패턴(pattern), 숫자 범위(range), 사용자 정의 함수(custom) 규칙을 노드 단위로 등록한 뒤, 단일 노드/여러 노드/폼 전체 단위로 검증을 실행하고 실패 메시지를 모아서 보여줄 수 있습니다.

로드 방법

syn.js가 로드되면 전역에 syn.$v(원본 이름: syn.$validation)로 즉시 사용할 수 있습니다.

빠른 시작

syn.$v.required('txt_userName', true, '이름을 입력해 주세요.');
const isValid = syn.$v.validateControl('txt_userName');
if (isValid == false) {
    alert(syn.$v.toMessages());
}

주요 시나리오

1. 필수 입력 검사

required(el, isRequired, message)로 노드에 필수 입력 규칙을 등록하고, validateControl()로 검사합니다.

syn.$v.required('txt_userName', true, '이름은 필수 입력입니다.');

if (syn.$v.validateControl('txt_userName') == false) {
    alert(syn.$v.toMessages());
}

2. 정규식 패턴 검사

syn.$v.regexs에 미리 정의된 정규식(numeric, email, juminNo, url, mobilePhone 등)을 활용하거나 직접 정규식을 전달할 수 있습니다.

syn.$v.pattern('txt_email', 'email', {
    expr: syn.$v.regexs.email,
    message: '올바른 이메일 형식이 아닙니다.'
});

3. 숫자 범위 검사

range(el, validID, options)은 minOperator/maxOperator 비교 연산자를 조합해 다양한 범위 조건을 표현할 수 있습니다.

syn.$v.pattern('txt_age', 'numeric', { expr: syn.$v.regexs.numeric, message: '숫자를 입력해 주세요.' });
syn.$v.range('txt_age', 'ageRange', {
    min: 0, max: 100,
    minOperator: '<', maxOperator: '>',
    message: '1 ~ 100 사이의 값을 입력해 주세요.'
});

4. 사용자 정의 검증 함수

custom()은 페이지 스크립트의 $this.method 아래 정의된 함수(또는 전역 함수)를 호출해 검증합니다.

// syn.loader.js 페이지 스크립트의 method 블록
method: {
    customValidation(options) {
        return syn.$l.get('txt_custom').value.trim() != '';
    }
}

// 검증 규칙 등록
syn.$v.custom('txt_custom', 'notEmpty', {
    functionName: 'customValidation',
    message: '사용자 지정 검사에 실패했습니다.'
});

5. 여러 노드 / 폼 전체 검증

validateControls(els)는 지정한 노드 목록을, validateForm()은 지금까지 규칙이 등록된 모든 노드를 한 번에 검사합니다.

const isValid = syn.$v.validateForm();
if (isValid == false) {
    alert(syn.$v.toMessages());
}

실전 예제 페이지

/sample/syn/validate.html 예제에서 다음 항목을 실습할 수 있습니다.

속성: isContinue, messages, elements, targetEL, regexs, roles, valueType/validType
메서드: setElement, required, pattern, range, custom, removeValidate/remove, clear, validateControl, validateControls, validateForm, toMessages, getRoleValue/getRoleName

주의 사항

required(), pattern(), range(), custom()은 등록 시 message(그리고 pattern/range는 expr/min,max,minOperator,maxOperator)가 없으면 경고 로그만 남기고 아무 규칙도 등록하지 않습니다.
isContinue가 true(기본값)이면 검증 중 실패가 있어도 모든 규칙을 계속 검사하며, false이면 첫 실패에서 즉시 중단합니다.
toMessages()를 호출하면 내부 messages 배열이 비워지므로, 여러 번 메시지를 참조해야 한다면 호출 전에 값을 복사해 두어야 합니다.
custom() 검증은 $this.method[functionName]을 우선 찾고, 없으면 전역(context[functionName])에서 함수를 찾습니다. 두 곳 모두 없으면 검증이 실패로 처리됩니다.
validateForm()은 elements에 등록된 노드만 검사하므로, setElement()/pattern()/range()/custom()으로 최소 한 번 등록된 노드만 대상이 됩니다.

API 참조

모듈 정보

항목	내용
전역 별칭	`syn.$v` (원본: `context.$validation`)
소스 위치	`2.Modules/wwwroot/wwwroot/js/syn.js` (약 2351~2679번째 줄)
예제 페이지	`/sample/syn/validate.html`
의존 모듈	`syn.$l`(`getElement`, `eventLog`), `syn.$string`(`isNullOrEmpty`, `isNumber`, `toNumber`), `context.$this`(사용자 정의 검증 함수 조회용)

속성

`syn.$v.isContinue`

타입: boolean
설명: 검증 도중 실패가 발생해도 나머지 규칙을 계속 검사할지(true, 기본값) 아니면 첫 실패에서 즉시 중단할지(false) 여부입니다.

`syn.$v.messages`

타입: string[]
설명: 검증 실패 시 등록된 message들이 누적되는 배열입니다. toMessages() 호출 시 비워집니다.

`syn.$v.targetEL`

타입: HTMLElement | null
설명: setElement()로 마지막에 설정된 대상 노드입니다.

`syn.$v.elements`

타입: object
설명: 노드 id를 key로, { pattern: {}, range: {}, custom: {} } 형태의 검증 규칙 모음을 value로 갖는 맵입니다.

`syn.$v.roles`

타입: object (Object.freeze)
설명: Root(0), Administrator(100), Master(200), Architect(300), Manager(400), BusinessOwner(500), Operator(600), Developer(700), Designer(800), User(900) 권한 등급 상수입니다.

`syn.$v.valueType`

타입: object (Object.freeze)
설명: valid, valueMissing, typeMismatch, patternMismatch, tooLong, rangeUnderflow, rangeOverflow, stepMismatch 값 검증 상태 코드입니다.

`syn.$v.validType`

타입: object (Object.freeze)
설명: required(0), pattern(1), range(2), custom(3) 검증 종류 코드입니다.

`syn.$v.regexs`

타입: object (Object.freeze)
설명: pattern() 검증에서 바로 사용할 수 있는 사전 정의된 정규식 모음입니다. (alphabet, juminNo, numeric, email, url, ipAddress, date, mobilePhone, seoulPhone, areaPhone, onesPhone, float, isoDate)

메서드

`syn.$v.initializeValidObject(el)`

설명: 지정한 DOM 엘리먼트의 id에 대해 elements 맵에 { pattern: {}, range: {}, custom: {} } 항목이 없으면 생성합니다. setElement() 내부에서 자동으로 호출되는 헬퍼로, 보통 직접 호출할 필요는 없습니다.
매개변수
이름 타입 필수 설명
el HTMLElement Y id를 가진 DOM 엘리먼트
반환값: object — 해당 노드의 검증 규칙 객체

이름	타입	필수	설명
el	HTMLElement	Y	id를 가진 DOM 엘리먼트

예시

const el = document.getElementById('txt_userName');
const validObject = syn.$v.initializeValidObject(el);

`syn.$v.setElement(el)`

설명: 유효성 검사 대상 노드를 targetEL로 설정하고, 해당 노드의 검증 규칙 저장 공간을 초기화합니다. required/pattern/range/custom 내부에서 자동으로 호출됩니다.
매개변수
이름 타입 필수 설명
el string | HTMLElement Y 노드 id 또는 DOM 엘리먼트
반환값: syn.$v — 메서드 체이닝을 위한 자기 자신
예시
```
syn.$v.setElement('txt_userName');
```

`syn.$v.required(el, isRequired, message)`

설명: 지정한 노드에 필수 입력 검증 규칙을 설정합니다. message가 없으면 로그만 남기고 아무 작업도 하지 않습니다.
매개변수
이름 타입 필수 설명
el string | HTMLElement Y 노드 id 또는 DOM 엘리먼트
isRequired boolean N 필수 여부, 기본값 true
message string Y 검증 실패 시 표시할 메시지
반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

예시

syn.$v.required('txt_userName', true, '이름을 입력해 주세요.');

`syn.$v.pattern(el, validID, options)`

설명: 지정한 노드에 정규식 패턴 검증 규칙을 추가합니다. options.expr와 options.message가 없으면 로그만 남기고 등록하지 않습니다.

매개변수

이름	타입	필수	설명
el	string \| HTMLElement	Y	노드 id 또는 DOM 엘리먼트
validID	string	Y	규칙 식별자 (동일 노드에 여러 pattern 규칙을 등록할 때 구분용)
options.expr	RegExp	Y	검사할 정규식
options.message	string	Y	검증 실패 시 표시할 메시지

반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

예시

syn.$v.pattern('txt_email', 'email', { expr: syn.$v.regexs.email, message: '이메일 형식이 아닙니다.' });

`syn.$v.range(el, validID, options)`

설명: 지정한 노드에 숫자 범위 검증 규칙을 추가합니다. options.min, options.max가 숫자가 아니거나 연산자/메시지가 없으면 등록하지 않습니다.

매개변수

이름	타입	필수	설명
el	string \| HTMLElement	Y	노드 id 또는 DOM 엘리먼트
validID	string	Y	규칙 식별자
options.min	number	Y	최소값
options.max	number	Y	최대값
options.minOperator	string	Y	최소값 비교 연산자 (`>`, `>=`, `<`, `<=`, `==`, `!=`)
options.maxOperator	string	Y	최대값 비교 연산자 (`>`, `>=`, `<`, `<=`, `==`, `!=`)
options.message	string	Y	검증 실패 시 표시할 메시지

반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

예시

syn.$v.range('txt_age', 'ageRange', { min: 0, max: 100, minOperator: '<', maxOperator: '>', message: '1 ~ 100 사이 값을 입력해 주세요.' });

`syn.$v.custom(el, validID, options)`

설명: 지정한 노드에 사용자 정의 함수 기반 검증 규칙을 추가합니다. options.functionName, options.message가 없으면 등록하지 않습니다.

매개변수

이름	타입	필수	설명
el	string \| HTMLElement	Y	노드 id 또는 DOM 엘리먼트
validID	string	Y	규칙 식별자
options.functionName	string	Y	`$this.method` 또는 전역에 정의된 검증 함수 이름
options.message	string	Y	검증 실패 시 표시할 메시지
options.*	any	N	검증 함수에 전달할 추가 매개변수

반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

예시

syn.$v.custom('txt_custom', 'notEmpty', { functionName: 'customValidation', message: '검사에 실패했습니다.' });

`syn.$v.removeValidate(validType, validID)`

설명: 현재 targetEL(마지막으로 setElement()한 노드)에서 지정한 종류(pattern/range/custom)의 규칙 하나를 제거합니다.
매개변수
이름 타입 필수 설명
validType string Y 'pattern', 'range', 'custom' 중 하나
validID string Y 제거할 규칙 식별자
반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

이름	타입	필수	설명
validType	string	Y	`'pattern'`, `'range'`, `'custom'` 중 하나
validID	string	Y	제거할 규칙 식별자

예시

syn.$v.setElement('txt_email');
syn.$v.removeValidate('pattern', 'email');

`syn.$v.remove(validID)`

설명: 현재 targetEL에서 pattern/range/custom 전체 종류를 대상으로 지정한 validID의 규칙을 모두 제거합니다.
매개변수
이름 타입 필수 설명
validID string Y 제거할 규칙 식별자
반환값: syn.$v — 메서드 체이닝을 위한 자기 자신

이름	타입	필수	설명
validID	string	Y	제거할 규칙 식별자

예시

syn.$v.setElement('txt_age');
syn.$v.remove('numeric');

`syn.$v.clear()`

설명: isContinue를 true로, messages를 빈 배열로, targetEL을 null로, elements를 빈 객체로 초기화하여 모든 검증 상태를 리셋합니다.
매개변수: 없음
반환값: syn.$v — 메서드 체이닝을 위한 자기 자신
예시
```
syn.$v.clear();
```

`syn.$v.validateControl(el)`

설명: 단일 노드에 등록된 required/pattern/range/custom 규칙을 순서대로 검사합니다. 실패한 규칙의 메시지는 messages에 누적됩니다.
매개변수
이름 타입 필수 설명
el string | HTMLElement Y 노드 id 또는 DOM 엘리먼트
반환값: boolean — 모든 규칙 통과 여부 (엘리먼트를 찾지 못하면 true)

예시

const isValid = syn.$v.validateControl('txt_userName');

`syn.$v.validateControls(els)`

설명: 여러 노드를 한 번에 검사합니다. isContinue가 false이면 첫 실패 노드에서 검사를 중단합니다.
매개변수
이름 타입 필수 설명
els HTMLElement[] | HTMLElement Y 노드 배열 또는 단일 노드
반환값: boolean — 모든 노드의 검증 통과 여부

이름	타입	필수	설명
els	HTMLElement[] \| HTMLElement	Y	노드 배열 또는 단일 노드

예시

const isValid = syn.$v.validateControls(syn.$l.get('txt_userName', 'txt_email'));

`syn.$v.validateForm()`

설명: elements에 등록된 모든 노드에 대해 validateControl()을 실행합니다.
매개변수: 없음
반환값: boolean — 모든 노드의 검증 통과 여부
예시
```
const isValid = syn.$v.validateForm();
```

`syn.$v.toMessages()`

설명: 누적된 messages 배열을 줄바꿈(\n)으로 연결한 문자열로 반환하고, 내부 messages 배열을 비웁니다.
매개변수: 없음
반환값: string — 연결된 오류 메시지 문자열

예시

if (syn.$v.validateForm() == false) {
    alert(syn.$v.toMessages());
}

`syn.$v.getRoleValue(roleNames, isHighLow)`

설명: 역할 이름(들)을 roles에 정의된 값으로 변환합니다. 여러 개를 전달하면 isHighLow에 따라 최소값 또는 최대값을 반환합니다.
매개변수
이름 타입 필수 설명
roleNames string | string[] Y 역할 이름 또는 이름 배열
isHighLow boolean N true(기본값)면 최소값, false면 최대값 반환
반환값: number — 역할 값 (일치하는 이름이 없으면 -1)

이름	타입	필수	설명
roleNames	string \| string[]	Y	역할 이름 또는 이름 배열
isHighLow	boolean	N	true(기본값)면 최소값, false면 최대값 반환

예시

const value = syn.$v.getRoleValue('Manager'); // 400

`syn.$v.getRoleName(roleValues, isHighLow)`

설명: 역할 값(들)을 roles에 정의된 이름으로 변환합니다. 여러 개를 전달하면 isHighLow에 따라 최소값 또는 최대값에 해당하는 이름을 반환합니다.
매개변수
이름 타입 필수 설명
roleValues number | string | Array Y 역할 값 또는 값 배열
isHighLow boolean N true(기본값)면 최소값, false면 최대값 기준으로 이름 반환
반환값: string | null — 역할 이름 (일치하는 값이 없으면 null)

이름	타입	필수	설명
roleValues	number \| string \| Array	Y	역할 값 또는 값 배열
isHighLow	boolean	N	true(기본값)면 최소값, false면 최대값 기준으로 이름 반환

예시

const name = syn.$v.getRoleName(400); // 'Manager'

이름	타입	필수	설명
el	string \| HTMLElement	Y	노드 id 또는 DOM 엘리먼트
isRequired	boolean	N	필수 여부, 기본값 true
message	string	Y	검증 실패 시 표시할 메시지

개요​

로드 방법​

빠른 시작​

주요 시나리오​

1. 필수 입력 검사​

2. 정규식 패턴 검사​

3. 숫자 범위 검사​

4. 사용자 정의 검증 함수​

5. 여러 노드 / 폼 전체 검증​

실전 예제 페이지​

주의 사항​

관련 모듈​

API 참조​

모듈 정보​

속성​

syn.$v.isContinue​

syn.$v.messages​

syn.$v.targetEL​

syn.$v.elements​

syn.$v.roles​

syn.$v.valueType​

syn.$v.validType​

syn.$v.regexs​

메서드​

syn.$v.initializeValidObject(el)​

syn.$v.setElement(el)​

syn.$v.required(el, isRequired, message)​

syn.$v.pattern(el, validID, options)​

syn.$v.range(el, validID, options)​

syn.$v.custom(el, validID, options)​

syn.$v.removeValidate(validType, validID)​

syn.$v.remove(validID)​

syn.$v.clear()​

syn.$v.validateControl(el)​

syn.$v.validateControls(els)​

syn.$v.validateForm()​

syn.$v.toMessages()​

syn.$v.getRoleValue(roleNames, isHighLow)​

syn.$v.getRoleName(roleValues, isHighLow)​

개요

로드 방법

빠른 시작

주요 시나리오

1. 필수 입력 검사

2. 정규식 패턴 검사

3. 숫자 범위 검사

4. 사용자 정의 검증 함수

5. 여러 노드 / 폼 전체 검증

실전 예제 페이지

주의 사항

관련 모듈

API 참조

모듈 정보

속성

`syn.$v.isContinue`

`syn.$v.messages`

`syn.$v.targetEL`

`syn.$v.elements`

`syn.$v.roles`

`syn.$v.valueType`

`syn.$v.validType`

`syn.$v.regexs`

메서드

`syn.$v.initializeValidObject(el)`

`syn.$v.setElement(el)`

`syn.$v.required(el, isRequired, message)`

`syn.$v.pattern(el, validID, options)`

`syn.$v.range(el, validID, options)`

`syn.$v.custom(el, validID, options)`

`syn.$v.removeValidate(validType, validID)`

`syn.$v.remove(validID)`

`syn.$v.clear()`

`syn.$v.validateControl(el)`

`syn.$v.validateControls(els)`

`syn.$v.validateForm()`

`syn.$v.toMessages()`

`syn.$v.getRoleValue(roleNames, isHighLow)`

`syn.$v.getRoleName(roleValues, isHighLow)`