# 정렬
## Content
The **피벗 테이블 정렬** 기능은 SpreadJS에서 피벗 테이블 내 데이터 항목의 순서를 제어할 수 있게 하여, 보다 명확하고 효율적인 데이터 분석을 가능하게 합니다.
정렬은 `PivotTable.sort()` API와 `sortInfo` 객체를 사용하여 **프로그래밍 방식**으로 설정하거나, **Designer**에서 **대화형**으로 설정할 수 있습니다.
개발자는 필드 이름, 값 또는 사용자 지정 로직을 기준으로 정렬 순서를 지정할 수 있으며, **사용자 지정 콜백 함수** 정렬, **사용자 지정 목록** 정렬(“첫 번째 키 정렬 순서” 목록), **수동 드래그 앤 드롭 재정렬**과 같은 고급 기능을 선택적으로 사용할 수 있습니다.
이러한 옵션은 워크시트의 피벗 테이블 전반에 걸쳐 일관된 정렬 동작을 정의하고 유지할 수 있는 유연한 방법을 제공합니다.
## 정렬 모드
다음의 4가지 주요 정렬 모드를 지원합니다:
| **모드** | **설명** | **UI 표시** |
| --- | --- | ----- |
| 오름차순 | 필드 항목을 알파벳/오름차순으로 정렬합니다. | - `autoSort = true`: 
- `autoSort = false`: 
|
| 내림차순 | 필드 항목을 역순/알파벳 내림차순으로 정렬합니다. | - `autoSort = true`: 
- `autoSort = false`: 
|
| 사용자 지정(콜백) | 사용자 지정 비교 함수를 사용하여 정렬 로직을 정의합니다. |  |
| 사용자 지정(목록) | 미리 정의된 값 목록을 사용하여 명시적인 순서를 정의합니다. |  |
## 관련 API
| **유형** | **이름** | **설명** |
| --- | --- | --- |
| 열거형 | [SortType](/spreadjs/api/enums/GC.Pivot.SortType) | 정렬 모드: `asc`, `desc`, `custom` |
| 인터페이스 | [IPivotViewSortInfo](/spreadjs/api/modules/GC.Pivot#ipivotviewsortinfo) | 필드에 대한 정렬 구성
주요 필드: `sortType`, `sortValueFieldName`, `customSortList`, `customSortCallback` |
| 메서드 | [PivotTable.sort(fieldName, sortInfo)](/spreadjs/api/classes/GC.Spread.Pivot.PivotTable-1#sort) | 필드의 정렬 구성을 가져오거나 설정합니다. |
| 메서드 | [PivotTable.autoSortState(fieldName, enabled?)](/spreadjs/api/classes/GC.Spread.Pivot.PivotTable-1#autosortstate) | 필드의 자동 정렬 상태를 조회/전환합니다(기본값: 사용).
사용 시 `PivotTableManager.customList`는 적용되지 않습니다. |
| 메서드 | [PivotTable.getItemsByField(fieldName, sorted?)](/spreadjs/api/classes/GC.Spread.Pivot.PivotTable-1#getitemsbyfield) | 필드 항목을 반환합니다.- `sorted=true`: 현재 정렬된 순서를 반환
- 그 외: 정렬되지 않은 목록 반환
값 기준으로 정렬된 경우, 최신 레이블 정렬의 내부 레이블 순서를 반환합니다. |
| 메서드 | [PivotTableManager.customList(customList?)](/spreadjs/api/classes/GC.Spread.Sheets.PivotTableManager#customlist) | 워크시트 공유 사용자 지정 정렬 목록을 가져오거나 설정합니다.
필드의 `autoSort`가 비활성화되고 `asc`/`desc`일 때만 적용됩니다. |
>type=note
> **참고 사항:**
>
> * **정렬 우선순위:** `autoSort`(기본적으로 사용)가 워크시트 공유 `customList`보다 우선합니다. `autoSort = false`이고 `sortType ∈ {asc, desc}`인 경우에만 공유 `customList`가 순서에 영향을 줍니다.
> * **범위:** `PivotTableManager.customList`는 동일한 워크시트 내 모든 피벗 테이블에 적용되며, 통합 문서 범위는 아닙니다.
> * **영속성:** 공유 사용자 지정 목록은 `Workbook.options.customList`에 저장되지 않으며, Excel로 내보내기/가져오기 시에도 포함되지 않습니다.
>
> 자세한 동작 설명과 설계 배경은 **설계 참고 사항 및 제한 사항**을 참조하세요.
## 사용 예제
**기본 코드**
이 섹션의 모든 예제는 아래의 기본 설정을 기반으로 하며, 데모를 위해 샘플 통합 문서와 피벗 테이블을 생성합니다.
```javascript
// 샘플 데이터로 통합 문서를 초기화하고 기본 피벗 테이블을 생성합니다.
// 아래 설정은 이후 모든 예제에서 공통으로 사용됩니다.
var spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"),{sheetCount:3});
var sourceSheet = spread.getSheet(0);
var sheet = spread.getSheet(1);
var sourceData = [["Date","Buyer","Type","Amount"],
["01-Jan","Mom","Fuel",74],
["15-Jan","Mom","Food",235],
["17-Jan","Dad","Sports",20],
["21-Jan","Kelly","Books",125]];
sourceSheet.setArray(0, 0, sourceData );
sourceSheet.tables.add('sourceData', 0, 0, 5, 4);
var layout = GC.Spread.Pivot.PivotTableLayoutType.compact;
var theme = GC.Spread.Pivot.PivotTableThemes.medium2;
var options = {showRowHeader: true, showColumnHeader: true};
var pivotTable = sheet.pivotTables.add("pivotTable_1",'sourceData',1,1,layout,theme,options);
pivotTable.add("Buyer","Buyer",GC.Spread.Pivot.PivotTableFieldType.rowField);
pivotTable.add("Type","Type",GC.Spread.Pivot.PivotTableFieldType.columnField);
pivotTable.add("Amount","Amount",GC.Spread.Pivot.PivotTableFieldType.valueField);
pivotTable.autoFitColumn();
```
**정렬 모드 설정**
`sortInfo`의 `sortType` 속성을 사용하여 정렬 모드를 설정합니다.
```javascript
// 오름차순
pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.asc });
// 내림차순
pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.desc });
// 사용자 지정 순서
pivotTable.sort("Buyer", {sortType: GC.Pivot.SortType.custom });
```
>type=note
> **참고:**
> `custom` 모드(`GC.Pivot.SortType.custom`)를 선택한 경우, `customSortCallback` 또는 `customSortList`를 사용하여 정렬 규칙을 반드시 지정해야 합니다.
**필드 항목 이름으로 정렬**
특정 필드를 기준으로 피벗 테이블 데이터를 정렬하려면 `pivotTable.sort(fieldName, sortInfo)` 메서드를 호출하고, `sortInfo`의 `sortType` 속성으로 정렬 순서(오름차순, 내림차순 또는 사용자 지정)를 지정합니다.
```javascript
pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.desc });
// 결과: [“Mom”, “Kelly”, “Dad”]
```
**값 필드 기준 정렬**
다른 필드의 집계 값을 기준으로 피벗 필드를 정렬할 수 있습니다.
이를 위해 `pivotTable.sort()` 호출 시 `sortInfo` 객체에 다음 속성을 설정합니다:
* `sortType` – 정렬 방향(오름차순 또는 내림차순)을 정의합니다.
* `sortValueFieldName` – 비교 기준으로 사용할 값 필드를 지정합니다.
* `sortByPivotReferences` – 정렬에 사용할 집계 값이 위치한 피벗 영역(예: 특정 열)을 정의합니다.
```javascript
pivotTable.sort("Buyer", {
sortType: GC.Pivot.SortType.asc,
sortValueFieldName: "Amount",
sortByPivotReferences: [
{
fieldName: "Type",
items: [
"Books"
]
}
]
});
// 결과: [“Dad”, “Mom”, “Kelly”]
```
**사용자 지정 콜백 함수로 정렬**
`sortType`을 `GC.Pivot.SortType.custom`으로 설정하고 `customSortCallback` 함수를 제공하여 필드에 대한 사용자 지정 정렬 로직을 정의할 수 있습니다.
콜백은 대상 필드의 모든 항목이 포함된 배열(`list`)을 인수로 받아 재정렬된 배열을 반환해야 합니다. 이를 통해 문자열 길이, 알파벳 패턴, 외부 순위 등 다양한 사용자 지정 규칙을 구현할 수 있습니다.
```javascript
pivotTable.sort("Buyer", {
sortType: GC.Pivot.SortType.custom,
customSortCallback: function (list) {
return list.sort((a, b) => a.length - b.length);
}
});
// 결과: [“Mom”, “Dad”, “Kelly”]
```
**사용자 지정 정렬 목록으로 정렬**
필드의 `sortType`을 `GC.Pivot.SortType.custom`으로 설정하고 `customSortList`를 지정하면 고정된 정렬 순서를 정의할 수 있습니다.
`customSortList`의 항목은 필드 항목이 표시되는 정확한 순서를 정의합니다.
>type=note
> **참고 사항:**
>
> * 피벗 필드에 실제로 존재하는 항목만 정렬되며, 목록에 있지만 존재하지 않는 항목은 무시됩니다.
> * 정렬은 대소문자를 구분하지 않습니다.
> * `customSortList`에 포함되지 않은 항목은 지정된 항목 뒤에 기본 순서를 유지한 채 표시됩니다.
```javascript
pivotTable.sort("Type", {
sortType: GC.Pivot.SortType.custom,
customSortList: ["FOOD", "sports", "Books", "fUel" ]// 대소문자 구분 없음
});
// 결과: [“Food”, “Sports”, “Books”, “Fuel”]
pivotTable.sort("Buyer", {
sortType: GC.Pivot.SortType.custom,
customSortList: ["Food", "Sports"]// 나머지 항목은 기본 순서 유지
});
// 결과: [“Food”, “Sports”, “Books”, “Fuel”]
```
두 예제 모두 동일한 순서를 생성합니다.
첫 번째는 대소문자 구분 없는 매칭을 보여주며, 두 번째는 목록에 없는 항목이 기본 순서를 유지함을 보여줍니다.
**사용자 지정 목록과 자동 정렬 상태 결합**
피벗 테이블의 정렬 동작에 사용자 지정 목록을 결합할 수 있습니다.
목록 순서를 적용하려면 먼저 자동 정렬을 비활성화한 후 `PivotManager.customList`를 적용합니다:
```javascript
pivotTable.autoSortState("Type", false);
sheet.pivotTables.customList(["Food", "Sports"]);
// 오름차순 동작
pivotTable.sort("Type", { sortType: GC.Pivot.SortType.asc });
// 결과: [“Food”, “Sports”, “Books”, “Fuel”]
// 내림차순 동작
pivotTable.sort("Type", { sortType: GC.Pivot.SortType.desc });
// 결과: [“Fuel”, “Books”, “Sports”, “Food”]
```
**수동 재정렬(드래그 앤 드롭)**
사용자는 전체 정렬 이후 항목을 드래그하여 피벗 필드 항목을 수동으로 재정렬할 수 있습니다.
변경 사항은 즉시 적용되며 **사용자 지정 정렬** 상태로 저장됩니다.
자세한 내용은 **드래그 앤 드롭**을 참조하세요.
**정렬 정보 가져오기 및 초기화**
`pivotTable.sort()` 메서드를 사용하여 필드의 정렬 정보를 가져오거나 초기화할 수 있습니다.
```javascript
// 현재 정렬 정보 가져오기
let info = pivotTable.sort("Buyer");
// 정렬 초기화
pivotTable.sort("Buyer", null);
```
## 디자이너사용
Designer에서는 **컨텍스트 메뉴**를 통해 피벗 테이블 데이터를 직접 정렬할 수 있습니다.
피벗 테이블의 항목(행, 열 또는 값 영역에 속한 항목)을 마우스 오른쪽 버튼으로 클릭하면 컨텍스트 메뉴에 **정렬** 옵션이 표시됩니다.
**정렬** 옵션에는 다음 세 가지 하위 옵션이 있습니다:
* **오름차순 정렬** (A → Z / 작은 값 → 큰 값)
* **내림차순 정렬** (Z → A / 큰 값 → 작은 값)
* **추가 정렬 옵션…**
처음 두 옵션은 선택한 필드의 데이터 형식에 따라 빠른 오름차순 또는 내림차순 정렬을 수행합니다.
**추가 정렬 옵션…**을 선택하면 추가적인 정렬 제어를 제공하는 해당 대화 상자가 열립니다.
아래 표는 피벗 테이블의 서로 다른 영역에서 **추가 정렬 옵션…** 명령을 실행했을 때의 동작을 설명합니다.
| **항목 영역** | **대화 상자** | **동작** |
| ----- | ----- | --- |
| 일반 값 영역 |  | **값 기준 정렬** 대화 상자가 표시됩니다. |
| 총합계 영역 |  | **값 기준 정렬** 대화 상자가 표시됩니다. 단, 다음 조건과 함께 정렬 방향이 비활성화됩니다:- 총합계 열의 경우 기본 방향은 위에서 아래입니다.
- 총합계 행의 경우 기본 방향은 왼쪽에서 오른쪽입니다.
- 총합계 행과 열 모두인 경우 대화 상자가 표시되지 않습니다.
|
| 행 머리글 영역/모서리 영역 |  | 다음 조건과 함께 **필드 정렬** 대화 상자가 열립니다:- 압축 레이아웃의 경우 모서리 영역에는 **정렬** 옵션이 표시되지 않습니다.
- 선택한 필드가 Σ값 필드인 경우 **값 기준 정렬** 대화 상자가 표시됩니다.
- 선택한 행 영역이 Σ값 항목인 경우 대화 상자가 표시되지 않습니다.
|
| 열 머리글 영역 |  | 다음 조건과 함께 **필드 정렬** 대화 상자가 열립니다:- 선택한 필드가 Σ값 필드인 경우 **값 기준 정렬** 대화 상자가 표시됩니다.
- 선택한 열 영역이 Σ값 항목인 경우 대화 상자가 표시되지 않습니다.
|
>type=note
> **참고:**
> 사용자 지정 정렬이 수행되면 정렬 옵션 대화 상자는 자동으로 **수동**으로 전환됩니다.
**추가 옵션...**을 클릭하면 고급 정렬 제어를 제공하는 추가 **정렬** 대화 상자가 열립니다.
**정렬** 대화 상자에서는 *총합계* 값(기본 옵션)을 기준으로 정렬하거나, 특정 필드 또는 항목의 값에 따라 정렬할 수 있습니다.
아래 이미지는 Designer에 표시되는 **정렬(Type)** 대화 상자의 예입니다:
정렬 설정이 없는 필드는 자동 정렬 모드로 유지되며, **추가 정렬 옵션**을 열면 **자동** 옵션이 **기본값**으로 선택되어 표시됩니다.
**자동 정렬** 옵션을 해제하면 피벗 필드는 **수동** 정렬 모드로 전환됩니다. 이후 첫 번째 키 정렬 순서를 지정하여 오름차순 및 내림차순 사용자 지정 정렬의 적용 방식을 정의할 수 있습니다.
>type=note
> **참고:**
> **추가 옵션...** 버튼은 **행** 또는 **열** 영역에 배치된 필드에서 접근할 경우 비활성화될 수 있습니다.
### 드래그 앤 드롭
디자이너의 **드래그 앤 드롭** 기능을 사용하면 대화 상자나 메뉴를 사용하지 않고도, 피벗 테이블 내에서 필드를 직접 끌어서 재배치할 수 있습니다.
이 기능은 피벗 테이블 레이아웃을 직관적이고 효율적으로 사용자 지정할 수 있는 방법을 제공합니다.
**지원 영역**
드래그 앤 드롭은 **열 피벗 필드**와 **행 피벗 필드** 모두에서 동일한 기본 상호작용 방식으로 지원됩니다.
**선택 모드**
| **선택 모드** | **예시 화면** |
| ----- | ----- |
| 피벗 필드 머리글만 선택 |  |
| 분할된 값 범위를 포함한 머리글 |  |
| 전체 값 범위를 포함한 머리글 |  |
| 필드 머리글 클릭하여 전체 범위 선택 |  |
>type=note
> **참고:**
> 위 네 가지 선택 모드에서만 드래그 앤 드롭이 지원됩니다. 다른 선택 모드는 지원되지 않습니다.
**드래그 앤 드롭 방법**
1. **드래그 시작**
* 선택된 피벗 필드의 테두리로 커서를 이동합니다.
* 커서가 이동 아이콘으로 바뀌면 마우스 버튼을 누른 채로 드래그를 시작합니다.
* 삽입 위치를 표시하는 **드래그 표시기**가 나타납니다.
2. **필드 이동 및 위치 지정**
* **열 필드:**
커서가 대상 열 너비의 절반을 넘으면 표시기는 오른쪽 삽입을, 그렇지 않으면 왼쪽 삽입을 표시합니다.
* **행 필드:**
커서가 대상 행 높이의 절반을 넘으면 표시기는 아래 삽입을, 그렇지 않으면 위 삽입을 표시합니다.
* **상위 필드:**
상위 피벗 필드를 드래그할 경우 구조적 무결성을 유지하기 위해 하위 필드는 자동으로 건너뜁니다.
3. **필드 놓기**
* 마우스 버튼을 놓아 선택한 피벗 필드를 새 위치에 삽입합니다.
>type=note
> **참고:**
> 수동 재배치 후 **정렬 옵션** 대화 상자를 열면 정렬 모드가 **수동**으로 설정되어 있음을 확인할 수 있습니다.
**지원되지 않는 경우**
다음 상황에서는 드래그 앤 드롭이 **지원되지 않습니다**:
* 워크시트 전체 열 또는 행을 선택한 상태에서 드래그하는 경우
* 서로 다른 상위 필드 아래에 있는 동일한 하위 피벗 필드를 여러 개 드래그하려는 경우
## 설계 참고 사항 및 제한 사항
**정렬 우선순위 및 상호작용**
자동 정렬(`autoSortState = true`)은 공유 사용자 지정 목록보다 높은 우선순위를 가지며, 동적으로 변경되는 데이터 집합에서도 일관된 순서를 보장합니다.
자동 정렬이 활성화되어 있으면 `PivotTableManager.customList`는 무시됩니다. 공유 목록은 `autoSort`가 꺼져 있고 `sortType`이 `asc` 또는 `desc`일 때만 적용됩니다.
**범위 및 영속성**
워크시트 공유 `customList`는 통합 문서 간에 전파되지 않습니다. 또한 `Workbook.options.customList`에 자동으로 기록되지 않으며, Excel 가져오기/내보내기 시에도 포함되지 않습니다. 이는 여러 피벗 테이블이 공존할 때 의도치 않은 순서 전달을 방지합니다.
**사용자 지정 정렬 목록의 동작**
`customSortList`는 대소문자를 구분하지 않고 매칭합니다.
* 목록이 모든 필드 항목을 포함하는 경우 → 목록이 전체 순서를 정의합니다.
* 일부만 포함하는 경우 → 나열된 항목은 먼저(오름차순) 또는 마지막에(내림차순, 역순) 표시되며, 나머지 항목은 원래의 상대적 순서를 유지합니다.
이러한 목록은 자동 정렬이 비활성화된 상태에서, 오름차순/내림차순 모드의 필드에만 영향을 줍니다.
**값 기준 정렬 통합**
값 기준으로 필드를 정렬하는 경우(`sortValueFieldName` 지정), `getItemsByField(sorted=true)`에 반환되는 레이블 순서는 최신 레이블 기반 정렬에 의해 결정된 내부 레이블 순서를 반영합니다. 이를 통해 값 기반 업데이트 전반에서 표시 순서가 일관되게 유지됩니다.
**오류 복구**
`customSortCallback`이 오류를 발생시키거나 일관되지 않은 비교 결과를 생성하는 경우, 피벗 테이블은 예측 가능한 정렬과 UI 안정성을 유지하기 위해 레이블 순서로 되돌아갑니다.