TextArea
이 컨트롤은 무엇인가요?
TextArea는 네이티브 <textarea> 요소를 향상(enhancement)시키는 syn.uicontrols 컨트롤입니다.
syn-options 속성에 지정한 옵션 값(toSynControl: true, 기본값)에 따라 내부적으로 CodeMirror 에디터로 변환되어, 줄 번호(line number) 표시, 들여쓰기 단위 지정 등 코드 편집에 가까운 UI를 제공합니다. toSynControl: false로 설정하면 CodeMirror 변환 없이 순수 HTML <textarea> 그대로 동작하며, maxlength(또는 maxlengthB) 속성에 의한 글자 수(바이트 수) 초과 알림 기능만 덧붙습니다.
컨트롤이 로드되면 페이지 스크립트 안에서 syn.uicontrols.$textarea의 메서드(getValue, setValue, clear 등)로 값을 읽고 쓸 수 있고, syn-events 속성에 등록한 이벤트 이름에 대응하는 event.<엘리먼트ID>_<이벤트명> 핸들러가 자동으로 연결됩니다.
언제 사용하나요?
- 여러 줄(멀티라인)의 텍스트를 입력받아야 할 때 (예: 메모, 설명, 소스 코드, 쿼리문 등)
- 입력 글자 수(또는 바이트 수) 제한과 초과 알림이 필요할 때 (
maxlength/maxlengthB) - 줄 번호를 보여주며 소스 코드나 정형화된 텍스트를 편집해야 할 때 (
toSynControl: true, 기본값)
TextBox와의 차이
| 구분 | TextBox | TextArea |
|---|---|---|
| 입력 형태 | 한 줄(single-line) 입력 | 여러 줄(multi-line) 입력 |
| 기반 요소 | <input> | <textarea> |
| 편집기 확장 | 없음 | toSynControl: true일 때 CodeMirror 기반 에디터로 확장 (줄 번 호, 들여쓰기 등) |
| 대표 용도 | 이름, 코드값 등 짧은 문자열 | 메모, 설명, 소스 코드 등 긴 텍스트 |
빠른 시작
<textarea id="txtMemo" syn-options="{width: '100%', height: '200px'}" syn-events="[]"></textarea>
페이지가 로드되면 syn 프레임워크가 id="txtMemo" 요소를 자동으로 찾아 syn.uicontrols.$textarea로 초기화합니다. 별도의 JS 초기화 코드를 작성할 필요가 없습니다.
값을 읽고 쓸 때는 페이지 스크립트에서 다음과 같이 사용합니다.
// 값 읽기
var text = syn.uicontrols.$textarea.getValue('txtMemo');
// 값 쓰기
syn.uicontrols.$textarea.setValue('txtMemo', '안녕하세요');
// 값 지우기
syn.uicontrols.$textarea.clear('txtMemo');
예제 실행하기
아래 예제는 /uicontrols/TextArea/example/ 경로에서 직접 열어 확인할 수 있습니다.
example/basic.html— 기본 사용법, getValue/setValue/clear 버튼 데모example/validation.html—maxlength/maxlengthB를 이용한 글자 수(바이트 수) 제한 데모example/events.html—syn-events로 CodeMirror 이벤트(change 등)를 연결하는 데모
각 예제 html은 <script src="/js/syn.loader.js"></script> 한 줄만 있으면 되며, 나머지 CSS/JS는 로더가 자동으로 주입합니다.
더 알아보기
자세한 옵션, 메서드, 이벤트 목록은 같은 폴더의 아래 API 참조 섹션 문서를 참고하세요.
실전 예제 페이지
/uicontrols/TextArea/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.
basic.html
events.html
validation.html
소스와 로드 파일
| 항목 | 내용 |
|---|---|
| 컨트롤 | TextArea |
| 전역 별칭 | syn.uicontrols.$textarea |
| 버전 | v2025.3.14 |
| 소스 | uicontrols/TextArea/TextArea.js |
| 스타일 | uicontrols/TextArea/TextArea.css |
API 참조
syn.uicontrols.$textarea
마크업
<textarea id="txtMemo"
syn-options="{width: '100%', height: '200px', lineNumbers: true}"
syn-events="['change', 'blur']"
maxlengthB="200">기본값</textarea>
syn-options: JSON 형식의 문자열로 옵션(defaultSetting)을 덮어씁니다.syn-events: 이 요 소에서 사용할 이벤트 이름 배열(문자열)입니다. 페이지 스크립트의event.<엘리먼트ID>_<이벤트명>핸들러와 자동으로 연결됩니다. (toSynControl: true일 때만 동작, 아래 "이벤트" 참고)maxlength/maxlengthB: 입력 가능한 최대 길이를 제한합니다.maxlengthB가 있으면 이 값이 우선하며 바이트 기준(한글 등 비영문 문자는 3바이트로 계산)으로 초과 여부를 검사합니다.maxlengthB가 있으면 실제maxlength속성값으로 복사되어 적용됩니다.
Options (defaultSetting)
TextArea.js의 defaultSetting에 정의된 값 그대로입니다. syn-options 속성으로 필요한 값만 덮어써서 사용합니다.
| 옵션 | 기본값 | 설명 |
|---|---|---|
width | '100%' | 컨트롤 너비. 엘리먼트에 인라인 style.width가 지정돼 있으면 그 값이 우선됩니다. |
height | '240px' | 컨트롤 높이. 엘리먼트에 인라인 style.height가 지정돼 있으면 그 값이 우선됩니다. |
indentUnit | 4 | toSynControl: true(CodeMirror 모드)일 때 들여쓰기 폭(칸 수). |
lineNumbers | true | toSynControl: true(CodeMirror 모드)일 때 줄 번호 표시 여부. |
toSynControl | true | true이면 <textarea>를 CodeMirror 에디터로 변환합니다(줄 번호, 들여쓰기 등 코드 편집 UI 제공). false이면 순수 HTML <textarea> 그대로 사용하고, maxlength/maxlengthB 초과 알림 기능만 덧붙습니다. |
resize | false | false이면 el.style.resize = 'none'으로 설정해 사용자가 크기를 조절하지 못하게 막습니다. |
dataType | 'string' | 값의 데이터 타입 표기. |
belongID | null | 소속 그룹/컨테이너 식별자. |
getter | false | 값 조회 시 사용할 커스텀 로직 연결 여부. |
setter | false | 값 설정 시 사용할 커스텀 로직 연결 여부. |
controlText | null | 컨트롤에 표시할 보조 텍스트. |
validators | null | 유효성 검증 설정. |
transactConfig | null | 데이터 송수신(트랜잭션) 관련 설정. |
triggerConfig | null | 트리거 동작 관련 설정. |
메서드
syn.uicontrols.$textarea.<메서드명>(...) 형태로 호출합니다.
| 메서드 | 매개변수 | 반환값 | 설명 |
|---|---|---|---|
getValue | elID | string | 현재 입력 된 텍스트를 반환합니다. toSynControl: true이면 CodeMirror 에디터의 값을, 아니면 <textarea>의 value를 반환합니다. |
setValue | elID, value | 없음 | 텍스트 값을 설정합니다. |
clear | elID, isControlLoad | 없음 | 텍스트 값을 빈 문자열로 초기화합니다. |
countLines | elID | number | 현재 텍스트를 \n 기준으로 나눈 줄 수를 반환합니다. |
getControl | elID | `object \ | null` |
controlLoad | elID, setting | 없음 | 컨트롤 초기화 로직입니다. syn 프레임워크가 페이지 로드 시 자동으로 호출하며, 직접 호출할 필요는 없습니다. |
setLocale | elID, translations, control, options | 없음 | 다국어 텍스트 적용 훅입니다. 현재 구현은 빈 함수(별도 동작 없음)입니다. |
이벤트 (syn-events)
syn-events="[...]"에 나열한 이벤트 이름은 toSynControl: true(기본값, CodeMirror 모드)일 때만 동작합니다. 각 이름은 CodeMirror 에디터의 editor.on(이벤트명, handler)에 그대로 전달되므로, CodeMirror 5 이벤트 이름을 사용할 수 있습 니다. 자주 쓰는 이벤트는 다음과 같습니다.
| 이벤트 | 설명 |
|---|---|
change | 텍스트 내용이 변경되었을 때 발생합니다. |
blur | 컨트롤이 포커스를 잃을 때 발생합니다. |
focus | 컨트롤이 포커스를 얻을 때 발생합니다. |
cursorActivity | 커서 위치나 선택 영역이 바뀔 때 발생합니다. |
이벤트 핸들러는 페이지 스크립트에서 다음과 같이 정의합니다.
let $pagename = {
event: {
txtMemo_change(cm, change) {
syn.$l.eventLog('txtMemo_change', cm.getValue());
}
}
}
참고:
maxlength또는maxlengthB속성이 지정되어 있으면,syn-events에blur를 등록하지 않아도 내부적으로 blur 시 글자 수(바이트 수) 초과 여부를 검사해 알림을 띄우는 동작이 항상 추가됩니다.
toSynControl: false(순수<textarea>모드)로 설정하면syn-events로 등록한 커스텀 이벤트는 연결되지 않으며,maxlength/maxlengthB에 의한 blur 시 초과 알림만 동작합니다.
참고
- 실제 구현 파일:
TextArea.js,TextArea.css toSynControl: true일 때 내부적으로 CodeMirror 5를 사용합니다. 세부 옵션은 CodeMirror 공식 문서를 참고하세요.- 글자 수 제한 검사는 UTF-8 바이트 기준으로 계산되며, 한글 등 비영문 문자는 3바이트로 계산됩니다.