import type { ChartAppearanceTarget, ChartLegendSpec, ChartSubtitleSpec, ChartTitleSpec, IChartAppearanceSpec, InvalidValueType } from '@univerjs-pro/engine-chart'; import type { IPivotTableLabelFieldJSON, IPivotTableShowDataAsInfo, IPivotTableSnapshot, IPivotTableSortInfo, IPivotTableValueFieldJSON, IPivotTableValueFilter, IValueFilterInfoItem, PivotDateGroupFieldDateTypeEnum } from '@univerjs-pro/engine-pivot'; import type { IPivotChartControls, IPivotChartPivotTableReference, PivotChartTypeString } from '@univerjs-pro/pivot-chart'; import type { ChartAnchorSpec } from '@univerjs-pro/sheets-chart'; import type { IUnitRangeNameWithSubUnitId } from '@univerjs-pro/sheets-pivot'; import type { IPivotChartDataFieldInfo, IPivotChartFieldSettingOptions, ISheetPivotChartInfo } from '@univerjs-pro/sheets-pivot-chart'; import type { DeepReadonly, Injector } from '@univerjs/core'; import type { FBoundSheetPivotChartBuilderOf } from './f-pivot-chart-builder'; import { PivotTableFiledAreaEnum, PivotTableValuePositionEnum } from '@univerjs-pro/engine-pivot'; import { PivotChartSourceKind } from '@univerjs-pro/pivot-chart'; import { FPivotTable } from '@univerjs-pro/sheets-pivot/facade'; import { FBase } from '@univerjs/core/facade'; /** * A live PivotChart hosted by a worksheet. * * The Chart visual and Drawing placement belong to this PivotChart. The effective Pivot report * belongs either to this chart (range source) or to the referenced PivotTable (linked source). * Linked PivotCharts therefore share field, filter, sort, Show Values As, and collapse changes. * * @example Create an owned PivotChart * ```ts * import '@univerjs-pro/sheets-pivot-chart/facade'; * * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getSheetByName('Sales'); * const info = fWorksheet * .newPivotChart(univerAPI.Enum.ChartTypeString.Column) * .setSource('A1:G100') * .setPosition('J2') * .setSize(640, 360) * .setTitle('Sales by region') * .build(); * const fPivotChart = await fWorksheet.insertPivotChart(info); * const sourceFields = fPivotChart.getSourceFieldsInfo(); * await fPivotChart.addField(sourceFields[0].id, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0); * await fPivotChart.addField(sourceFields[5].id, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0); * ``` * * @example Link multiple PivotCharts to one PivotTable * ```ts * import '@univerjs-pro/sheets-pivot-chart/facade'; * * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getSheetByName('Dashboard'); * const fPivotTable = fWorkbook.getPivotTableById('pivot-table-1'); * if (!fWorksheet || !fPivotTable) throw new Error('Pivot source is unavailable.'); * * const first = await fWorksheet.insertPivotChart( * fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Column).setPosition('A1').build() * ); * const second = await fWorksheet.insertPivotChart( * fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Line).setPosition('J1').build() * ); * const rowFieldId = first.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Row)[0]; * await first.setLabelSort(rowFieldId, { type: univerAPI.Enum.PivotDataFieldSortOperatorEnum.ascending }); * console.log(second.getFieldsConfig()); // Reads the same PivotTable-owned report. * ``` * * @example Configure Show Values As and a value filter * ```ts * const rowFieldId = fPivotChart.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Row)[0]; * const valueFieldId = fPivotChart.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Value)[0]; * await fPivotChart.setShowDataAs(valueFieldId, { * type: univerAPI.Enum.PivotShowAsTypeEnum.percentOfGrandTotal, * baseFieldId: '', * baseItem: '', * }); * await fPivotChart.setValueFilter(rowFieldId, { * operator: univerAPI.Enum.PivotFilterOperatorEnum.valueGreaterThan, * expected: 1000, * valueFieldId, * }); * ``` * * @example Handle an unavailable linked PivotTable * ```ts * if (fPivotChart.isLinkedToPivotTable() && !fPivotChart.getPivotTable()) { * // Report writes resolve to false until the same PivotTable ID becomes available again. * console.log(await fPivotChart.resetFields()); * // Per-chart visual changes remain available. * fPivotChart.setTheme('default'); * } * ``` * * @hideconstructor */ export declare class FSheetPivotChart extends FBase { readonly unitId: string; readonly subUnitId: string; readonly pivotChartId: string; protected readonly _injector: Injector; constructor(unitId: string, subUnitId: string, pivotChartId: string, _injector: Injector); /** * Returns the stable identifier of this PivotChart. * @returns {string} The PivotChart identifier. */ getId(): string; /** * Returns the current PivotChart type. * @returns {PivotChartTypeString} The supported Chart type. */ getType(): PivotChartTypeString; /** * Returns detached information that can be inspected, copied, or passed to {@link update}. * @returns {DeepReadonly} A defensive PivotChart snapshot. */ getInfo(): DeepReadonly; /** * Creates a detached, source-locked Builder prefilled from this PivotChart. * @returns {FBoundSheetPivotChartBuilderOf} A source-locked Builder. */ toBuilder(): FBoundSheetPivotChartBuilderOf; /** * Creates a detached, source-locked Builder converted to another supported Chart type. * @param {T} type The target supported Chart type. * @returns {FBoundSheetPivotChartBuilderOf} A source-locked Builder for the target type. */ toBuilder(type: T): FBoundSheetPivotChartBuilderOf; /** * Atomically updates visual configuration, controls, name, and placement. * * The source mode, source identity, and live PivotModel are locked. Use {@link setSourceRange} * or the field APIs for report changes. * * @param {ISheetPivotChartInfo} info Detached information created by {@link getInfo} or {@link toBuilder}. * @returns {Promise} This live PivotChart after the command is accepted. * @throws If the source, report fields, Chart type, or Drawing layout is invalid. */ update(info: ISheetPivotChartInfo): Promise; /** * Returns whether this PivotChart owns a range report or references a PivotTable. * @returns {PivotChartSourceKind} The current source ownership kind. */ getSourceKind(): PivotChartSourceKind; /** * Returns whether this PivotChart shares a PivotTable-owned report. * @returns {boolean} `true` for a linked PivotChart. */ isLinkedToPivotTable(): boolean; /** * Returns the effective source range for owned and available linked reports. * @returns {IUnitRangeNameWithSubUnitId | undefined} A defensive range snapshot, if available. */ getSourceRangeInfo(): IUnitRangeNameWithSubUnitId | undefined; /** * Updates the effective report source without changing its ownership mode. * * Linked PivotCharts delegate this operation to their referenced PivotTable. * * @param {IUnitRangeNameWithSubUnitId} source The complete source range identity. * @returns {Promise} Whether the source update was accepted. */ setSourceRange(source: IUnitRangeNameWithSubUnitId): Promise; /** * Returns the stable linked PivotTable reference. * @returns {DeepReadonly | undefined} The reference for linked charts. */ getPivotTableReference(): DeepReadonly | undefined; /** * Returns a live facade for the referenced PivotTable. * @returns {FPivotTable | null} The shared PivotTable, or `null` while the reference is unavailable. */ getPivotTable(): FPivotTable | null; /** * Returns the current effective report fields configuration. * @returns {DeepReadonly | undefined} A defensive report snapshot, if available. */ getFieldsConfig(): DeepReadonly | undefined; /** * Returns source fields available to the effective Pivot report. * @returns {IPivotChartDataFieldInfo[]} Defensive field information in source order. */ getSourceFieldsInfo(): IPivotChartDataFieldInfo[]; /** * Returns one report field setting. * @param {string} fieldId The table-field identifier. * @returns {IPivotTableValueFieldJSON | IPivotTableLabelFieldJSON | undefined} A defensive field snapshot. */ getFieldSetting(fieldId: string): IPivotTableValueFieldJSON | IPivotTableLabelFieldJSON | undefined; /** * Returns table-field identifiers in one report area. * @param {PivotTableFiledAreaEnum} area The Pivot report area. * @returns {string[]} Table-field identifiers in display order. */ getFieldIdsByArea(area: PivotTableFiledAreaEnum): string[]; /** * Replaces all report fields in one command and one Pivot query. * @param {IPivotTableSnapshot} config The complete fields configuration. * @returns {Promise} Whether the report update was accepted. */ setFieldsConfig(config: IPivotTableSnapshot): Promise; /** * Removes all fields or only fields in one report area. * @param {PivotTableFiledAreaEnum} [area] The area to clear; omit it to clear all report fields. * @returns {Promise} Whether the report update was accepted. */ resetFields(area?: PivotTableFiledAreaEnum): Promise; /** * Adds one source field to a report area. * @param {string | number} dataFieldIdOrIndex A source-field identifier or zero-based source index. * @param {PivotTableFiledAreaEnum} area The target report area. * @param {number} index The zero-based target index. * @returns {Promise} Whether the field was added. */ addField(dataFieldIdOrIndex: string | number, area: PivotTableFiledAreaEnum, index: number): Promise; /** * Removes report fields by their table-field identifiers. * @param {string[]} fieldIds The table-field identifiers to remove together. * @returns {Promise} Whether the fields were removed. */ removeField(fieldIds: string[]): Promise; /** * Moves one report field to a zero-based area index. * @param {string} fieldId The table-field identifier. * @param {PivotTableFiledAreaEnum} area The target area. * @param {number} index The zero-based target index. * @returns {Promise} Whether the field was moved. */ updateFieldPosition(fieldId: string, area: PivotTableFiledAreaEnum, index: number): Promise; /** * Moves the synthetic multiple-values field. * @param {PivotTableValuePositionEnum} position The row, column, or absent position. * @param {number} index The zero-based row or column field index. * @returns {Promise} Whether the value position was updated. */ updateValuePosition(position: PivotTableValuePositionEnum, index: number): Promise; /** * Updates a report field display name, format, aggregation, or Show Values As rule. * @param {string} fieldId The table-field identifier. * @param {IPivotChartFieldSettingOptions} setting The field properties to update together. * @returns {Promise} Whether the field setting was updated. */ setFieldSetting(fieldId: string, setting: IPivotChartFieldSettingOptions): Promise; /** * Renames a report field. * @param {string} fieldId The table-field identifier. * @param {string} name The new display name. * @returns {Promise} Whether the field was renamed. */ renameField(fieldId: string, name: string): Promise; /** * Returns the Show Values As rule for a value field. * @param {string} fieldId The value table-field identifier. * @returns {IPivotTableShowDataAsInfo | undefined} A defensive rule snapshot. */ getShowDataAs(fieldId: string): IPivotTableShowDataAsInfo | undefined; /** * Sets the Show Values As rule for a value field. * @param {string} fieldId The value table-field identifier. * @param {IPivotTableShowDataAsInfo} value The Show Values As rule. * @returns {Promise} Whether the rule was updated. */ setShowDataAs(fieldId: string, value: IPivotTableShowDataAsInfo): Promise; /** * Restores normal value display for a value field. * @param {string} fieldId The value table-field identifier. * @returns {Promise} Whether the rule was reset. */ resetShowDataAs(fieldId: string): Promise; /** * Sets label sorting for a row or column field. * @param {string} fieldId The row or column table-field identifier. * @param {IPivotTableSortInfo} info The sort rule. * @returns {Promise} Whether sorting was updated. */ setLabelSort(fieldId: string, info: IPivotTableSortInfo): Promise; /** * Clears label sorting for a row or column field. * @param {string} fieldId The row or column table-field identifier. * @returns {Promise} Whether sorting was cleared. */ clearLabelSort(fieldId: string): Promise; /** * Sets a manual label filter for a report field. * @param {string} fieldId The table-field identifier. * @param {string[]} items The selected item keys. * @param {boolean} [isAll] Whether all current items are selected. * @returns {Promise} Whether the filter was updated. */ setLabelManualFilter(fieldId: string, items: string[], isAll?: boolean): Promise; /** * Returns the value filter owned by a row or column field. * @param {string} fieldId The row or column table-field identifier. * @returns {IPivotTableValueFilter | undefined} A defensive filter snapshot. */ getValueFilter(fieldId: string): IPivotTableValueFilter | undefined; /** * Returns value filters in evaluation order. * @returns {IValueFilterInfoItem[]} Defensive ordered filter snapshots. */ getValueFilters(): IValueFilterInfoItem[]; /** * Sets, replaces, or removes the value filter owned by a row or column field. * @param {string} fieldId The row or column table-field identifier. * @param {Omit} [filter] The rule, or `undefined` to remove it. * @returns {Promise} Whether the value filter was updated. */ setValueFilter(fieldId: string, filter?: Omit): Promise; /** * Removes the value filter owned by a row or column field. * @param {string} fieldId The row or column table-field identifier. * @returns {Promise} Whether the value filter was removed. */ clearValueFilter(fieldId: string): Promise; /** * Groups a row or column date field using a Pivot date interval. * @param {string} fieldId The source date or existing date-group table-field identifier. * @param {PivotDateGroupFieldDateTypeEnum} dateType The requested date interval. * @returns {Promise} Whether the date group was updated. */ setDateGroupType(fieldId: string, dateType: PivotDateGroupFieldDateTypeEnum): Promise; /** * Collapses or expands a row hierarchy field or one item. * @param {string} fieldId The row table-field identifier. * @param {boolean} collapse Whether to collapse the target. * @param {string} [item] An optional item key; omit it to target the whole field. * @returns {Promise} Whether the hierarchy state was updated. */ setCollapse(fieldId: string, collapse: boolean, item?: string): Promise; /** * Expands the category hierarchy through the requested row field. * @param {string} fieldId The deepest row table-field identifier to display. * @returns {Promise} Whether the category level was updated. */ setCategoryLevel(fieldId: string): Promise; /** * Returns resolved PivotChart button visibility controls. * @returns {DeepReadonly} A defensive resolved controls snapshot. */ getControls(): DeepReadonly; /** * Sets the current supported Chart type. * @param {PivotChartTypeString} type The target supported type. * @returns {this} This PivotChart for chaining. * @throws If the type is not supported by PivotChart. */ setType(type: PivotChartTypeString): this; /** * Sets the Chart title. * @param {ChartTitleSpec} value The title specification. * @returns {this} This PivotChart for chaining. */ setTitle(value: ChartTitleSpec): this; /** * Clears the Chart title. * @returns {this} This PivotChart for chaining. */ clearTitle(): this; /** * Sets the Chart subtitle. * @param {ChartSubtitleSpec} value The subtitle specification. * @returns {this} This PivotChart for chaining. */ setSubtitle(value: ChartSubtitleSpec): this; /** * Clears the Chart subtitle. * @returns {this} This PivotChart for chaining. */ clearSubtitle(): this; /** * Sets the Chart legend. * @param {ChartLegendSpec} value The legend specification. * @returns {this} This PivotChart for chaining. */ setLegend(value: ChartLegendSpec): this; /** * Clears the Chart legend. * @returns {this} This PivotChart for chaining. */ clearLegend(): this; /** * Sets the Chart theme. * @param {string} name The registered theme name. * @returns {this} This PivotChart for chaining. */ setTheme(name: string): this; /** * Clears the Chart theme. * @returns {this} This PivotChart for chaining. */ clearTheme(): this; /** * Sets an explicit series palette. * @param {readonly string[]} colors The series colors. * @returns {this} This PivotChart for chaining. */ setPalette(colors: readonly string[]): this; /** * Clears the explicit series palette. * @returns {this} This PivotChart for chaining. */ clearPalette(): this; /** * Sets common Chart appearance. * @param {IChartAppearanceSpec} value The appearance overrides. * @returns {this} This PivotChart for chaining. */ setAppearance(value: IChartAppearanceSpec): this; /** * Clears all or one common Chart appearance property. * @param {ChartAppearanceTarget} [target] The property to clear; omit it to clear all appearance overrides. * @returns {this} This PivotChart for chaining. */ clearAppearance(target?: ChartAppearanceTarget): this; /** * Enables or disables automatic gradient fill. * @param {boolean} value Whether automatic gradients are enabled. * @returns {this} This PivotChart for chaining. */ setAutoGradientFill(value: boolean): this; /** * Restores the default automatic-gradient behavior. * @returns {this} This PivotChart for chaining. */ resetAutoGradientFill(): this; /** * Sets how invalid Pivot values are rendered. * @param {InvalidValueType} value The invalid-value strategy. * @returns {this} This PivotChart for chaining. */ setInvalidValueStrategy(value: InvalidValueType): this; /** * Restores the default invalid-value strategy. * @returns {this} This PivotChart for chaining. */ resetInvalidValueStrategy(): this; /** * Merges PivotChart button visibility controls. * @param {Partial} controls The controls to override. * @returns {this} This PivotChart for chaining. */ setControls(controls: Partial): this; /** * Shows or hides all Pivot field buttons. * @param {boolean} visible Whether field buttons are visible. * @returns {this} This PivotChart for chaining. */ setFieldButtonsVisible(visible: boolean): this; /** * Shows or hides category hierarchy expand and collapse buttons. * @param {boolean} visible Whether expand and collapse buttons are visible. * @returns {this} This PivotChart for chaining. */ setExpandCollapseButtonsVisible(visible: boolean): this; /** * Sets the worksheet cell anchor of this PivotChart. * @param {ChartAnchorSpec} anchor A1 notation or a zero-based row and column anchor. * @returns {this} This PivotChart for chaining. */ setPosition(anchor: ChartAnchorSpec): this; /** * Sets the absolute worksheet Drawing position. * @param {number} x The horizontal position in pixels. * @param {number} y The vertical position in pixels. * @returns {this} This PivotChart for chaining. */ setAbsolutePosition(x: number, y: number): this; /** * Sets the worksheet Drawing size. * @param {number} width The width in pixels. * @param {number} height The height in pixels. * @returns {this} This PivotChart for chaining. */ setSize(width: number, height: number): this; /** Moves this PivotChart to the front. @returns {this} This PivotChart for chaining. */ bringToFront(): this; /** Moves this PivotChart forward by one level. @returns {this} This PivotChart for chaining. */ bringForward(): this; /** Moves this PivotChart backward by one level. @returns {this} This PivotChart for chaining. */ sendBackward(): this; /** Moves this PivotChart to the back. @returns {this} This PivotChart for chaining. */ sendToBack(): this; /** * Moves this PivotChart to a zero-based Drawing order index. * @param {number} index The target zero-based z-order index. * @returns {this} This PivotChart for chaining. */ setZOrder(index: number): this; /** * Removes this PivotChart and its worksheet Drawing. * @returns {Promise} Whether the removal was accepted. */ remove(): Promise; private _arrange; private _apply; private _commit; }