PivotValueField extends PivotField

Properties

static defaults: Omit (opens in a new tab)<PivotValueFieldOptions, 'name'>

각 클래스별 기본 설정 값들. 하위 클래스에서 재정의한다. 객체 인스턴스의 _op에는 명시적으로 설정된 값들만 들어가므로, 효과 값(effective value)을 읽을 때는 항상 이 기본값을 fallback으로 사용해야 한다.(single-source-of-truth)

default: undefined

hasDeterministicFormat: boolean (opens in a new tab) readonly

formatter 콜백 / showAs / overlay text 영향 없이 컬럼 너비를 정확히 추정할 수 있는지 여부.

default: undefined

hasFormatterCallback: boolean (opens in a new tab) readonly

formatter 콜백이 등록되어 있는지 여부. true면 표시 텍스트 분포를 raw 값으로 추정할 수 없다.

default: undefined

showAsKind: string (opens in a new tab) readonly

options.showAs가 문자열(미리 정의된 타입)이면 해당 문자열, 콜백/없음이면 null.

default: undefined

statsManager: ValueFieldStatsManager readonly

이 필드의 셀 분포 통계 매니저. overlay들이 공유하여 셀 4중 순회를 1회로 줄인다. 첫 호출 시 lazily 생성한다.

default: undefined

Methods

baseValue(cell, baseField, baseItem): number (opens in a new tab)

셀의 dimension 경로에서 baseField 축의 라벨을 baseItem으로 치환한 셀 값. baseItem은 라벨 값이거나 'first' | 'last' | 'previous' | 'next'.

bool(prop): boolean (opens in a new tab)

boolean (opens in a new tab) 타입의 옵션 값에 특화된 prop() 메서드. prop()과 달리 boolean (opens in a new tab)으로 변환해서 반환한다.
해석 순서는 prop()과 동일하다(명시값(_op) → preset → 클래스 defaults).

return boolean (opens in a new tab) 타입의 옵션 값.

boolAt(path): boolean (opens in a new tab)

점(dot) 표기법으로 경로를 지정해서 boolean (opens in a new tab) 타입의 옵션 값을 반환한다.

return 경로에 해당하는 boolean (opens in a new tab) 타입의 옵션 값 또는 false

cellValue(row, col): number (opens in a new tab)

임의 위치 (row, col) 셀의 raw 집계 값. (소계/총계 포함)

clean(recursive?): this

_op에 명시적으로 설정되어 있지만 값이 현재 defaults와 동일한 항목들을 제거해 _op를 minimal delta 상태로 정규화한다.

[주의] 대부분의 경우 호출할 필요가 없다.

• 효과 값(prop/num/props)은 영향 없음.
• 직렬화(saveOptions)도 어차피 defaults와 같은 값을 필터링하므로 결과가 동일하다. 즉 외부 저장 결과는 clean 전후가 같다.

clean이 실제로 차이를 만드는 경우는 다음과 같다.

• _op의 메모리 사용을 줄이고 싶을 때(loadOptions로 큰 source를 읽어들인 직후 등).
• getOption()/saveOption()처럼 _op의 own value를 그대로 반환하는 API의 결과를 "사용자가 명시했는가"의 의미로 사용해야 할 때(예: 디자이너 UI의 "기본값 사용 중" 표시). 이 경우 clean 후에는 defaults와 같은 값들이 undefined로 보고된다.

return 모델 객체 자신

clearOptions(recursive?, render?): this

명시적으로 설정된 모든 모델 설정 값들을 제거한다.

return 모델 객체 자신

colTotal(cell): number (opens in a new tab)

셀이 속한 열 그룹 × 모든 행의 합계.

deleteAt(path, render?): any (opens in a new tab)

명시적으로 설정된 하위 모델의 설정 값을 제거해서 모델의 기본 값이 적용되도록 한다.
path 매개변수는 하위 모델의 속성 이름을 점(.)으로 구분해서 지정한다. 예를 들어, "axis.x"는 axis 모델의 x 속성을 의미한다.
render와 force 매개변수는 toggleOption과 동일하다.

dispose(): null

객체를 해제하고 null을 반환한다.
사용 예: this._obj = this._obj.dispose();

return null

formatCellRich(info): string (opens in a new tab) | IPivotFormatResult

셀의 raw formatter 결과(rich object 또는 string (opens in a new tab))를 그대로 반환한다. 자동 폭 계산 등 className/icon 같은 부수 필드까지 필요할 때 사용.

formatCellText(info): string (opens in a new tab)

셀 정보로부터 실제 표시 텍스트를 생성한다(formatter / showAs 결과 반영). IPivotFormatResult가 반환되면 .text만 추출해 string (opens in a new tab)으로 변환한다.

