PivotCellAnnotationCollection extends PivotAnnotationCollection

Properties

static defaults: ROptions readonly

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

default: undefined

addMissingOnUpdate: boolean (opens in a new tab) readonly

updateOptions 호출에서 addMissing을 생략했을 때 쓰는 지속 기본 정책. (호출 시 source의 updateMode.addMissing을 주면 그 호출에 한해 이 값을 덮어쓴다 — transient.)

• true(기본): source에 있고 매칭 안 된 원소를 새 항목으로 추가(upsert).
• false: 추가하지 않음 — 기존 항목만 수정하고 모르는 키는 무시(update-only). 외부 입력을 부분 신뢰만 하는 컬렉션이면 false로 override한다.

default: undefined

count: number (opens in a new tab) readonly

항목 개수.

default: undefined

items: Array (opens in a new tab)<T> readonly

항목 배열(읽기 전용 복사본). 변경은 add/insert/removeItemAt/clear 또는 update/load로 한다.

default: undefined

keyProp: string (opens in a new tab) readonly

항목 식별 키로 쓸 속성명. 미지정(undefined)이면 **인덱스(배열 위치)**를 키로 쓴다. updateOptions(키 매칭 merge)에서 각 원소를 기존 항목과 매칭하는 기준이다. 키가 같은 항목이 여럿이면 첫 번째가 매칭된다(키는 유일해야 한다). * [주의] 미지정(index 모드)이면 매칭이 위치 기반이므로, source items의 i번째 원소가 그대로 i번째 기존 항목에 병합된다. 따라서 호출하는 쪽이 source 원소를 기존 항목 순서에 맞춰(같은 위치에 같은 항목이 오도록) 전달할 책임이 있다. 특정 항목 하나만 부분 수정하려고 그 항목 하나만 담아 보내면 의도와 다른 앞 항목이 바뀜에 주의한다(그런 부분 수정은 keyProp를 지정하거나 경로 API로 한다).

default: undefined

removeMissingOnUpdate: boolean (opens in a new tab) readonly

updateOptions 호출에서 removeMissing을 생략했을 때 쓰는 지속 기본 정책. (호출 시 source의 updateMode.removeMissing을 주면 그 호출에 한해 이 값을 덮어쓴다 — transient.)

• false(기본): source에 없는 기존 항목을 유지(부분 패치에 안전).
• true: source에 없는 기존 항목을 삭제 → 목록 구성이 source와 일치. [주의] 이건 목록 "구성"만 맞추며 항목 내용은 여전히 부분 병합이다(full sync 아님). 항목 내용까지 통째 교체하려면 loadOptions(전체 교체)를 쓴다. 목록이 항상 "전체 목록"을 의미하는 컬렉션이면 true로 override한다(주로 keyProp가 있는 경우).

default: undefined

reorderOnUpdate: boolean (opens in a new tab) readonly

updateOptions 호출에서 reorder를 생략했을 때 쓰는 지속 기본 정책. (호출 시 source의 updateMode.reorder을 주면 그 호출에 한해 이 값을 덮어쓴다 — transient.)

• false(기본): 매칭된 항목의 기존 위치를 유지하고 새 항목은 끝에 추가.
• true: 동기화 후 최종 순서를 source 순서에 맞춤(key 모드에서만 의미, index 모드는 무시). removeMissing:true와 함께 쓰면 목록의 구성과 순서가 source와 같아진다(단, 항목 내용은 여전히 부분 병합).

default: undefined

Methods

addSource(source?, render?): PivotCellAnnotation

끝에 새 항목을 추가하고 반환한다.

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

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 모델 객체 자신

clear(render?): boolean (opens in a new tab)

모든 항목을 제거한다. 제거되는 항목들은 dispose된다.

clearOptions(recursive?, render?): this

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

return 모델 객체 자신

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

findAt(row, col): PivotCellAnnotation

(row, col) 위치에 지정된 cell annotation을 찾는다. 없으면 undefined.

get(index): PivotCellAnnotation

