@univerjs/sheets-drawing 0.24.0 → 0.25.0-insiders.20260608-e4336f7

package/lib/types/facade/f-over-grid-image.d.ts

@@ -36,7 +36,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set initial image configuration.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setImage({
      *     drawingId: '123456',
@@ -63,7 +64,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -80,7 +82,8 @@ export declare class FOverGridImageBuilder {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.toBuilder().getSource());
@@ -94,7 +97,8 @@ export declare class FOverGridImageBuilder {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.toBuilder().getSourceType());
@@ -111,7 +115,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -130,7 +135,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -149,7 +155,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell and horizontal offset is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -169,7 +176,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell and vertical offset is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -189,7 +197,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 120px and height is 50px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -210,7 +219,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 120px and height is 50px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -229,7 +239,8 @@ export declare class FOverGridImageBuilder {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      *
      * // image1 position is start from A6 cell, anchor type is Position.
      * // Only the position of the drawing follows the cell changes. When rows or columns are inserted or deleted, the position of the drawing changes, but the size remains the same.
@@ -278,7 +289,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, top crop is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -298,7 +310,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, left crop is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -318,7 +331,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, bottom crop is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -338,7 +352,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, right crop is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -359,7 +374,8 @@ export declare class FOverGridImageBuilder {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, rotate 90 degrees.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -388,7 +404,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.getId());
@@ -402,7 +419,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.getType());
@@ -416,7 +434,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.remove();
      * console.log(result);
@@ -429,7 +448,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.toBuilder().getSource());
@@ -444,7 +464,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4');
      * console.log(result);
@@ -459,7 +480,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL);
      * console.log(result);
