CheckBox

이 컨트롤은 무엇인가요?

CheckBox는 브라우저 네이티브 <input type="checkbox"> 엘리먼트를 그대로 사용하면서, 여기에 syn-datafield, syn-options, syn-events 속성을 붙여 체크 여부에 따라 원하는 값(문자열, 코드값 등)을 폼 데이터로 주고받을 수 있게 "강화(enhancement)"해주는 컨트롤입니다. 다른 컨트롤들(DropDownList, TreeView 등)처럼 커스텀 태그(<syn_xxx>)를 쓰는 것이 아니라, 이미 있는 <input type="checkbox"> 태그에 속성만 추가하면 되므로 가장 가볍고 배우기 쉬운 컨트롤입니다.

체크박스 자체의 boolean 상태(체크됨/안됨)는 그대로 두되, 실제로 서버에 저장하거나 화면 로직에서 쓰는 값은 checkedValue(기본 '1') / uncheckedValue(기본 '0')로 자유롭게 매핑할 수 있는 것이 핵심 기능입니다. 예를 들어 체크되면 'Y', 안되면 'N'을 넘기고 싶다면 옵션만 바꾸면 되고, HTML이나 페이지 스크립트를 따로 고칠 필요가 없습니다.

언제 사용하나요?

• 사용 여부(UseYN), 동의 여부(AgreeYN) 처럼 On/Off 두 가지 상태를 표현할 때
• 목록 화면에서 여러 항목을 각각 체크해서 일괄 처리(선택 삭제, 선택 다운로드 등)할 때
• 폼에서 "이용약관에 동의합니다"와 같이 단일 항목의 동의/거부를 받을 때
• 여러 개의 체크박스를 같은 name으로 묶어 그룹을 이루고, getGroupNames()로 화면에 존재하는 체크박스 그룹 이름들을 한 번에 조회하고 싶을 때

CheckBox는 "여러 개 중 하나만" 고를 때 쓰는 RadioButton과 다릅니다. RadioButton은 같은 그룹 내에서 상호 배타적으로 하나만 선택되지만, CheckBox는 각 항목이 독립적으로 켜지고 꺼집니다. 또한 선택지가 많거나 목록 데이터를 기반으로 다중 선택 UI를 구성해야 한다면(콤보박스 형태의 드롭다운에 체크박스 목록을 넣는 경우) DropDownCheckList처럼 리스트 데이터 바인딩을 지원하는 컨트롤을 쓰는 것이 더 적합합니다. 화면에 이미 고정된 개수의 체크박스를 하나하나 배치하는 경우라면 CheckBox로 충분합니다.

빠른 시작

가장 단순한 형태는 syn-datafield만 지정하면 됩니다.

<input id="chkAgree" type="checkbox" syn-datafield="AgreeYN">
<label for="chkAgree">이용약관에 동의합니다</label>

체크/미체크 값을 직접 지정하고 라벨을 자동으로 붙이고 싶다면 syn-options를 추가합니다.

<input id="chkUseYN" type="checkbox" syn-datafield="UseYN"
    syn-options="{checkedValue: 'Y', uncheckedValue: 'N', textContent: '사용 여부'}">

값 변경을 감지하려면 syn-events에 change를 등록하고, 페이지 스크립트(<페이지파일명>.js)에 <엘리먼트ID>_change 함수를 정의합니다.

<input id="chkNotify" type="checkbox" syn-datafield="NotifyYN" syn-events="['change']">

'use strict';
let $mypage = {
    event: {
        chkNotify_change(evt) {
            var value = syn.uicontrols.$checkbox.getValue('chkNotify');
            syn.$l.eventLog('chkNotify_change', 'value: ' + value);
        }
    }
}

페이지에는 위 스크립트 외에 다음 한 줄만 있으면 됩니다. syn.loader.js가 화면에 있는 컨트롤들을 스캔해서 필요한 CSS/JS를 알아서 불러옵니다.

