# 체크박스 셀 

## Content

**SpreadJS CheckBox**는 스프레드시트 내에 삽입되는 인터랙티브 셀 컨트롤로, 사용자가 이진 상태(선택/미선택) 또는 삼중 상태(불확정 상태 포함)를 전환할 수 있도록 합니다. 데이터 검증 워크플로우를 간소화하고 사용자 상호작용을 강화하도록 설계되었으며, 기존 드롭다운이나 라디오 버튼을 직관적인 시각적 표시기로 대체합니다.

## 기본 사용법

[GC.Spread.Sheets.CellTypes.CheckBox](/spreadjs/api/v19/classes/GC.Spread.Sheets.CellTypes.CheckBoxList) 클래스를 사용하여 CheckBox 셀을 생성하고 완전히 커스터마이징할 수 있습니다. 이를 통해 외관 정의, 상태 전환(선택/미선택/불확정), 레이아웃(`textAlign`) 설정, `textTrue`, `textFalse`, `isThreeState`, `boxSize`와 같은 주요 속성을 통한 상호작용 동작 조정이 가능합니다.

아래 예제는 CheckBox 셀 타입을 생성하고 커스텀 속성으로 구성하는 방법을 보여줍니다.

```javascript
// 체크박스 셀 생성 예제
var activeSheet = spread.getSheet(0);
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.caption("caption");
cellType.textTrue("true");
cellType.textFalse("false");
cellType.textIndeterminate("indeterminate");
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.bottom);
cellType.boxSize(20);
activeSheet.getCell(1, 1).cellType(cellType);
```

![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/216c2e7e-5246-4c37-8843-3854aa344a6a/gif1.dcdd78.8076b6.gif?width=150)

## **불확정(Indeterminate) 상태**

