PropertyGrid

이 컨트롤은 무엇인가요?

PropertyGrid는 자바스크립트 객체 하나를 "속성명 / 값" 두 칸짜리 표 형태로 보여주고, 값의 타입에 맞는 입력 위젯(텍스트, 숫자, 체크박스, 색상, 드롭다운, JSON 편집 등)을 자동으로 만들어 주는 컨트롤입니다. Visual Studio나 여러 디자인 툴에서 흔히 보는 "속성(Properties)" 패널과 같은 역할을 합니다.

값의 타입만 보고도 대부분의 입력 위젯을 자동으로 골라주기(autoMeta) 때문에 meta를 전혀 지정하지 않아도 바로 쓸 수 있고, 필요하면 meta로 그룹 묶음·표시 이름·전용 위젯 타입·도움말·읽기전용 여부 등을 속성별로 세밀하게 조정할 수 있습니다.

언제 사용하나요?

다른 컨트롤(차트, 그리드, 커스텀 위젯 등)의 옵션 객체(defaultSetting)를 화면에서 직접 편집하게 하고 싶을 때 — createDefaultSettingMeta로 그룹/설명이 자동으로 붙은 meta를 만들 수 있습니다.
관리자 화면에서 "설정(config)" 객체처럼 속성 개수나 종류가 미리 정해지지 않은 데이터를 편집해야 할 때
폼 컨트롤을 하나하나 배치하기보다, 객체 하나를 통째로 넘겨서 표 형태 편집 UI를 빠르게 만들고 싶을 때
속성을 그룹으로 묶어서 보여주거나(meta.group), 그룹 단위로 접고 펼치는(isCollapsible) UI가 필요할 때

이미 화면 레이아웃이 고정되어 있고 입력 항목 종류가 소수로 정해져 있다면, TextBox/DropDownList/CheckBox 같은 개별 컨트롤을 직접 배치하는 편이 더 간단합니다. PropertyGrid는 "객체의 속성 구성 자체가 가변적이거나 많을 때" 진가를 발휘합니다.

빠른 시작

가장 단순한 형태는 data에 객체만 넘기면 됩니다. meta가 없으면 값의 타입을 보고 위젯이 자동으로 결정됩니다.

<syn_propertygrid id="pgBasic" syn-options="{
    data: {
        Name: '홍길동',
        Age: 32,
        UseYN: true,
        FavoriteColor: '#2563eb'
    }
}"></syn_propertygrid>

속성을 그룹으로 묶고, 각 속성의 표시 방식을 지정하고 싶다면 meta를 추가합니다.

<syn_propertygrid id="pgOptions" syn-options="{
    sort: true,
    isCollapsible: true,
    data: {
        Width: 240,
        Mode: 'edit',
        ThemeColor: '#16a34a'
    },
    meta: {
        Width: { group: 'Layout', type: 'number', options: { min: 0, max: 999, step: 10 } },
        Mode: { group: 'Behavior', type: 'options', options: ['view', 'edit', 'readonly'] },
        ThemeColor: { group: 'Layout', type: 'color' }
    }
}"></syn_propertygrid>

값이 바뀔 때마다 알림을 받고 싶다면 callback에 페이지 스크립트 함수를 점(.) 경로 문자열로 지정합니다.

<syn_propertygrid id="pgEvents" syn-options="{
    data: { NotifyYN: true, Volume: 50 },
    callback: '$this.method.handleChange'
}"></syn_propertygrid>

'use strict';
let $mypage = {
    method: {
        handleChange(element, name, value, control) {
            syn.$l.eventLog('pgEvents_change', name + ' = ' + JSON.stringify(value));
        }
    }
}

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

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

값을 조회하거나 다시 채워 넣을 때는 getValue/setValue를 사용합니다.

var value = syn.uicontrols.$propertygrid.getValue('pgBasic');
syn.uicontrols.$propertygrid.setValue('pgBasic', { Name: '김철수', Age: 28, UseYN: false, FavoriteColor: '#dc2626' });
syn.uicontrols.$propertygrid.clear('pgBasic');

