# 시나리오 매니저

## Content

시나리오 분석은 명명된 입력 값 집합을 저장하고 이를 통합 문서에 적용하여 비즈니스 결과를 비교하는 What-If 분석 기능입니다.
시나리오에는 하나 이상의 변경 셀에 대한 값이 포함됩니다. 시나리오가 적용되면 SpreadJS는 저장된 값을 대상 셀에 쓰고 종속 수식을 다시 계산합니다. 이를 통해 각 입력 셀을 직접 편집하지 않고도 낙관적, 비관적, 손익분기점 예측과 같은 가정 간에 쉽게 전환할 수 있습니다.

>type=note
> **참고:**
>
> * 시나리오는 통합 문서 수준에서 관리됩니다. 하나의 시나리오에 하나 이상의 워크시트에 있는 변경 셀을 포함할 수 있습니다.
> * 테이블 시트, 간트 시트 및 리포트 시트는 지원되지 않습니다.

![demo-20260720.ecc081.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/demo-20260720.ecc081-20260820.ad61be.gif?width=800)

## 시나리오 개념

시나리오 분석에서는 다음과 같은 개념을 사용합니다.

| 개념 | 설명 |
| --- | --- |
| 시나리오 | 통합 문서에 적용할 수 있는 명명된 저장 값 집합입니다. |
| 변경 셀 | 시나리오에 값이 저장되고 시나리오가 적용될 때 덮어쓰는 셀입니다. |
| 재정의 | 시나리오의 변경 셀과 저장된 값을 정의하는 워크시트 수준의 항목입니다. |
| 기본값 | 시나리오가 적용된 후 셀을 복원하는 데 사용되는 캡처된 원래 값입니다. |
| 적용된 시나리오 | 현재 적용되어 있으며 아직 복원되지 않은 시나리오입니다. |

**기본값**은 시나리오 값이 대상 셀을 덮어쓰기 전에 자동으로 캡처됩니다. 기본값은 영향을 받는 셀을 복원하는 데만 사용되며 사용자가 작성하는 시나리오 정의에는 포함되지 않습니다.

## 프로그래밍 방식으로 시나리오 관리

코드를 통해 시나리오를 관리하려면 `spread.scenarioManager`를 사용합니다.
일반적인 시나리오 관리 워크플로에는 다음이 포함됩니다.

* `all`을 사용하여 시나리오 나열
* `apply`를 사용하여 시나리오 적용
* `restore`를 사용하여 시나리오 복원
* `setActiveScenario`를 사용하여 시나리오 캡처 활성화
* `remove`를 사용하여 시나리오 제거

### 시나리오 만들기 및 업데이트

통합 문서의 `scenarioManager`를 사용하여 시나리오를 관리합니다.
시나리오를 만들거나 업데이트하는 권장 방법은 시나리오 캡처를 활성화하고 셀 값을 편집한 다음 시나리오 캡처를 비활성화하는 것입니다.

```javascript
var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
var sheet = spread.getActiveSheet();
var manager = spread.scenarioManager;

sheet.name("Forecast");
sheet.setValue(1, 1, 1000);           // B2
sheet.setValue(2, 1, 0.15);           // B3
sheet.setFormula(4, 1, "=B2*(1+B3)"); // B5

// Start recording edits into a scenario.
manager.setActiveScenario("Optimistic");

// These value changes are saved in the active scenario.
sheet.setValue(1, 1, 1200);
sheet.setValue(2, 1, 0.18);

// Stop recording edits.
manager.setActiveScenario(null);
```

시나리오를 만든 후 시나리오 매니저에서 가져올 수 있습니다.

```javascript
var scenario = manager.get("Optimistic");
console.log(scenario);
```

통합 문서의 모든 시나리오를 가져오려면 `all`을 사용합니다.

```javascript
var scenarios = manager.all();
```

### 시나리오 적용 및 복원

시나리오를 적용하면 저장된 값이 대상 변경 셀에 쓰입니다.

```javascript
manager.apply("Optimistic");
```

시나리오가 적용되면 적용된 값을 기반으로 종속 수식이 다시 계산됩니다.
특정 시나리오의 영향을 받은 셀을 기본값으로 복원하려면 시나리오 이름과 함께 `restore`를 사용합니다.

```javascript
manager.restore("Optimistic");
```

적용된 모든 시나리오를 복원하려면 시나리오 이름 없이 `restore`를 호출합니다.

```javascript
manager.restore();
```

현재 적용된 시나리오를 확인하려면 `getAppliedScenarios`를 사용할 수 있습니다.

```javascript
var applied = manager.getAppliedScenarios();
```

### 활성 시나리오 모드

활성 시나리오 모드는 이후의 셀 값 편집 내용을 대상 시나리오에 기록합니다.
사용자가 워크시트 셀을 직접 편집하여 시나리오를 만들거나 업데이트하도록 하려는 경우 활성 시나리오 모드를 사용합니다.