@@ -475,7 +497,8 @@ export declare class FOverGridImage extends FBase {
      * ```ts
      * // set the position of the image, the start position is F6 cell.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setPositionAsync(5, 5);
      * console.log(result);
@@ -492,7 +515,8 @@ export declare class FOverGridImage extends FBase {
      * ```ts
      * // set the position of the image, the start position is F6 cell, and the offset is 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setPositionAsync(5, 5, 10, 10);
      * console.log(result);
@@ -508,7 +532,8 @@ export declare class FOverGridImage extends FBase {
      * ```ts
      * // set the image width 120px and height 50px
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setSizeAsync(120, 50);
      * console.log(result);
@@ -526,7 +551,8 @@ export declare class FOverGridImage extends FBase {
      * ```ts
      * // set the crop of the image, top 10px, left 10px, bottom 10px, right 10px.
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setCrop(10, 10, 10, 10);
      * console.log(result);
@@ -541,7 +567,8 @@ export declare class FOverGridImage extends FBase {
      * ```ts
      * // set 90 degrees rotation of the image
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setRotate(90);
      * console.log(result);
@@ -554,7 +581,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setForward();
      * console.log(result);
@@ -567,7 +595,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setBackward();
      * console.log(result);
@@ -580,7 +609,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setBack();
      * console.log(result);
@@ -593,7 +623,8 @@ export declare class FOverGridImage extends FBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      * const result = image?.setFront();
      * console.log(result);

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import type { IFBlobSource } from '@univerjs/core/facade';
-import type { ISheetImage } from '@univerjs/sheets-drawing';
+import type { ISheetDrawing, ISheetImage } from '@univerjs/sheets-drawing';
 import { FWorksheet } from '@univerjs/sheets/facade';
 import { FOverGridImage, FOverGridImageBuilder } from './f-over-grid-image';
 /**
@@ -28,7 +28,8 @@ export interface IFWorksheetDrawingMixin {
      * @example
      * ```ts
      * // Insert an image to the sheet, default position is A1
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4');
      * console.log(result);
      * ```
@@ -42,7 +43,8 @@ export interface IFWorksheetDrawingMixin {
      * @example
      * ```ts
      * // Insert an image to the sheet, position is F6
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5);
      * console.log(result);
      * ```
@@ -58,7 +60,8 @@ export interface IFWorksheetDrawingMixin {
      * @example
      * ```ts
      * // Insert an image to the sheet, position is F6, offset is 10px
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5, 10, 10);
      * console.log(result);
      * ```
@@ -77,7 +80,8 @@ export interface IFWorksheetDrawingMixin {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -101,7 +105,8 @@ export interface IFWorksheetDrawingMixin {
      * @returns {FOverGridImage[]} The FOverGridImage instances
      * @example
      * ```ts
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getImages();
      * images.forEach((image) => {
      *   console.log(image, image.getId());
@@ -115,7 +120,8 @@ export interface IFWorksheetDrawingMixin {
      * @returns {FOverGridImage | null} The FOverGridImage instance
      * @example
      * ```ts
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImageById('xxxx');
      * console.log(image);
      * ```
@@ -127,7 +133,8 @@ export interface IFWorksheetDrawingMixin {
      * @returns {FWorksheet} The FWorksheet instance for chaining
      * @example
      * ```ts
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = fWorksheet.getImages()[0];
      *
      * // Delete the first image of the sheet
@@ -144,7 +151,8 @@ export interface IFWorksheetDrawingMixin {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -168,7 +176,8 @@ export interface IFWorksheetDrawingMixin {
      * @returns {FOverGridImage[]} The FOverGridImage instances
      * @example
      * ```ts
-     * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+     * const fWorksheet = univerAPI.getActiveWorkbook().getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const images = fWorksheet.getActiveImages();
      * images.forEach((image) => {
      *   console.log(image, image.getId());
@@ -184,7 +193,8 @@ export interface IFWorksheetDrawingMixin {
      * // create a new image builder and set image source.
      * // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const image = await fWorksheet.newOverGridImage()
      *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
      *   .setColumn(5)
@@ -196,6 +206,161 @@ export interface IFWorksheetDrawingMixin {
      * ```
      */
     newOverGridImage(): FOverGridImageBuilder;
+    /**
+     * Group drawings on the current sheet.
+     * @param {string[]} drawingIds - The drawing ids to group. At least two drawings are required.
+     * @param {string} [groupId] - Optional group drawing id. If omitted, a new id will be generated.
+     * @returns {string | null} The group id if the operation succeeds, otherwise null.
+     * @example
+     * ```ts
+     * // Group two over-grid images on the active sheet.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const image1 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(1)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * const image2 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(3)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * fWorksheet.insertImages([image1, image2]);
+     * const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId]);
+     * console.log(groupId);
+     * ```
+     */
+    groupDrawings(drawingIds: string[], groupId?: string): string | null;
+    /**
+     * Ungroup drawing groups on the current sheet.
+     * @param {string[]} groupIds - The group drawing ids to ungroup.
+     * @returns {boolean} true if the operation succeeds, otherwise false.
+     * @example
+     * ```ts
+     * // Group two images, then ungroup the generated group.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const image1 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(1)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * const image2 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(3)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * fWorksheet.insertImages([image1, image2]);
+     * const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId]);
+     * if (groupId) {
+     *   const result = fWorksheet.ungroupDrawings([groupId]);
+     *   console.log(result);
+     * }
+     * ```
+     */
+    ungroupDrawings(groupIds: string[]): boolean;
+    /**
+     * Get children of a drawing group on the current sheet.
+     * @param {string} groupId - The group drawing id.
+     * @param {boolean} [recursive] - Whether to return all descendants.
+     * @returns {ISheetDrawing[]} The child drawings.
+     * @example
+     * ```ts
+     * // Get the direct children of a drawing group.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const image1 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(1)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * const image2 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(3)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * fWorksheet.insertImages([image1, image2]);
+     * const groupId = fWorksheet.groupDrawings([image1.drawingId, image2.drawingId]);
+     * if (groupId) {
+     *   const children = fWorksheet.getDrawingGroupChildren(groupId);
+     *   console.log(children.map((drawing) => drawing.drawingId));
+     * }
+     * ```
+     */
+    getDrawingGroupChildren(groupId: string, recursive?: boolean): ISheetDrawing[];
+    /**
+     * Get the parent group of a drawing on the current sheet.
+     * @param {string} drawingId - The child drawing id.
+     * @returns {ISheetDrawing | null} The parent group drawing, or null if the drawing is not grouped.
+     * @example
+     * ```ts
+     * // Get the parent group of a drawing.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const image1 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(1)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * const image2 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(3)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * fWorksheet.insertImages([image1, image2]);
+     * fWorksheet.groupDrawings([image1.drawingId, image2.drawingId]);
+     * const parentGroup = fWorksheet.getDrawingParentGroup(image1.drawingId);
+     * console.log(parentGroup?.drawingId);
+     * ```
+     */
+    getDrawingParentGroup(drawingId: string): ISheetDrawing | null;
+    /**
+     * Returns whether a drawing is inside a group on the current sheet.
+     * @param {string} drawingId - The drawing id.
+     * @returns {boolean} true if the drawing has a parent group.
+     * @example
+     * ```ts
+     * // Check whether a drawing is inside a group.
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const image1 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(1)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * const image2 = await fWorksheet.newOverGridImage()
+     *   .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)
+     *   .setColumn(3)
+     *   .setRow(1)
+     *   .setWidth(100)
+     *   .setHeight(100)
+     *   .buildAsync();
+     * fWorksheet.insertImages([image1, image2]);
+     * fWorksheet.groupDrawings([image1.drawingId, image2.drawingId]);
+     * const isGrouped = fWorksheet.isDrawingGrouped(image1.drawingId);
+     * console.log(isGrouped);
+     * ```
+     */
+    isDrawingGrouped(drawingId: string): boolean;
 }
 export declare class FWorksheetDrawingMixin extends FWorksheet implements IFWorksheetDrawingMixin {
     insertImage(url: IFBlobSource | string, column?: number, row?: number, offsetX?: number, offsetY?: number): Promise<boolean>;
@@ -206,6 +371,13 @@ export declare class FWorksheetDrawingMixin extends FWorksheet implements IFWork
     getActiveImages(): FOverGridImage[];
     updateImages(sheetImages: ISheetImage[]): FWorksheet;
     newOverGridImage(): FOverGridImageBuilder;
+    groupDrawings(drawingIds: string[], groupId?: string): string | null;
+    ungroupDrawings(groupIds: string[]): boolean;
+    getDrawingGroupChildren(groupId: string, recursive?: boolean): ISheetDrawing[];
+    getDrawingParentGroup(drawingId: string): ISheetDrawing | null;
+    isDrawingGrouped(drawingId: string): boolean;
+    private _applyGroupDrawingOperation;
+    private _invertGroupOperationObjects;
 }
 declare module '@univerjs/sheets/facade' {
     interface FWorksheet extends IFWorksheetDrawingMixin {