예제 실행하기

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

basic.html / basic.js — meta 없이 data만 넘겨 문자열/숫자/불리언/색상 값이 각각 어떤 위젯으로 자동 표시되는지 보여주는 기본 예제이며, getValue/setValue/clear 메서드도 함께 확인합니다.
options.html / options.js — meta로 그룹(group)·타입(type)·선택 목록(options)·설명(description)을 지정하고, sort/isCollapsible로 정렬과 그룹 접기·펼치기를 사용하는 예제입니다.
events.html / events.js — callback으로 값 변경을 실시간으로 감지하고, 버튼을 눌러 getValue/setValue/clear 메서드를 직접 호출해보는 예제입니다.

더 알아보기

옵션, meta/customTypes 세부 규칙, 메서드, 콜백 시그니처의 전체 목록은 아래 API 참조 섹션을 참고하세요.
실제 소스: wwwroot/uicontrols/PropertyGrid/PropertyGrid.js, PropertyGrid.css
스타일 커스터마이징: PropertyGrid.css의 .syn-propertygrid, .pgTable, .pgGroupRow, .pgRow, .pgInput, .pgInvalid 클래스를 통해 색상/레이아웃을 재정의할 수 있습니다.

실전 예제 페이지

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

basic.html

options.html

events.html

소스와 로드 파일

항목	내용
컨트롤	`PropertyGrid`
전역 별칭	`syn.uicontrols.$propertygrid`
소스	`uicontrols/PropertyGrid/PropertyGrid.js`
스타일	`uicontrols/PropertyGrid/PropertyGrid.css`

API 참조

싱글턴 객체: syn.uicontrols.$propertygrid 소스 파일: wwwroot/uicontrols/PropertyGrid/PropertyGrid.js, wwwroot/uicontrols/PropertyGrid/PropertyGrid.css

마크업

PropertyGrid는 네이티브 태그가 아니라 <syn_propertygrid> 커스텀 태그로 사용합니다.

<syn_propertygrid id="pgSample" syn-options="{
    data: { Name: '홍길동', Age: 32, UseYN: true, FavoriteColor: '#2563eb' },
    meta: {
        Age: { group: 'General', description: '나이(세)' }
    },
    sort: false,
    isCollapsible: false,
    callback: '$mypage.handleChange'
}"></syn_propertygrid>

id는 페이지 내에서 유일해야 하며, syn.uicontrols.$propertygrid의 각종 메서드에서 이 id(elID)를 사용합니다.
data(또는 value)에 넣은 객체의 각 속성(key)이 한 줄(행)이 되고, meta가 없으면 autoMeta가 값의 자바스크립트 타입을 보고 입력 위젯 종류를 자동으로 정합니다.
callback은 함수를 직접 넣거나, "$페이지스크립트.함수명"처럼 점(.)으로 구분된 경로 문자열을 넣을 수 있습니다. 문자열이면 controlLoad 시점에 window부터 경로를 따라가며 실제 함수로 해석(resolveCallback)됩니다. 값이 바뀔 때마다 callback(element, name, value, control) 형태로 호출됩니다.
syn-options는 최초 렌더링에만 적용됩니다. 데이터를 바꿔서 다시 그리려면 setValue(elID, value, meta)를 호출하세요.

Options (defaultSetting)

