PivotValueFieldOptions extends PivotFieldOptions

값(values) 축에 배치하는 집계(measure) 필드 옵션.

Options

name: string (opens in a new tab)

필드명.
피벗테이블의 row/column dimension 또는 value 필드로 사용되는 데이터큐브 컬럼명을 반드시 지정한다. [주의] 생성 시 필수이며, 생성 후에는 변경할 수 없다.

default: undefined

width: number (opens in a new tab)

필드 표시 너비 (px).
지정하지 않으면 테이블 설정에 따라 기본 너비나 계산된 너비로 표시된다. 컬럼 헤더에 표시되는 경우 컬럼 헤더의 마지막 level 필드일 때만 적용된다. 즉, measure가 표시되면 상위 dimension 필드에는 적용되지 않는다.

default: undefined

headerWidth: number (opens in a new tab)

행에 표시될 때 너비.
지정하지 않으면 행 헤더의 기본 설정 너비나 계산된 너비로 표시된다.

default: undefined

measure: string (opens in a new tab)

[주의] 최초 생성 후 변경할 수 없다.

default: undefined

aggregate: 'var' | 'first' | 'last' | 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct' | 'product' | 'stdev' | 'stdevp' | 'varp' | 'p25' | 'p50' | 'p75'

값 필드의 집계 함수 유형.
지정하지 않으면 'sum'으로 집계한다.

default: undefined

dataBar: PivotDataBarOptions

셀 값 크기에 비례하는 막대를 셀 배경에 표시하는 옵션.
PivotDataBarOptions 참조.

default: undefined

heatmap: PivotHeatmapOptions

셀 값에 따라 색상을 달리하는 히트맵 옵션.
PivotHeatmapOptions 참조.

default: undefined

highlight: PivotHighlightOptions

특정 조건에 따라 셀을 강조 표시하는 옵션.
예를 들어, 값이 특정 임계값을 초과하는 경우 셀 배경색을 빨간색으로 표시하는 등의 조건부 서식 기능을 제공한다.

default: undefined

icon: PivotIconOverlayOptions

셀 값 범위에 따라 자동 N등분된 아이콘을 표시하는 overlay. 동일 셀에 dataBar가 활성화되어 있으면 dataBar가 우선이며 icon은 무시된다.

default: undefined

className: string (opens in a new tab)

값 필드의 모든 셀에 적용할 CSS 클래스 이름. 데이터바나 히트맵 등 셀 오버레이 스타일과는 별도로, 셀의 텍스트 스타일 등을 조정하기 위해 사용할 수 있다. [주의] 데이터바와 background-color 등 셀 스타일을 동시에 적용할 때, 클래스 이름이 셀 오버레이 스타일보다 우선 적용되므로 의도치 않은 스타일 충돌이 발생할 수 있다. 클래스 이름을 사용할 때는 셀 오버레이 스타일과의 조합에 주의해야 한다.

default: undefined

totalClass: string (opens in a new tab)

소계 셀에 추가로 적용할 CSS 클래스 이름.
지정하지 않으면 className이 소계 셀에도 동일하게 적용된다.

default: undefined

grandTotalClass: string (opens in a new tab)

총계 셀에 추가로 적용할 CSS 클래스 이름.
지정하지 않으면 className이 총계 셀에도 동일하게 적용된다.

default: undefined

numberFormat: string (opens in a new tab)

값 필드의 자료형이 '[number](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean)'일 때 숫자 표시 형식.
지정하지 않으면 피벗테이블에 설정된 기본 형식을 사용한다.

default: undefined

dateFormat: string (opens in a new tab)

값 필드의 자료형이 'date'일 때 날짜 표시 형식.
지정하지 않으면 피벗테이블에 설정된 기본 형식을 사용한다.

default: undefined

textFormat: string (opens in a new tab)

값 필드의 자료형이 'text'일 때 텍스트 표시 형식.
지정하지 않으면 피벗테이블에 설정된 기본 형식을 사용한다.

default: undefined

formatter: (cell: IPivotValueCellInfo, stats: ScopedStats) => string (opens in a new tab)|IPivotFormatResult

value 필드인 경우, 집계 값 대신 표시할 대체 텍스트(또는 텍스트+스타일)를 반환하는 콜백.

반환값:

• null 또는 undefined: 콜백 호출이 무시되고 원래 집계 값이 표시된다.
• string: 셀에 표시할 대체 텍스트. 문자열에 ${value} 토큰은 포맷된 셀 값으로 치환된다.
• IPivotFormatResult: 텍스트와 스타일을 함께 지정하는 객체.

예: { text: '▲ ${value}', color: 'red', bold: true, align: 'center' } → 빨간색 굵은 글씨로 '▲ 100' 중앙 정렬 표시. 예: { text: cell.value, className: 'highlight' } → 셀 값 그대로 표시하되, 클래스 highlight 적용. 예: { text: cell.value, color: 'red', bold: true, align: 'center', backgroundColor: '#ffff00' } → 빨간색 굵은 글씨로 중앙 정렬 표시, 배경색은 노란색.