<script src="/js/syn.loader.js"></script>

예제 실행하기

example/ 폴더에 3가지 예제가 있습니다. 로컬 서버 실행 후 브라우저에서 아래 경로로 접근해서 확인하세요 (예: /uicontrols/CheckBox/example/basic.html).

• basic.html / basic.js — 옵션 없이 가장 단순하게 사용하는 기본 체크박스와, checked 속성으로 기본 체크 상태를 지정하는 예제입니다.
• options.html / options.js — checkedValue / uncheckedValue로 커스텀 값(Y/N, ACTIVE/INACTIVE 등)을 지정하는 방법, disabled로 비활성화하는 방법, 같은 name으로 여러 체크박스를 묶어 배치하고 getGroupNames()로 그룹명을 조회하는 방법을 보여줍니다.
• events.html / events.js — syn-events="['change']"로 변경 이벤트를 감지하고, 버튼을 눌러 getValue / setValue / toggleValue / clear 메서드를 직접 호출해보는 예제입니다.

더 알아보기

옵션, 메서드, 이벤트의 전체 목록과 시그니처는 아래 API 참조 섹션를 참고하세요.

실전 예제 페이지

/uicontrols/CheckBox/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.

basic.html

events.html

options.html

소스와 로드 파일

항목	내용
컨트롤	CheckBox
전역 별칭	syn.uicontrols.$checkbox
버전	v2025.10.1
소스	uicontrols/CheckBox/CheckBox.js
스타일	uicontrols/CheckBox/CheckBox.css

API 참조

syn.uicontrols.$checkbox (버전: v2025.10.1)

소스: uicontrols/CheckBox/CheckBox.js, uicontrols/CheckBox/CheckBox.css

마크업

CheckBox는 커스텀 태그가 아니라 네이티브 <input type="checkbox">를 강화(enhancement)하는 방식입니다.

<input id="elId" type="checkbox" syn-datafield="Field"
    syn-options="{checkedValue: 'Y', uncheckedValue: 'N', textContent: '사용 여부'}"
    syn-events="['change']">

• id : 컨트롤 식별자(필수). 메서드 호출 시 elID로 사용합니다.
• syn-datafield : 폼 전송/바인딩 시 사용할 필드명.
• syn-options : defaultSetting을 덮어쓸 JSON(객체 리터럴) 문자열. 생략하면 기본값이 적용됩니다.
• syn-events : 페이지 스크립트의 <elID>_<eventName> 핸들러와 연결할 이벤트명 배열.
• checked : 초기 체크 상태는 네이티브 checked 속성으로 지정합니다(HTML 표준 방식 그대로).
• disabled : 네이티브 disabled 속성 또는 syn-options의 disabled 값으로 지정할 수 있습니다.

Options (defaultSetting)

옵션명	타입	기본값	설명
contents	string	''	다른 컨트롤과 공통으로 쓰이는 예약 필드입니다. CheckBox 내부 로직에서는 실제로 참조되지 않습니다.
toSynControl	boolean	false	true로 설정하면 원본 <input>을 숨기고(_hidden 접미사 부여) span.form-control 래퍼 안에 새 <input class="ui_checkbox">와 <label>을 자동 생성해 렌더링합니다. false면 원본 <input>에 syn-options만 부여하고 그대로 사용합니다.
disabled	boolean	false	체크박스 비활성화 여부. toSynControl: true일 때는 새로 생성되는 <input>의 disabled 속성에 반영됩니다.
checkedValue	string	'1'	체크되었을 때 getValue가 반환할 값이자, setValue 호출 시 이 값과 일치하면 체크 상태로 처리하는 기준값입니다.
uncheckedValue	string	'0'	체크 해제되었을 때 getValue가 반환할 값입니다.
dataType	string	'string'	값의 데이터 타입 힌트(다른 컨트롤과 공통 스키마).
belongID	string | null	null	상위 컨테이너/그룹 식별자(공통 스키마).
controlText	any | null	null	공통 스키마에 포함된 예약 필드로, CheckBox 내부 로직에서는 실제로 사용되지 않습니다.
textContent	string	''	toSynControl: true일 때 체크박스 옆에 표시할 <label> 텍스트입니다.
validators	object | null	null	유효성 검증 설정(공통 스키마).
transactConfig	object | null	null	트랜잭션(서버 호출) 연동 설정(공통 스키마). triggerEvent를 지정하면 해당 이벤트 발생 시 자동으로 트랜잭션이 실행됩니다.
triggerConfig	object | null	null	트리거 연동 설정(공통 스키마).

