@univerjs-pro/sheets-pivot 0.24.0 → 0.25.0

package/lib/types/facade/f-pivot-table.d.ts

@@ -1,5 +1,5 @@
-import type { IPivotTableLabelFieldJSON, IPivotTableSortInfo, IPivotTableValueFieldJSON, IPivotTableValueFilter, IValueFilterInfoItem, PivotDataFieldDataTypeEnum, PivotDateGroupFieldDateTypeEnum, PivotSubtotalTypeEnum, PivotTableValuePositionEnum } from '@univerjs-pro/engine-pivot';
-import type { IPivotTableConfig } from '@univerjs-pro/sheets-pivot';
+import type { IPivotTableLabelFieldJSON, IPivotTableOptions, IPivotTableSortInfo, IPivotTableValueFieldJSON, IPivotTableValueFilter, IValueFilterInfoItem, PivotDataFieldDataTypeEnum, PivotDateGroupFieldDateTypeEnum, PivotSubtotalTypeEnum, PivotTableValuePositionEnum } from '@univerjs-pro/engine-pivot';
+import type { IPivotTableConfig, IPivotTableMatrixInfo, IUnitRangeNameWithSubUnitId } from '@univerjs-pro/sheets-pivot';
 import type { Injector, IRange, Nullable } from '@univerjs/core';
 import { PivotTableFiledAreaEnum } from '@univerjs-pro/engine-pivot';
 interface IPivotTableDataFieldInfo {
@@ -8,6 +8,20 @@ interface IPivotTableDataFieldInfo {
     fieldDataType: PivotDataFieldDataTypeEnum;
     displayName?: string;
 }
+export interface IPivotTableFieldSettingOptions {
+    /**
+     * The display name of the pivot table field. Leave it undefined to keep the current display name.
+     */
+    displayName?: string;
+    /**
+     * The number format code of the pivot table field. Leave it undefined to keep the current format.
+     */
+    format?: string;
+    /**
+     * The subtotal type of the value field. Leave it undefined to keep the current subtotal type.
+     */
+    subtotalType?: PivotSubtotalTypeEnum;
+}
 /**
  * The facade class for the pivot table.Which uses to setting the pivot table fields configs.
  * @hideconstructor
@@ -40,8 +54,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -51,12 +66,183 @@ export declare class FPivotTable {
      * ```
      */
     getConfig(): Nullable<IPivotTableConfig>;
+    /**
+     * @description Get the pivot table id.
+     * @returns {string} The pivot table id.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * const pivotTableId = fPivotTable?.getId();
+     * console.log(pivotTableId);
+     * ```
+     */
+    getId(): string;
+    /**
+     * @description Get the source range info of the pivot table.
+     * @typedef SourceInfo
+     * @property {string} unitId The unit id of the source workbook.
+     * @property {string} subUnitId The sheet id of the source worksheet.
+     * @property {string} sheetName The source worksheet name.
+     * @property {IRange} range The source data range.
+     * @returns {SourceInfo|undefined} The source range info or undefined if the pivot table no longer exists.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * const sourceRangeInfo = fPivotTable?.getSourceRangeInfo();
+     * console.log(sourceRangeInfo?.range);
+     * ```
+     */
+    getSourceRangeInfo(): IUnitRangeNameWithSubUnitId | undefined;
+    /**
+     * @description Get the target cell info of the pivot table.
+     * @typedef TargetCellInfo
+     * @property {string} unitId The unit id of the target workbook.
+     * @property {string} subUnitId The sheet id of the target worksheet.
+     * @property {number} row The target row index.
+     * @property {number} col The target column index.
+     * @property {string} [sheetName] The target worksheet name if it is stored in the config.
+     * @returns {TargetCellInfo|undefined} The target cell info or undefined if the pivot table no longer exists.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * const targetCellInfo = fPivotTable?.getTargetCellInfo();
+     * console.log(targetCellInfo?.row, targetCellInfo?.col);
+     * ```
+     */
+    getTargetCellInfo(): IPivotTableConfig['targetCellInfo'] | undefined;
+    /**
+     * @description Get the display options of the pivot table.
+     * @typedef PivotTableOptions
+     * @property {number} [pageWrap] The max page fields count before wrapping to the next line.
+     * @property {boolean} [pageOverThenDown] Whether page fields are laid out over then down.
+     * @property {boolean} [showColHeaders] Whether to show column headers.
+     * @property {boolean} [showColStripes] Whether to show column stripes.
+     * @property {boolean} [showLastColumn] Whether to highlight the last column.
+     * @property {boolean} [showRowHeaders] Whether to show row headers.
+     * @property {boolean} [showRowStripes] Whether to show row stripes.
+     * @property {boolean} [mergeItems] Whether to merge repeated header items.
+     * @property {boolean} [repeatRowLabels] Whether to repeat row labels.
+     * @property {boolean} [showRowSubtotal] Whether to show row subtotals.
+     * @property {boolean} [showRowGrandTotal] Whether to show row grand totals.
+     * @property {boolean} [showColSubtotal] Whether to show column subtotals.
+     * @property {boolean} [showColGrandTotal] Whether to show column grand totals.
+     * @returns {PivotTableOptions|undefined} The display options or undefined if the pivot table no longer exists.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * const options = fPivotTable?.getOptions();
+     * console.log(options?.showRowGrandTotal);
+     * ```
+     */
+    getOptions(): IPivotTableOptions | undefined;
+    /**
+     * @description Get the pivot table matrix cache generated by the last render.
+     * @returns {IPivotTableMatrixInfo|undefined} The matrix cache or undefined if the pivot table has not rendered.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * const matrixInfo = fPivotTable?.getPivotTableMatrixInfo();
+     * console.log(matrixInfo?.matrix);
+     * ```
+     */
+    getPivotTableMatrixInfo(): IPivotTableMatrixInfo | undefined;
     /**
      * @description Set the pivot table fields config.It will add fields to the pivot table from provided config.Before setting the fields config, you should ensure the pivot table is empty to avoid the conflict.
      * @param {IPivotTableConfig['fieldsConfig']} config The pivot table fields config.
      * @returns {Promise<boolean>} Whether the pivot table fields config is set successfully.
      */
     setFieldsConfig(config: IPivotTableConfig['fieldsConfig']): Promise<boolean>;
+    /**
+     * @description Set the display options of the pivot table through command. It keeps undo/redo, collaboration and render update paths consistent with panel operations.
+     * @param {PivotTableOptions} options The display options to set.
+     * @typedef PivotTableOptions
+     * @property {number} [pageWrap] The max page fields count before wrapping to the next line.
+     * @property {boolean} [pageOverThenDown] Whether page fields are laid out over then down.
+     * @property {boolean} [showColHeaders] Whether to show column headers.
+     * @property {boolean} [showColStripes] Whether to show column stripes.
+     * @property {boolean} [showLastColumn] Whether to highlight the last column.
+     * @property {boolean} [showRowHeaders] Whether to show row headers.
+     * @property {boolean} [showRowStripes] Whether to show row stripes.
+     * @property {boolean} [mergeItems] Whether to merge repeated header items.
+     * @property {boolean} [repeatRowLabels] Whether to repeat row labels.
+     * @property {boolean} [showRowSubtotal] Whether to show row subtotals.
+     * @property {boolean} [showRowGrandTotal] Whether to show row grand totals.
+     * @property {boolean} [showColSubtotal] Whether to show column subtotals.
+     * @property {boolean} [showColGrandTotal] Whether to show column grand totals.
+     * @returns {Promise<boolean>} Whether the pivot table options are set successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(fWorkbook.getId(), subUnitId, 0, 8);
+     * await fPivotTable?.setOptions({
+     *   repeatRowLabels: true,
+     *   showRowGrandTotal: false,
+     *   showColGrandTotal: true
+     * });
+     * ```
+     */
+    setOptions(options: IPivotTableOptions): Promise<boolean>;
+    /**
+     * @description Update the source range of the pivot table through command.
+     * @param {SourceInfo} dataRangeInfo The new source data range info.
+     * @typedef SourceInfo
+     * @property {string} unitId The unit id of the source workbook.
+     * @property {string} subUnitId The sheet id of the source worksheet.
+     * @property {string} sheetName The source worksheet name.
+     * @property {IRange} range The new source data range.
+     * @returns {Promise<boolean>} Whether the source range is updated successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const unitId = fWorkbook.getId();
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
+     * await fPivotTable?.setSourceRange({
+     *   unitId,
+     *   subUnitId,
+     *   sheetName: fWorksheet.getSheetName(),
+     *   range: {
+     *     startRow: 0,
+     *     endRow: 100,
+     *     startColumn: 0,
+     *     endColumn: 6
+     *   }
+     * });
+     * ```
+     */
+    setSourceRange(dataRangeInfo: IUnitRangeNameWithSubUnitId): Promise<boolean>;
     /**
      * @description Clear the fields by provided field area or clear all fields.
      * @param {PivotTableFiledAreaEnum} [resetArea] The area of the field to reset or undefined to reset all fields.
@@ -71,8 +257,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -90,8 +277,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -115,7 +303,8 @@ export declare class FPivotTable {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -135,8 +324,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -156,8 +346,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -177,8 +368,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -195,8 +387,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -215,8 +408,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -238,8 +432,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -260,8 +455,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -286,8 +482,9 @@ export declare class FPivotTable {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -311,8 +508,9 @@ export declare class FPivotTable {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -333,8 +531,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -347,6 +546,35 @@ export declare class FPivotTable {
      * ```
      */
     setSubtotalType(fieldId: string, subtotalType: PivotSubtotalTypeEnum): Promise<boolean>;
+    /**
+     * @description Set the pivot table field display name, number format or subtotal type through command.
+     * @param {string} tableFieldId - The pivot table field id.
+     * @param {PivotTableFieldSettingOptions} setting - The field setting options.
+     * @typedef PivotTableFieldSettingOptions
+     * @property {string} [displayName] The display name of the pivot table field. Leave it undefined to keep the current display name.
+     * @property {string} [format] The number format code of the pivot table field. Leave it undefined to keep the current format.
+     * @property {PivotSubtotalTypeEnum} [subtotalType] The subtotal type of the value field. Leave it undefined to keep the current subtotal type.
+     * @returns {Promise<boolean>} Whether the pivot table field setting is updated successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const unitId = fWorkbook.getId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
+     * const valueId = fPivotTable?.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Value)[0];
+     * if (fPivotTable && valueId) {
+     *   await fPivotTable.setFieldSetting(valueId, {
+     *     displayName: 'Revenue',
+     *     format: '$#,##0',
+     *     subtotalType: univerAPI.Enum.PivotSubtotalTypeEnum.sum
+     *   });
+     * }
+     * ```
+     */
+    setFieldSetting(tableFieldId: string, setting: IPivotTableFieldSettingOptions): Promise<boolean>;
     /**
      * @description Set the pivot table sort info.
      * @param {string} tableFieldId - The field id of the sort.
@@ -359,8 +587,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -384,8 +613,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -412,8 +642,9 @@ export declare class FPivotTable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -432,7 +663,27 @@ export declare class FPivotTable {
      * }
      * ```
      */
-    setValueFilter(fieldId: string, filterInfo: Omit<IPivotTableValueFilter, 'type'>): Promise<boolean>;
+    setValueFilter(fieldId: string, filterInfo?: Omit<IPivotTableValueFilter, 'type'>): Promise<boolean>;
+    /**
+     * @description Clear the value filter of the pivot table field through command.
+     * @param {string} fieldId - The field id of the value filter.
+     * @returns {Promise<boolean>} Whether the value filter is cleared successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const unitId = fWorkbook.getId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
+     * const rowId = fPivotTable?.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Row)[0];
+     * if (fPivotTable && rowId) {
+     *   await fPivotTable.clearValueFilter(rowId);
+     * }
+     * ```
+     */
+    clearValueFilter(fieldId: string): Promise<boolean>;
     /**
      * @description Rename the pivot table field.
      * @param {string} fieldId - The field id.
@@ -443,8 +694,9 @@ export declare class FPivotTable {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -467,8 +719,9 @@ export declare class FPivotTable {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subSheetName = fSheet.getSheetName();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subSheetName = fWorksheet.getSheetName();
      * // Here we assume that you already have a pivot table in cell A8 of the table.
      * // If not, please call fWorkbook.addPivotTable() according to the documentation.
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
@@ -490,8 +743,9 @@ export declare class FPivotTable {
      * // and drag the date dimension to the row or column
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * const pivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 0);
      * // Here we assume that the field index of the date type is 0
      * await pivotTable.addField(0, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
@@ -503,5 +757,47 @@ export declare class FPivotTable {
      * ```
      */
     setDateGroupType(tableFieldId: string, dateType: PivotDateGroupFieldDateTypeEnum): Promise<boolean>;
+    /**
+     * @description Collapse or expand a pivot table item by the cell position through command.
+     * @param {number} row - The row index of the pivot item cell.
+     * @param {number} col - The column index of the pivot item cell.
+     * @param {boolean} collapse - Whether to collapse the pivot item. True means collapse, false means expand.
+     * @returns {Promise<boolean>} Whether the pivot item collapse state is updated successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const unitId = fWorkbook.getId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
+     * // the cell must be a cell has collapse or expand button, otherwise the command will fail, and the cell (2,8) is just an example, you can pass any cell in the pivot table which has collapse or expand button.
+     * await fPivotTable?.setCellCollapse(2, 8, true);
+     * ```
+     */
+    setCellCollapse(row: number, col: number, collapse: boolean): Promise<boolean>;
+    /**
+     * @description Drill down a pivot value cell through command and create a sheet with the related source records.
+     * @param {number} row - The row index of the pivot value cell.
+     * @param {number} col - The column index of the pivot value cell.
+     * @returns {Promise<boolean>} Whether the drill down sheet is created successfully.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const unitId = fWorkbook.getId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
+     * await fPivotTable?.drillDown(5, 10);
+     * ```
+     */
+    drillDown(row: number, col: number): Promise<boolean>;
+    private _getPivotPanelTableFieldInfo;
+    private _getPivotPanelSourceFieldInfo;
+    private _isDataFieldUsed;
+    private _isCellInCurrentPivotTable;
 }
 export {};

