# 셀 버튼

## Content

셀 버튼(Cell buttons)은 시트 셀에 추가하여 부가적인 기능을 구성할 수 있는 미리 정의된 버튼 집합입니다. 셀 버튼은 사용자가 셀 버튼을 클릭하거나, 셀을 편집하거나, 셀 위에 마우스를 올리는 등의 작업에 대해 특정 동작을 구성할 수 있도록 합니다.
[cellbuttons](/spreadjs/api/v19/classes/GC.Spread.Sheets.Style#cellButtons) 유형은 [Style](/spreadjs/api/v19/classes/GC.Spread.Sheets.Style) 클래스에 속하므로, 선택적으로 적용할 수 있는 이름이 지정된 스타일(named style)을 생성하여 셀에 쉽게 적용할 수 있습니다.
예를 들어, 셀에 색상 선택기 드롭다운이 있는 버튼을 만들기 위해 사용자 정의 색상 선택기 스타일을 정의하고 이를 사용하여 셀에 적용할 수 있습니다. 스타일은 재사용 가능하며 다른 셀에도 쉽게 적용할 수 있습니다.
아래 GIF는 원하는 사용자 정의 작업을 달성하기 위해 일부 셀 버튼 명령 및 속성을 사용하는 예시를 보여줍니다.

* 'Insert' 캡션이 있는 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/basic-cellbutton.gif)

    ```JavaScript
    // Workbook과 Worksheet 구성
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    // 캡션이 있는 기본 버튼 추가
    var basicButttonStyle = new GC.Spread.Sheets.Style();
    basicButttonStyle.cellButtons = 
    [
        {
            caption: "Insert"
        }
    ];
    activeSheet.setText(2, 3, "Basic button with caption");
    activeSheet.setStyle(2, 4, basicButttonStyle);
    ```
* 'enabled' 속성이 `true` 및 `false`로 설정된 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/enable-disable-cellbutton.gif)

    ```JavaScript
    // Workbook과 Worksheet 구성
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    // 버튼을 추가할 때 위치, 스타일, 사용 가능 여부(활성/비활성) 등 다양한 구성 설정을 지정 가능
    var customButtonStyle = new GC.Spread.Sheets.Style();
    customButtonStyle.cellButtons = 
    [
        {
            caption: "enable",
            useButtonStyle: true,
            // enabled: true,
            hoverBackColor: "#3390FF",          
            position: GC.Spread.Sheets.ButtonPosition.left
        },
        {
            caption: "disabled",
            useButtonStyle: false,
            enabled: false,
            position: GC.Spread.Sheets.ButtonPosition.right
        }
    ];
    activeSheet.setText(4, 3, "enabled/disabled buttons");
    activeSheet.setStyle(4, 4, customButtonStyle);
    ```
* 선택된 셀에 셀 버튼이 표시되도록 설정
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/cellbutton-visible.gif)

    ```JavaScript
    // Workbook과 Worksheet 구성 
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    // 버튼 visibility 속성 추가
    var onScreenstyle = new GC.Spread.Sheets.Style();
    onScreenstyle.cellButtons = [
         {
            caption: "On Select",
            buttonBackColor:"#ffdc9d",
            visibility: GC.Spread.Sheets.ButtonVisibility.onSelected
       }
    ];
    activeSheet.setStyle(10, 10, onScreenstyle);
    activeSheet.getCell(10,10).value("Select cell..").vAlign(GC.Spread.Sheets.VerticalAlign.bottom);
    ```
* 내장된 이미지와 사용자 지정 이미지가 있는 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/image-cellbutton.gif)

    ```JavaScript
    // Workbook과 Worksheet 구성 
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    //내장된 이미지와 사용자 지정 이미지가 있는 셀 버튼 추가 
    var ImageStyle = new GC.Spread.Sheets.Style();
    ImageStyle.cellButtons =
    [
        {
            useButtonStyle: true,
            imageSize: {
                    height: 8,
                    width: 8
            },
            imageType: GC.Spread.Sheets.ButtonImageType.ellipsis
        },
        {
            useButtonStyle: true,
            imageType: GC.Spread.Sheets.ButtonImageType.custom,
            imageSrc:"data:image/bmp;base64, Qk1eAAAAAAAAAD4AAAAoAAAACAAAAAgAAAABAAEAAAAAACAAAADEDgAAxA4AAAAAAAAAAAAAAAAAAP///wB+AAAApQAAANsAAAClAAAApQAAANsAAAClAAAAfgAAAA=="
        }
    ];
    activeSheet.setText(6, 3, "Image Buttons");
    activeSheet.setStyle(6, 4, ImageStyle);
    ```
* 워크시트에서 확대 및 축소 작업을 수행하도록 `command` 함수가 설정된 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/cmd-func-cellbutton.gif)

    ```JavaScript
    //Workbook과 Worksheet 구성 
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    // 명령 함수가 있는 버튼 추가
     명령 var buttonCommandfunction = new GC.Spread.Sheets.Style();
    buttonCommandfunction.cellButtons =
    [
        {
            imageType: GC.Spread.Sheets.ButtonImageType.search,
            command: (sheet, row, col, option) =>
            {
                if (sheet.zoom() === 1) {
                    sheet.zoom(1.5);
                } else {
                    sheet.zoom(1);
                }
            }
        }
    ];
    activeSheet.setText(10, 3, "Button with command function");
    activeSheet.setStyle(10, 4, buttonCommandfunction);
    ```
