동시 편집 정책

이 매뉴얼에서는 SpreadJS 동시 작업의 동작 및 사용 정책에 대해 설명합니다. 이러한 메커니즘은 공유 워크북 환경에서 여러 클라이언트 간의 실시간 동기화가 작동하는 방식을 제어합니다.

목적

개발자가 변경 사항이 클라이언트 간에 언제, 어떻게 동기화되는지 이해할 수 있도록 합니다.
스타일, 인쇄 설정 또는 기타 중첩 개체를 수정하는 올바른 방법을 정의합니다.
반복 계산 중 수식 계산, 동기화 및 동작을 제어하는 규칙을 설명합니다.

기능 설명

1. 중첩 개체 수정 동기화

핵심 개념

중첩 개체를 로컬에서 직접 수정한 내용은 클라이언트 간에 동기화되지 않습니다.
업데이트를 동기화하려면 setter 메서드를 통해 전체 개체를 다시 설정하거나 재할당해야 합니다.

예시

시나리오	로컬 효과	동기화 동작	권장 작업
`getStyle(row, column)`에서 반환된 개체의 속성 수정	로컬 스타일 업데이트가 해당 클라이언트에서만 표시됨	변경 사항이 다른 클라이언트에 전달되지 않음	`setStyle(row, column, style)`을 사용하여 전체 개체 교체
`printInfo`의 중첩 속성 수정(예: `printInfo.pageHeaderFooter.left()`)	로컬 보기에만 영향을 줌	동기화되지 않음	전체 setter를 사용하여 인쇄 설정 재할당(예: `sheet.printInfo = new PrintInfo()`)

동기화 전략

올바른 동기화를 트리거하려면 다음을 수행합니다.

수정할 개체를 가져옵니다.
로컬에서 개체를 업데이트합니다.
setter를 호출하여 업데이트된 전체 개체를 워크시트 또는 워크북에 다시 적용합니다.

예:

// 잘못된 방법 – 동기화되지 않음
let s = sheet.getStyle(1, 1);
s.backColor = "yellow"; // 로컬에만 적용
// 올바른 방법 – 동기화됨
let style = sheet.getStyle(1, 1);
style.backColor = "yellow";
sheet.setStyle(1, 1, style); // 동시 작업 동기화 트리거

2. 수식 동시 작업 동작

동시 작업에서는 수식이 다르게 동작합니다. 각 클라이언트는 공유된 수식 정의를 기반으로 독립적으로 계산을 수행하고 자체 로컬 상태를 유지합니다.

스냅샷 저장

스냅샷에는 수식 식만 저장됩니다.
수식 결과는 클라이언트 간에 저장되거나 동기화되지 않습니다.

수식 다시 계산

워크북이 로드되면 각 클라이언트에서 독립적으로 수식을 다시 계산합니다.
실행 순서 또는 반복 계산의 차이로 인해 다시 계산된 결과가 일시적으로 다를 수 있습니다.

동기화 범위

동시 작업 서비스는 수식 편집 작업(삽입, 삭제, 편집)을 동기화합니다.
계산 결과(숫자 출력)는 전송되거나 동기화되지 않습니다.

CalculationMode 정책

각 클라이언트는 자체 CalculationMode(Manual 또는 Automatic)를 유지합니다.
한 클라이언트의 계산 모드를 변경해도 다른 클라이언트나 서버에는 영향을 주지 않습니다.

다음 원칙을 따르세요.

평소와 같이 수식을 작성합니다(예: =A1 + B1).
저장된 결과에 의존하지 마세요. 각 클라이언트에서 독립적으로 다시 계산됩니다.
반복 함수 또는 휘발성 함수(RAND, NOW 등)를 사용할 때는 결과가 클라이언트마다 다를 수 있으므로 주의하세요.

반복 계산 동작

범주	설명	수식 예	동기화 동작
자체 수렴	안정적인 결과에 도달할 때까지 반복(모든 클라이언트에서 동일)	상호 의존적인 부서 비용 할당	클라이언트 간 및 새로 고침 후에도 일관됨
비수렴	무한히 또는 불안정하게 반복	`=A1 + 1`	클라이언트마다 다르며 새로 고침 후 재설정됨
자동 데이터 입력(일회성)	일회성 반복 수행(예: 타임스탬프)	`=IF(A1="","", IF(B1="", NOW(), B1))`	클라이언트마다 독립적인 타임스탬프가 생성되며 새로 고침 후 재설정됨

3. 워크북 동시 작업 상태

사용자가 workbook.collaboration.onChangeSet을 통해 변경 집합 리스너를 등록하면 SpreadJS는 동시 작업 상태로 간주됩니다.

SpreadJS가 동시 작업 모드인 경우 동시 작업의 데이터 동기화 메커니즘으로 인해 일부 API가 유효하지 않으며 아무런 효과가 없습니다.

동시 작업 모드에서 적용되지 않는 API

API 위치	API 이름	동작
Workbook	`fromJSON`	아무 작업도 수행하지 않습니다. JSON 콘텐츠를 워크북으로 가져오지 않습니다.
Workbook	`import`	파일 콘텐츠를 가져오지 않습니다. 작업이 오류 콜백으로 전달됩니다.
Workbook	`open`	파일 콘텐츠를 열지 않습니다. 작업이 오류 콜백으로 전달됩니다.
Worksheet	`reset`	아무 작업도 수행하지 않습니다. 워크시트가 재설정되지 않습니다.

디자이너 동작

디자이너에서는 동시 작업 모드에서 파일 메뉴의 파일 로드 명령이 지원되지 않습니다.

사용자가 파일 형식에 관계없이 열기 또는 가져오기 명령을 통해 파일을 선택하면 파일이 열리거나 가져와지지 않습니다. 대신 디자이너에 동시 작업 모드에서는 새 파일 가져오기가 지원되지 않는다는 오류 대화 상자가 표시됩니다.

image-20260803.1e62e3.png

저장, 내보내기, 인쇄 및 정보와 같은 명령은 계속 정상적으로 작동합니다.