formatRawValue(value): string (opens in a new tab)

사용자 formatter 콜백을 거치지 않고 raw value를 type formatter만으로 변환한다. 컬럼 너비 자동 계산 등 fast path에서 사용한다.

getOption(option): any (opens in a new tab)

옵션 값을 읽는다.
prop()과 달리 효과 값이 아닌 명시적으로 설정된 값만 읽는다. 설정되지 않은 옵션은 undefined를 반환한다.

return 명시적으로 설정된 값 또는 undefined

getOptionAt(path): any (opens in a new tab)

점(dot) 표기법으로 경로를 지정해서 옵션 값을 읽는다.

return 경로에 해당하는 옵션 값 또는 undefined

getStats(cellScope?, compareScope?, opts?): ScopedStats

이 필드 셀들의 분포 통계를 조회한다.

formatter 내부에서 자체 정규화/임계값/랭킹 으로 텍스트를 만들 때 사용한다. heatmap/dataBar 등 overlay와 동일 캐시를 공유하며 prepare() 이후 언제든 호출 가능.

고급 overlay들(heatmap/dataBar/iconOverlay/highlight)과 동일한 캐시를 공유하므로 같은 (cellScope, compareScope) 조합이면 추가 순회 비용이 없다. prepare() 이후 언제든 호출 가능.

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

grandTotal(measure): number (opens in a new tab)

해당 measure의 전체 합계(grand total).

indexOfSelf(sibs, cell): number (opens in a new tab)

siblings 배열에서 cell 자신의 인덱스. 없으면 -1.

init(): this

특정 부모에 마운팅되지 않은 독립된 옵션 객체를 초기화한다.

initAndLoad(source): this

특정 부모에 마운팅되지 않은 독립된 옵션 객체를 초기화하고, source 객체로부터 옵션 값을 읽어서 설정한다.

invertOptions(source?): any (opens in a new tab)

source를 updateOptions에 적용했을 때 그 변경을 되돌리는 역(inverse) update 페이로드를 현재 상태 기준으로 계산해 반환한다. redo 적용 전에 호출해야 한다(현재 값이 곧 "before"다). command의 undo용 스냅샷을 최소 델타로 만들기 위한 것이다:

const inverse = model.invertOptions(options); model.updateOptions(options);
model.updateOptions(inverse);

키 종류별 처리(다형적으로 자식에 위임):

• 자식 모델: child.invertOptions(source[key])로 위임한다. RCollection은 이를 override해 추가/삭제/재정렬까지 되돌리는 구조 역델타를 만든다.
• 스칼라/외부 키: 해당 키의 현재 값을 force 스냅샷한다(default였던 값도 포함하므로 undo가 default로 되돌릴 수 있다). source의 값 자체는 키 선택자로만 쓰이고 무시된다.

source가 일반 객체가 아니면(undefined/원시값/배열) base로선 되돌릴 키가 없으므로 **no-op 역({})**을 반환한다. 배열 source나 _doSetSimple로 상태를 통째 세팅하는 소스를 실제로 다루는 클래스는 이 메서드를 override한다(RCollection이 그 예로, 배열/{items,updateMode} source의 구조 역델타를 만든다).

levelSiblingsAlong(cell, axis): SiblingPositions

siblingsAlong과 비슷하나 leaf가 아닌 같은 type/level + 같은 부모 그룹을 갖는 셀들을 수집한다. 소계/총계 셀에 대한 누적 계산 등에서 사용한다.

loadOptions(source, clear?): this

source 객체로부터 모델 설정 값을 읽어서 적용한다.

[정책] load는 source에 명시된 값을 "사용자 의도"로 그대로 보존한다. 즉 source의 값이 현재 defaults와 같더라도 _op에 그대로 기록된다. 이는 단순한 성능 최적화가 아니라 의미상 의도된 동작이다:

• defaults는 라이브러리 버전업 시 변경될 수 있다.
• load 시점에 "defaults와 같다"는 이유로 키를 버리면, 이후 defaults가 바뀌었을 때 저장본이 표현하던 값이 조용히 달라진다.
• 그대로 보존하면 사용자가 명시적으로 지정한 값이 항상 우선한다.

직렬화(saveOptions)는 어차피 defaults와 같은 값을 필터링하므로, 외부에 저장되는 결과의 크기와 내용에는 영향이 없다. 추가 비용은 _op에 약간의 메모리뿐이다. (메모리 정리나 getOption()의 "사용자 명시 여부" 의미가 필요한 특수 케이스에 한해서만 clean()을 명시적으로 호출한다.)

