@univerjs/sheets 0.15.0 → 0.15.1-insiders.20260117-8ce4a01

package/lib/types/commands/commands/add-worksheet-merge.command.d.ts

@@ -1,9 +1,8 @@
 import { IAccessor, ICellData, ICommand, IMutationInfo, Injector, IRange, Nullable, Worksheet, Dimension, ObjectMatrix } from '@univerjs/core';
-export interface IAddMergeCommandParams {
+import { ISheetCommandSharedParams } from '../utils/interface';
+export interface IAddMergeCommandParams extends ISheetCommandSharedParams {
     value?: Dimension.ROWS | Dimension.COLUMNS;
     selections: IRange[];
-    unitId: string;
-    subUnitId: string;
     defaultMerge?: boolean;
 }
 export declare enum MergeType {
@@ -11,6 +10,21 @@ export declare enum MergeType {
     MergeVertical = "mergeVertical",
     MergeHorizontal = "mergeHorizontal"
 }
+export interface IMergeCellsUtilOptions {
+    /**
+     * Whether to use the default merge behavior when there are existing cell contents in the merge ranges.
+     * If true, only the value in the upper left cell is retained.
+     * If false, a confirm dialog will be shown to the user.
+     * @default true
+     */
+    defaultMerge?: boolean;
+    /**
+     * Whether to force merge even if there are existing merged cells that overlap with the new merge ranges.
+     * If true, the overlapping merged cells will be removed before performing the new merge.
+     * @default false
+     */
+    isForceMerge?: boolean;
+}
 export declare function getClearContentMutationParamsForRanges(accessor: IAccessor, unitId: string, worksheet: Worksheet, ranges: IRange[]): {
     undos: IMutationInfo[];
     redos: IMutationInfo[];
@@ -20,5 +34,5 @@ export declare const AddWorksheetMergeCommand: ICommand;
 export declare const AddWorksheetMergeAllCommand: ICommand;
 export declare const AddWorksheetMergeVerticalCommand: ICommand;
 export declare const AddWorksheetMergeHorizontalCommand: ICommand;
-export declare function addMergeCellsUtil(injector: Injector, unitId: string, subUnitId: string, ranges: IRange[], defaultMerge: boolean): void;
+export declare function addMergeCellsUtil(injector: Injector, unitId: string, subUnitId: string, ranges: IRange[], options?: IMergeCellsUtilOptions): void;
 export declare function getMergeableSelectionsByType(type: MergeType, selections: Nullable<IRange[]>): Nullable<IRange[]>;

package/lib/types/commands/commands/set-range-custom-metadata.command.d.ts

@@ -0,0 +1,14 @@
+import { CustomData, ICommand, IRange } from '@univerjs/core';
+import { ISheetCommandSharedParams } from '../utils/interface';
+interface ICustomMetadata {
+    custom: CustomData;
+}
+export interface ISetRangeCustomMetadataCommandParams extends Partial<ISheetCommandSharedParams> {
+    range: IRange;
+    customMetadata: ICustomMetadata | ICustomMetadata[][];
+}
+/**
+ * The command to set custom metadata for a range of cells, and not support undo/redo.
+ */
+export declare const SetRangeCustomMetadataCommand: ICommand;
+export {};

package/lib/types/commands/commands/set-tab-color.command.d.ts

@@ -1,5 +1,6 @@
 import { ICommand } from '@univerjs/core';
-export interface ISetTabColorCommandParams {
+import { ISheetCommandSharedParams } from '../utils/interface';
+export interface ISetTabColorCommandParams extends Partial<ISheetCommandSharedParams> {
     value: string;
 }
 export declare const SetTabColorCommand: ICommand;

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

@@ -1,5 +1,5 @@
 import { AbsoluteRefType, BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, Dimension, ICommandService, Injector, RichTextValue, TextStyleValue, WrapStrategy } from '@univerjs/core';
-import { SplitDelimiterEnum } from '@univerjs/sheets';
+import { IMergeCellsUtilOptions, SplitDelimiterEnum } from '@univerjs/sheets';
 import { IFacadeClearOptions } from './f-worksheet';
 import { FHorizontalAlignment, FVerticalAlignment } from './utils';
 import { FBaseInitialable } from '@univerjs/core/facade';
@@ -971,7 +971,9 @@ export declare class FRange extends FBaseInitialable {
     setFontColor(color: string | null): this;
     /**
      * Merge cells in a range into one merged cell
-     * @param {boolean} [defaultMerge] - If true, only the value in the upper left cell is retained.
+     * @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
+     * @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
+     * @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
      * @returns {FRange} This range, for chaining
      * @example
      * ```ts
@@ -981,11 +983,21 @@ export declare class FRange extends FBaseInitialable {
      * fRange.merge();
      * console.log(fRange.isMerged());
      * ```
+     *
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('B1:C2');
+     * // Assume A1:B2 is already merged.
+     * fRange.merge({ isForceMerge: true });
+     * ```
      */
-    merge(defaultMerge?: boolean): FRange;
+    merge(options?: IMergeCellsUtilOptions): FRange;
     /**
      * Merges cells in a range horizontally.
-     * @param {boolean} [defaultMerge] - If true, only the value in the upper left cell is retained.
+     * @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
+     * @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
+     * @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
      * @returns {FRange} This range, for chaining
      * @example
      * ```ts
@@ -1000,11 +1012,21 @@ export declare class FRange extends FBaseInitialable {
      *   console.log(item.getA1Notation());
      * });
      * ```
+     *
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('B1:C2');
+     * // Assume A1:B2 is already merged.
+     * fRange.mergeAcross({ isForceMerge: true });
+     * ```
      */
-    mergeAcross(defaultMerge?: boolean): FRange;
+    mergeAcross(options?: IMergeCellsUtilOptions): FRange;
     /**
      * Merges cells in a range vertically.
-     * @param {boolean} [defaultMerge] - If true, only the value in the upper left cell is retained.
+     * @param {IMergeCellsUtilOptions} [options] - The options for merging cells.
+     * @param {boolean} [options.defaultMerge] - If true, only the value in the upper left cell is retained. If false, a confirm dialog will be shown to the user. Default is true.
+     * @param {boolean} [options.isForceMerge] - If true, the overlapping merged cells will be removed before performing the new merge. Default is false.
      * @returns {FRange} This range, for chaining
      * @example
      * ```ts
@@ -1019,8 +1041,16 @@ export declare class FRange extends FBaseInitialable {
      *   console.log(item.getA1Notation());
      * });
      * ```
+     *
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fRange = fWorksheet.getRange('B1:C2');
+     * // Assume A1:B2 is already merged.
+     * fRange.mergeVertically({ isForceMerge: true });
+     * ```
      */
-    mergeVertically(defaultMerge?: boolean): FRange;
+    mergeVertically(options?: IMergeCellsUtilOptions): FRange;
     /**
      * Returns true if cells in the current range overlap a merged cell.
      * @returns {boolean} is overlap with a merged cell

package/lib/types/index.d.ts

@@ -24,7 +24,7 @@ export { SplitDelimiterEnum, splitRangeText } from './basics/split-range-text';
 export { findFirstNonEmptyCell } from './basics/utils';
 export { generateNullCell, generateNullCellValue, getVisibleRanges, rangeToDiscreteRange } from './basics/utils';
 export { AddRangeProtectionCommand, type IAddRangeProtectionCommandParams } from './commands/commands/add-range-protection.command';
-export { addMergeCellsUtil, AddWorksheetMergeAllCommand, AddWorksheetMergeCommand, AddWorksheetMergeHorizontalCommand, AddWorksheetMergeVerticalCommand, getClearContentMutationParamForRange, getClearContentMutationParamsForRanges, } from './commands/commands/add-worksheet-merge.command';
+export { addMergeCellsUtil, AddWorksheetMergeAllCommand, AddWorksheetMergeCommand, AddWorksheetMergeHorizontalCommand, AddWorksheetMergeVerticalCommand, getClearContentMutationParamForRange, getClearContentMutationParamsForRanges, type IMergeCellsUtilOptions, } from './commands/commands/add-worksheet-merge.command';
 export { AddWorksheetProtectionCommand } from './commands/commands/add-worksheet-protection.command';
 export { SetWorksheetRangeThemeStyleCommand } from './commands/commands/add-worksheet-range-theme.command';
 export { AppendRowCommand, type IAppendRowCommandParams } from './commands/commands/append-row.command';
@@ -60,6 +60,7 @@ export { type ICancelFrozenCommandParams, type ISetFrozenCommandParams } from '.
 export { CancelFrozenCommand, SetFrozenCommand } from './commands/commands/set-frozen.command';
 export { type ISetGridlinesColorCommandParams, SetGridlinesColorCommand } from './commands/commands/set-gridlines-color.command';
 export { SetProtectionCommand } from './commands/commands/set-protection.command';
+export { type ISetRangeCustomMetadataCommandParams, SetRangeCustomMetadataCommand } from './commands/commands/set-range-custom-metadata.command';
 export { type ISetRangeValuesCommandParams, SetRangeValuesCommand } from './commands/commands/set-range-values.command';
 export { type ISetRowDataCommandParams, SetRowDataCommand } from './commands/commands/set-row-data.command';
 export { type ISetSpecificRowsVisibleCommandParams, SetRowHiddenCommand, SetSelectedRowsVisibleCommand, SetSpecificRowsVisibleCommand, } from './commands/commands/set-row-visible.command';
@@ -143,7 +144,7 @@ export { SetWorksheetProtectionMutation } from './commands/mutations/set-workshe
 export type { ISetWorksheetProtectionParams } from './commands/mutations/set-worksheet-protection.mutation';
 export { SetWorksheetRightToLeftMutation } from './commands/mutations/set-worksheet-right-to-left.mutation';
 export { type ISetWorksheetRowCountMutationParams, SetWorksheetRowCountMutation, SetWorksheetRowCountUndoMutationFactory } from './commands/mutations/set-worksheet-row-count.mutation';
-export { type ISetWorksheetRowAutoHeightMutationParams, type ISetWorksheetRowHeightMutationParams, type ISetWorksheetRowIsAutoHeightMutationParams, SetWorksheetRowAutoHeightMutation, SetWorksheetRowAutoHeightMutationFactory, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightMutation, } from './commands/mutations/set-worksheet-row-height.mutation';
+export { type ISetWorksheetRowAutoHeightMutationParams, type ISetWorksheetRowHeightMutationParams, type ISetWorksheetRowIsAutoHeightMutationParams, SetWorksheetRowAutoHeightMutation, SetWorksheetRowAutoHeightMutationFactory, SetWorksheetRowHeightMutation, SetWorksheetRowHeightMutationFactory, SetWorksheetRowIsAutoHeightMutation, SetWorksheetRowIsAutoHeightMutationFactory, } from './commands/mutations/set-worksheet-row-height.mutation';
 export { type IToggleGridlinesMutationParams, ToggleGridlinesMutation } from './commands/mutations/toggle-gridlines.mutation';
 export { type IUnregisterWorksheetRangeThemeStyleMutationParams, UnregisterWorksheetRangeThemeStyleMutation } from './commands/mutations/unregister-range-theme-style.mutation';
 export { type IScrollToCellOperationParams, ScrollToCellOperation } from './commands/operations/scroll-to-cell.operation';