RadioButton

이 컨트롤은 무엇인가요?

RadioButton은 HTML이 기본으로 제공하는 <input type="radio"> 태그를 "강화(enhancement)"하는 컨트롤입니다. 다른 syn.uicontrols 컨트롤들(예: TreeView, DropDownList)은 커스텀 태그(<syn-xxx>)나 별도 위젯 라이브러리를 새로 그려 넣는 방식이지만, RadioButton은 원래 있던 <input type="radio"> 엘리먼트를 그대로 사용하면서 다음 기능만 덧붙여 줍니다.

• syn-options 속성으로 선언한 설정값을 읽어 컨트롤로 등록
• syn-datafield를 이용한 폼 데이터 바인딩(getValue/setValue/clear)
• syn-events에 적어둔 이벤트 이름(change 등)을 페이지 스크립트의 event.<엘리먼트ID>_<이벤트이름> 핸들러에 자동 연결
• 같은 name을 공유하는 라디오 그룹 단위로 선택값을 조회/설정하는 헬퍼 메서드(getGroupNames, getSelectedByValue 등)

즉 화면에는 여러분이 직접 작성한 <input type="radio"> 마크업이 그대로 보이고, syn.uicontrols.$radio는 그 뒤에서 값 관리와 이벤트 연결만 대신 해주는 얇은 래퍼(wrapper)라고 이해하면 됩니다.

언제 사용하나요?

라디오버튼은 "여러 선택지 중 정확히 하나만" 고르게 할 때 사용합니다. 비슷한 역할을 하는 다른 컨트롤과 헷갈리기 쉬우므로 차이를 정리합니다.

상황	추천 컨트롤
여러 선택지 중 정확히 1개만 선택 (예: 성별, 사용여부, 배송 방법)	RadioButton
여러 선택지 중 0개 이상 여러 개를 선택 (예: 관심사, 알림 수신 항목)	CheckBox
선택지가 많아서 드롭다운으로 접어두고 그 중 1개를 선택 (예: 국가, 부서 목록)	DropDownList

정리하면, 선택지 개수가 적고(보통 2~5개) 화면에 항상 노출해서 한눈에 비교하며 고르게 하고 싶다면 RadioButton을, 선택지가 많거나 화면 공간을 아껴야 한다면 DropDownList를, 다중 선택이 필요하다면 CheckBox를 사용하세요.

빠른 시작

가장 단순한 사용 방법은 네이티브 <input type="radio"> 여러 개에 같은 name을 지정하고, 각각에 syn-options를 붙이는 것입니다.

<form autocomplete="off" id="form1" syn-datafield="MainForm">
    <input id="rdoUseYn1" name="rdoUseYn" type="radio" syn-datafield="UseYn" value="Y"
        checked="checked" syn-events="['change']" syn-options="{textContent: '사용', toSynControl: true}">
    <input id="rdoUseYn2" name="rdoUseYn" type="radio" syn-datafield="UseYn" value="N"
        syn-events="['change']" syn-options="{textContent: '미사용', toSynControl: true}">
</form>

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

페이지 스크립트(.js)에서는 이렇게 값을 읽고 씁니다.

'use strict';
let $mypage = {
    event: {
        rdoUseYn1_change() {
            console.log('선택 여부:', syn.uicontrols.$radio.getValue('rdoUseYn1'));
        }
    }
}

• syn.loader.js가 페이지의 라디오 엘리먼트를 스캔해서 RadioButton 컨트롤에 필요한 CSS/JS를 자동으로 불러와 주므로, 개발자가 별도의 <script>/<link> 태그를 더 추가할 필요가 없습니다.
• syn-options의 toSynControl: true는 "라벨(label)까지 자동으로 그려 달라"는 옵션입니다. 이미 직접 <label>을 작성해두었다면 toSynControl을 생략(기본값 false)해도 됩니다.

예제 실행하기

실습용 예제는 /uicontrols/RadioButton/example/ 아래에 있습니다. 브라우저로 아래 경로를 열어 직접 동작을 확인해 보세요.

• /uicontrols/RadioButton/example/basic.html — 라디오 그룹 기본 마크업과 라벨 자동 생성(toSynControl) 예제
• /uicontrols/RadioButton/example/getset.html — getValue/setValue/clear/selectedValue 등 값 다루기 예제
• /uicontrols/RadioButton/example/events.html — change 이벤트 처리와 그룹 조회 메서드(getGroupNames, getSelectedByValue 등) 예제

각 예제는 /js/syn.loader.js 한 줄만으로 필요한 리소스를 자동 로드하므로, HTML 파일과 짝을 이루는 .js 파일을 함께 열어 보면 실제 페이지 스크립트를 어떻게 작성하는지 확인할 수 있습니다.

더 알아보기

옵션, 메서드, 이벤트의 전체 목록과 상세 설명은 아래 API 참조 섹션 문서를 참고하세요.

실전 예제 페이지

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

basic.html

events.html

getset.html

소스와 로드 파일

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

API 참조

syn.uicontrols.$radio (v2025.10.1 기준, RadioButton.js 참고)

마크업

RadioButton은 네이티브 <input type="radio"> 엘리먼트를 그대로 사용합니다. 같은 라디오 그룹으로 묶을 항목들은 반드시 동일한 name 속성 값을 가져야 합니다.

<input id="rdoUseYn1" name="rdoUseYn" type="radio" syn-datafield="UseYn" value="Y"
    checked="checked" syn-events="['change']" syn-options="{textContent: '사용', toSynControl: true}">
<input id="rdoUseYn2" name="rdoUseYn" type="radio" syn-datafield="UseYn" value="N"
    syn-events="['change']" syn-options="{textContent: '미사용', toSynControl: true}">