• updateOptions: 값이 현재 effective 값과 같으면 건너뛰고, 객체 값은 부분 병합한다.
• loadOptions(source, false): 포함된 키는 load 의미로 적용한다. 즉 defaults와 같아도 _op에 그대로 기록하고, 객체/자식 값은 부분 병합이 아니라 통째 교체한다. |

num(prop): number (opens in a new tab)

숫자 타입의 옵션 값에 특화된 prop() 메서드. prop()과 달리 숫자로 변환해서 반환한다.
해석 순서는 prop()과 동일하다(명시값(_op) → preset → 클래스 defaults).

return 숫자 타입의 옵션 값. 어디에서도 숫자를 얻지 못하면 NaN.

numAt(path): number (opens in a new tab)

점(dot) 표기법으로 경로를 지정해서 숫자 타입의 옵션 값을 반환한다.

return 경로에 해당하는 숫자 타입의 옵션 값 또는 NaN

parentColTotal(cell): number (opens in a new tab)

셀의 부모 열 그룹 소계 셀(같은 행 위치) 값.

parentRowTotal(cell): number (opens in a new tab)

셀의 부모 행 그룹 소계 셀(같은 열 위치) 값.

parentTotal(cell, baseField): number (opens in a new tab)

baseField로 지정한 dimension 그룹까지의 합계를 반환한다. parentPercent resolver의 분모로 사용되며, 사용자 정의 콜백에서도 활용할 수 있다.

preset(preset, recursive?): this

이 인스턴스의 preset(그룹/공유 기본값)을 설정한다.
preset이 설정되면 prop/num/bool/props 등 효과 값 조회 시 이 인스턴스에 명시되지 않은 옵션을 클래스 defaults보다 먼저 preset에서 가져온다 (해석 순서: _op → preset → defaults).

preset은 동일 클래스의 인스턴스를 전제한다(따라서 defaults가 동일하므로 preset의 명시값 delta만 참조해도 충분하다). 내부적으로 preset._op(명시값 delta)를 라이브로 참조하므로 원본 preset의 이후 변경이 전파된다. 직렬화(saveOptions)의 minimal-delta 기준은 여전히 클래스 defaults이며 preset은 읽기 전용 오버레이로만 작용한다.

prop(prop): PivotValueFieldOptions\[K]

옵션의 효과 값(effective value)을 반환한다.
해석 순서는 명시값(_op) → preset → 클래스 defaults이다. 이 인스턴스에 명시적으로 설정된 값이 있으면 그 값을, 없고 preset이 설정돼 있으면 preset의 명시값을, 그것도 없으면 클래스 defaults의 기본값을 반환한다.
옵션 값을 읽을 때는 options.prop 직접 접근 대신 이 메서드를 사용한다.

propAt(path): any (opens in a new tab)

점(dot) 표기법으로 경로를 지정해서 옵션의 효과 값(effective value)을 반환한다.

return 경로에 해당하는 옵션 값 또는 undefined

propIs(prop, value): boolean (opens in a new tab)

옵션 값이 특정 값과 일치하는지 여부를 반환한다.

return 일치 여부

propIsNot(prop, value): boolean (opens in a new tab)

옵션 값이 특정 값과 일치하지 않는지 여부를 반환한다.

return 불일치 여부

props(props): Pick (opens in a new tab)<OP, K>

지정한 옵션들의 효과 값(effective value)을 묶어서 반환한다.
여러 옵션을 destructuring으로 한꺼번에 읽을 때 사용한다. 각 항목의 해석 순서는 prop()과 동일하다(명시값(_op) → preset → 클래스 defaults).

const { color, radius } = this.props('color', 'radius');

removeOption(prop, render?): this

명시적으로 설정된 모델 설정 값을 제거해서 모델의 기본 값이 적용되도록 한다.
prop이 자식 모델 이름인 경우에는 해당 자식의 clearOptions(true)를 호출한다.

return 모델 객체 자신

resolveHighlight(info): ResolvedHighlight

셀에 매칭되는 highlight rule을 평가해 style + className 번들로 반환. 매칭이 없거나 highlight가 비활성이면 null. 반환 객체는 필드 내부 캐시 참조이므로 호출자는 즉시 소비해야 한다.

resolveOverlay(info, highlight?): ResolvedOverlay

셀에 적용할 heatmap/dataBar overlay 번들을 계산한다. 계산된 bar 객체는 필드 내부 캐시와 동일 참조이므로 호출자는 즉시 소비해야 한다.

highlight가 매칭된 경우 그 style의 icon이 PivotIconOverlay보다 우선한다.

rowTotal(cell): number (opens in a new tab)

셀이 속한 행 그룹 × 모든 열의 합계.

