原生樞紐分析輸出、交叉篩選查詢與缺漏成員

原生快取工作表輸出

function TXLSXWorkbook.MaterializeNativePivotTable(
  ATable: TXLSPivotTable): Integer;
function TXLSXWorkbook.MaterializeNativePivotTable(
  ATable: TXLSPivotTable; AAdoptExisting: Boolean): Integer;

這個操作會先暫存完整的原生精簡、表格或大綱報表格線，連同其 location、rowItems、colItems 與資料軸中繼資料，然後才一起提交工作表值與輸出擁有權；成功回傳 1，狀態不受支援或有碰撞時回傳 -1 並附診斷

受支援的非空本機檢視保留當前篩選、精確的快取成員識別、普通階層、受支援的分組定義域、預設或自訂小計，以及任一受支援的資料軸；原生格線使用原始彙總值，而不是重新組合顯示的平均值或其他不可加總的結果

既有的儲存格物件與格式繼續可用，縮小或搬移報表只清空未變更的先前持有值；被編輯過的輸出、來源重疊、合併、公式、陣列與其他報表都會在修改前被拒

已匯入的純量輸出需要以 AAdoptExisting=True 明確收養；後續更新使用持久化的逐儲存格擁有權，儲存與重新開啟之後依然有效

這個操作讀取當前快取記錄，不重新整理來源資料，也不重算公式；Cache.RefreshOnLoad=False 是合理的，因為工作表現在已有實際暫存的原生結果

呼叫端的記錄篩選回呼參與分離預覽，但在 OOXML 中沒有表示法；Excel 的明確原生重新整理無法重現任意的回呼限制，而受支援且持久化的手動與交叉分析篩選器篩選則保留其傳輸表示

受支援的 SUM 計算快取欄位與快取持有的計算項目，使用原生計算樞紐分析欄位與快取持有的項目所描述的內容加總契約；自訂成員標題與不受支援的版面組合會被明確拒絕，而受支援的產生原始版面保留無關 XML 與當前成員遮罩

TryXLSXMakeNativePivotLayout(const Xml: WideString; Table: TXLSPivotTable; AWriter: TlxPivotResultWriter; out ResultXml, Reason: WideString): Boolean 是 lxPivotXml 中較底層的暫存版面輔助函式

其寫入器以列主序收到整個報表矩形，包括空白儲存格，偏移相對資料表錨點且以零為基底；XML 與格線前置檢查在第一次回呼之前完成，但若回呼擲出例外，呼叫端已寫入的內容無法回復

活頁簿外觀層提供分離的擷取寫入器來做交易式儲存格更新；暫存預覽與原生 Variant 格線合計以 4194304 儲存格為限

原生預覽路徑可以透過 TXLSPivotTable.MakePreview 的選用 AUseNativeGrandTotals 參數要求原生總計方向；既有的單寫入器與版面寫入器呼叫保留其先前行為

版面與重複標籤

在具體化之前，先設定報表與每個列欄位的 Compact 與 Outline；表格欄位兩個旗標都是 False，大綱欄位是 Compact=False 加 Outline=True，精簡欄位則兩個都是 True

property TXLSPivotField.RepeatLabels: Boolean;

RepeatLabels 預設 False，隨欄位獨立複製，讀寫原生 x14:pivotField fillDownLabels 擴充；它在表格與大綱輸出中重複上層標籤，對精簡與大綱旗標同時開啟的欄位沒有作用

每個獨立的列欄位拿到自己的實體欄，相鄰的精簡大綱欄位共用一個標籤欄；列上的多個量值跟隨 CompactData，欄上的多個量值保留獨立的資料標題與總計

預設的表格小計出現在群組下方；大綱的 SubtotalTop 選擇頂端或底端位置，而列上的量值使用群組下方獨立的彙總列，並保留各量值的標題

原生快取輸出把缺席的列欄交叉點留白，並保留實際的數值零；普通的 Make 與未開原生選項的預覽保留先前的空結果行為

不活動與量值欄位會在暫存原生中繼資料中繼承報表版面，讓 Excel 的明確重新整理保留正確的欄位與資料標題；這個操作保留現用欄位設定與既有的擁有權檢查

已匯入的重複標籤擴充接受命名空間別名，包括擴充元素本身上的宣告；未知且無關的 XML 仍由原生具體化路徑保留