```javascript
manager.setActiveScenario("Pessimistic");

// Cell value edits are captured into the active scenario.
sheet.setValue(1, 1, 800);
sheet.setValue(2, 1, 0.08);

// End scenario capture.
manager.setActiveScenario(null);
```

활성 시나리오 모드는 셀 값 변경 내용을 캡처합니다. 수식 재계산 결과는 시나리오 값으로 기록되지 않습니다.
통합 문서에서는 한 번에 하나의 시나리오만 활성화할 수 있습니다. 시나리오를 비활성화하면 이후의 캡처가 중지되지만 워크시트 값은 복원되지 않습니다.

### 기존 시나리오 이름 바꾸기

기존 시나리오의 이름을 바꾸려면 먼저 새 시나리오를 만든 다음 기존 시나리오를 대체합니다.

```auto
// Assume "Plan A" exist.
scenarioManager.setActiveScenario("Plan B");
scenarioManager.setActiveScenario(null);
let scenario = scenarioManager.get("Plan A");
scenario.name = "Plan B";
scenarioManager.set(scenario);
scenarioManager.remove("Plan A");
```

### 시나리오 제거

하나의 시나리오를 제거하려면 시나리오 이름을 `remove`에 전달합니다.

```javascript
manager.remove("Optimistic");
```

통합 문서에서 모든 시나리오를 제거하려면 시나리오 이름 없이 `remove`를 호출합니다.

```javascript
manager.remove();
```

시나리오를 제거하면 시나리오 정의가 제거됩니다. 시나리오를 적용하여 이미 변경된 워크시트 값은 자동으로 복원되지 않습니다.

## 다중 워크시트 시나리오

시나리오에는 여러 워크시트의 변경 셀이 포함될 수 있습니다. 이를 통해 하나의 명명된 시나리오로 통합 문서 전체의 가정 집합을 나타낼 수 있습니다.

```javascript
var manager = spread.scenarioManager;

var incomeSheet = spread.getActiveSheet();
incomeSheet.name("Income");

var costSheet = new GC.Spread.Sheets.Worksheet("Cost");
spread.addSheet(1, costSheet);

incomeSheet.setValue(1, 1, 1000);
costSheet.setValue(1, 1, 600);

manager.setActiveScenario("Expansion");

incomeSheet.setValue(1, 1, 1300);
costSheet.setValue(1, 1, 780);

manager.setActiveScenario(null);
```

나중에 이 시나리오를 적용하면 SpreadJS는 저장된 값을 해당 워크시트에 적용합니다.
시나리오에서 참조하는 워크시트의 이름이 변경되면 시나리오 참조가 자동으로 업데이트됩니다. 참조된 워크시트가 제거되면 해당 워크시트 항목이 시나리오 정의에서 제거됩니다.

## 시나리오 패널

시나리오 패널은 통합 문서 시나리오를 보고 관리하기 위한 런타임 UI를 제공합니다.

```javascript
let workbook = new GC.Spread.Sheets.Workbook("spread-host");
let scenarioPanel = new GC.Spread.Sheets.Scenarios.ScenarioPanel("scenario-panel-host");

scenarioPanel.attach(workbook);
```

패널은 `spread.scenarioManager`에서 관리하는 것과 동일한 통합 문서 수준의 시나리오를 사용합니다. 패널에서 수행한 작업은 해당 `ScenarioManager` 작업과 동일한 방식으로 통합 문서를 업데이트합니다.
![image-20260803.3ee56a.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260803.3ee56a-20260820.a9259f.png?width=600)

### 시나리오 관리

도구 모음은 시나리오 만들기, 복원, 제거, 활성화 및 비활성화를 위한 통합 문서 수준의 명령을 제공합니다.
각 시나리오 카드에는 해당 시나리오에 포함된 워크시트와 변경 셀이 표시됩니다. 시나리오 헤더의 명령을 사용하여 다음 작업을 수행할 수 있습니다.

* 시나리오를 적용하고 저장된 값을 통합 문서에 씁니다.
* 시나리오의 영향을 받은 셀을 캡처된 기본값으로 복원합니다.
* 통합 문서에서 시나리오를 제거합니다.
* 시나리오 세부 정보를 확장하거나 축소합니다.

시나리오 이름 아래의 배지는 시나리오에 포함된 워크시트 및 변경 셀의 수를 표시합니다. **활성** 배지는 현재 셀 값 편집 내용을 캡처하고 있는 시나리오를 나타냅니다.
![runtime-scenario-panel-icon-annotations-v6-20260803.094bf0.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/runtime-scenario-panel-icon-annotations-v6-20260803.094bf0-20260820.80c60b.png?width=600)
시나리오 패널에는 다음과 같은 컨트롤이 포함되어 있습니다.