옵션명	타입	기본값	설명
`data`	object \| null	`null`	그리드에 표시할 원본 값. `value`보다 우선합니다. 객체가 아니면(`null`, 배열 등) 빈 객체로 취급합니다.
`value`	object \| null	`null`	`data`가 없을 때 사용하는 표시 값(하위 호환용 별칭).
`meta`	object \| null	`null`	속성명별 메타 정보(`{ 속성명: { group, type, options, description, ... } }`). 자세한 내용은 meta 옵션 참고.
`customTypes`	object \| null	`null`	`meta.type`으로 참조할 수 있는 사용자 정의 입력 위젯(`{ 타입명: { html, valueFn 또는 makeValueFn } }`).
`helpHtml`	string	`'[?]'`	`meta.description`이 있을 때 라벨 옆에 표시되는 도움말 아이콘(툴팁 트리거)의 HTML
`sort`	boolean \| function	`false`	속성 이름 정렬 여부. `true`면 사전순 정렬, 함수를 넣으면 `Array.prototype.sort`의 비교 함수로 사용됩니다.
`isCollapsible`	boolean	`false`	`true`면 그룹 제목 행을 클릭해 해당 그룹의 속성 행을 접고 펼 수 있습니다.
`defaultGroupName`	string	`'Other'`	`meta.group`을 지정하지 않은 속성이 속하는 기본 그룹명
`mode`	string	`''`	내부적으로 `'defaultSetting'`을 지정하면 `meta`가 없는 속성에 대해 그룹/설명을 자동 추론합니다(`createDefaultSettingMeta` 참고). 일반적인 사용에서는 비워 둡니다.
`autoMeta`	boolean	`true`	`meta.type`이 없을 때 값의 자바스크립트 타입(`boolean`/`number`/`function`/객체·배열·`null`·`undefined` → `json`/`#rrggbb` 형식 문자열 → `color`)을 보고 입력 위젯 타입을 자동으로 정할지 여부
`jsonRows`	number	`5`	`type: 'json'` 또는 `type: 'function'`일 때 기본으로 표시할 `<textarea>` 줄 수(`meta.rows`로 속성별 재정의 가능)
`includeFunctions`	boolean	`true`	`false`로 지정하면 값이 함수인 속성은 목록에서 제외합니다.
`classNames`	string	`'syn-propertygrid'`	그리드 최상위 엘리먼트에 추가되는 CSS 클래스
`callback`	function \| string \| null	`null`	값이 바뀔 때마다 `(element, name, value, control)`로 호출되는 콜백. 문자열이면 점 경로로 함수를 찾아 해석합니다.
`dataType`	string	`'object'`	다른 컨트롤과 형식을 맞추기 위한 공통 속성
`belongID` / `getter` / `setter` / `controlText` / `validators` / `transactConfig` / `triggerConfig`	-	`null`/`false`	syn.uicontrols 공통 옵션(값 바인딩·유효성검사·트랜잭션 연동용)

meta 옵션 (속성명별 표시 방식)

meta는 { 속성명: { ... } } 형태이며, 각 속성별로 다음 키를 지정할 수 있습니다.

속성	타입	설명
`name`	string	라벨에 표시할 이름. 생략하면 속성명(key) 그대로 표시합니다.
`group`	string	이 속성이 속할 그룹명. 같은 그룹명끼리 묶여서 그룹 제목 행 아래에 표시됩니다.
`type`	string	입력 위젯 종류. 아래 type별 입력 위젯 참고. 생략하고 `autoMeta: true`이면 값의 타입으로 자동 추론합니다.
`options`	array \| object	`type: 'options'`일 때 선택 목록(문자열 배열 또는 `{value, text}` 배열), `type: 'number'`일 때 `{min, max, step}`
`description`	string	라벨 옆 도움말 아이콘(`helpHtml`)에 표시할 툴팁 텍스트
`showHelp`	boolean	`false`로 지정하면 도움말 아이콘 대신 입력 엘리먼트의 `title` 속성으로 설명을 붙입니다.
`readonly` / `readOnly`	boolean	입력 엘리먼트에 `readonly` 속성 부여(둘 중 하나라도 `true`면 적용)
`disabled`	boolean	입력 엘리먼트에 `disabled` 속성 부여
`placeholder`	string	입력 엘리먼트의 `placeholder` 속성
`browsable`	boolean	`false`로 지정하면 이 속성 행 자체를 렌더링하지 않습니다.
`colspan2`	boolean	`true`면 라벨 열 없이 값 입력 엘리먼트가 전체 2칸(colspan)을 차지합니다.
`rows`	number	`type: 'json'` / `'function'`일 때 `<textarea>` 줄 수(`jsonRows` 재정의)