saveOption(prop): PivotValueFieldOptions[K]{ aggregate: any;baseAxis: any;baseField: any;baseItem: any;className: any;dataBar: any;dateFormat: any;formatter: any;formatterStats: any;grandStyle: any;grandTotalClass: any;headerWidth: any;heatmap: any;highlight: any;icon: any;measure: any;name: any;numberFormat: any;showAs: any;style: any;textFormat: any;totalClass: any;totalStyle: any;width: any; }

옵션 값을 읽는다.
prop()과 달리 효과 값이 아닌 명시적으로 설정된 값만 읽는다. 설정되지 않은 옵션은 undefined를 반환한다.

return 명시적으로 설정된 값 또는 undefined

saveOptions(props?, recursive?, includeDefs?, force?): Partial (opens in a new tab)<OP>

모델의 설정 값을 json 객체로 직렬화한다.

• (keyof OP)[] 배열: 해당 키들만 저장.
• 객체 ({ [K in keyof OP]?: any }): 객체에 정의된 키들만 저장. 자식 모델 키의 값으로 객체를 지정하면 해당 자식의 saveOptions(childFilter, true, includeDefs, force) 호출 시 필터로 전달된다.
• 생략 또는 빈 배열: 모든 속성 저장. | | recursive | boolean (opens in a new tab) | 자식 모델까지 재귀 저장 여부. | | includeDefs | boolean (opens in a new tab) | 기본값과 동일한 값도 저장 여부. | | force | boolean (opens in a new tab) | true이면 props로 명시된 속성은 _op나 defaults에 값이 없더라도 결과에 포함된다 (일반 옵션은 undefined, 명시된 자식은 빈 {}이라도 포함). props가 없을 때는 무시된다. |

saveTo(target, props?, recursive?, includeDefs?, force?): Partial (opens in a new tab)<OP>

모델의 설정 값을 target 객체에 복사해서 저장한다.

siblingsAlong(cell, axis): SiblingPositions

같은 부모 그룹 + 같은 measure offset을 가진 leaf 셀들의 (row, col) 위치 배열. axis가 'row'면 같은 행에서 열 방향 순회, 'column'이면 같은 열에서 행 방향 순회.

str(prop): string (opens in a new tab)

문자열 타입의 옵션 값에 특화된 prop() 메서드. prop()과 달리 문자열로 변환해서 반환한다.
해석 순서는 prop()과 동일하다(명시값(_op) → preset → 클래스 defaults).
어디에서도 값을 얻지 못하면 String(undefined) 즉 "undefined" 문자열이 반환되며, 값이 null이면 "null"이 된다. 미설정 시 기본값이 필요하면 strDef를 사용한다.

return 문자열로 변환한 옵션 값

strAt(path): string (opens in a new tab)

점(dot) 표기법으로 경로를 지정해서 문자열 타입의 옵션 값을 반환한다.
해석은 str과 동일하며, 경로가 유효하지 않으면 undefined를 반환한다.

return 경로에 해당하는 문자열 옵션 값 또는 undefined

toggleAt(path, render?): any (opens in a new tab)

boolean (opens in a new tab) 타입의 모델 설정 값을 반대 값으로 변경한다.
path 매개변수는 하위 모델의 속성 이름을 점(.)으로 구분해서 지정한다. 예를 들어, "axis.x"는 axis 모델의 x 속성을 의미한다.
render와 force 매개변수는 toggleOption과 동일하다.

toggleOption(prop, render?): this

boolean (opens in a new tab) 타입의 모델 설정 값을 반대 값으로 변경한다.
prop이 자식 모델 이름인 경우에는 아무것도 하지 않고 무시된다.

return 모델 객체 자신

updateAt(path, value, render?, force?): any (opens in a new tab)

하위 모델의 설정 값을 변경한다.
path 매개변수는 하위 모델의 속성 이름을 점(.)으로 구분해서 지정한다. 예를 들어, "axis.x"는 axis 모델의 x 속성을 의미한다.
render와 force 매개변수는 updateOption과 동일하다.

updateOption(prop, value, render?, force?): this

하나의 속성 값을 설정한다.
여러 속성들을 한꺼번에 변경할 때는 updateOptions를 사용한다. 기본적으로 이전 값과 다른 경우에만 적용된다. 특히, 속성값이 객체인 경우 객체 속성만 바뀐 경우 적용되지 않는다. 바꾸고 싶다면 force 매개변수를 true로 지정해서 호출한다.
또, prop 매개변수가 하위 모델 이름인 경우 하위 모델의 updateOptions를 호출한 것과 동일하다.

return 모델 객체 자신

updateOptions(source?, render?): this

모델 설정 값들을 변경한다.
source에 자식 모델 이름의 키가 포함되면 해당 값은 자식 모델의 updateOptions에 위임된다.

return 모델 객체 자신