정렬

The 피벗 테이블 정렬 기능은 SpreadJS에서 피벗 테이블 내 데이터 항목의 순서를 제어할 수 있게 하여, 보다 명확하고 효율적인 데이터 분석을 가능하게 합니다.

정렬은 PivotTable.sort() API와 sortInfo 객체를 사용하여 프로그래밍 방식으로 설정하거나, Designer에서 대화형으로 설정할 수 있습니다.

개발자는 필드 이름, 값 또는 사용자 지정 로직을 기준으로 정렬 순서를 지정할 수 있으며, 사용자 지정 콜백 함수 정렬, 사용자 지정 목록 정렬(“첫 번째 키 정렬 순서” 목록), 수동 드래그 앤 드롭 재정렬과 같은 고급 기능을 선택적으로 사용할 수 있습니다.

이러한 옵션은 워크시트의 피벗 테이블 전반에 걸쳐 일관된 정렬 동작을 정의하고 유지할 수 있는 유연한 방법을 제공합니다.

정렬 모드

다음의 4가지 주요 정렬 모드를 지원합니다:

관련 API

사용 예제

기본 코드

이 섹션의 모든 예제는 아래의 기본 설정을 기반으로 하며, 데모를 위해 샘플 통합 문서와 피벗 테이블을 생성합니다.

// 샘플 데이터로 통합 문서를 초기화하고 기본 피벗 테이블을 생성합니다.
// 아래 설정은 이후 모든 예제에서 공통으로 사용됩니다.

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 속성을 사용하여 정렬 모드를 설정합니다.

// 오름차순
pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.asc });

// 내림차순
pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.desc });

// 사용자 지정 순서
pivotTable.sort("Buyer", {sortType: GC.Pivot.SortType.custom });

필드 항목 이름으로 정렬

특정 필드를 기준으로 피벗 테이블 데이터를 정렬하려면 pivotTable.sort(fieldName, sortInfo) 메서드를 호출하고, sortInfo의 sortType 속성으로 정렬 순서(오름차순, 내림차순 또는 사용자 지정)를 지정합니다.

pivotTable.sort("Buyer", { sortType: GC.Pivot.SortType.desc });
// 결과: [“Mom”, “Kelly”, “Dad”]

값 필드 기준 정렬

다른 필드의 집계 값을 기준으로 피벗 필드를 정렬할 수 있습니다.

이를 위해 pivotTable.sort() 호출 시 sortInfo 객체에 다음 속성을 설정합니다:

• sortType – 정렬 방향(오름차순 또는 내림차순)을 정의합니다.

• sortValueFieldName – 비교 기준으로 사용할 값 필드를 지정합니다.

• sortByPivotReferences – 정렬에 사용할 집계 값이 위치한 피벗 영역(예: 특정 열)을 정의합니다.

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)을 인수로 받아 재정렬된 배열을 반환해야 합니다. 이를 통해 문자열 길이, 알파벳 패턴, 외부 순위 등 다양한 사용자 지정 규칙을 구현할 수 있습니다.

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의 항목은 필드 항목이 표시되는 정확한 순서를 정의합니다.

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를 적용합니다:

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() 메서드를 사용하여 필드의 정렬 정보를 가져오거나 초기화할 수 있습니다.

// 현재 정렬 정보 가져오기
let info = pivotTable.sort("Buyer");

// 정렬 초기화
pivotTable.sort("Buyer", null);

디자이너사용

Designer에서는 컨텍스트 메뉴를 통해 피벗 테이블 데이터를 직접 정렬할 수 있습니다.

피벗 테이블의 항목(행, 열 또는 값 영역에 속한 항목)을 마우스 오른쪽 버튼으로 클릭하면 컨텍스트 메뉴에 정렬 옵션이 표시됩니다.

정렬 옵션에는 다음 세 가지 하위 옵션이 있습니다:

• 오름차순 정렬 (A → Z / 작은 값 → 큰 값)

• 내림차순 정렬 (Z → A / 큰 값 → 작은 값)

• 추가 정렬 옵션…

처음 두 옵션은 선택한 필드의 데이터 형식에 따라 빠른 오름차순 또는 내림차순 정렬을 수행합니다.

추가 정렬 옵션…을 선택하면 추가적인 정렬 제어를 제공하는 해당 대화 상자가 열립니다.

아래 표는 피벗 테이블의 서로 다른 영역에서 추가 정렬 옵션… 명령을 실행했을 때의 동작을 설명합니다.

추가 옵션...을 클릭하면 고급 정렬 제어를 제공하는 추가 정렬 대화 상자가 열립니다.

