체크박스 셀

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

기본 사용법

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

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

// 체크박스 셀 생성 예제
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);

불확정(Indeterminate) 상태

SpreadJS CheckBox는 삼중 상태 기능을 지원하여 선택, 미선택, 불확정 상태를 나타낼 수 있습니다. isThreeState() 메서드를 사용해 부분적이거나 정의되지 않은 상태가 필요한 체크박스를 설정할 수 있습니다.

체크박스 상태는 value 메서드를 사용하여 코드에서 설정할 수 있습니다:

코드 예제

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

// 액티브 시트 가져오기
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);

텍스트 줄바꿈(Wrap Text)

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

// 긴 캡션 설정
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이 활성화되고 셀의 수직 정렬이 설정된 경우, 체크박스는 아래와 같이 표시됩니다:

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

토글 모드

CheckBox.mode('toggle') 메서드를 사용하여 일반 체크박스를 인터랙티브 토글 스위치로 변환할 수 있습니다.

주요 기능

• 커스터마이징 가능한 외관

  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는 텍스트 오버플로우를 무시하고 토글 버튼 크기만 고려합니다.

코드 예제

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

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);