속성	설명
id	컨트롤을 식별하는 고유 ID. getValue/setValue 등 개별 라디오 항목을 다루는 메서드의 대상이 됩니다.
name	라디오 그룹을 묶는 값. 같은 name을 가진 항목들 중 하나만 선택됩니다. getGroupNames/selectedValue 등 그룹 단위 메서드가 이 값을 사용합니다.
syn-datafield	폼 데이터 바인딩 시 사용할 필드명입니다.
syn-events	자동 연결할 이벤트 이름 배열(JS 배열 리터럴 문자열)입니다. 예: "['change']"
syn-options	RadioButton의 옵션(아래 Options 표 참고)을 JS 객체 리터럴 문자열로 지정합니다.
value / checked	표준 HTML 라디오 속성과 동일하게 동작합니다.

Options (defaultSetting)

syn-options에 지정할 수 있는 항목입니다. 지정하지 않으면 아래 기본값이 적용됩니다.

옵션	기본값	설명
contents	''	예약된 콘텐츠 설정값(현재 버전에서는 별도 렌더링에 사용되지 않음).
toSynControl	false	true이면 원본 <input>을 숨김 처리(id를 _hidden으로 변경)하고, textContent로 지정한 라벨과 함께 새 <span class="form-control"> 래퍼를 자동 생성해 화면에 보여줍니다. false이면 마크업을 그대로 사용하며(순수 enhancement), 라벨은 개발자가 직접 작성해야 합니다.
dataType	'string'	값의 데이터 타입 힌트입니다.
belongID	null	소속 컨테이너/그룹 식별자(다른 컨트롤과의 연계용)입니다.
getter	false	값을 읽어올 때 사용할 커스텀 처리 지정 여부입니다.
setter	false	값을 설정할 때 사용할 커스텀 처리 지정 여부입니다.
controlText	null	컨트롤에 표시할 텍스트(구현체별 사용처가 다를 수 있음)입니다.
textContent	(defaultSetting에는 없으나 toSynControl: true일 때 사용)	자동 생성되는 <label>에 표시할 문자열입니다.
validators	null	값 검증 규칙입니다.
transactConfig	null	트랜잭션(서버 통신) 관련 설정입니다.
triggerConfig	null	다른 컨트롤/이벤트와 연동하기 위한 트리거 설정입니다.

참고: toSynControl: true로 생성된 화면상의 <input>은 원래 선언했던 id를 그대로 물려받고, 원본 엘리먼트는 id + '_hidden'으로 이름이 바뀐 채 display: none 처리됩니다. getSelectedByValue/getSelectedByText/getSelectedByID 메서드는 이 _hidden 엘리먼트를 결과에서 제외하도록 구현되어 있습니다.

메서드

메서드	시그니처	설명
controlLoad	controlLoad(elID, setting)	컨트롤 초기화(생성자 역할). syn.loader.js가 자동으로 호출하므로 직접 호출할 일은 거의 없습니다.
getValue	getValue(elID, meta)	지정한 라디오 항목 하나의 checked 상태(true/false)를 반환합니다.
setValue	setValue(elID, value, meta)	지정한 라디오 항목 하나의 checked 상태를 설정합니다.
clear	clear(elID, isControlLoad)	지정한 라디오 항목의 선택을 해제합니다(checked = false).
setLocale	setLocale(elID, translations, control, options)	다국어(로케일) 적용 훅입니다(현재 버전은 별도 동작 없음).
getGroupNames	getGroupNames()	화면에 존재하는 모든 라디오 그룹의 name 목록을 중복 없이 반환합니다.
getSelectedByValue	getSelectedByValue(group)	지정한 그룹(name)에서 선택된 라디오의 value를 반환합니다.
getSelectedByText	getSelectedByText(group)	지정한 그룹에서 선택된 라디오의 라벨 텍스트(다음 형제 엘리먼트의 텍스트)를 반환합니다.
getSelectedByID	getSelectedByID(group)	지정한 그룹에서 선택된 라디오의 id를 반환합니다.
selectedValue	selectedValue(group, value)	지정한 그룹에서 value와 일치하는 라디오 항목을 선택 상태로 만듭니다.

이벤트 (syn-events)

RadioButton 자체가 별도로 발생시키는 커스텀 이벤트는 없으며, 네이티브 <input type="radio">가 발생시키는 브라우저 표준 이벤트를 syn-events에 등록해 사용합니다.

이벤트	설명
change	라디오 선택 상태가 바뀌었을 때 발생합니다. 실무에서 가장 많이 사용하는 이벤트입니다.
click	라디오 항목을 클릭했을 때 발생합니다.
focus / blur	라디오 항목이 포커스를 받거나 잃었을 때 발생합니다.

이벤트를 받으려면 syn-events="['change']"처럼 배열로 이벤트 이름을 선언하고, 페이지 스크립트에 event.<엘리먼트ID>_<이벤트이름> 형태의 핸들러 함수를 작성하면 자동으로 연결됩니다.

let $mypage = {
    event: {
        rdoUseYn1_change(evt) {
            console.log('변경됨:', syn.uicontrols.$radio.getValue('rdoUseYn1'));
        }
    }
}

참고

• 원본 소스: 1.WebHost/rdy/modules/wwwroot/wwwroot/uicontrols/RadioButton/RadioButton.js
• 스타일 정의: 1.WebHost/rdy/modules/wwwroot/wwwroot/uicontrols/RadioButton/RadioButton.css (.syn-radio 클래스)
• 사용 예제: ./example 폴더, 그리고 이 문서의 사용법 섹션의 "빠른 시작" 절