# 명명된 셀 템플릿

## Content

명명된 셀 템플릿을 사용하면 통합 문서 내의 지원되는 모든 범위에 적용할 수 있는 재사용 가능한 셀 구성을 정의할 수 있습니다.
시각적 스타일 속성만 포함하는 명명된 스타일과 달리, 명명된 셀 템플릿은 여러 셀 관련 설정을 하나의 재사용 가능한 정의에 포함할 수 있습니다.

* 스타일
* 조건부 서식 규칙
* 데이터 유효성 검사 규칙
* 셀 상태

이러한 설정을 하나의 템플릿으로 그룹화하면 워크시트 및 기타 지원되는 시트 유형 전반에서 일관성을 유지하고 반복적인 설정 작업을 줄일 수 있습니다.

## 핵심 개념

### 템플릿 정의

명명된 셀 템플릿은 다음과 같습니다.

* 고유한 이름으로 식별됨
* 통합 문서 수준에서 관리됨
* 이름 기준 대/소문자 구분 안 함

이미 존재하는 이름으로 템플릿을 추가하면 이전 정의가 대체됩니다.
템플릿은 `workbook.namedCellTemplates`를 통해 관리됩니다.

### 적용 전용 모델

명명된 셀 템플릿은 적용 전용(apply-only) 모델을 따릅니다.

* 템플릿은 적용되는 시점에만 적용됩니다.
* 템플릿과 대상 범위 사이의 바인딩 관계는 유지되지 않습니다.
* 템플릿을 업데이트해도 이미 적용된 범위에는 영향을 주지 않습니다.

이전에 서식이 지정된 범위에 변경 사항을 반영하려면 템플릿을 다시 적용해야 합니다.

### 불변 검색

템플릿 관리자에서 `get(name)`을 호출하면 저장된 템플릿의 깊은 복사본(deep copy)이 반환됩니다.
반환된 객체를 수정해도 등록된 템플릿에는 영향을 주지 않습니다.
기존 템플릿 정의를 업데이트하려면 동일한 이름으로 `add()`를 다시 호출해야 합니다. 이전 정의는 덮어써집니다.

## 적용 동작

명명된 셀 템플릿을 대상 범위에 적용하면 각 설정은 다음 규칙에 따라 동작합니다.

| 설정 | 동작 |
| --- | --- |
| 스타일 | 기존 스타일 덮어쓰기 |
| 데이터 유효성 검사 | 기존 유효성 검사 덮어쓰기 |
| 조건부 서식 | 새 규칙 추가 |
| 셀 상태 | 새 상태 추가 |

추가 규칙:

* 병합 또는 중복 제거는 수행되지 않습니다.
* 기존 조건부 서식 및 셀 상태 규칙은 유지됩니다.
* 새로 추가된 규칙의 삽입 우선순위는 SpreadJS의 기본 규칙 정렬 동작을 따릅니다.

템플릿은 적용 전용 모델이므로 이후 템플릿을 변경해도 이전에 서식이 적용된 범위에는 반영되지 않습니다.

## 템플릿 관리

템플릿은 통합 문서에서 제공하는 `INamedCellTemplatesManager`를 통해 관리됩니다.

* 템플릿 추가
* 기존 셀에서 템플릿 생성
* 템플릿 가져오기
* 템플릿 제거
* 모든 템플릿 열거
* 모든 템플릿 지우기
* JSON을 통한 직렬화 및 역직렬화

템플릿은 통합 문서 수준에 저장되며 통합 문서 직렬화에도 포함됩니다.
전체 메서드 시그니처 및 옵션은 API 참조 문서를 참고하세요.

* `INamedCellTemplatesManager`
* `INamedCellTemplate`

### 예제: 템플릿 생성

```auto
spread.namedCellTemplates.add("Financial Amount", {
    style: {
        formatter: "#,##0.00",
        hAlign: GC.Spread.Sheets.HorizontalAlign.right
    },
    conditionalFormats: [{
        ruleType: GC.Spread.Sheets.ConditionalFormatting.RuleType.cellValueRule,
        operator: GC.Spread.Sheets.ConditionalFormatting.ComparisonOperators.lessThan,
        value1: 0,
        style: { foreColor: "Accent 2" }
    }]
});
```

## 시트 유형 지원

명명된 셀 템플릿은 여러 시트 유형에 적용할 수 있습니다.
동작 방식은 시트 구현에 따라 약간 다를 수 있습니다.

### 워크시트

워크시트 또는 범위에서 `applyNamedCellTemplate`을 사용합니다.

```auto
sheet.applyNamedCellTemplate("Financial Amount", "A1:A10");

// or
sheet.getRange("B1:B10")
     .applyNamedCellTemplate("Financial Amount");
```

**지원되는 주소 형식**

* A1 스타일 범위 (`"A1:C3"`)
* 전체 행 또는 열 (`"A:A"`, `"1:3"`)
* 테이블 구조 참조 (`"Table1"`, `"Table1[[#Data]]"`, `"Table1[[#Headers]]"`)

다음 API 참조 문서를 확인하세요.

* `Worksheet.applyNamedCellTemplate`
* `CellRange.applyNamedCellTemplate`

### 리포트 시트

`ReportSheet`는 템플릿 적용 메서드를 직접 제공하지 않습니다.
대신 레이아웃 및 서식을 정의하는 TemplateSheet에 템플릿을 적용합니다.

```auto
const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
const templateSheet = report.getTemplate();

templateSheet.applyNamedCellTemplate("Financial Amount", "A1:A5");
```

### 테이블 시트

`TableSheet`에서는 데이터 원본 필드 이름을 지정하여 템플릿을 적용합니다.

```auto
tableSheet.applyNamedCellTemplate("Financial Amount", ["price", "quantity"]);
```

**동작**

* 바인딩된 `dataSource`가 필요합니다. 데이터 원본이 없으면 템플릿이 적용되지 않습니다.
* 템플릿은 지정된 필드 이름 기준으로 열 단위로 적용됩니다.
* 데이터 원본에 존재하지 않는 필드 이름은 무시됩니다.
* 템플릿의 `cellStates`는 지원되지 않으며 무시됩니다.
* 일반 조건부 서식 규칙은 열 단위로 적용됩니다.
* 상태 기반 규칙은 시트 수준에서 적용됩니다.

다음 API 참조 문서를 확인하세요.

* `TableSheet.applyNamedCellTemplate`

### 간트 시트

`GanttSheet`는 `TableSheet`와 동일한 방식으로 명명된 셀 템플릿을 지원합니다.
**추가 동작**

* 간트 차트 열은 자동으로 건너뜁니다.
* 기본 제공 기능 열은 대화형 편집기를 유지합니다.

## 명명된 셀 템플릿 사용 시점

다음과 같은 경우 명명된 셀 템플릿 사용을 권장합니다.

* 스타일 이상의 재사용 가능한 구성이 필요한 경우
* 조건부 서식 및 유효성 검사 규칙의 일관성을 유지해야 하는 경우
* 대화형 셀 상태를 표준화해야 하는 경우

재사용 가능한 시각적 서식만 필요한 경우에는 Named Style 사용을 고려하세요.

## SpreadJS 디자이너와의 통합

명명된 셀 템플릿은 SpreadJS 런타임 API를 통해 완전히 지원됩니다.
SpreadJS 디자이너는 템플릿 생성, 편집 및 적용을 위한 시각적 인터페이스를 제공하며, 편의를 위해 추가 기본 템플릿을 포함할 수도 있습니다.
자세한 내용은 SpreadJS 디자이너 문서의 [명명된 셀 템플릿](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/named-cell-templates)를 참고하세요.