@univerjs/sheets-drawing 1.0.3 → 1.1.0

package/lib/es/index.js

@@ -1,5 +1,5 @@
-import { CopySheetCommand, DeleteRangeMoveLeftCommand, DeleteRangeMoveUpCommand, DeltaColumnWidthCommand, DeltaRowHeightCommand, InsertColCommand, InsertRangeMoveDownCommand, InsertRangeMoveRightCommand, InsertRowCommand, MoveColsCommand, MoveRangeCommand, MoveRowsCommand, RemoveColCommand, RemoveRowCommand, RemoveSheetCommand, SetColHiddenCommand, SetColHiddenMutation, SetColVisibleMutation, SetColWidthCommand, SetRowHeightCommand, SetRowHiddenCommand, SetRowHiddenMutation, SetRowVisibleMutation, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetWorksheetColWidthMutation, SetWorksheetRowAutoHeightMutation, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightMutation, SheetInterceptorService, SheetSkeletonService, SheetsSelectionsService, UniverSheetsPlugin, attachRangeWithCoord, convertPositionCellToSheetOverGrid, convertPositionSheetOverGridToAbsolute, getSheetCommandTarget } from "@univerjs/sheets";
-import { ArrangeTypeEnum, CommandType, DependentOn, Disposable, DrawingTypeEnum, ICommandService, IConfigService, IResourceManagerService, IUndoRedoService, IUniverInstanceService, Inject, Injector, Plugin, RANGE_TYPE, Rectangle, UniverInstanceType, createIdentifier, merge, sequenceExecute, toDisposable } from "@univerjs/core";
+import { CopySheetCommand, DeleteRangeMoveLeftCommand, DeleteRangeMoveUpCommand, DeltaColumnWidthCommand, DeltaRowHeightCommand, InsertColCommand, InsertRangeMoveDownCommand, InsertRangeMoveRightCommand, InsertRowCommand, MoveColsCommand, MoveRangeCommand, MoveRowsCommand, RemoveColCommand, RemoveRowCommand, RemoveSheetCommand, SetColHiddenCommand, SetColHiddenMutation, SetColVisibleMutation, SetColWidthCommand, SetRowHeightCommand, SetRowHiddenCommand, SetRowHiddenMutation, SetRowVisibleMutation, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetWorksheetColWidthMutation, SetWorksheetRowAutoHeightMutation, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightMutation, SheetInterceptorService, SheetSkeletonService, UniverSheetsPlugin, attachRangeWithCoord, convertPositionCellToSheetOverGrid, convertPositionSheetOverGridToAbsolute, getSheetCommandTarget } from "@univerjs/sheets";
+import { ArrangeTypeEnum, CommandType, DependentOn, Disposable, DrawingTypeEnum, ICommandService, IConfigService, IResourceManagerService, IUndoRedoService, IUniverInstanceService, Inject, Injector, Plugin, Rectangle, UniverInstanceType, createIdentifier, merge, sequenceExecute, toDisposable } from "@univerjs/core";
 import { IDrawingManagerService, UnitDrawingService, UniverDrawingPlugin, getOrCreateDrawingCopyPlan, resolveDrawingRotateEnabled } from "@univerjs/drawing";
 import { IRenderManagerService } from "@univerjs/engine-render";
 
@@ -365,7 +365,7 @@ function getSheetDrawingPlacement(drawing) {
 	};
 }
 function applySheetDrawingPlacement(drawing, input, skeleton) {
-	const placement = normalizeSheetDrawingPlacement(input, skeleton);
+	const placement = normalizePlacement(input, skeleton, drawing.drawingType === DrawingTypeEnum.DRAWING_IMAGE || drawing.drawingType === DrawingTypeEnum.DRAWING_DOM);
 	if (placement.kind === "2") {
 		const transform = withExistingTransform(drawing.transform, placement);
 		const sheetTransform = absoluteSheetTransform(placement, drawing.sheetTransform);
@@ -409,15 +409,18 @@ function applySheetDrawingPlacement(drawing, input, skeleton) {
 * Position, Both, or None Placement.
 */
 function normalizeSheetDrawingPlacement(input, skeleton) {
+	return normalizePlacement(input, skeleton, false);
+}
+function normalizePlacement(input, skeleton, requiresArea) {
 	if (!("bounds" in input)) {
-		validatePlacement(input);
+		validatePlacement(input, requiresArea);
 		if (input.kind === "1" && skeleton) validateBounds(convertPositionSheetOverGridToAbsolute(skeleton.worksheet.getUnitId(), skeleton.worksheet.getSheetId(), {
 			from: input.from,
 			to: input.to
-		}, skeleton));
+		}, skeleton), requiresArea);
 		return input;
 	}
-	validateBounds(input.bounds);
+	validateBounds(input.bounds, requiresArea);
 	if (input.kind === "2") return {
 		kind: "2",
 		...input.bounds
@@ -470,10 +473,10 @@ function absoluteSheetTransform(placement, current) {
 		}
 	};
 }
