# 템플릿 기반 통합 문서 초기화

## Content

사용자가 SpreadJS 디자이너에서 새 파일을 만들면 일반적으로 빈 통합 문서에서 시작합니다. 그러나 많은 애플리케이션에서는 사용자가 미리 정의된 레이아웃, 스타일 또는 비즈니스 전용 구조를 기반으로 작업을 시작해야 합니다.
`templatesConfig` 옵션을 사용하면 디자이너의 시작 환경을 정의할 수 있습니다. 빈 통합 문서를 여는 대신, 디자이너가 미리 정의된 템플릿으로 초기화되도록 하고 새로 만들기(New) 워크플로에서 여러 템플릿 선택지를 제공할 수 있습니다.
![selectTemplates-20260401.ee3f7f.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/selectTemplates-20260401.ee3f7f-20260602.6d6242.gif?width=800)

>type=note
> 이 기능은 디자이너 컴포넌트에서만 사용할 수 있습니다.

## 템플릿 기반 초기화 사용

사용자 지정 템플릿을 사용하려면 디자이너 인스턴스를 생성할 때 `templatesConfig` 옵션을 지정합니다.

```javascript
const designer = new GC.Spread.Sheets.Designer.Designer("container", {
  templatesConfig: "/templates/templatesConfig.json"
});
```

값은 JSON 구성 파일의 경로를 나타내는 문자열입니다.
`templatesConfig`를 지정하지 않으면 디자이너는 기본 동작을 유지하며 빈 통합 문서를 생성합니다.

## 템플릿 구성 파일 구조

구성 파일은 템플릿 정의를 포함하는 JSON 배열이어야 합니다.
예제:

```json
[
  {
    "name": "Blank",
    "data": "./templates/blank.ssjson",
    "thumbnail": "./templates/blank.png"
  },
  {
    "name": "Aging Report",
    "data": "./templates/aging_report.sjs",
    "thumbnail": "./templates/aging_report.png"
  }
]
```

### 템플릿 속성

| 속성 | 필수 | 설명 |
| --- | --- | --- |
| `name` | 예 | UI에 표시되는 템플릿 이름입니다. |
| `data` | 아니요 | 템플릿 콘텐츠입니다. 템플릿 파일 URL 또는 인라인 Workbook JSON 객체를 지정할 수 있습니다. 생략하면 빈 템플릿으로 처리됩니다. |
| `thumbnail` | 아니요 | 템플릿 미리 보기에 사용되는 이미지 URL 또는 Base64 문자열입니다. 생략하면 기본 빈 템플릿 썸네일이 사용됩니다. |

**`data` 동작**

* `data`가 문자열이면 URL로 처리됩니다. 디자이너는 리소스를 가져온 후 파일 확장자에 따라 로드 방식을 결정합니다.
* `data`가 객체이면 Workbook JSON 데이터로 처리되어 직접 적용됩니다.

### 지원되는 템플릿 형식

`data`가 URL인 경우 다음 형식을 지원합니다.

* `.ssjson`
* `.sjs`
* `.xlsx`
* `.xltx`
* `.xlsm`
* `.xltm`

## 기본 템플릿 동작

구성 배열의 첫 번째 템플릿(`templates[0]`)은 **기본 템플릿**으로 처리됩니다.
다음 경우 자동으로 적용됩니다.

* **디자이너 초기화** - `new Designer()` 호출 후 기본 템플릿이 로드되어 통합 문서에 적용됩니다.
* **초기화 작업** \- 사용자가 **새로 만들기(New)** 를 선택하거나 초기화 작업을 수행하면 빈 통합 문서를 생성하는 대신 기본 템플릿이 로드됩니다.

다른 템플릿은 사용자가 템플릿 선택기에서 명시적으로 선택한 경우에만 적용됩니다.
템플릿이 성공적으로 로드되면 해당 통합 문서는 수정되지 않은 새 파일 상태로 처리됩니다.

## 비동기 로드 고려 사항

기본 템플릿은 비동기적으로 로드됩니다.
디자이너 인스턴스를 생성한 직후 통합 문서에 접근하거나 수정하면 템플릿 로드 완료 시 변경 내용이 덮어써질 수 있습니다.
초기화 과정에서 통합 문서를 조작해야 하는 경우 템플릿 로드가 완료될 때까지 기다려야 합니다.

```javascript
const designer = new GC.Spread.Sheets.Designer.Designer("container", {
  templatesConfig: "/templates/templatesConfig.json"
});

await designer.waitForDefaultTemplateLoaded();

const workbook = designer.getWorkbook();
workbook.getActiveSheet().setValue(0, 0, "Safe to modify");
```

`templatesConfig`가 구성되지 않은 경우 디자이너 초기화는 동기 방식으로 유지됩니다. 이전 버전의 기존 코드는 수정 없이 계속 사용할 수 있습니다.

## 런타임에 템플릿 업데이트

디자이너가 생성된 이후에도 템플릿 구성을 업데이트할 수 있습니다.

`setData` 사용:

```javascript
designer.setData("templatesConfig", [
  {
    name: "Blank",
    data: "./templates/blank.ssjson",
    thumbnail: "./templates/blank.png"
  },
  {
    name: "Financial Report",
    data: "./templates/financial_report.sjs",
    thumbnail: "./templates/financial_report.png"
  }
]);
```

`setConfig` 사용:

```javascript
const config = {
  ...GC.Spread.Sheets.Designer.DefaultConfig,
  templatesConfig: "/templates/newTemplatesConfig.json"
};

designer.setConfig(config);
```

`setConfig`에 `templatesConfig` 속성이 포함되어 있으면 디자이너는 템플릿 구성을 업데이트합니다.
`setConfig`에 `templatesConfig` 속성이 없으면 기존 템플릿 구성은 유지됩니다.
`templatesConfig` 변경 사항은 이후 초기화 작업에만 영향을 미치며 현재 로드된 통합 문서는 자동으로 변경되지 않습니다.

## 이벤트

### `DesignerResetDone`

이 이벤트는 초기화 작업이 완료되고 선택된 템플릿이 완전히 로드된 후 발생합니다.

```javascript
designer.bind(
  GC.Spread.Sheets.Designer.Events.DesignerResetDone,
  () => {
    console.log("Reset completed and template applied.");
  }
);
```

### `FileLoading` 및 `FileLoaded`

초기화, 리셋 또는 템플릿 선택 중 템플릿을 로드할 때도 표준 파일 로드 이벤트가 발생합니다. 이러한 이벤트는 파일을 열 때와 동일하게 동작합니다.

## 대체 동작

* `templatesConfig`가 설정되지 않았거나 비어 있으면 디자이너는 빈 통합 문서를 생성하며 기본 빈 템플릿만 사용할 수 있습니다.
* 기본 템플릿 로드에 실패하면 디자이너는 빈 통합 문서로 대체합니다.
* 기본 템플릿이 아닌 템플릿의 로드에 실패한 경우에도 빈 통합 문서가 대신 사용됩니다.