Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(api): add the optional isForceMerge parameter to the merge-related APIs (#6418)

wpxp123456883eab6648ce
diff --git a/packages/sheets/src/commands/commands/add-worksheet-merge.command.ts b/packages/sheets/src/commands/commands/add-worksheet-merge.command.ts
index 95aab59e2e..9f4e858a0c 100644
--- a/packages/sheets/src/commands/commands/add-worksheet-merge.command.ts
+++ b/packages/sheets/src/commands/commands/add-worksheet-merge.command.ts
@@ -17,6 +17,7 @@
import type { IAccessor, ICellData, ICommand, IMutationInfo, Injector, IRange, Nullable, Worksheet } from '@univerjs/core';
import type { IAddWorksheetMergeMutationParams, IRemoveWorksheetMergeMutationParams } from '../../basics/interfaces/mutation-interface';
import type { ISetRangeValuesMutationParams } from '../mutations/set-range-values.mutation';
+import type { ISheetCommandSharedParams } from '../utils/interface';
import {
CellModeEnum,
CommandType,
@@ -38,13 +39,12 @@ import { AddMergeUndoMutationFactory, AddWorksheetMergeMutation } from '../mutat
import { RemoveMergeUndoMutationFactory, RemoveWorksheetMergeMutation } from '../mutations/remove-worksheet-merge.mutation';
import { SetRangeValuesMutation, SetRangeValuesUndoMutationFactory } from '../mutations/set-range-values.mutation';
import { AddMergeRedoSelectionsOperationFactory, AddMergeUndoSelectionsOperationFactory } from '../utils/handle-merge-operation';
+import { RemoveWorksheetMergeCommand } from './remove-worksheet-merge.command';
import { getSheetCommandTarget } from './utils/target-util';
-export interface IAddMergeCommandParams {
+export interface IAddMergeCommandParams extends ISheetCommandSharedParams {
value?: Dimension.ROWS | Dimension.COLUMNS;
selections: IRange[];
- unitId: string;
- subUnitId: string;
defaultMerge?: boolean;
}
@@ -54,6 +54,22 @@ export enum MergeType {
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;
+}
+
function checkCellContentInRanges(worksheet: Worksheet, ranges: IRange[]): boolean {
return ranges.some((range) => checkCellContentInRange(worksheet, range));
}
@@ -313,10 +329,12 @@ export const AddWorksheetMergeHorizontalCommand: ICommand = {
},
};
-export function addMergeCellsUtil(injector: Injector, unitId: string, subUnitId: string, ranges: IRange[], defaultMerge: boolean) {
- const univerInstanceService = injector.get(IUniverInstanceService);
- const target = getSheetCommandTarget(univerInstanceService, { unitId, subUnitId });
+export function addMergeCellsUtil(injector: Injector, unitId: string, subUnitId: string, ranges: IRange[], options: IMergeCellsUtilOptions = {}) {
+ const target = getSheetCommandTarget(injector.get(IUniverInstanceService), { unitId, subUnitId });
if (!target) return;
+
+ const commandService = injector.get(ICommandService);
+ const { defaultMerge = true, isForceMerge = false } = options;
const { worksheet } = target;
const mergeData = worksheet.getMergeData();
const overlap = mergeData.some((mergeRange) => {
@@ -324,10 +342,19 @@ export function addMergeCellsUtil(injector: Injector, unitId: string, subUnitId:
return Rectangle.intersects(range, mergeRange);
});
});
+
if (overlap) {
- throw new Error('The ranges to be merged overlap with the existing merged cells');
+ if (!isForceMerge) {
+ throw new Error('The ranges to be merged overlap with the existing merged cells');
+ }
+
+ commandService.syncExecuteCommand(RemoveWorksheetMergeCommand.id, {
+ unitId,
+ subUnitId,
+ ranges,
+ });
}
- const commandService = injector.get(ICommandService);
+
commandService.executeCommand(AddWorksheetMergeCommand.id, {
unitId,
subUnitId,
diff --git a/packages/sheets/src/commands/commands/remove-worksheet-merge.command.ts b/packages/sheets/src/commands/commands/remove-worksheet-merge.command.ts
index e3a87e50d3..234d25f69d 100644
--- a/packages/sheets/src/commands/commands/remove-worksheet-merge.command.ts
+++ b/packages/sheets/src/commands/commands/remove-worksheet-merge.command.ts
@@ -17,6 +17,7 @@
import type { IAccessor, ICellData, ICommand, IMutationInfo, IRange, Nullable, Worksheet } from '@univerjs/core';
import type { IAddWorksheetMergeMutationParams, IRemoveWorksheetMergeMutationParams } from '../../basics/interfaces/mutation-interface';
import type { ISetRangeValuesMutationParams } from '../mutations/set-range-values.mutation';
+import type { ISheetCommandSharedParams } from '../utils/interface';
import { CommandType, ICommandService, IUndoRedoService, IUniverInstanceService, ObjectMatrix, Rectangle, sequenceExecute, Tools } from '@univerjs/core';
import { SetSelectionsOperation } from '../../commands/operations/selection.operation';
import { SelectionMoveType } from '../../services/selections';
@@ -26,7 +27,7 @@ import { RemoveMergeUndoMutationFactory, RemoveWorksheetMergeMutation } from '..
import { SetRangeValuesMutation } from '../mutations/set-range-values.mutation';
import { getSheetCommandTarget } from './utils/target-util';
-interface IRemoveWorksheetMergeCommandParams {
+interface IRemoveWorksheetMergeCommandParams extends ISheetCommandSharedParams {
ranges?: IRange[];
}
@@ -38,12 +39,11 @@ export const RemoveWorksheetMergeCommand: ICommand = {
const selectionManagerService = accessor.get(SheetsSelectionsService);
const commandService = accessor.get(ICommandService);
const undoRedoService = accessor.get(IUndoRedoService);
- const univerInstanceService = accessor.get(IUniverInstanceService);
const selections = params?.ranges || selectionManagerService.getCurrentSelections()?.map((s) => s.range);
if (!selections?.length) return false;
- const target = getSheetCommandTarget(univerInstanceService);
+ const target = getSheetCommandTarget(accessor.get(IUniverInstanceService), params);
if (!target) return false;
const { subUnitId, unitId, worksheet } = target;
diff --git a/packages/sheets/src/facade/f-range.ts b/packages/sheets/src/facade/f-range.ts
index 763537a605..ed18f07775 100644
--- a/packages/sheets/src/facade/f-range.ts
+++ b/packages/sheets/src/facade/f-range.ts
@@ -16,6 +16,7 @@
import type { AbsoluteRefType, BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IColorStyle, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, ITextDecoration, Nullable, Workbook, Worksheet } from '@univerjs/core';
import type {
+ IMergeCellsUtilOptions,
ISetBorderBasicCommandParams,
ISetHorizontalTextAlignCommandParams,
ISetRangeCustomMetadataCommandParams,
@@ -1709,7 +1710,9 @@ export class FRange extends FBaseInitialable {
/**
* 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
@@ -1719,19 +1722,29 @@ export 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 = true): FRange {
+ merge(options?: IMergeCellsUtilOptions): FRange {
const unitId = this._workbook.getUnitId();
const subUnitId = this._worksheet.getSheetId();
- addMergeCellsUtil(this._injector, unitId, subUnitId, [this._range], defaultMerge);
+ addMergeCellsUtil(this._injector, unitId, subUnitId, [this._range], options);
return this;
}
/**
* 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
@@ -1746,20 +1759,30 @@ export 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 = true): FRange {
+ mergeAcross(options?: IMergeCellsUtilOptions): FRange {
const ranges = getAddMergeMutationRangeByType([this._range], Dimension.ROWS);
const unitId = this._workbook.getUnitId();
const subUnitId = this._worksheet.getSheetId();
- addMergeCellsUtil(this._injector, unitId, subUnitId, ranges, defaultMerge);
+ addMergeCellsUtil(this._injector, unitId, subUnitId, ranges, options);
return this;
}
/**
* 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
@@ -1774,13 +1797,21 @@ export 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 = true): FRange {
+ mergeVertically(options?: IMergeCellsUtilOptions): FRange {
const ranges = getAddMergeMutationRangeByType([this._range], Dimension.COLUMNS);
const unitId = this._workbook.getUnitId();
const subUnitId = this._worksheet.getSheetId();
- addMergeCellsUtil(this._injector, unitId, subUnitId, ranges, defaultMerge);
+ addMergeCellsUtil(this._injector, unitId, subUnitId, ranges, options);
return this;
}
@@ -1819,7 +1850,11 @@ export class FRange extends FBaseInitialable {
* ```
*/
breakApart(): FRange {
- this._commandService.syncExecuteCommand(RemoveWorksheetMergeCommand.id, { ranges: [this._range] });
+ this._commandService.syncExecuteCommand(RemoveWorksheetMergeCommand.id, {
+ unitId: this._workbook.getUnitId(),
+ subUnitId: this._worksheet.getSheetId(),
+ ranges: [this._range],
+ });
return this;
}
diff --git a/packages/sheets/src/index.ts b/packages/sheets/src/index.ts
index 5fa6bd2319..8d6dce7870 100644
--- a/packages/sheets/src/index.ts
+++ b/packages/sheets/src/index.ts
@@ -64,6 +64,7 @@ export {
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';