type별 입력 위젯

`type` 값	입력 위젯	비고
(생략, `autoMeta: true`)	값의 자바스크립트 타입에 따라 자동 결정	`boolean`→체크박스, `number`→숫자, `function`→읽기전용 함수 텍스트, 객체/배열/`null`/`undefined`→JSON, `#rrggbb` 문자열→색상, 그 외→일반 텍스트
`'boolean'`	`<input type="checkbox">`
`'number'`	`<input type="number">`	`options.min`/`max`/`step` 적용
`'options'`	`<select>`	`options` 배열 필요(문자열 배열 또는 `{value, text}` 배열)
`'color'`	`<input type="color">`	값이 `#rrggbb` 형식이 아니면 `#000000`으로 보정
`'label'`	읽기 전용 `<label>`	값을 그대로 텍스트로 표시(편집 불가)
`'json'`	`<textarea>`	`JSON.stringify`로 표시, 저장 시 `JSON.parse`. 파싱 실패 시 `pgInvalid` 클래스가 붙고 이전 값이 유지됩니다.
`'function'`	읽기 전용 `<textarea>`	함수 소스코드(`toString()`)를 표시만 하며 값 자체는 원본 함수가 그대로 유지됩니다.
그 외(사용자 정의)	`customTypes[type]`	아래 customTypes 참고
(매칭 없음)	`<input type="text">`	기본값

customTypes (사용자 정의 입력 위젯)

meta.type에 표준 타입에 없는 이름을 쓰고 싶다면, customTypes에 같은 이름의 정의를 등록합니다.

customTypes: {
    rating: {
        html(elemId, name, value, meta) {
            return `<input type="range" id="${elemId}" min="0" max="5" value="${value || 0}">`;
        },
        valueFn(elemId, name) {
            var element = document.getElementById(elemId);
            return element ? Number(element.value) : 0;
        }
    }
}

키	필수	설명
`html(elemId, name, value, meta)`	예	입력 엘리먼트의 HTML 문자열(또는 DOM 노드)을 반환합니다. 최상위 엘리먼트가 하나가 아니면 `span.pgCustomValue`로 감쌉니다.
`valueFn(elemId, name)`	`makeValueFn`이 없으면 예	`getValue` 호출 시 현재 값을 읽어오는 함수. 지정하지 않으면 `document.getElementById(elemId).value`를 기본으로 사용합니다.
`makeValueFn(elemId, name, value, meta)`	아니오	`valueFn` 대신, 렌더링 시점에 클로저로 `valueFn`을 직접 만들어야 할 때 사용합니다. 반환값이 실제 `valueFn`으로 등록됩니다.

주의: customTypes로 렌더링한 입력 엘리먼트는 bindChange(change/input/keyup/paste 자동 연결)가 적용되지 않습니다. callback을 실시간으로 받으려면 html에서 만든 엘리먼트에 직접 이벤트를 연결하세요.

메서드

syn.uicontrols.$propertygrid.<메서드명>(...) 형태로 호출합니다.

