이벤트

SpreadJS는 개발자가 사용자 상호 작용, 데이터 수정, 구조 변경 및 고급 통합 문서 작업에 대응할 수 있도록 포괄적인 이벤트 시스템을 제공합니다.

모든 이벤트는 GC.Spread.Sheets.Events 클래스에 정의되어 있으며, 작업 범위에 따라 Workbook 또는 Worksheet에 바인딩할 수 있습니다.

이 페이지에서는 SpreadJS 전반에서 사용되는 이벤트 모델, 바인딩 메커니즘, 수명 주기 패턴 및 사용 원칙을 소개합니다.

이벤트 범위

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

통합 문서 수준 이벤트

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

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

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

워크시트 수준 이벤트

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

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

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

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

이벤트 바인딩 및 해제

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

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 – 컨텍스트 정보를 포함하는 이벤트별 인수 개체

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

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 — 확정된 결과 처리

취소 가능한 이벤트

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

args.cancel = true;

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

예를 들어:

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

취소는 반드시 Changing 또는 Ending과 같은 적절한 사전 작업 단계에서 수행해야 합니다.

Changed 또는 Ended와 같은 사후 작업 이벤트는 취소할 수 없습니다.

취소 가능한 이벤트는 일반적으로 다음과 같은 용도로 사용됩니다.

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

이벤트 범주

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

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

이 구조를 통해 개발자는 사용자 작업과 시스템 동작을 세밀하게 제어하면서 SpreadJS를 복잡한 애플리케이션 로직에 통합할 수 있습니다.

자세한 이벤트 정의 및 매개변수 사양은 다음 API 참조 문서에서 확인할 수 있습니다.

GC.Spread.Sheets.Events

사용 지침

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

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

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

이벤트