콜백 내부에서 분포 기반 표시(자체 정규화/임계값/랭킹 등)가 필요하면 formatterStats를 지정한다. 지정된 옵션으로 measure 렌더 시작 시 단 한 번 통계를 계산해 stats 인자로 전달하므로, formatter 호출당 추가 비용이 없다. (지정하지 않으면 stats는 undefined이고 통계 계산도 일어나지 않는다.)

예: 행 단위 min~max 정규화로 백분율 표시

{
  formatterStats: { compareScope: 'row' },
  formatter: (cell, stats) => {
    const g = stats!.groups.get(stats!.groupKey(cell)) ?? stats!.all;
    const t = (cell.value - g.min) / (g.max - g.min);
    return `${(t * 100).toFixed(0)}%`;
  }
}

예: 전체 상위 10% 셀만 굵게 표시

{
  formatterStats: { withSorted: true },
  formatter: (cell, stats) => {
    const sorted = stats!.all.sorted!; // 내림차순
    const threshold = sorted[Math.floor(sorted.length * 0.1)];
    return cell.value >= threshold
      ? { text: cell.value, bold: true }
      : null;
  }
}

default: undefined

formatterStats: FormatterStatsOptions

formatter에 전달할 분포 통계의 사전 계산 옵션.

지정하면 measure 렌더 시작 시 1회만 통계를 산출하여 모든 formatter 호출에 같은 참조를 전달한다. 지정하지 않으면(undefined) 통계 계산은 일어나지 않고 stats 인자는 undefined.

formatter가 설정되어 있지 않으면 이 옵션은 무시된다.

heatmap/dataBar/iconOverlay/highlight 등 다른 overlay가 같은 measure에 있으면 통계 계산 자체가 캐시 공유되므로 추가 비용도 없다.

default: undefined

showAs: ValueShowAs | (cell: IPivotValueCellInfo) => any (opens in a new tab)

value 필드의 값 표시 방식.
집계 값을 그대로 표시하거나 백분율, 차이, 누적, 순위 등으로 변환하여 표시한다. 지정하지 않으면 'normal'로 표시한다.

빌트인 ValueShowAs 항목으로 표현이 어려운 경우 콜백 함수를 직접 지정할 수 있다. 콜백은 raw 집계 값을 가진 cell을 받아 변환된 표시값을 반환한다. 콜백 내부에서 빌트인 showAs와 유사한 계산이 필요하면 cell.field.model(= PivotValueFieldModel)에 노출된 헬퍼 API(rowTotal/colTotal/grandTotal/parentRowTotal/parentColTotal/ cellValue/siblingsAlong/indexOfSelf/baseValue)를 사용할 수 있다.

default: undefined

baseField: string (opens in a new tab)

showAs가 'basePercent' | 'baseDiff' | 'basePercentDiff'일 때 비교 기준이 되는 dimension 필드명.
지정한 필드 축에서 baseItem으로 지정한 항목의 셀 값을 기준값으로 사용한다.

default: undefined

baseItem: string (opens in a new tab) | number (opens in a new tab)

showAs가 'basePercent' | 'baseDiff' | 'basePercentDiff'일 때 비교 기준이 되는 항목 값 또는 상대 위치.

• string | number: baseField 축에서 해당 값과 일치하는 항목을 기준으로 사용.
• '@first' / '@last': 축의 첫 번째 / 마지막 항목.
• '@previous' / '@next': 직전 / 직후 항목.

상대 위치 항목은 현재 셀이 속한 부모 그룹 안에서 찾는다(중첩 축에서 그룹 경계를 넘지 않음). @previous/@next는 해당 방향으로 이동하며 조합이 실제로 존재하는 가장 가까운 항목을 기준으로 삼고, 조합 자체가 없는 항목은 건너뛴다. 방향으로 존재하는 조합이 하나도 없으면 결과는 빈 셀이다. 기준 항목(조합)은 존재하나 그 단면에서 값만 비어 있으면 기준값을 0으로 간주하여, 'baseDiff'는 현재값을, 'basePercent'/ 'basePercentDiff'는 0 나눗셈으로 빈 셀이 된다.

default: undefined

baseAxis: ShowAsAxis

showAs가 'diff' | 'percentDiff' | 'running' | 'rank'일 때 비교/누적/순위 계산의 기준 축.
Excel의 base field 축 개념과 동일하다. 기준 field가 놓인 축을 가리킨다.

• 'row': 기준 field가 행 축 → 행을 따라(세로) 이동하며 이웃 셀을 비교한다.
• 'column': 기준 field가 열 축 → 열을 따라(가로) 이동하며 이웃 셀을 비교한다.

같은 부모 그룹 내의 동일 measure 셀들만 형제로 간주한다.

default: 'row'

style: PivotCellStyle

값 필드의 모든 셀에 적용할 스타일.
className으로 설정된 css 클래스 스타일들보다 우선한다.

default: undefined

totalStyle: PivotCellStyle

값 필드의 소계 셀에 추가로 적용할 스타일.
totalClass으로 설정된 css 클래스 스타일들보다 우선한다. 또, styles로 설정된 스타일보다 우선한다.

default: undefined

grandStyle: PivotCellStyle

값 필드의 총계 셀에 추가로 적용할 스타일.
grandTotalClass으로 설정된 css 클래스 스타일들보다 우선한다. 또, styles로 설정된 스타일보다 우선한다.

default: undefined