정렬 대화 상자에서는 총합계 값(기본 옵션)을 기준으로 정렬하거나, 특정 필드 또는 항목의 값에 따라 정렬할 수 있습니다.

아래 이미지는 Designer에 표시되는 정렬(Type) 대화 상자의 예입니다:

정렬 설정이 없는 필드는 자동 정렬 모드로 유지되며, 추가 정렬 옵션을 열면 자동 옵션이 기본값으로 선택되어 표시됩니다.

자동 정렬 옵션을 해제하면 피벗 필드는 수동 정렬 모드로 전환됩니다. 이후 첫 번째 키 정렬 순서를 지정하여 오름차순 및 내림차순 사용자 지정 정렬의 적용 방식을 정의할 수 있습니다.

드래그 앤 드롭

디자이너의 드래그 앤 드롭 기능을 사용하면 대화 상자나 메뉴를 사용하지 않고도, 피벗 테이블 내에서 필드를 직접 끌어서 재배치할 수 있습니다.

이 기능은 피벗 테이블 레이아웃을 직관적이고 효율적으로 사용자 지정할 수 있는 방법을 제공합니다.

지원 영역

드래그 앤 드롭은 열 피벗 필드와 행 피벗 필드 모두에서 동일한 기본 상호작용 방식으로 지원됩니다.

선택 모드

드래그 앤 드롭 방법

1. 드래그 시작

• 선택된 피벗 필드의 테두리로 커서를 이동합니다.

• 커서가 이동 아이콘으로 바뀌면 마우스 버튼을 누른 채로 드래그를 시작합니다.

• 삽입 위치를 표시하는 드래그 표시기가 나타납니다.

2. 필드 이동 및 위치 지정

• 열 필드:

  커서가 대상 열 너비의 절반을 넘으면 표시기는 오른쪽 삽입을, 그렇지 않으면 왼쪽 삽입을 표시합니다.

• 행 필드:

  커서가 대상 행 높이의 절반을 넘으면 표시기는 아래 삽입을, 그렇지 않으면 위 삽입을 표시합니다.

• 상위 필드:

  상위 피벗 필드를 드래그할 경우 구조적 무결성을 유지하기 위해 하위 필드는 자동으로 건너뜁니다.

3. 필드 놓기

• 마우스 버튼을 놓아 선택한 피벗 필드를 새 위치에 삽입합니다.

지원되지 않는 경우

다음 상황에서는 드래그 앤 드롭이 지원되지 않습니다:

• 워크시트 전체 열 또는 행을 선택한 상태에서 드래그하는 경우

• 서로 다른 상위 필드 아래에 있는 동일한 하위 피벗 필드를 여러 개 드래그하려는 경우

설계 참고 사항 및 제한 사항

정렬 우선순위 및 상호작용

자동 정렬(autoSortState = true)은 공유 사용자 지정 목록보다 높은 우선순위를 가지며, 동적으로 변경되는 데이터 집합에서도 일관된 순서를 보장합니다.

자동 정렬이 활성화되어 있으면 PivotTableManager.customList는 무시됩니다. 공유 목록은 autoSort가 꺼져 있고 sortType이 asc 또는 desc일 때만 적용됩니다.

범위 및 영속성

워크시트 공유 customList는 통합 문서 간에 전파되지 않습니다. 또한 Workbook.options.customList에 자동으로 기록되지 않으며, Excel 가져오기/내보내기 시에도 포함되지 않습니다. 이는 여러 피벗 테이블이 공존할 때 의도치 않은 순서 전달을 방지합니다.

사용자 지정 정렬 목록의 동작

customSortList는 대소문자를 구분하지 않고 매칭합니다.

• 목록이 모든 필드 항목을 포함하는 경우 → 목록이 전체 순서를 정의합니다.

• 일부만 포함하는 경우 → 나열된 항목은 먼저(오름차순) 또는 마지막에(내림차순, 역순) 표시되며, 나머지 항목은 원래의 상대적 순서를 유지합니다.

  이러한 목록은 자동 정렬이 비활성화된 상태에서, 오름차순/내림차순 모드의 필드에만 영향을 줍니다.

값 기준 정렬 통합

값 기준으로 필드를 정렬하는 경우(sortValueFieldName 지정), getItemsByField(sorted=true)에 반환되는 레이블 순서는 최신 레이블 기반 정렬에 의해 결정된 내부 레이블 순서를 반영합니다. 이를 통해 값 기반 업데이트 전반에서 표시 순서가 일관되게 유지됩니다.

오류 복구

customSortCallback이 오류를 발생시키거나 일관되지 않은 비교 결과를 생성하는 경우, 피벗 테이블은 예측 가능한 정렬과 UI 안정성을 유지하기 위해 레이블 순서로 되돌아갑니다.