메서드	시그니처	설명
controlLoad	`controlLoad(elID, setting)`	컨트롤 초기화(생성자 역할). `syn.loader.js`가 화면 스캔 시 자동으로 호출하며, 개발자가 직접 호출할 일은 없습니다.
render	`render(elID, value, setting)`	주어진 `value`/`setting`으로 그리드 테이블을 새로 그립니다. `setValue`가 내부적으로 사용합니다.
getValue	`getValue(elID, meta)`	각 속성의 현재 입력값을 모아 `{ 속성명: 값 }` 객체로 반환합니다.
setValue	`setValue(elID, value, meta)`	기존 `runtimeSetting`(또는 `setting`)을 유지한 채, 새 `value`(와 선택적으로 새 `meta`)로 그리드를 다시 그립니다.
clear	`clear(elID, isControlLoad)`	그리드 내용(테이블 DOM과 내부 `valueFuncs`/`fields`)을 모두 비웁니다.
getControl	`getControl(elID)`	등록된 컨트롤 정보(`{ id, sequence, setting, runtimeSetting, valueFuncs, fields }`)를 반환합니다.
createDefaultSettingMeta	`createDefaultSettingMeta(defaultSetting, meta)`	다른 컨트롤의 `defaultSetting` 객체를 받아, 이 PropertyGrid로 "설정값 편집기"를 만들 때 쓸 `meta`를 자동 생성합니다(그룹/설명 자동 추론, `mode: 'defaultSetting'`).
inferType	`inferType(value)`	값 하나를 보고 `autoMeta`가 사용하는 위젯 타입 문자열을 반환합니다.
normalizeSource	`normalizeSource(value)`	객체가 아니거나 배열이면 빈 객체(`{}`)로 바꿔 반환합니다.
resolveCallback	`resolveCallback(callback)`	함수는 그대로, 점(`.`) 경로 문자열은 `window`부터 따라가며 실제 함수로 변환해 반환합니다.
toSerializableSetting	`toSerializableSetting(setting)`	`setting`에서 함수 타입 값을 제외한 사본을 반환합니다(`syn-options` 속성 직렬화용).
addModuleList	`addModuleList(el, moduleList, setting, controlType)`	폼 제출 시 참조할 모듈 목록에 컨트롤 정보를 등록하는 내부용 메서드입니다. 직접 호출하지 않습니다.
setLocale	`setLocale(elID, translations, control, options)`	다국어 처리 훅입니다. PropertyGrid는 현재 별도 구현 없이 빈 함수로 제공됩니다.

이벤트 (syn-events)

PropertyGrid는 syn-events로 연결되는 <elID>_<이벤트명> 방식의 이벤트 훅을 별도로 선언하지 않습니다. 대신, 값이 바뀔 때마다 syn-options의 callback 함수가 (element, name, value, control) 인자로 직접 호출됩니다.

<syn_propertygrid id="pgEvents" syn-options="{
    data: { NotifyYN: true, Volume: 50 },
    callback: '$this.method.handleChange'
}"></syn_propertygrid>

'use strict';
let $mypage = {
    method: {
        handleChange(element, name, value, control) {
            syn.$l.eventLog('pgEvents_change', name + ' = ' + JSON.stringify(value));
        }
    }
}

element : 값이 바뀐 입력 엘리먼트(DOM)
name : 속성명(key)
value : 변환된 현재 값(체크박스는 boolean, number는 숫자, json은 파싱된 값 등)
control : getControl(elID)가 반환하는 것과 같은 컨트롤 정보 객체

customTypes로 만든 사용자 정의 입력 위젯에는 callback이 자동으로 연결되지 않으므로, 필요하면 html로 만든 엘리먼트에 직접 이벤트 리스너를 붙이세요.

참고

실행 가능한 예제: example/basic.html, example/options.html, example/events.html
스타일 커스터마이징: PropertyGrid.css의 .syn-propertygrid, .pgTable, .pgGroupRow, .pgRow, .pgInput, .pgInvalid 클래스를 통해 색상/레이아웃을 재정의할 수 있습니다.

이 컨트롤은 무엇인가요?​

언제 사용하나요?​

빠른 시작​

예제 실행하기​

더 알아보기​

실전 예제 페이지​

basic.html​

options.html​

events.html​

소스와 로드 파일​

API 참조​

마크업​

Options (defaultSetting)​

meta 옵션 (속성명별 표시 방식)​

type별 입력 위젯​

customTypes (사용자 정의 입력 위젯)​

메서드​

이벤트 (syn-events)​

참고​