-function validatePlacement(placement) {
+function validatePlacement(placement, requiresArea) {
 	if (placement.kind === "0") {
 		validateCellPosition(placement.from);
-		validateExtent(placement.width, placement.height);
+		validateExtent(placement.width, placement.height, requiresArea);
 		return;
 	}
 	if (placement.kind === "1") {
@@ -483,20 +486,24 @@ function validatePlacement(placement) {
 	}
 	if (placement.kind === "2") {
 		if (!Number.isFinite(placement.left) || !Number.isFinite(placement.top)) throw new TypeError("SHEET_DRAWING_PLACEMENT_POSITION_INVALID");
-		validateExtent(placement.width, placement.height);
+		validateExtent(placement.width, placement.height, requiresArea);
 		return;
 	}
 	throw new Error("SHEET_DRAWING_PLACEMENT_KIND_INVALID");
 }
-function validateBounds(bounds) {
+function validateBounds(bounds, requiresArea) {
 	if (!Number.isFinite(bounds.left) || !Number.isFinite(bounds.top)) throw new TypeError("SHEET_DRAWING_PLACEMENT_POSITION_INVALID");
-	validateExtent(bounds.width, bounds.height);
+	validateExtent(bounds.width, bounds.height, requiresArea);
 }
 function validateCellPosition(position) {
 	if (!Number.isInteger(position.row) || !Number.isInteger(position.column) || position.row < 0 || position.column < 0 || !Number.isFinite(position.rowOffset) || !Number.isFinite(position.columnOffset)) throw new Error("SHEET_DRAWING_PLACEMENT_CELL_INVALID");
 }
-function validateExtent(width, height) {
-	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) throw new Error("SHEET_DRAWING_PLACEMENT_EXTENT_INVALID");
+function validateExtent(width, height, requiresArea) {
+	const hasInvalidZeroExtent = requiresArea ? width === 0 || height === 0 : width === 0 && height === 0;
+	if (!Number.isFinite(width) || !Number.isFinite(height) || width < 0 || height < 0 || hasInvalidZeroExtent) throw Object.assign(/* @__PURE__ */ new Error("SHEET_DRAWING_PLACEMENT_EXTENT_INVALID"), {
+		width,
+		height
+	});
 }
 
 //#endregion
@@ -735,7 +742,7 @@ const SetWorksheetBackgroundImageCommand = {
 };
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
@@ -743,7 +750,7 @@ function __decorateParam(paramIndex, decorator) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -927,7 +934,7 @@ SheetsDrawingLoadController = __decorate([
 //#endregion
 //#region package.json
 var name = "@univerjs/sheets-drawing";
-var version = "1.0.3";
+var version = "1.1.0";
 
 //#endregion
 //#region src/config/config.ts
@@ -951,7 +958,7 @@ const configSymbol = Symbol(SHEETS_DRAWING_PLUGIN_CONFIG_KEY);
 const defaultPluginConfig = {};
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -962,7 +969,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -975,14 +982,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -1061,12 +1068,11 @@ const REFRESH_MUTATIONS = [
 	SetWorksheetColWidthMutation.id
 ];
 let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffectedController extends Disposable {
-	constructor(_commandService, _sheetSkeletonService, _sheetInterceptorService, _selectionManagerService, _sheetDrawingService, _drawingManagerService, _univerInstanceService, _transformPlanService) {
+	constructor(_commandService, _sheetSkeletonService, _sheetInterceptorService, _sheetDrawingService, _drawingManagerService, _univerInstanceService, _transformPlanService) {
 		super();
 		this._commandService = _commandService;
 		this._sheetSkeletonService = _sheetSkeletonService;
 		this._sheetInterceptorService = _sheetInterceptorService;
-		this._selectionManagerService = _selectionManagerService;
 		this._sheetDrawingService = _sheetDrawingService;
 		this._drawingManagerService = _drawingManagerService;
 		this._univerInstanceService = _univerInstanceService;
@@ -1127,70 +1133,13 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 				const { range } = params;
 				return this._getRangeMoveUndo(range, 3);
 			} else if (id === SetRowHiddenCommand.id || id === SetSpecificRowsVisibleCommand.id) {
-				var _this$_selectionManag;
-				const _params = params;
-				const target = getSheetCommandTarget(this._univerInstanceService, _params);
-				if (!target) return {
-					redos: [],
-					undos: []
-				};
-				const { unitId, subUnitId } = target;
-				const ranges = _params.ranges || ((_this$_selectionManag = this._selectionManagerService.getCurrentSelections()) === null || _this$_selectionManag === void 0 ? void 0 : _this$_selectionManag.map((s) => s.range).filter((r) => r.rangeType === RANGE_TYPE.ROW));
-				if (!ranges || ranges.length === 0) return {
-					redos: [],
-					undos: []
-				};
+				const { unitId, subUnitId, ranges } = params;
 				return this._getDrawingUndoForRowVisible(unitId, subUnitId, ranges);
 			} else if (id === SetColHiddenCommand.id || id === SetSpecificColsVisibleCommand.id) {
-				var _this$_selectionManag2;
-				const _params = params;
-				const target = getSheetCommandTarget(this._univerInstanceService, _params);
-				if (!target) return {
-					redos: [],
-					undos: []
-				};
-				const { unitId, subUnitId } = target;
-				const ranges = _params.ranges || ((_this$_selectionManag2 = this._selectionManagerService.getCurrentSelections()) === null || _this$_selectionManag2 === void 0 ? void 0 : _this$_selectionManag2.map((s) => s.range).filter((r) => r.rangeType === RANGE_TYPE.COLUMN));
-				if (!ranges || ranges.length === 0) return {
-					redos: [],
-					undos: []
-				};
+				const { unitId, subUnitId, ranges } = params;
 				return this._getDrawingUndoForColVisible(unitId, subUnitId, ranges);
-			} else if (id === DeltaRowHeightCommand.id || id === DeltaColumnWidthCommand.id) {
-				const target = getSheetCommandTarget(this._univerInstanceService);
-				if (!target) return {
-					redos: [],
-					undos: []
-				};
-				const { unitId, subUnitId, worksheet } = target;
-				const ranges = [];
-				if (id === DeltaRowHeightCommand.id) ranges.push({
-					startRow: params.anchorRow,
-					endRow: params.anchorRow,
-					startColumn: 0,
-					endColumn: worksheet.getColumnCount() - 1
-				});
-				else ranges.push({
-					startRow: 0,
-					endRow: worksheet.getRowCount() - 1,
-					startColumn: params.anchorCol,
-					endColumn: params.anchorCol
-				});
-				return this._getDrawingUndoForRowAndColSize(unitId, subUnitId, ranges);
-			} else if (id === SetRowHeightCommand.id || id === SetColWidthCommand.id) {
-				var _this$_selectionManag3;
-				const _params = params;
-				const target = getSheetCommandTarget(this._univerInstanceService, _params);
-				if (!target) return {
-					redos: [],
-					undos: []
-				};
-				const { unitId, subUnitId } = target;
-				const ranges = _params.ranges || ((_this$_selectionManag3 = this._selectionManagerService.getCurrentSelections()) === null || _this$_selectionManag3 === void 0 ? void 0 : _this$_selectionManag3.map((s) => s.range));
-				if (!ranges || ranges.length === 0) return {
-					redos: [],
-					undos: []
-				};
+			} else if (id === DeltaRowHeightCommand.id || id === DeltaColumnWidthCommand.id || id === SetRowHeightCommand.id || id === SetColWidthCommand.id) {
+				const { unitId, subUnitId, ranges } = params;
 				return this._getDrawingUndoForRowAndColSize(unitId, subUnitId, ranges);
 			}
 			return {
@@ -1354,7 +1303,7 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 		const deleteDrawings = [];
 		const { sheetTransform, anchorType = "0", transform, unitId, subUnitId, drawingId } = drawing;
 		const sheetSkeletonParam = this._sheetSkeletonService.getSkeletonParam(unitId, subUnitId);
-		if (!sheetTransform || !transform || !sheetSkeletonParam) return {
+		if (anchorType === "2" || !sheetTransform || !transform || !sheetSkeletonParam) return {
 			updateDrawings,
 			deleteDrawings
 		};
@@ -1694,17 +1643,13 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 			const { sheetTransform, transform, anchorType = "0" } = drawing;
 			if (anchorType === "2") this._remainDrawingSize(transform, updateDrawings, drawing, skeleton);
 			else {
-				const { from, to } = sheetTransform;
-				const { row: fromRow, column: fromColumn } = from;
-				const { row: toRow, column: toColumn } = to;
+				const { row: toRow, column: toColumn } = sheetTransform.to;
 				for (let i = 0; i < ranges.length; i++) {
-					const { startRow, endRow, startColumn, endColumn } = ranges[i];
+					const { startRow, startColumn } = ranges[i];
 					if (toRow < startRow || toColumn < startColumn) continue;
 					if (anchorType === "0") {
-						if (fromRow <= startRow && toRow >= endRow || fromColumn <= startColumn && toColumn >= endColumn) {
-							this._remainDrawingSize(transform, updateDrawings, drawing, skeleton);
-							continue;
-						}
+						updateDrawings.push(applySheetDrawingPlacement(drawing, getSheetDrawingPlacement(drawing), skeleton));
+						break;
 					}
 					const newTransform = drawingPositionToTransform({ ...sheetTransform }, sheetSkeletonParam);
 					if (newTransform) {
@@ -1723,10 +1668,8 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 		};
 		return this._createUndoAndRedoMutation(unitId, subUnitId, updateDrawings);
 	}
-	_getUnitIdAndSubUnitId(params, type) {
-		let target;
-		if (type === "insert") target = getSheetCommandTarget(this._univerInstanceService, params);
-		else target = getSheetCommandTarget(this._univerInstanceService);
+	_getUnitIdAndSubUnitId(params) {
+		const target = getSheetCommandTarget(this._univerInstanceService, params);
 		if (!target) return;
 		const { unitId, subUnitId } = target;
 		return {
@@ -1791,7 +1734,7 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 		return this._finalizePlan(unitId, subUnitId, updateDrawings);
 	}
 	_moveRowInterceptor(params, type) {
-		const target = this._getUnitIdAndSubUnitId(params, type);
+		const target = this._getUnitIdAndSubUnitId(params);
 		if (!target) return {
 			redos: [],
 			undos: []
@@ -1859,7 +1802,7 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 		return this._finalizePlan(unitId, subUnitId, updateDrawings, deleteDrawings);
 	}
 	_moveColInterceptor(params, type) {
-		const target = this._getUnitIdAndSubUnitId(params, type);
+		const target = this._getUnitIdAndSubUnitId(params);
 		if (!target) return {
 			redos: [],
 			undos: []
@@ -2254,6 +2197,7 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 	}
 	_refreshDrawingTransform(command, unitId, subUnitId, ranges) {
 		const sheetSkeletonParam = this._getCalculatedSkeletonParam(unitId, subUnitId);
+		if (!sheetSkeletonParam) return;
 		const drawingData = this._drawingManagerService.getDrawingData(unitId, subUnitId) ?? {};
 		const updateDrawings = [];
 		Object.keys(drawingData).forEach((drawingId) => {
@@ -2277,7 +2221,10 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 					startColumn: fromColumn,
 					endColumn: toColumn
 				}) || fromRow > endRow || fromColumn > endColumn) {
-					const isPositionAnchor = anchorType === "0";
+					if (anchorType === "0") {
+						updateDrawings.push(applySheetDrawingPlacement(drawing, getSheetDrawingPlacement(drawing), sheetSkeletonParam.skeleton));
+						break;
+					}
 					const newTransform = drawingPositionToTransform(sheetTransform, sheetSkeletonParam);
 					updateDrawings.push({
 						...drawing,
@@ -2285,8 +2232,8 @@ let SheetDrawingTransformAffectedController = class SheetDrawingTransformAffecte
 							...transform,
 							left: newTransform === null || newTransform === void 0 ? void 0 : newTransform.left,
 							top: newTransform === null || newTransform === void 0 ? void 0 : newTransform.top,
-							width: isPositionAnchor ? transform === null || transform === void 0 ? void 0 : transform.width : newTransform === null || newTransform === void 0 ? void 0 : newTransform.width,
-							height: isPositionAnchor ? transform === null || transform === void 0 ? void 0 : transform.height : newTransform === null || newTransform === void 0 ? void 0 : newTransform.height
+							width: newTransform === null || newTransform === void 0 ? void 0 : newTransform.width,
+							height: newTransform === null || newTransform === void 0 ? void 0 : newTransform.height
 						}
 					});
 					break;
@@ -2300,11 +2247,10 @@ SheetDrawingTransformAffectedController = __decorate([
 	__decorateParam(0, ICommandService),
 	__decorateParam(1, Inject(SheetSkeletonService)),
 	__decorateParam(2, Inject(SheetInterceptorService)),
-	__decorateParam(3, Inject(SheetsSelectionsService)),
-	__decorateParam(4, ISheetDrawingService),
-	__decorateParam(5, IDrawingManagerService),
-	__decorateParam(6, IUniverInstanceService),
-	__decorateParam(7, Inject(SheetDrawingTransformPlanService))
+	__decorateParam(3, ISheetDrawingService),
+	__decorateParam(4, IDrawingManagerService),
+	__decorateParam(5, IUniverInstanceService),
+	__decorateParam(6, Inject(SheetDrawingTransformPlanService))
 ], SheetDrawingTransformAffectedController);
 
 //#endregion

package/lib/facade.js

@@ -6,7 +6,7 @@ import { DrawingApplyType, ISheetDrawingService, InsertSheetDrawingCommand, Remo
 import { getGroupState, transformObjectOutOfGroup } from "@univerjs/engine-render";
 import { FWorksheet } from "@univerjs/sheets/facade";
 
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -17,7 +17,7 @@ function _typeof(o) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -30,14 +30,14 @@ function toPrimitive(t, r) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -48,7 +48,7 @@ function _defineProperty(e, r, t) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
@@ -56,7 +56,7 @@ function __decorateParam(paramIndex, decorator) {
 }
 
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -267,6 +267,23 @@ let FOverGridImageBuilder = class FOverGridImageBuilder {
 		return this._image.imageSourceType;
 	}
 	/**
+	* Set the whole-image opacity from zero (transparent) through one (opaque).
+	* @param {number} opacity The opacity from 0 through 1.
+	* @returns {FOverGridImageBuilder} This builder.
+	*/
+	setOpacity(opacity) {
+		validateImageOpacity(opacity);
+		this._image.opacity = opacity;
+		return this;
+	}
+	/**
+	* Get the configured whole-image opacity.
+	* @returns {number} The opacity from 0 (transparent) through 1 (opaque).
+	*/
+	getOpacity() {
+		return this._image.opacity ?? 1;
+	}
+	/**
 	* Set the horizontal position of the image
 	* @param {number} column - The column index of the image start position, start at 0
 	* @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining
@@ -812,6 +829,35 @@ let FOverGridImage = class FOverGridImage extends FBase {
 		return getSheetDrawingPlacement(current ?? this._image);
 	}
 	/**
+	* Get the current whole-image opacity.
+	* @returns {number} The opacity from 0 (transparent) through 1 (opaque).
+	*/
+	getOpacity() {
+		const current = this._sheetDrawingService.getDrawingByParam({
+			unitId: this._image.unitId,
+			subUnitId: this._image.subUnitId,
+			drawingId: this._image.drawingId
+		});
+		return (current === null || current === void 0 ? void 0 : current.opacity) ?? this._image.opacity ?? 1;
+	}
+	/**
+	* Set the whole-image opacity from zero (transparent) through one (opaque).
+	* @param {number} opacity The opacity from 0 through 1.
+	* @returns {boolean} Whether the update succeeded.
+	*/
+	setOpacity(opacity) {
+		validateImageOpacity(opacity);
+		return this._commandService.syncExecuteCommand(SetSheetDrawingCommand.id, {
+			unitId: this._image.unitId,
+			drawings: [{
+				unitId: this._image.unitId,
+				subUnitId: this._image.subUnitId,
+				drawingId: this._image.drawingId,
+				opacity
+			}]
+		});
+	}
+	/**
 	* Set this image's explicit placement through the drawing command.
 	* `Position`, `Both`, and `None` correspond to OneCell, TwoCell, and
 	* Absolute. Bounds inference is preferable when preserving the current
@@ -1105,6 +1151,9 @@ FOverGridImage = __decorate([
 	__decorateParam(3, ISheetDrawingService),
 	__decorateParam(4, Inject(SheetSkeletonService))
 ], FOverGridImage);
+function validateImageOpacity(opacity) {
+	if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) throw new RangeError("Sheet image opacity must be between 0 and 1.");
+}
 
 //#endregion
 //#region src/facade/f-worksheet.ts