# 이벤트

## Content

SpreadJS는 개발자가 사용자 상호 작용, 데이터 수정, 구조 변경 및 고급 통합 문서 작업에 대응할 수 있도록 포괄적인 이벤트 시스템을 제공합니다.
모든 이벤트는 [GC.Spread.Sheets.Events](/spreadjs/api/classes/GC.Spread.Sheets.Events) 클래스에 정의되어 있으며, 작업 범위에 따라 `Workbook` 또는 `Worksheet`에 바인딩할 수 있습니다.
이 페이지에서는 SpreadJS 전반에서 사용되는 이벤트 모델, 바인딩 메커니즘, 수명 주기 패턴 및 사용 원칙을 소개합니다.

## 이벤트 범위

SpreadJS의 이벤트는 이벤트를 발생시키는 개체에 따라 범위가 결정됩니다.

### 통합 문서 수준 이벤트

통합 문서 이벤트는 다음과 같이 통합 문서 전체에 영향을 주는 작업에 의해 발생합니다.

* 활성 시트 변경
* 클립보드 작업
* 테이블 구조 업데이트
* 협업 워크플로
* 계산 진행 상태
* 권한 변경

이러한 이벤트는 `Workbook` 인스턴스에 바인딩해야 합니다.

### 워크시트 수준 이벤트

워크시트 이벤트는 특정 시트 내의 상호 작용에 의해 발생하며 다음을 포함합니다.

* 셀 상호 작용 및 선택
* 편집 수명 주기
* 값 및 범위 변경
* 행 및 열 작업
* 필터링 및 정렬
* 도형, 그림, 움직이는 개체 및 양식 컨트롤 업데이트
* PivotTable 및 고급 기능 작업

이러한 이벤트는 `Worksheet` 인스턴스에 바인딩해야 합니다.
올바른 범위에 이벤트를 바인딩하면 예측 가능한 동작을 보장하고 불필요한 핸들러 실행을 방지할 수 있습니다.

## 이벤트 바인딩 및 해제

이벤트 핸들러를 등록하려면 `bind` 메서드를 사용하고, 제거하려면 `unbind`(또는 `unbindAll`)를 사용합니다.

```javascript
const spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
const sheet = spread.getActiveSheet();
sheet.bind(GC.Spread.Sheets.Events.CellClick, function (sender, args) {
    console.log("Row:", args.row, "Column:", args.col);
});
```

각 핸들러는 다음 인수를 받습니다.

* sender – 이벤트를 발생시킨 개체(Workbook 또는 Worksheet)
* args – 컨텍스트 정보를 포함하는 이벤트별 인수 개체

핸들러를 제거하려면 다음과 같이 사용합니다.

```javascript
sheet.unbind(GC.Spread.Sheets.Events.CellClick, handler);
sheet.unbindAll(GC.Spread.Sheets.Events.CellClick);
```

## 이벤트 인수 모델

인수 속성은 이벤트 유형에 따라 다르지만, 많은 이벤트가 다음과 같은 공통 패턴을 따릅니다.

* 위치 컨텍스트 — `row`, `col`, `sheet`, `sheetName`
* 범위 컨텍스트 — `cellRange`, `changedCells`
* 상태 표시기 — `action`, `isUndo`
* 제어 플래그 — `cancel`

이벤트별 인수에 대한 자세한 내용은 API 참조 문서를 확인하십시오.

## 이벤트 수명 주기 패턴

많은 SpreadJS 이벤트는 일관된 수명 주기 명명 패턴을 따릅니다. 이러한 패턴을 이해하면 작업을 가로채거나 응답해야 하는 시점을 판단하는 데 도움이 됩니다.

### 1\. Changing → Changed

구조 또는 상태 변경에 사용됩니다.

* Changing — 작업이 적용되기 전에 발생합니다. 일반적으로 취소할 수 있습니다.
* Changed — 작업이 완료된 후 발생합니다.

예제 패턴:

* `SheetChanging` → `SheetChanged`
* `ColumnWidthChanging` → `ColumnWidthChanged`

일반적인 시나리오는 다음과 같습니다.

* 시트 삽입, 삭제, 이름 변경 또는 이동
* 행 또는 열 속성 업데이트
* 필터링 및 정렬 작업
* 테이블 및 범위 수정

Changing 이벤트는 검증 및 차단에 사용합니다.
Changed 이벤트는 작업 후 처리 또는 동기화에 사용합니다.

### 2\. Starting → Ending → Ended

상호 작용 및 편집 워크플로에 사용됩니다.

* Starting — 프로세스 시작 전
* Ending — 완료 직전(일반적으로 취소 가능)
* Ended — 완료 후

예제 패턴:

* `EditStarting`
* `EditEnding`
* `EditEnded`

용도:

* Starting — 상태 초기화
* Ending — 검증 또는 취소
* Ended — 확정된 결과 처리

## 취소 가능한 이벤트

일부 이벤트는 다음과 같이 설정하여 기본 동작을 방지할 수 있습니다.

```javascript
args.cancel = true;
```

취소 가능한 이벤트는 일반적으로 Changing 또는 Ending 단계에서 발생합니다.
예를 들어:

* 편집 모드 종료 방지
* 시트 전환 방지
* 붙여넣기 작업 방지
* 열 크기 조정 방지

취소는 반드시 `Changing` 또는 `Ending`과 같은 적절한 사전 작업 단계에서 수행해야 합니다.
`Changed` 또는 `Ended`와 같은 사후 작업 이벤트는 취소할 수 없습니다.
취소 가능한 이벤트는 일반적으로 다음과 같은 용도로 사용됩니다.

* 시트 전환 방지
* 잘못된 편집 차단
* 크기 조정 작업 제한
* 붙여넣기 작업 가로채기
* 비즈니스 규칙 적용

## 이벤트 범주

SpreadJS 이벤트 시스템은 다음을 포함한 여러 기능 영역에 걸쳐 있습니다.

* 셀 상호 작용 및 선택
* 편집 수명 주기
* 데이터 및 구조 변경
* 필터링, 정렬, 그룹화 및 테이블
* 시트 및 통합 문서 수명 주기
* 클립보드 통합
* 도형, 그림, 움직이는 개체 및 양식 컨트롤
* PivotTable, 리포트 시트 및 테이블 시트 작업
* 계산 및 협업 워크플로
* 권한 및 보기 관련 작업

이 구조를 통해 개발자는 사용자 작업과 시스템 동작을 세밀하게 제어하면서 SpreadJS를 복잡한 애플리케이션 로직에 통합할 수 있습니다.
자세한 이벤트 정의 및 매개변수 사양은 다음 API 참조 문서에서 확인할 수 있습니다.
[GC.Spread.Sheets.Events](/spreadjs/api/classes/GC.Spread.Sheets.Events)

## 사용 지침

이벤트 로직을 구현할 때는 다음 사항을 권장합니다.

* 올바른 범위(Workbook 또는 Worksheet)에 이벤트를 바인딩합니다.
* 사전 작업 이벤트는 검증 및 취소에 사용합니다.
* 사후 작업 이벤트는 로깅 및 동기화에 사용합니다.
* 자주 발생하는 이벤트(예: 선택 변경, 스크롤링)에서는 무거운 처리를 피합니다.
* 의도하지 않은 동작을 방지하기 위해 시트를 제거하거나 다시 생성할 때 핸들러를 제거합니다.

다음 섹션에서는 이벤트를 기능 범주별로 구성하고 일반적인 개발 시나리오에 대한 지침과 예제를 제공합니다.