分組成員、軸順序與自訂小計

原生輸出支援完整的數值範圍群組、日期群組，以及由快取既有具型別分組中繼資料表示的手動成員群組；產生的標題保留精確的已匯入 GroupItemLabels，包括 Unicode 與本地化的日期標題

分組在分離的快取上評估，保留現用快取的記錄、共用項目控制代碼與群組識別；無效邊界、零區間、不完整定義域或不受支援的群組項目值型別，都會在工作表輸出改變之前被拒

既有的以零為基底 TXLSPivotField.Position 決定穩定的原生列欄軸順序；相同位置保留撰寫的欄位順序，因此用預設位置新建立的欄位保留其先前的排序

已匯入的原生年/月與父系或手動成員階層保留其明確軸序，而快取欄位索引、檢視欄位索引與顯示計算的基底識別不變；手動群組遵循明確的樞紐項目順序，不對群組標籤或快取索引排序

自訂列小計支援 xlpsSum、xlpsCount、xlpsAverage、xlpsMax、xlpsMin、xlpsProduct、xlpsCountNumbers、xlpsStdDev、xlpsStdDevP、xlpsVar 與 xlpsVarP，包括多選函式、表格或大綱欄位，以及列上的量值

每個函式在自己的小計範圍內彙總原始來源記錄；其暫存列中繼資料獨立標識選定的函式，保留 Excel 對不可加總計算與空結果或錯誤結果的明確重新整理行為

已匯入的自訂小計選取會排除隱含的自動小計，即使原生 XML 中沒有 defaultSubtotal 也一樣；應用程式不應把 xlpsDefault 與自訂函式混用，這種有歧義的具型別請求會在修改前被拒

多層欄位加小計、不受支援的精簡資料軸組合、摺疊成員與自訂標題，都在這份原生輸出契約之外；計算欄位與項目有自己更窄的 SUM 與成員識別要求，原始保留也不代表支援重新計算或具體化某個功能

儲存、重新開啟與重新具體化保留受支援的分組、軸序與小計識別；已匯入的原生檢視與獨立複製的具型別快取，也已針對 Excel 驗證過初次開啟與明確重新整理兩種情境

原生顯示計算

呼叫 MaterializeNativePivotTable 之前，先設定每個普通資料欄位的 ShowDataAs 或 ExtendedShowDataAs；基本與延伸顯示模式互斥

基本模式包括差異、佔基準項目百分比、差異百分比、累加總計、佔列欄或總計百分比與索引；延伸模式包括父列、父欄與指定父系百分比、累積百分比，以及遞增或遞減的密集排名

BaseField 是比較、累加總計、指定父系百分比與排名所用的以零為基底樞紐欄位索引；比較使用以零為基底的 BaseItem 位置，或以 xlPivotBaseItemPrevious 與 xlPivotBaseItemNext 表示有效顯示順序中相鄰的可見成員

父列與父欄百分比直接選對應的最內層軸欄位，不使用 BaseField；對應軸缺席時這些結果留白

簡單百分比以相關範圍內的原始彙總為分母，包括不可加總的平均值；累積百分比把顯示的成員彙總相加，內層基底欄位使用原始軸總計，外層基底欄位則使用其相符其餘成員的和，因此平均值可能超過 100%

原生排名計算不同的前段彙總值，比較則保留 Excel 對缺席交叉點、缺失基底、零除數與前一個或下一個邊界的空白與錯誤行為；簡單百分比把缺席的分子當成零

總計使用所選模式的原生語意，包括比較或累加軸上的空白總計；變更顯示模式仍保留報表的交易式擁有權、碰撞與預算檢查

儲存與重新開啟保留所選的基本或延伸模式與基底識別，暫存的原生中繼資料支援明確的 Excel 重新整理；普通的 Make 與未開原生選項的預覽保留其既有計算契約

交叉分析篩選器交叉篩選可用性

property TXLSXSlicerCache.ItemHasData[Index: Integer]: Boolean;

這個唯讀查詢評估當前受支援的非 OLAP 快取記錄，忽略這個交叉分析篩選器自己的選取，並保留其他交叉分析篩選器選取、手動篩選、呼叫端述詞與適用的彙總篩選

