[]
DEMOS DOC DESIGNER API
DOWNLOAD
(Showing Draft Content)

양식 컨트롤

SpreadJS는 워크시트에 양식 컨트롤을 추가하거나, 양식 컨트롤이 포함된 기존 Excel 파일을 열 수 있습니다.

양식 컨트롤은 사용자가 워크시트의 셀 데이터와 상호작용할 수 있도록 도와줍니다. 예를 들어, 양식 컨트롤은 다이얼로그 시트에서 항목을 선택하는 데 사용할 수 있습니다. 이는 다음 이미지에서 볼 수 있습니다.

overview-formcontrols.png

SpreadJS는 다음과 같은 유형의 양식 컨트롤을 지원합니다:

  • 버튼

  • 스핀 버튼

  • 목록 상자

  • 콤보 상자

  • 체크박스

  • 옵션 버튼

  • 그룹 버튼

  • 레이블

  • 스크롤바

SpreadJS는 GC.Spread.Sheets.Shapes 네임스페이스를 제공하며, 이 네임스페이스의 addFormControl 함수를 통해 새 양식 컨트롤을 도형 컬렉션에 추가할 수 있습니다. 또한 FormControlType 열거형을 통해 모든 내장 양식 컨트롤 유형을 정의할 수 있습니다.

양식 컨트롤을 구현하기 위해서는 IFormControlOptions 인터페이스에서 제공하는 다양한 옵션(IOptionButtonFormControlOptions, ICheckBoxFormControlOptions, ISpinButtonFormControlOptions, IScrollBarFormControlOptions, IListBoxFormControlOptions, IComboBoxFormControlOptions, IGroupBoxFormControlOptions 등)을 사용할 수 있습니다.

또한, 양식 컨트롤은 cellLink 속성을 통해 셀과 연결될 수 있습니다. 이로 인해 양식 컨트롤의 값이 변경되면 연결된 셀의 값도 변경됩니다. UI 작업, API 호출 또는 연결된 셀의 값을 변경할 때 양식 컨트롤의 값이 변경되면 FormControlValueChanged 이벤트가 발생합니다. 양식 컨트롤에는 상호작용을 제어하는 enabled 속성도 있으며, false로 설정하면 상호작용이 비활성화됩니다. 기본값은 true입니다.

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와 일관되지만, 모든 스타일 설정이 모든 양식 컨트롤에서 적용 가능한 것은 아닙니다.

참고: SpreadJS는 JSON 입출력 작업 시 Excel 양식 컨트롤을 지원합니다.


양식 컨트롤 추가하기

워크시트에 각 양식 컨트롤을 추가하는 방법을 살펴보겠습니다.


버튼

버튼 양식 컨트롤은 addFormControl 메서드에 FormControlType 열거형의 button 옵션을 전달하여 워크시트에 추가할 수 있습니다. text 및 style 속성을 사용하여 버튼 컨트롤의 텍스트와 스타일을 설정할 수 있습니다. 또한 bind 이벤트를 호출하여 버튼 클릭 시 사용자에게 알림을 줄 수 있습니다.

button-gif.gif

다음 코드는 버튼 양식 컨트롤을 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 스핀 버튼 값이 변경되었을 때 콘솔에 메시지를 기록하거나 출력할 수 있습니다.

spin-button-gif.gif

다음 코드는 스핀 버튼을 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 컨트롤의 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.

listbox-formcontrol.png

다음 코드는 리스트박스를 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 값이 변경되었을 때 콘솔에 메시지를 출력할 수 있습니다.

combobox-formcontrol.png

다음 코드는 콤보박스를 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 컨트롤 값이 변경될 때 콘솔에 메시지를 출력할 수도 있습니다.

checkbox-gif.gif

다음 코드는 체크박스를 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.

option-button.gif

다음 코드는 옵션 버튼을 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 값 변경 시 콘솔에 메시지를 출력할 수 있습니다.

group-box.png

다음 코드는 그룹박스를 추가하는 방법을 보여줍니다:

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 속성을 사용하여 텍스트를 설정할 수 있습니다.

label.png

다음 코드는 레이블을 추가하는 방법을 보여줍니다:

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 이벤트를 호출하여 값이 변경될 때 콘솔에 메시지를 출력할 수 있습니다.

scroll-bar.png

다음 코드는 스크롤바를 추가하는 방법을 보여줍니다:

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)에서 원하는 양식 컨트롤을 선택합니다.

    ribbon-for-form-controls.png

    선택한 양식 컨트롤이 시트에 추가됩니다.

    control-added-sheet.png

  2. 양식 컨트롤을 선택한 다음, Ctrl + 마우스 왼쪽 클릭 또는 마우스 오른쪽 클릭으로 컨트롤을 이동하거나 크기를 조정할 수 있습니다.

    combobox-designer-gif.gif

  3. 앞의 GIF와 같이 오른쪽 클릭 후 [도형 서식(Format Shape)] 옵션을 선택하여 도형 모양, 텍스트, 컨트롤 옵션 등을 양식 컨트롤의 유형에 따라 사용자 정의할 수 있습니다.


일반적으로 양식 컨트롤이 선택되지 않은 상태에서는 마우스 왼쪽 버튼으로 직접 상호작용할 수 있으며, 선택된 상태에서는 이동이나 크기 조정은 가능하지만 회전은 불가능합니다.

제한 사항

양식 컨트롤은 VBA 코드 및 매크로를 지원하지 않습니다.