SpreadJS CheckBox는 삼중 상태 기능을 지원하여 선택, 미선택, **불확정** 상태를 나타낼 수 있습니다. [isThreeState()](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox#isthreestate) 메서드를 사용해 부분적이거나 정의되지 않은 상태가 필요한 체크박스를 설정할 수 있습니다.

![image](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/216c2e7e-5246-4c37-8843-3854aa344a6a/image.436822.png?width=400)

체크박스 상태는 [value](/spreadjs/api/v19/classes/GC.Spread.Sheets.CellRange#value) 메서드를 사용하여 코드에서 설정할 수 있습니다:

| **값(Value)** | **상태(State)** |
| -------- | --------- |
| `null` | 불확정(Indeterminate) |
| `0` | 미선택(Unchecked) |
| `1` | 선택(Checked) |

### 코드 예제

삼중 상태 체크박스를 생성하는 예제입니다.

```javascript
// 액티브 시트 가져오기
var activeSheet = spread.getSheet(0);
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.caption("caption");
cellType.textTrue("True");
cellType.textFalse("False");
cellType.textIndeterminate("Indeterminate");
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.bottom);
cellType.isThreeState(true);
cellType.boxSize(20);
activeSheet.getCell(1, 1).cellType(cellType);
//activeSheet.getCell(1, 1).value(1);
```

![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/216c2e7e-5246-4c37-8843-3854aa344a6a/gif2.50419c.cb1391.gif?width=150)

## 텍스트 줄바꿈(Wrap Text)

체크박스 캡션이 셀에 맞지 않게 긴 경우, 표시 텍스트를 줄바꿈하려면 셀 스타일의 **wordWrap** 속성을 `true`로 설정해야 합니다. 기본값은 `false`입니다.

```javascript
// 긴 캡션 설정
cellType.caption("This is a very very long long text"); 
activeSheet.getCell(1, 1).cellType(cellType); 
activeSheet.setRowHeight(1, 120); 
activeSheet.setColumnWidth(1, 110); 
// wordWrap 속성 활성화
activeSheet.getCell(1, 1).wordWrap(true);
```

| **wordWrap 속성** | **결과** |
| ----------- | --- |
| **wordWrap** = false | ![wordWrap_false](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_false.a6ede2.PNG?width=200) |
| **wordWrap** = true | ![wordWrap_true](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_true.1db0f2.PNG?width=200) |

**줄바꿈 규칙**
체크박스 셀의 줄바꿈 규칙은 먼저 단어 단위로 줄을 나누고, 필요 시 내부 단어를 추가로 나누어 공간에 맞춥니다.

![wordWrap_innerWordBreak](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_innerWordBreak.d51d01.PNG?width=200)

**수직 정렬**
체크박스 셀에서 **wordWrap**이 활성화되고 셀의 수직 정렬이 설정된 경우, 체크박스는 아래와 같이 표시됩니다:

| **수직 정렬** | **결과** |
| ----- | --- |
| 셀 vAlign가 top이면 체크박스가 텍스트와 함께 위쪽에 정렬됩니다. | ![wordWrap_true](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_true.08d8f5.PNG?width=200) |
| 셀 vAlign가 middle이면 체크박스가 텍스트 중앙에 정렬됩니다. | ![wordWrap_middleAlign](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_middleAlign.f596f7.PNG?width=200) |
| 셀 vAlign가 bottom이면 체크박스가 텍스트 하단에 정렬됩니다. | ![wordWrap_bottomAlign](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_bottomAlign.f325dc.PNG?width=200) |

셀의 hAlign 값에 따라 줄바꿈 텍스트의 수평 정렬을 변경할 수도 있습니다. 예를 들어, 셀 hAlign가 `right`이면 캡션 텍스트만 셀 오른쪽으로 정렬됩니다. hAlign가 `left` 또는 `center`이면 캡션 텍스트만 왼쪽 또는 중앙으로 정렬됩니다.

## 토글 모드

[CheckBox.mode('toggle')](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox#mode) 메서드를 사용하여 일반 체크박스를 인터랙티브 토글 스위치로 변환할 수 있습니다.

**주요 기능**

* **커스터마이징 가능한 외관**
    IToggleOptions 인터페이스를 통해 시각적 속성을 구성합니다.
    * **크기**: 고정 `width/height` 설정 또는 `autoSize`로 텍스트 동적 크기 조정 가능
    * **색상**: 활성(`sliderColorOn`, `trackColorOn`) 및 비활성(`sliderColorOff`, `trackColorOff`) 상태 정의
    * **애니메이션**: `animationDuration`(밀리초)로 전환 부드러움 조절
    * **레이아웃**: `sliderMargin`(슬라이더와 트랙 간 간격), `trackRadius`(모서리 둥글기) 조정
* **텍스트 정렬**
    `CheckBoxTextAlign.inside` 옵션은 텍스트를 토글 버튼 내부에 삽입할 수 있어 공간 효율적인 레이아웃을 제공합니다. 기존 정렬 옵션(top, bottom, left, right)과 함께 사용 가능합니다.

**사용 제한 사항**

* **사용 불가 속성**: 토글 모드에서는 `boxSize`, `isThreeState`, `textIndeterminate` 속성을 사용할 수 없습니다.
* **상호작용 제한**: 더블 클릭 편집은 비활성화되며, 상태 변경은 **토글 버튼 클릭**으로만 이루어집니다. 셀 영역 클릭으로는 변경되지 않습니다.
* **텍스트 정렬**: `autoSize: false` 및 `textAlign: inside`일 경우, `autoFitWidth`/`autoFitHeight`는 텍스트 오버플로우를 무시하고 토글 버튼 크기만 고려합니다.

**코드 예제**
아래 예제는 체크박스 셀에서 토글 모드를 구현한 예제입니다.

```javascript
const spread = new GC.Spread.Sheets.Workbook();
const sheet = spread.getActiveSheet();
const cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.textTrue('ON');
cellType.textFalse('OFF');
cellType.mode('toggle');
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.inside);
cellType.toggleOptions({
  width: 65,
  height: 30,
  sliderMargin: 2,
  trackColorOn: '#8cbae8',
  trackColorOff: '#9e9e9e',
  sliderColorOn: '#1565c0',
  sliderColorOff: '#ffffff',
});
sheet.setCellType(0, 0, cellType);
```

![](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/216c2e7e-5246-4c37-8843-3854aa344a6a/gif5.fb3e46.1f0476.gif?width=150)