| 영역 | 설명 |
| --- | --- |
| 통합 문서 수준 명령 | 시나리오를 만들거나, 적용된 시나리오를 복원하거나, 시나리오를 제거하거나, 활성 시나리오 캡처를 제어합니다. |
| 활성 시나리오 컨트롤 | 이후의 셀 값 편집 내용을 캡처할 시나리오를 선택하거나 현재 시나리오를 비활성화하여 편집 내용 캡처를 중지합니다. |
| 시나리오 작업 | 개별 시나리오를 적용, 복원 또는 제거합니다. |
| 시나리오 상태 | 포함된 워크시트 및 변경 셀의 수를 확인하고 시나리오가 활성 상태인지 확인합니다. |
| 워크시트 항목 | 워크시트 항목을 확장하여 해당 워크시트에 속한 변경 셀을 확인합니다. |
| 보호 컨트롤 | 워크시트 수준 시나리오 항목의 잠금 및 숨김 상태를 구성합니다. |
| 변경 셀 | 대상 셀과 저장된 시나리오 값을 확인합니다. 해당되는 경우 패널에는 비교를 위해 현재 셀 값도 표시됩니다. |
| 변경 셀 제거 | 시나리오 정의에서 개별 변경 셀을 제거합니다. |

![panel-20260803.9f4c84.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/panel-20260803.9f4c84-20260820.6fa653.gif?width=800)

### 활성 시나리오 캡처

시나리오가 활성 상태이면 통합 문서에서 수행한 값 편집 내용이 해당 시나리오에 기록됩니다. 수식 재계산 결과는 시나리오 값으로 기록되지 않습니다.
통합 문서에서는 한 번에 하나의 시나리오만 활성화할 수 있습니다. 활성 시나리오를 비활성화하면 이후의 캡처가 중지되지만 워크시트 값은 복원되지 않습니다.

### 워크시트 및 변경 셀 세부 정보

시나리오를 확장한 다음 워크시트 항목을 확장하여 변경 셀을 확인합니다.
각 변경 셀 항목은 대상 셀과 시나리오에 저장된 값을 나타냅니다. 현재 워크시트 값이 저장된 시나리오 값과 다른 경우 패널에는 비교를 위해 두 값이 표시됩니다.
변경 셀은 시나리오에서 개별적으로 제거할 수 있습니다.
잠금 및 표시 여부 컨트롤은 워크시트 수준 시나리오 항목의 보호 관련 동작을 구성합니다. 이러한 설정은 워크시트 보호가 활성화된 경우 적용됩니다. 자세한 내용은 보호 동작을 참조하세요.

## 이벤트

SpreadJS는 시나리오 작업을 모니터링하거나 작업이 완료되기 전에 취소할 수 있는 시나리오 이벤트를 제공합니다.
시나리오 작업이 발생하기 전에 처리하려면 `ScenarioChanging`을 사용합니다.

```javascript
spread.bind(GC.Spread.Sheets.Events.ScenarioChanging, function (e, info) {
    if (info.action === "remove" && info.scenario.name === "Base Plan") {
        info.cancel = true;
    }
});
```

시나리오 작업이 완료된 후 응답하려면 `ScenarioChanged`를 사용합니다.

```javascript
spread.bind(GC.Spread.Sheets.Events.ScenarioChanged, function (e, info) {
    console.log(info.action, info.scenario.name);
});
```

시나리오 이벤트는 시나리오 추가, 업데이트, 제거, 적용, 복원, 활성화 및 비활성화와 같은 작업에서 발생합니다.

## 보호 동작

워크시트 보호는 시나리오 패널 및 SpreadJS 디자이너를 통해 수행되는 시나리오 작업을 제한합니다. 보호 관련 동작은 시나리오에서 참조하는 워크시트 전체에서 평가됩니다.
시나리오 정의 편집에는 시나리오 업데이트 또는 제거가 포함됩니다.
참조된 워크시트가 보호되어 있고 `allowEditScenarios`가 true인 경우 잠금 및 숨김 설정과 관계없이 해당 시나리오 재정의를 편집하고 표시할 수 있습니다.
참조된 워크시트가 보호되어 있고 `allowEditScenarios`가 true가 아닌 경우:

* `locked`가 true로 설정된 재정의는 읽기 전용입니다.
* `locked`가 false로 설정된 재정의는 계속 편집할 수 있습니다.
* `hidden`이 true로 설정된 재정의는 시나리오 패널에서 숨겨집니다.
* `hidden`이 false로 설정된 재정의는 계속 표시됩니다.

시나리오 패널의 잠금 ![image-20260803.8ccfe9.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260803.8ccfe9-20260820.39c637.png) 및 표시 여부 ![image-20260803.cb6e65.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260803.cb6e65-20260820.a52523.png) 아이콘을 사용하여 워크시트 수준 시나리오 항목에 대해 이러한 설정을 구성할 수 있습니다.

## 호환성

시나리오는 통합 문서와 함께 저장되며 Excel 파일에서 가져오거나 Excel 파일로 내보낼 수 있습니다.
SpreadJS 시나리오는 통합 문서 범위인 반면 Excel 시나리오는 워크시트 범위입니다. 가져오기 및 내보내기 중 SpreadJS는 필요에 따라 시나리오 범위를 변환합니다.
자세한 내용은 [Excel 호환성](/spreadjs/docs/features/what-if-analysis/excel-compatibility)을 참조하세요.