package/lib/types/facade/f-workbook.d.ts

@@ -21,16 +21,17 @@ export interface IFWorkbookSheetsPivotMixin {
      * @param {SourceInfo} sourceInfo The source data range info of the pivot table.
      * @param {PositionType} positionType whether new a sheet or insert a pivot table to the existing sheet.
      * @param {AnchorCellInfo} anchorCellInfo The target cell info of the pivot table.
-     * @returns {string|undefined} The added pivot table id.
+     * @returns {FPivotTable|undefined} The added pivot table instance.
      *
      * @example
      * ```typescript
      * // should ensure the sheet range A1:G9 is not empty
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
-     * const sheetName = fSheet.getSheetName();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
+     * const sheetName = fWorksheet.getSheetName();
      * const sourceInfo = {
      *   unitId,
      *   subUnitId,
@@ -48,17 +49,9 @@ export interface IFWorkbookSheetsPivotMixin {
      *   row: 0,
      *   col: 8
      * };
-     * const fPivotTable = await fWorkbook.addPivotTable(sourceInfo, 'existing', anchorCellInfo);
-     * const pivotTableId = fPivotTable.getPivotTableId();
-     * let hasAdded = false;
-     * // the addPivotTable is async, you can add pivot fields after the pivot table is added
-     * univerAPI.addEvent(univerAPI.Event.PivotTableRendered, (params) => {
-     *   if (!hasAdded && params.pivotTableId === pivotTableId) {
-     *     fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
-     *     fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0);
-     *     hasAdded = true;
-     *   }
-     * });
+     * const fPivotTable = await fWorkbook.addPivotTable(sourceInfo, univerAPI.Enum.PositionTypeEnum.Existing, anchorCellInfo);
+     * await fPivotTable?.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
+     * await fPivotTable?.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0);
      * ```
      */
     addPivotTable(sourceInfo: IUnitRangeName & {
@@ -76,8 +69,9 @@ export interface IFWorkbookSheetsPivotMixin {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const unitId = fWorkbook.getId();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const subUnitId = fSheet.getSheetId();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const subUnitId = fWorksheet.getSheetId();
      * const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
      * if(fPivotTable) {
      *   fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
@@ -106,6 +100,7 @@ export declare class FWorkbookSheetsPivotMixin extends FWorkbook implements IFWo
     addPivotTable(sourceInfo: IUnitRangeName & {
         subUnitId: string;
     }, positionType: PositionType, anchorCellInfo: IPivotCellPositionInfo): Promise<FPivotTable | undefined>;
+    private _waitForPivotTableReady;
     getPivotTableByCell(unitId: string, subUnitId: string, row: number, col: number): FPivotTable | undefined;
     getPivotTableById(pivotTableId: string): FPivotTable | undefined;
 }

package/lib/types/facade/f-worksheet.d.ts

@@ -13,8 +13,9 @@ export interface IFWorksheetPivotMixin {
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const pivotTable = fSheet.getPivotTableByCell(1, 1);
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const pivotTable = fWorksheet.getPivotTableByCell(1, 1);
      * if(pivotTable) {
      *   pivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
      * }

package/lib/types/index.d.ts

@@ -11,6 +11,8 @@ export { PivotDrillDownCommand } from './commands/command/pivot-drill-down.comma
 export type { IPivotDrillDownCommandParams } from './commands/command/pivot-drill-down.command';
 export { RemovePivotFieldCommand } from './commands/command/remove-pivot-field.command';
 export type { IRemovePivotFieldCommandParams } from './commands/command/remove-pivot-field.command';
+export { RemovePivotTableCommand } from './commands/command/remove-pivot-table.command';
+export type { IRemovePivotTableCommandParams } from './commands/command/remove-pivot-table.command';
 export { ResetPivotFieldsConfigCommand } from './commands/command/reset-pivot-fields-config.command';
 export type { IResetPivotFieldsConfigCommandParams } from './commands/command/reset-pivot-fields-config.command';
 export { SetPivotCollapseCommand } from './commands/command/set-pivot-collapse.command';
@@ -53,7 +55,7 @@ export { UpdateValuePositionMutation } from './commands/mutations/update-value-p
 export { PivotTableViewDirtyMarkOperation } from './commands/operations/pivot-table-dirty-view.operation';
 export { BLANK_ROW_COUNT, getAdjustRangesPosition, PivotDisplayDataType, PositionType, SHEET_PIVOT_TABLE_PLUGIN } from './const/const';
 export { DEFAULT_PIVOT_NUMBER, defaultThemeStyle, transFromCellValue } from './const/const';
-export type { IAddPivotFieldMutationParams, IAddPivotTableMutationParams, IPivotCellPositionInfo, IPivotPanelDataInfo, IPivotPanelSourceList, IPivotPanelTableListItemBase, IPivotRangesInfo, IPivotRenderCache, IPivotTableAddedEventParams, IPivotTableCellData, IPivotTableConfig, IPivotTableMovedEventParams, IPivotTableRemovedEventParams, IPivotTableRenderedEventParams, IPivotTableUpdatedEventParams, IPivotViewUpdateInfo, IRangePosition, IRemovePivotFieldMutationParams, IRemovePivotTableMutationParams, IRenamePivotFieldMutationParams, ISetPivotCollapseMutation, ISetPivotFieldFormatMutationParams, ISetPivotFilterMutationParams, ISetPivotOptionMutationParams, ISetPivotPositionMutationParams, ISetPivotSortMutationParams, ISetPivotSubtotalTypeMutationParams, ISetPivotValueFilterMutationParams, IUnitRangeNameWithSubUnitId, IUpdateFieldPositionMutationParams, IUpdatePivotFieldSourceInfoMutationParams, IUpdateValuePositionMutationParams, } from './const/type';
+export type { IAddPivotFieldMutationParams, IAddPivotTableMutationParams, IPivotCellPositionInfo, IPivotPanelDataInfo, IPivotPanelSourceList, IPivotPanelTableListItemBase, IPivotRangesInfo, IPivotRenderCache, IPivotTableAddedEventParams, IPivotTableCellData, IPivotTableConfig, IPivotTableMatrixInfo, IPivotTableMovedEventParams, IPivotTableRemovedEventParams, IPivotTableRenderedEventParams, IPivotTableUpdatedEventParams, IPivotViewUpdateInfo, IRangePosition, IRemovePivotFieldMutationParams, IRemovePivotTableMutationParams, IRenamePivotFieldMutationParams, ISetPivotCollapseMutation, ISetPivotFieldFormatMutationParams, ISetPivotFilterMutationParams, ISetPivotOptionMutationParams, ISetPivotPositionMutationParams, ISetPivotSortMutationParams, ISetPivotSubtotalTypeMutationParams, ISetPivotValueFilterMutationParams, IUnitRangeNameWithSubUnitId, IUpdateFieldPositionMutationParams, IUpdatePivotFieldSourceInfoMutationParams, IUpdateValuePositionMutationParams, } from './const/type';
 export { PivotTableOperationEnum } from './const/type';
 export { SHEETS_PIVOT_PLUGIN_CONFIG_KEY } from './controllers/config.schema';
 export type { IUniverSheetsPivotConfig } from './controllers/config.schema';

package/lib/types/locale/ar-SA.d.ts

@@ -0,0 +1,3 @@
+import type enUS from './en-US';
+declare const locale: typeof enUS;
+export default locale;