인덱스로 항목을 반환한다. 범위를 벗어나면 undefined.

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

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

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

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

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

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

indexOf(item): number (opens in a new tab)

항목의 인덱스를 반환한다. 없으면 -1.

init(): this

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

initAndLoad(source): this

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

insertSource(source, index, render?): PivotCellAnnotation

index 위치에 새 항목을 삽입하고 반환한다.

invertOptions(source?): RCollectionOptions

source(updateOptions에 줄 값)의 적용을 되돌리는 역 update 페이로드를 현재 상태 기준으로 만든다(ROptionable.invertOptions의 컬렉션 override). redo 적용 전에 호출해야 한다.

key 모드이고 변경이 내용/추가만이면 최소 역델타를 만든다:

• 매칭되는(내용 변경될) 항목 → source가 바꿀 속성만 현재 값으로 복원(default였던 것도 force 포함).
• source에만 있어 추가될 항목 → undo시 updateMode.remove로 삭제.

반면 삭제/재정렬/remove:'*' 가 개입하거나 index 모드면 위치 복원이 최소 델타로는 취약하므로, 현재 전체 목록을 통째로 되돌리는 안전한 역델타({ items: 현재전체, updateMode:{ remove:'*', addMissing/removeMissing/reorder } })를 만든다.

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

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): PivotCellAnnotationCollectionOptions\[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');

removeAt(index, render?): PivotCellAnnotation

index 위치의 항목을 제거하고 반환한다(범위 밖이면 undefined). 제거된 항목은 dispose하지 않는다. 소유권이 호출자에게 넘어가므로 필요시 직접 dispose한다.

removeOption(prop, render?): this

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

return 모델 객체 자신

saveOption(prop): PivotCellAnnotationCollectionOptions[K]{ items: any;keyProp: any;style: any;updateMode: any; }

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

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

saveOptions(props?, recursive?, includeDefs?, force?): any (opens in a new tab)

각 항목을 직렬화한 배열을 반환한다(항상 배열, 객체 아님). updateMode는 호출마다 주는 transient 파라미터이므로 인스턴스에 저장되지 않고 직렬화에도 포함되지 않는다.

대칭(round-trip): per-item 필터 없이 저장한 전체 배열은 loadOptions에 그대로 넣으면 원래 상태로 복원된다(coll.loadOptions(coll.saveOptions())는 항등). command stack의 undo/redo도 이 성질을 쓴다: before = parent.saveOptions(delta, true, true, true)로 변경 전 스냅샷을 잡는다. delta가 컬렉션 키의 배열이면 각 원소가 per-item 필터가 되어, 그 항목에서 지정한 속성만(force면 없는 속성도 undefined로) 스냅샷된다. key 모드면 원소를 keyProp 값으로 항목과 매칭해 매칭된 항목만(필터에 든 것만) 스냅샷하고, index 모드면 같은 위치 항목을 스냅샷한다. undo에서 이 배열을 updateOptions로 되먹이면 인덱스/키로 매칭되어 변경된 속성이 원복된다. 항목 추가/삭제처럼 개수가 바뀌는 변경의 undo는 { items, updateMode: { removeMissing: true } }처럼 그 호출에 removeMissing을 실어 보내거나 loadOptions(전체 교체)로 처리한다(updateMode는 transient라 호출 페이로드에 명시해야 한다).

props 처리:

• 컬렉션 값-형태({ items:[...], updateMode:{...} }): items 배열을 아래 배열 필터로 언랩해 처리하고 updateMode는 무시한다(save에는 동기화 정책이 무의미). updateOptions에 준 페이로드를 그대로 save 필터로 재사용하는 경우(예: undo 스냅샷)를 위해 두 API가 같은 값 문법을 받도록 한 대칭 장치다.
• 객체({ color:1, ... }): 모든 항목에 동일하게 적용되는 per-item projection 필터로 전달된다.
• 배열([ {color:1}, ... ]): per-item 필터. keyProp가 있으면(key 모드) 각 필터 원소를 keyProp 값으로 항목과 매칭해 매칭된 항목만 그 필터로 저장한다(필터에 없는 항목은 저장 안 됨, 결과는 필터 순서). 예: 항목 [{name:'a'},{name:'b'}]에 [{name:'b'}]를 주면 [{name:'b'}]만 저장된다(updateOptions의 키 매칭과 대칭). keyProp가 없으면(index 모드) 위치별 필터로, 원소 props[i]가 항목 i의 필터가 되며 배열 길이를 넘는 항목은 필터 없이 전체 저장된다. 부분 배열은 조회/표시·스냅샷용이다. update/load는 항목을 통째로 교체하므로 부분 배열을 되먹이면 나머지 속성이 사라진다(부분 수정은 개별 항목을 root로 하는 경로/도구로 한다). recursive/includeDefs/force는 각 항목 저장에 그대로 전달된다.

[키 보장] keyProp가 있으면 저장 결과 각 항목에 키 속성값을 항상 포함한다(필터로 빠지거나 default와 같아 생략될 값이어도 강제로 채운다). 저장본을 키로 다시 매칭(updateOptions) 할 수 있어야 하기 때문이다.

saveTo(_target, props?, recursive?, includeDefs?, force?): any (opens in a new tab)

컬렉션은 배열로 직렬화되므로 base의 saveTo처럼 임의의 객체 target에 속성으로 병합하는 의미가 성립하지 않는다. 따라서 target을 무시하고 saveOptions와 동일한 결과를 반환한다(두 공개 save 진입점을 일관되게 유지).

[주의] base의 saveTo는 내부적으로 _doSave를 호출하는데, RCollection은 save를 _doSave(target에 쓰는 hook)가 아니라 saveOptions(배열을 반환)에서 처리한다. (배열은 객체 target에 담을 수 없으므로 _doSave hook으로는 표현 불가.) 이 override가 없으면 collection.saveTo(t)가 base _doSave로 떨어져 빈 {}를 반환하는 비대칭이 생긴다. 부모가 자식 컬렉션을 저장할 때는 부모의 _doSave가 child.saveOptions(...)를 호출하므로 이 경로와 무관하게 정상 동작한다.

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를 **키 매칭 동기화(merge)**로 적용한다(base ROptionable의 부분 merge를 배열로 확장). source는 배열 [ ...item ]이거나 객체 { items?: [...], updateMode?: {...} }다. 그 외면 무시한다. updateMode는 이 호출에만 적용되는 transient 정책이고(저장 안 됨), items가 있으면 동기화한다.

각 원소를 키로 기존 항목과 매칭한다. 키는 keyProp이며, 미지정이면 인덱스다. (index 모드에선 매칭이 위치 기반이므로 호출하는 쪽이 source 원소를 기존 항목 순서에 맞춰 전달해야 한다.)

• 매칭됨: 그 항목에 item.updateOptions(원소)로 병합 → 지정한 속성만 갱신, 나머지 보존.
• 매칭 안 됨(새 키/범위 밖 인덱스): addMissing이면 새 항목으로 추가, 아니면 무시.
• source에 없는 기존 항목: removeMissing이면 삭제, 아니면 그대로 둔다.
• reorder이면 동기화 후 최종 순서를 source 순서에 맞춘다(key 모드 한정).
• updateMode.remove로 준 키들은 위 동기화가 끝난 뒤 추가로 삭제된다(특정 항목 직접 삭제).

동기화 축은 source의 updateMode로 주고, 생략한 축은 정책 getter (addMissingOnUpdate/removeMissingOnUpdate/reorderOnUpdate)를 따른다. 주요 조합은 RCollectionUpdateMode 참조. 기본은 upsert(수정+추가, 빠진 건 유지)로 현재 항목을 안전하게 보존한다.

어느 모드든 살아남는 항목은 merge하므로 지정 안 한 속성은 보존된다(항목을 새로 만드는 loadOptions(전체 교체, 속성 초기화)와 다른 점이다).