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(drawing): support absolute z-order updates (#7517)

wpxp1234562693cdf4e886
diff --git a/packages/core/src/common/__tests__/drawing-order.spec.ts b/packages/core/src/common/__tests__/drawing-order.spec.ts
new file mode 100644
index 0000000000..d2c0789e39
--- /dev/null
+++ b/packages/core/src/common/__tests__/drawing-order.spec.ts
@@ -0,0 +1,43 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ArrangeTypeEnum } from '../../types/interfaces/i-drawing';
+import { getDrawingOrderIndex, normalizeDrawingOrderIndex } from '../drawing-order';
+
+describe('drawing order', () => {
+ it('resolves relative arrangement to a zero-based order index', () => {
+ expect(getDrawingOrderIndex(1, 4, ArrangeTypeEnum.front)).toBe(3);
+ expect(getDrawingOrderIndex(1, 4, ArrangeTypeEnum.forward)).toBe(2);
+ expect(getDrawingOrderIndex(1, 4, ArrangeTypeEnum.backward)).toBe(0);
+ expect(getDrawingOrderIndex(1, 4, ArrangeTypeEnum.back)).toBe(0);
+ });
+
+ it('keeps relative arrangement inside the available order', () => {
+ expect(getDrawingOrderIndex(3, 4, ArrangeTypeEnum.forward)).toBe(3);
+ expect(getDrawingOrderIndex(0, 4, ArrangeTypeEnum.backward)).toBe(0);
+ expect(getDrawingOrderIndex(0, 0, ArrangeTypeEnum.front)).toBe(0);
+ });
+
+ it('normalizes absolute indexes to the available order', () => {
+ expect(normalizeDrawingOrderIndex(-1, 3)).toBe(0);
+ expect(normalizeDrawingOrderIndex(1.9, 3)).toBe(1);
+ expect(normalizeDrawingOrderIndex(99, 3)).toBe(2);
+ expect(normalizeDrawingOrderIndex(Number.POSITIVE_INFINITY, 3)).toBe(2);
+ expect(normalizeDrawingOrderIndex(Number.NaN, 3)).toBe(0);
+ expect(normalizeDrawingOrderIndex(1, 0)).toBe(0);
+ });
+});
diff --git a/packages/core/src/common/drawing-order.ts b/packages/core/src/common/drawing-order.ts
new file mode 100644
index 0000000000..7bce1651e7
--- /dev/null
+++ b/packages/core/src/common/drawing-order.ts
@@ -0,0 +1,32 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ArrangeTypeEnum } from '../types/interfaces/i-drawing';
+
+/** Clamps a requested zero-based index to an available drawing order. */
+export function normalizeDrawingOrderIndex(index: number, length: number): number {
+ const lastIndex = Math.max(0, length - 1);
+ return Math.max(0, Math.min(Math.floor(index), lastIndex)) || 0;
+}
+
+/** Resolves a relative drawing arrangement to its zero-based target index. */
+export function getDrawingOrderIndex(currentIndex: number, length: number, arrangeType: ArrangeTypeEnum): number {
+ const index = normalizeDrawingOrderIndex(currentIndex, length);
+ if (arrangeType === ArrangeTypeEnum.front) return normalizeDrawingOrderIndex(length - 1, length);
+ if (arrangeType === ArrangeTypeEnum.forward) return normalizeDrawingOrderIndex(index + 1, length);
+ if (arrangeType === ArrangeTypeEnum.backward) return normalizeDrawingOrderIndex(index - 1, length);
+ return 0;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 3e6a624d6d..20f4b1262d 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -24,6 +24,7 @@ export * from './common/async';
export { isBooleanString } from './common/boolean';
export * from './common/const';
export * from './common/di';
+export { getDrawingOrderIndex, normalizeDrawingOrderIndex } from './common/drawing-order';
export { shallowEqual } from './common/equal';
export { CanceledError, CustomCommandExecutionError } from './common/error';
export { noop, throttle } from './common/function';
diff --git a/packages/docs-drawing/src/commands/commands/set-drawing-arrange.command.ts b/packages/docs-drawing/src/commands/commands/set-drawing-arrange.command.ts
index 8f69b5f19d..e9e0540177 100644
--- a/packages/docs-drawing/src/commands/commands/set-drawing-arrange.command.ts
+++ b/packages/docs-drawing/src/commands/commands/set-drawing-arrange.command.ts
@@ -23,13 +23,15 @@ import {
ICommandService,
IUniverInstanceService,
JSONX,
+ normalizeDrawingOrderIndex,
UniverInstanceType,
} from '@univerjs/core';
import { RichTextEditingMutation } from '@univerjs/docs';
-export interface ISetDocDrawingArrangeCommandParams extends IDrawingOrderMapParam {
- arrangeType: ArrangeTypeEnum;
-}
+export type ISetDocDrawingArrangeCommandParams = IDrawingOrderMapParam & (
+ { arrangeType: ArrangeTypeEnum; zOrder?: never }
+ | { arrangeType?: never; zOrder: number }
+);
const DRAWINGS_ORDER_KEY = 'drawingsOrder' satisfies keyof IDocumentData;
@@ -75,6 +77,23 @@ function getArrangedDrawingOrder(
return arrangedDrawingOrder;
}
+function getDrawingOrderAtIndex(drawingOrder: string[], drawingIds: string[], zOrder: number): string[] {
+ if (drawingIds.length !== 1) {
+ return [...drawingOrder];
+ }
+
+ const arrangedDrawingOrder = [...drawingOrder];
+ const currentIndex = arrangedDrawingOrder.indexOf(drawingIds[0]);
+ if (currentIndex < 0) {
+ return arrangedDrawingOrder;
+ }
+
+ const [drawingId] = arrangedDrawingOrder.splice(currentIndex, 1);
+ const targetIndex = normalizeDrawingOrderIndex(zOrder, drawingOrder.length);
+ arrangedDrawingOrder.splice(targetIndex, 0, drawingId);
+ return arrangedDrawingOrder;
+}
+
/**
* Converts the target order into granular JSONX move operations. This avoids replacing
* the entire drawingsOrder array and keeps collaboration conflicts scoped to moved items.
@@ -125,7 +144,7 @@ export const SetDocDrawingArrangeCommand: ICommand = {
return false;
}
- const { unitId, drawingIds, arrangeType } = params;
+ const { unitId, drawingIds } = params;
const documentDataModel = accessor.get(IUniverInstanceService)
.getUnit<DocumentDataModel>(unitId, UniverInstanceType.UNIVER_DOC);
const drawingOrder = documentDataModel?.getDrawingsOrder();
@@ -133,7 +152,9 @@ export const SetDocDrawingArrangeCommand: ICommand = {
return false;
}
- const arrangedDrawingOrder = getArrangedDrawingOrder(drawingOrder, drawingIds, arrangeType);
+ const arrangedDrawingOrder = params.zOrder !== undefined
+ ? getDrawingOrderAtIndex(drawingOrder, drawingIds, params.zOrder)
+ : getArrangedDrawingOrder(drawingOrder, drawingIds, params.arrangeType);
const actions = createDrawingOrderActions(drawingOrder, arrangedDrawingOrder);
if (JSONX.isNoop(actions)) {
return false;
diff --git a/packages/drawing/src/services/drawing-manager-impl.service.ts b/packages/drawing/src/services/drawing-manager-impl.service.ts
index 17e9c04e38..eaa7722064 100644
--- a/packages/drawing/src/services/drawing-manager-impl.service.ts
+++ b/packages/drawing/src/services/drawing-manager-impl.service.ts
@@ -33,7 +33,7 @@ import type {
IDrawingVisibleParam,
IUnitDrawingService,
} from './drawing-manager.service';
-import { DrawingTypeEnum, sortRules, sortRulesByDesc } from '@univerjs/core';
+import { DrawingTypeEnum, normalizeDrawingOrderIndex, sortRules, sortRulesByDesc } from '@univerjs/core';
import * as json1 from 'ot-json1';
import { Subject } from 'rxjs';
@@ -830,6 +830,39 @@ export class UnitDrawingService<T extends IDrawingParam> implements IUnitDrawing
return { undo: invertOp, redo: op, unitId, subUnitId, objects: { ...orderParams, drawingIds: newIds } };
}
+ getDrawingOrderOp(orderParams: IDrawingOrderMapParam, zOrder: number): Nullable<IDrawingJsonUndo1> {
+ const { unitId, subUnitId, drawingIds } = orderParams;
+ if (drawingIds.length !== 1) {
+ return null;
+ }
+
+ const orders = this.getDrawingOrder(unitId, subUnitId);
+ const drawingId = drawingIds[0];
+ const currentIndex = orders.indexOf(drawingId);
+ const targetIndex = normalizeDrawingOrderIndex(zOrder, orders.length);
+ if (currentIndex < 0 || currentIndex === targetIndex) {
+ return null;
+ }
+
+ const op = json1.moveOp(
+ [unitId, subUnitId, DrawingMapItemType.order, currentIndex],
+ [unitId, subUnitId, DrawingMapItemType.order, targetIndex]
+ );
+ const invertOp = json1.type.invertWithDoc(op, this.drawingManagerData as unknown as json1.Doc);
+ const affectedDrawingIds = orders.slice(
+ Math.min(currentIndex, targetIndex),
+ Math.max(currentIndex, targetIndex) + 1
+ );
+
+ return {
+ undo: invertOp,
+ redo: op,
+ unitId,
+ subUnitId,
+ objects: { ...orderParams, drawingIds: affectedDrawingIds },
+ };
+ }
+
private _getDrawingCount(unitId: string, subUnitId: string) {
return this.getDrawingOrder(unitId, subUnitId).length || 0;
}
diff --git a/packages/drawing/src/services/drawing-manager.service.ts b/packages/drawing/src/services/drawing-manager.service.ts
index 9d379000a8..e8a662ca04 100644
--- a/packages/drawing/src/services/drawing-manager.service.ts
+++ b/packages/drawing/src/services/drawing-manager.service.ts
@@ -129,6 +129,7 @@ export interface IUnitOrderDrawingService {
getBackwardDrawingOp(orderParams: IDrawingOrderMapParam): unknown;
getFrontDrawingsOp(orderParams: IDrawingOrderMapParam): unknown;
getBackDrawingsOp(orderParams: IDrawingOrderMapParam): unknown;
+ getDrawingOrderOp(orderParams: IDrawingOrderMapParam, zOrder: number): unknown;
// replaceDrawingOrder(unitId: string, subUnitId: string, drawingIds: string[]): void;
getDrawingOrder(unitId: string, subUnitId: string): string[];
setDrawingOrder(unitId: string, subUnitId: string, order: string[]): void;
diff --git a/packages/sheets-drawing/src/commands/commands/__tests__/sheet-drawing.integration.spec.ts b/packages/sheets-drawing/src/commands/commands/__tests__/sheet-drawing.integration.spec.ts
index bc383e4837..b79527b47f 100644
--- a/packages/sheets-drawing/src/commands/commands/__tests__/sheet-drawing.integration.spec.ts
+++ b/packages/sheets-drawing/src/commands/commands/__tests__/sheet-drawing.integration.spec.ts
@@ -23,6 +23,7 @@ import {
ImageSourceType,
IUndoRedoService,
IUniverInstanceService,
+ RedoCommand,
UndoCommand,
UniverInstanceType,
} from '@univerjs/core';
@@ -528,6 +529,34 @@ describe('sheet drawing integration', () => {
expect(sheetDrawingService.getDrawingOrder('test', 'sheet1')).toEqual(['drawing-a', 'drawing-c', 'drawing-b']);
});
+ it('moves one drawing to a clamped zero-based order index with undo', async () => {
+ await commandService.executeCommand(InsertSheetDrawingCommand.id, {
+ unitId: 'test',
+ drawings: [
+ createSheetDrawing('drawing-a'),
+ createSheetDrawing('drawing-b'),
+ createSheetDrawing('drawing-c'),
+ ],
+ });
+
+ const sheetDrawingService = get(ISheetDrawingService);
+ expect(sheetDrawingService.getDrawingOrder('test', 'sheet1')).toEqual(['drawing-c', 'drawing-b', 'drawing-a']);
+
+ expect(await commandService.executeCommand(SetDrawingArrangeCommand.id, {
+ unitId: 'test',
+ subUnitId: 'sheet1',
+ drawingIds: ['drawing-b'],
+ zOrder: 99,
+ })).toBe(true);
+ expect(sheetDrawingService.getDrawingOrder('test', 'sheet1')).toEqual(['drawing-c', 'drawing-a', 'drawing-b']);
+
+ expect(commandService.syncExecuteCommand(UndoCommand.id)).toBe(true);
+ expect(sheetDrawingService.getDrawingOrder('test', 'sheet1')).toEqual(['drawing-c', 'drawing-b', 'drawing-a']);
+
+ expect(commandService.syncExecuteCommand(RedoCommand.id)).toBe(true);
+ expect(sheetDrawingService.getDrawingOrder('test', 'sheet1')).toEqual(['drawing-c', 'drawing-a', 'drawing-b']);
+ });
+
it('copies sheet drawings when a worksheet is duplicated', async () => {
await commandService.executeCommand(SetWorksheetActivateCommand.id, {
unitId: 'test',
diff --git a/packages/sheets-drawing/src/commands/commands/set-drawing-arrange.command.ts b/packages/sheets-drawing/src/commands/commands/set-drawing-arrange.command.ts
index fe81c8d5cd..04820d3714 100644
--- a/packages/sheets-drawing/src/commands/commands/set-drawing-arrange.command.ts
+++ b/packages/sheets-drawing/src/commands/commands/set-drawing-arrange.command.ts
@@ -25,9 +25,10 @@ import {
import { ISheetDrawingService } from '../../services/sheet-drawing.service';
import { DrawingApplyType, SetDrawingApplyMutation } from '../mutations/set-drawing-apply.mutation';
-export interface ISetDrawingArrangeCommandParams extends IDrawingOrderMapParam {
- arrangeType: ArrangeTypeEnum;
-}
+export type ISetDrawingArrangeCommandParams = IDrawingOrderMapParam & (
+ { arrangeType: ArrangeTypeEnum; zOrder?: never }
+ | { arrangeType?: never; zOrder: number }
+);
export const SetDrawingArrangeCommand: ICommand = {
id: 'sheet.command.set-drawing-arrange',
@@ -40,18 +41,20 @@ export const SetDrawingArrangeCommand: ICommand = {
const sheetDrawingService = accessor.get(ISheetDrawingService);
- const { unitId, subUnitId, drawingIds, arrangeType } = params;
+ const { unitId, subUnitId, drawingIds } = params;
const drawingOrderMapParam = { unitId, subUnitId, drawingIds } as IDrawingOrderMapParam;
let jsonOp: Nullable<IDrawingJsonUndo1>;
- if (arrangeType === ArrangeTypeEnum.forward) {
+ if (params.zOrder !== undefined) {
+ jsonOp = sheetDrawingService.getDrawingOrderOp(drawingOrderMapParam, params.zOrder) as Nullable<IDrawingJsonUndo1>;
+ } else if (params.arrangeType === ArrangeTypeEnum.forward) {
jsonOp = sheetDrawingService.getForwardDrawingsOp(drawingOrderMapParam) as IDrawingJsonUndo1;
- } else if (arrangeType === ArrangeTypeEnum.backward) {
+ } else if (params.arrangeType === ArrangeTypeEnum.backward) {
jsonOp = sheetDrawingService.getBackwardDrawingOp(drawingOrderMapParam) as IDrawingJsonUndo1;
- } else if (arrangeType === ArrangeTypeEnum.front) {
+ } else if (params.arrangeType === ArrangeTypeEnum.front) {
jsonOp = sheetDrawingService.getFrontDrawingsOp(drawingOrderMapParam) as IDrawingJsonUndo1;
- } else if (arrangeType === ArrangeTypeEnum.back) {
+ } else if (params.arrangeType === ArrangeTypeEnum.back) {
jsonOp = sheetDrawingService.getBackDrawingsOp(drawingOrderMapParam) as IDrawingJsonUndo1;
}