메서드

메서드	시그니처	설명
controlLoad	controlLoad(elID, setting)	컨트롤 초기화(생성자 역할). syn.loader.js가 화면 스캔 시 자동으로 호출하며, 개발자가 직접 호출할 일은 없습니다.
getValue	getValue(elID, meta)	체크 상태에 따라 checkedValue 또는 uncheckedValue를 반환합니다. syn-options가 없으면 checked 여부에 따라 '1'/'0'을 반환합니다.
setValue	setValue(elID, value, meta)	value를 대문자 문자열로 변환한 뒤, checkedValue와 일치하는지(또는 true/'TRUE'/'Y'/'1'인지) 비교해 checked 상태를 설정합니다. value가 falsy(빈 문자열, null 등)면 무조건 체크 해제합니다.
toggleValue	toggleValue(elID)	현재 체크 상태를 반전시킵니다(체크→해제, 해제→체크).
clear	clear(elID, isControlLoad)	체크 상태를 false(미체크)로 초기화합니다.
getGroupNames	getGroupNames()	현재 화면(document) 안의 모든 input[type='checkbox']가 가진 name 속성 값을 중복 제거해서 배열로 반환합니다.
setLocale	setLocale(elID, translations, control, options)	다국어 처리 훅입니다. CheckBox는 현재 별도 구현 없이 빈 함수로 제공됩니다.
addModuleList	addModuleList(el, moduleList, setting, controlType)	폼 제출 시 참조할 모듈 목록에 컨트롤 정보를 등록하는 내부용 메서드입니다. 직접 호출하지 않습니다.

이벤트 (syn-events)

CheckBox는 별도의 eventHooks 배열을 선언하지 않는 컨트롤입니다. 네이티브 <input type="checkbox">를 그대로 사용하기 때문에, syn-events 속성에 등록한 이벤트명은 syn.$l.addEvent(elID, eventName, handler)를 통해 표준 DOM 이벤트로 그대로 연결됩니다. 즉 브라우저가 지원하는 어떤 이벤트명이든 등록할 수 있지만, 실무에서는 아래 이벤트가 주로 사용됩니다.

이벤트명	핸들러 시그니처	설명	발생 시점
change	<elID>_change(evt)	체크 상태가 사용자 조작(클릭, 키보드 스페이스 등)으로 바뀌었을 때 발생하는 표준 DOM change 이벤트입니다.	체크박스의 체크 여부가 바뀌고 포커스가 유지된 상태에서 값이 확정될 때
click	<elID>_click(evt)	체크박스를 클릭했을 때 발생하는 표준 DOM click 이벤트입니다.	체크박스 영역(또는 연결된 <label>) 클릭 시

핸들러는 evt 인자(네이티브 Event 객체) 하나만 전달받습니다. 현재 값을 확인하려면 핸들러 안에서 syn.uicontrols.$checkbox.getValue(elID)를 호출하면 됩니다.

참고

• 실행 가능한 예제: example/basic.html, example/options.html, example/events.html
• 초보자용 개요와 사용 시나리오: 이 문서의 사용법 섹션
• 스타일 커스터마이징: CheckBox.css의 .syn-checkbox 클래스를 통해 색상 등을 재정의할 수 있습니다.