可用性是各連接檢視的聯集；沒有相符記錄的歷史成員沒有資料，空白的量值沒有資料，而非空的文字、布林、零、錯誤與日期量值在已驗證的原生契約下都算有資料

查詢使用讀取租約與分離的記錄預覽，保留現用控制代碼與選取，並遵守 FormulaArrayMemoryLimit；回呼失敗、重入、無效繫結或不受支援的彙總計算成員會在未提交現用變更的情況下擲出

查詢可用性不會重新整理快取、重算公式、執行檔案 I/O，也不更新序列化的原生無資料旗標；應用程式不應從這個唯讀操作推斷原生 UI 狀態

TlxPivotRecordWriter = procedure(ATable: TXLSPivotTable;
  ARecordIndex: Integer) of object;
function TXLSPivotTable.MakeRecordPreview(AWriter: TlxPivotRecordWriter;
  AFilterOwner: TObject = nil; AFilter: TlxPivotRecordFilter = nil): Integer;

進階記錄回呼在受支援的簡單與彙總篩選之後，收到分離預覽與以零為基底的記錄索引；EvaluationSourceTable 保留原始檢視身分，回傳值是輸出的記錄數

替換的篩選只取代所提供擁有者註冊的回呼；其他擁有者與外部述詞仍然有效，而非 nil 的替換回呼要求非 nil 的擁有者

明確的歷史成員清除

Removed := Workbook.PurgePivotCacheMissingItems(
  Pivot.CacheId, 0);
if Removed < 0 then
  raise Exception.Create('The cache member purge was rejected');

TXLSXWorkbook.PurgePivotCacheMissingItems(ACacheId: Integer; ARetainMissingItemsPerField: Integer = 0): Integer 在完整驗證並重新映射受支援的連結檢視與交叉分析篩選器之後，移除未使用的成員

它回傳所有欄位移除的共用項目總數，成功但無事可做時回傳零，被拒時回傳 -1 加診斷碼 1402；當前記錄參照的每個成員都保留，另外每個欄位最多保留指定數量的未使用成員，選擇標準是原始共用項目索引最大者

保留的成員維持原始相對順序與物件控制代碼，邏輯索引則壓縮；連結的欄位與項目控制代碼、手動隱藏與明細旗標、活動的頁面或比較成員，以及交叉分析篩選器選取都保留其身分

定義域旗標與邊界從保留的定義域重新計算；受支援的已匯入壓縮列欄與頁面位置被明確重新映射，總計虛擬參照與資料虛擬欄位序數則保持不變

支援普通的完整本機工作表快取；分組、計算、成員屬性、OLAP、外部、不完整或有歧義的快取，以及不受支援的不透明識別中繼資料都會在修改前被拒

移除活動的頁面或比較成員、整個選取的交叉分析篩選器子集，或先前非空的有效交叉點，都會以原子方式拒絕；具型別重建過程會遺失的原始成員屬性同樣拒絕

已知的具體化擁有權擴充保持不變，因為其座標與具型別值 token 不含快取成員索引；無關的不透明擴充則不假設安全

清除不會重新整理來源資料、不改寫工作表報表儲存格、不呼叫記錄回呼，也不自動套用 MissingItemsLimit 中繼資料；除非明確要求這個操作，重新整理仍然只附加不刪除

進階清除協調

TXLSPivotCache._PrepareMissingItemPurge 回傳不透明的 TXLSPivotCachePurgePlan；應用程式平常應使用活頁簿外觀層，讓每個連結檢視與交叉分析篩選器都被納入

MapItem 與 RemainingItemCount 檢視快取重新映射，StagePivotField 註冊一個連結欄位並回傳其暫存索引，MapViewItemPosition 檢視該欄位的傳輸位置映射；被移除的成員映射到 -1，RemovedCount 回報移除總數

Validate 檢查原始結構描述、記錄、欄位與項目的擁有權識別，以及暫存的檢視選取；Commit 再次驗證，並在第一次現用交換之後，不做配置也不呼叫回呼地轉移準備好的擁有權

計畫擁有分離快照，把可變的暫存快取保持私有，且絕不擁有原始快取或檢視物件；在計畫的 Destroy 釋放暫存之前，讓那些原始物件保持存活，且每個計畫只提交一次

被拒的欄位暫存會回復該階段，讓計畫可以重用；準備完成後不受支援的修改會在提交前被拒