* 알림 메시지를 트리거하도록 `command` 함수가 설정된 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/cellbutton-alert.gif)

    ```JavaScript
    // Workbook과 Worksheet 구성
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    // 경고 명령 동작이 있는 버튼 추가
    var visibleStyle = new GC.Spread.Sheets.Style();
    visibleStyle.cellButtons = 
    [
        {
            caption:"Alert",
            buttonBackColor: "#00C2D6",
            command: (sheet, row, col, option) => {
                alert("This is an alert.");
            }
        }
    ];
    activeSheet.setStyle(7, 10, visibleStyle);
    ```
* `ButtonImageType` 열거형에서 `dropdown` 값으로 설정되고 `opencolorpicker` 명령을 수행하도록 설정된 셀 버튼
    ![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/8d606653-16a0-474d-b9dc-e2b4d01c2446/images/cmd-action-dropdown-cellbutton.gif)

    ```JavaScript
    //Workbook과 Worksheet 구
    var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
    var activeSheet = spread.getActiveSheet();
    
    //명령 동작이 있는 드롭다운 버튼 추가
    var dropdownStylecommand = new GC.Spread.Sheets.Style();
    dropdownStylecommand.cellButtons =
    [
        {
            imageType: GC.Spread.Sheets.ButtonImageType.dropdown,
            useButtonStyle: true,
            command: "openColorPicker"
        }
    ];
    activeSheet.setText(8, 3, "Dropdown button with command");
    activeSheet.setStyle(8, 4, dropdownStylecommand);        
    ```

## 셀 버튼 구성

다음 표에 설명된 다양한 속성을 사용하여 셀 버튼을 구성할 수 있습니다:

| **속성** | **설명** |
| --- | --- |
| **ButtonPosition** | ButtonPosition 열거형 타입의 속성으로, 셀 버튼의 위치를 지정합니다. 버튼의 위치를 왼쪽 또는 오른쪽으로 설정하고 사용자 지정 스타일을 생성할 수 있습니다. |
| **CaptionAlignment** | CaptionAlignment 열거형 타입의 속성으로, 셀 버튼 내 캡션의 위치를 지정합니다. 캡션의 위치를 왼쪽 또는 오른쪽으로 설정할 수 있습니다. |
| **ButtonImageType** | ButtonImageType 열거형 타입의 속성으로, 셀 버튼의 이미지 유형을 지정합니다. 드롭다운, 검색, 실행 취소, 다시 실행 등과 같은 선호도에 따라 버튼 이미지 유형을 설정할 수 있습니다. 전체 목록은 [ButtonImageType Enumeration](/spreadjs/api/v19/enums/GC.Spread.Sheets.ButtonImageType) 을 참조하시기 바랍니다. |
| **ButtonVisibility** | ButtonVisibility 열거형 타입의 속성으로, 셀 버튼의 표시 여부를 지정합니다. 다음 값들을 사용하여 다양한 셀 상태에서 버튼의 표시 여부를 설정할 수 있습니다. |
| **caption** | 캡션에 표시될 버튼의 텍스트를 지정합니다. |
| **position** | 셀 내에서 버튼의 위치를 지정합니다. |
| **enabled** | 셀 버튼이 사용자 동작에 반응할 수 있는지를 지정합니다. 기본값은 `true`입니다. |
| **useButtonStyle** | 셀 버튼을 버튼 스타일로 사용할지 여부를 지정합니다. 기본값은 `false`입니다. |
| **width** | 버튼의 너비를 지정합니다. `null` 또는 `undefined`로 설정하면 캡션과 이미지 크기에 따라 자동으로 조정됩니다. |
| **visibility** | 버튼의 표시 여부를 지정합니다. `"always"`, `"onselect"`, `"edit"` 세 가지 옵션을 사용할 수 있습니다. |
| **imageType** | 버튼에 표시할 이미지 유형을 지정합니다. 기본값은 `"custom"`입니다. |
| **command** | 셀 버튼 클릭 시 Spread 명령 또는 콜백을 실행할 수 있도록 합니다. |
| **imageSrc** | `imageType`이 `"custom"`일 경우, 이미지 소스를 제공하여 이미지를 업로드할 수 있습니다. |
| **captionAlign** | 이미지와 캡션의 정렬 위치를 지정합니다. `"left"` 또는 `"right"` 중 선택 가능합니다. |
| **imageSize** | 이미지 크기를 지정합니다. 기본값은 `16px`입니다. |
| **hoverBackColor** | 버튼이 표시되고 활성화되어 있을 때 마우스 오버 시 배경색을 지정합니다. |

## 버튼 명령 정의

셀 버튼을 생성한 후, 아래 표에 나열된 옵션에 따라 다양한 기능을 버튼에 연결할 수 있습니다:

| **명령 옵션** | **설명** |
| ----- | --- |
| **openColorPicker** | 버튼 클릭 시 색상 선택기를 열 때 사용합니다. |
| **openDateTimePicker** | 버튼 클릭 시 날짜 시간 선택기를 열 때 사용합니다. |
| **openTimePicker** | 버튼 클릭 시 시간 선택기를 열 때 사용합니다. |
| **openMonthPicker** | 버튼 클릭 시 월 선택기를 열 때 사용합니다. |
| **openSlider** | 버튼 클릭 시 슬라이더 컨트롤을 열 때 사용합니다. |
| **openWorkflowList** | 버튼 클릭 시 워크플로 목록을 열 때 사용합니다. |
| **openCalculator** | 버튼 클릭 시 계산기를 열 때 사용합니다. |
| **openList** | 버튼 클릭 시 리스트를 열 때 사용합니다. |

> **참고 :** 위 명령들은 드롭다운 셀 버튼 설정에서도 사용 및 사용자 정의할 수 있습니다. 자세한 내용은 [셀 드롭다운](/spreadjs/docs/v19/features/cells/cell-dropdowns)을 참조하시기 바랍니다.