# 양식 컨트롤
## Content
SpreadJS는 워크시트에 양식 컨트롤을 추가하거나, 양식 컨트롤이 포함된 기존 Excel 파일을 열 수 있습니다.
양식 컨트롤은 사용자가 워크시트의 셀 데이터와 상호작용할 수 있도록 도와줍니다. 예를 들어, 양식 컨트롤은 다이얼로그 시트에서 항목을 선택하는 데 사용할 수 있습니다. 이는 다음 이미지에서 볼 수 있습니다.
SpreadJS는 다음과 같은 유형의 양식 컨트롤을 지원합니다:
* 버튼
* 스핀 버튼
* 목록 상자
* 콤보 상자
* 체크박스
* 옵션 버튼
* 그룹 버튼
* 레이블
* 스크롤바
SpreadJS는 **[GC.Spread.Sheets.Shapes](https://demo.mescius.co.kr/spreadjs/api/modules/GC.Spread.Sheets.Shapes)** 네임스페이스를 제공하며, 이 네임스페이스의 addFormControl 함수를 통해 새 양식 컨트롤을 도형 컬렉션에 추가할 수 있습니다. 또한 FormControlType 열거형을 통해 모든 내장 양식 컨트롤 유형을 정의할 수 있습니다.
양식 컨트롤을 구현하기 위해서는 **[IFormControlOptions](https://demo.mescius.co.kr/spreadjs/api/modules/GC.Spread.Sheets.Shapes#iformcontrolshapeoptions)** 인터페이스에서 제공하는 다양한 옵션(**IOptionButtonFormControlOptions, ICheckBoxFormControlOptions, ISpinButtonFormControlOptions, IScrollBarFormControlOptions, IListBoxFormControlOptions, IComboBoxFormControlOptions, IGroupBoxFormControlOptions** 등)을 사용할 수 있습니다.
또한, 양식 컨트롤은 cellLink 속성을 통해 셀과 연결될 수 있습니다. 이로 인해 양식 컨트롤의 값이 변경되면 연결된 셀의 값도 변경됩니다. UI 작업, API 호출 또는 연결된 셀의 값을 변경할 때 양식 컨트롤의 값이 변경되면 FormControlValueChanged 이벤트가 발생합니다. 양식 컨트롤에는 상호작용을 제어하는 enabled 속성도 있으며, false로 설정하면 상호작용이 비활성화됩니다. 기본값은 true입니다.
>type=warning
> **enabled** 속성은 Excel 가져오기/내보내기에서도 지원되며, Excel과 동일한 동작을 보장합니다.
## 스타일 설정
다음 표는 양식 컨트롤 유형별 지원되는 스타일 설정을 나타냅니다:
| 컨트롤 | 텍스트 스타일 | 텍스트 정렬 | 채우기 | 선 | Excel 지원 |
| --- | ------- | ------ | --- | --- | -------- |
| Button | Yes | Yes | No | No | Yes |
| Option Button | Yes | Yes | Yes | Yes | 일부 그라데이션 및 이미지 채우기 속성만 지원됨 |
| Checkbox | Yes | Yes | Yes | Yes | 일부 그라데이션 및 이미지 채우기 속성만 지원됨 |
| Label | Yes | Yes | Yes | Yes | 단색 채우기 및 채우기 없음만 지원됨. 선 스타일은 미지원 |
| Group Box | Yes | No | No | No | Yes |
| ComboBox | Yes | No | No | No | No |
| ListBox | Yes (글꼴)
No (색상) | No | No | No | No |
| Spin Button | No | No | No | No | Yes |
| Scrollbar | No | No | No | No | Yes |
스타일 API는 도형 API와 일관되지만, 모든 스타일 설정이 모든 양식 컨트롤에서 적용 가능한 것은 아닙니다.
>type=warning
> **참고:** SpreadJS는 JSON 입출력 작업 시 Excel 양식 컨트롤을 지원합니다.
>
## 양식 컨트롤 추가하기
워크시트에 각 양식 컨트롤을 추가하는 방법을 살펴보겠습니다.
### 버튼
버튼 양식 컨트롤은 `addFormControl` 메서드에 `FormControlType` 열거형의 `button` 옵션을 전달하여 워크시트에 추가할 수 있습니다. `text` 및 `style` 속성을 사용하여 버튼 컨트롤의 텍스트와 스타일을 설정할 수 있습니다. 또한 `bind` 이벤트를 호출하여 버튼 클릭 시 사용자에게 알림을 줄 수 있습니다.
다음 코드는 버튼 양식 컨트롤을 추가하는 방법을 보여줍니다:
```JavaScript
var button = sheet.shapes.addFormControl("button", GC.Spread.Sheets.Shapes.FormControlType.button, 50, 50, 160, 100);
button.text("Click me");
var style = button.style();
style.textEffect.color = "rgb(0, 0, 0)";
style.textEffect.font = "bold 21px Calibri";
style.textFrame.vAlign = GC.Spread.Sheets.VerticalAlign.center;
style.textFrame.hAlign = GC.Spread.Sheets.HorizontalAlign.center;
button.style(style);
sheet.bind(GC.Spread.Sheets.Events.FormControlButtonClicked, function (s, args) {
alert("button clicked...");
});
```
### 스핀 버튼
워크시트에 스핀 버튼(Spin button)을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `spinButton` 옵션을 전달하면 됩니다. 또한 `options` 메서드를 사용하여 스핀 버튼 옵션을 설정하고, 스핀 버튼 값을 할당할 수 있습니다. 나아가 `bind` 이벤트를 호출하여 스핀 버튼 값이 변경되었을 때 콘솔에 메시지를 기록하거나 출력할 수 있습니다.
**다음 코드는 스핀 버튼을 추가하는 방법을 보여줍니다:**
```JavaScript
var spinButton = sheet.shapes.addFormControl("spin button", GC.Spread.Sheets.Shapes.FormControlType.spinButton, 50, 50, 160, 100);
var options = spinButton.options();
options.minValue = 0;
options.maxValue = 50;
options.step = 1;
options.cellLink = "A1";
spinButton.options(options);
spinButton.value(25);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
### 리스트 박스
워크시트에 리스트박스(ListBox) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `listBox` 옵션을 전달하면 됩니다. `options` 메서드를 사용하여 리스트박스의 옵션을 설정하고, 입력 범위를 지정하며, 선택 유형을 설정하고 셀에 연결할 수 있습니다. 사용자가 리스트박스의 값을 변경하면 연결된 셀의 값도 함께 변경됩니다. 또한 `bind` 이벤트를 호출하여 컨트롤의 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.
다음 코드는 리스트박스를 추가하는 방법을 보여줍니다:
```JavaScript
for (var i = 0; i < 14; i++) {
sheet.setValue(i, 0, "A" + (i + 1));
}
var listBox = sheet.shapes.addFormControl("list box", GC.Spread.Sheets.Shapes.FormControlType.listBox, 100, 50, 200, 150);
var options = listBox.options();
options.inputRange = "A1:A14";
options.cellLink = "C1";
options.selectionType = GC.Spread.Sheets.Shapes.ListBoxSelectionType.single;
listBox.options(options);
listBox.value(2);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
### 콤보 박스
워크시트에 콤보박스(ComboBox) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `comboBox` 옵션을 전달하면 됩니다. `options` 메서드를 사용하여 콤보박스 옵션을 설정하고, 입력 범위를 지정하며, 드롭다운 길이를 설정하고 셀과 연결할 수 있습니다. 사용자가 콤보박스의 값을 변경하면 연결된 셀의 값도 함께 변경됩니다. 또한 `bind` 이벤트를 호출하여 값이 변경되었을 때 콘솔에 메시지를 출력할 수 있습니다.
다음 코드는 콤보박스를 추가하는 방법을 보여줍니다:
```JavaScript
for (let i = 0; i < 14; i++) {
sheet.setValue(i, 0, "A" + (i + 1));
}
var comboBox = sheet.shapes.addFormControl("comboBox", GC.Spread.Sheets.Shapes.FormControlType.comboBox, 100, 50, 200, 30);
var options = comboBox.options();
options.inputRange = "A1:A14";
options.cellLink = "C1";
options.dropDownLines = 6;
comboBox.options(options);
comboBox.value(1);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
### 체크 박스
워크시트에 체크박스(CheckBox) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `checkBox` 옵션을 전달하면 됩니다. 또한 `options` 메서드를 사용하여 체크박스의 옵션을 설정하고 스타일을 설정하며 셀과 연결할 수 있습니다. `bind` 이벤트를 호출하여 컨트롤 값이 변경될 때 콘솔에 메시지를 출력할 수도 있습니다.
다음 코드는 체크박스를 추가하는 방법을 보여줍니다:
```JavaScript
var checkBox = sheet.shapes.addFormControl("check box", GC.Spread.Sheets.Shapes.FormControlType.checkBox, 50, 50, 100, 30);
checkBox.text("football");
var options = checkBox.options();
options.cellLink = "C1";
checkBox.options(options);
var style = checkBox.style();
style.fill.type = GC.Spread.Sheets.Shapes.ShapeFillType.solid;
style.fill.color = "green";
style.fill.transparency = 0.5;
style.line.color = "red";
style.line.transparency = 0.5;
style.line.width = 2;
checkBox.style(style);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
### 옵션 버튼
워크시트에 옵션 버튼(Option Button) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `optionButton` 옵션을 전달하면 됩니다. 옵션 버튼의 `options` 메서드를 사용하여 스타일과 셀 연결 등을 설정할 수 있습니다. `bind` 이벤트를 호출하여 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.
다음 코드는 옵션 버튼을 추가하는 방법을 보여줍니다:
```JavaScript
var maleOptionButton = sheet.shapes.addFormControl("male", GC.Spread.Sheets.Shapes.FormControlType.optionButton, 50, 50, 100, 30);
maleOptionButton.text("male");
var options = maleOptionButton.options();
options.cellLink = "C1";
maleOptionButton.options(options);
maleOptionButton.value(true);
var femaleOptionButton = sheet.shapes.addFormControl("female", GC.Spread.Sheets.Shapes.FormControlType.optionButton, 160, 50, 100, 30);
femaleOptionButton.text("female");
var style = femaleOptionButton.style();
style.fill.type = GC.Spread.Sheets.Shapes.ShapeFillType.solid;
style.fill.color = "green";
style.fill.transparency = 0.5;
style.line.color = "red";
style.line.transparency = 0.5;
style.line.width = 2;
femaleOptionButton.style(style);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
### 그룹 박스
워크시트에 그룹박스(GroupBox) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `groupBox` 옵션을 전달하면 됩니다. `options` 메서드를 사용하여 그룹박스 옵션을 설정하고 셀을 연결하거나 텍스트를 추가할 수 있습니다. 또한 `bind` 이벤트를 호출하여 값 변경 시 콘솔에 메시지를 출력할 수 있습니다.
다음 코드는 그룹박스를 추가하는 방법을 보여줍니다:
```JavaScript
var contactMethod = sheet.shapes.addFormControl("email", GC.Spread.Sheets.Shapes.FormControlType.groupBox, 40, 130, 240, 80);
contactMethod.text("contact method");
var email = sheet.shapes.addFormControl("email", GC.Spread.Sheets.Shapes.FormControlType.optionButton, 50, 160, 100, 30);
email.text("email");
var phone = sheet.shapes.addFormControl("phone", GC.Spread.Sheets.Shapes.FormControlType.optionButton, 160, 160, 100, 30);
phone.text("phone");
options = phone.options();
options.cellLink = "C6";
phone.options(options);
phone.value(true);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
**GroupBox** 양식 **컨트롤을 사용하여 옵션 버튼을 그룹화하는 규칙은 다음과 같습니다:**
* 같은 그룹박스 내의 옵션 버튼은 동일한 그룹에 속합니다. 그룹박스 내부에 옵션 버튼의 경계선이 완전히 포함되어야 하며, 그룹박스 내부에 텍스트만 있는 경우는 그룹으로 간주되지 않습니다.
* 그룹박스 외부의 모든 옵션 버튼은 하나의 동일한 그룹으로 간주됩니다.
* 옵션 버튼이 셀과 연결되면, 동일 그룹의 모든 옵션 버튼은 해당 셀과 연결됩니다.
### 레이블
`FormControlType` 열거형의 `label` 옵션을 `addFormControl` 메서드에 전달하면 워크시트에 라벨(Label) 양식 컨트롤을 추가할 수 있습니다. `text` 속성을 사용하여 텍스트를 설정할 수 있습니다.
다음 코드는 레이블을 추가하는 방법을 보여줍니다:
```JavaScript
var label = sheet.shapes.addFormControl("label", GC.Spread.Sheets.Shapes.FormControlType.label, 50, 50, 160, 30);
label.text("I am a label");
```
### 스크롤바
워크시트에 스크롤바(ScrollBar) 양식 컨트롤을 추가할 수 있습니다. 이를 위해 `addFormControl` 메서드의 매개변수로 `FormControlType` 열거형의 `scrollBar` 옵션을 전달합니다. 또한 `options` 메서드를 사용하여 스크롤바의 옵션을 설정하고 셀과 값을 연결할 수 있습니다. `bind` 이벤트를 호출하여 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.
다음 코드는 스크롤바를 추가하는 방법을 보여줍니다:
```JavaScript
var scrollBar = sheet.shapes.addFormControl("scrollBar", GC.Spread.Sheets.Shapes.FormControlType.scrollBar, 125, 21, 30, 118);
var options = scrollBar.options();
options.minValue = 1;
options.maxValue = 5;
options.step = 1;
options.pageChange = 2;
options.cellLink = "C1";
scrollBar.options(options);
scrollBar.value(1);
sheet.bind(GC.Spread.Sheets.Events.FormControlValueChanged, function (s, args) {
console.log("value changed...", args.newValue);
});
```
## SpreadJS 디자이너 사용하기
디자이너에서 양식 컨트롤을 사용하려면 다음 단계를 따르시기 바랍니다:
1. 디자이너 리본에서 **[삽입(Insert)]** 탭을 클릭한 후, **컨트롤** 갤러리(Controls gallery)에서 원하는 양식 컨트롤을 선택합니다.
선택한 양식 컨트롤이 시트에 추가됩니다.
2. 양식 컨트롤을 선택한 다음, **Ctrl + 마우스 왼쪽 클릭** 또는 **마우스 오른쪽 클릭**으로 컨트롤을 이동하거나 크기를 조정할 수 있습니다.
3. 앞의 GIF와 같이 **오른쪽 클릭 후 [도형 서식(Format Shape)]** 옵션을 선택하여 도형 모양, 텍스트, 컨트롤 옵션 등을 양식 컨트롤의 유형에 따라 사용자 정의할 수 있습니다.
일반적으로 양식 컨트롤이 **선택되지 않은 상태**에서는 마우스 왼쪽 버튼으로 직접 상호작용할 수 있으며, **선택된 상태**에서는 이동이나 크기 조정은 가능하지만 회전은 불가능합니다.
## **제한 사항**
양식 컨트롤은 VBA 코드 및 매크로를 지원하지 않습니다.