API Reference

Drawing & Image

Packages@univerjs/sheets-drawing

This class should not be instantiated directly. Use factory methods on univerAPI instead.

Overview

@univerjs/sheets-drawing

MethodDescription
buildAsyncAsynchronously build the image and return the image data
getIdGet the id of the image
getUnitIdGet the workbook ID that owns the image
getSubUnitIdGet the worksheet ID that owns the image
getSourceGet the source of the image
getSourceTypeGet the source type of the image
getTypeGet the drawing type of the image
removeRemove the image from the sheet
setAnchorTypeSet the anchor type of the image, whether the position and size change with the cell
setBackMove the image layer to the bottom layer
setBackwardMove the image layer backward by one level
setColumnSet the horizontal position of the image
setColumnOffsetSet the horizontal offset of the image
setCropSet the cropping region of the image by defining the top, bottom, left, and right edges, thereby displaying the specific part of the image you want
setCropBottomSet the cropping region of the image by defining the bottom edges, thereby displaying the specific part of the image you want
setCropLeftSet the cropping region of the image by defining the left edges, thereby displaying the specific part of the image you want
setCropRightSet the cropping region of the image by defining the right edges, thereby displaying the specific part of the image you want
setCropTopSet the cropping region of the image by defining the top edges, thereby displaying the specific part of the image you want
setForwardMove the image layer forward by one level
setFrontMove the image layer to the top layer
setHeightSet the height of the image
setImageSet the initial image configuration for the image builder
setPositionAsyncAsynchronously set the position of the image
setRotateSet the rotation angle of the image
setRowSet the vertical position of the image
setRowOffsetSet the vertical offset of the image
setSizeAsyncSet the size of the image
setSourceSet the source URL of the image
setSubUnitIdSet the sub-unit (worksheet) ID for the image
setUnitIdSet the unit (workbook) ID for the image
setWidthSet the width of the image
toBuilderConvert the image to a FOverGridImageBuilder

APIs

Lifecycle & Creation

buildAsync

Signature

TypeScript
async buildAsync(): Promise<ISheetImage>

Returns

  • Promise<ISheetImage> — See signature above.
Source: @univerjs/sheets-drawing

Getters & Queries

getId

Get the id of the image

Signature

TypeScript
getId(): string

Returns

  • string — The id of the image

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const images = fWorksheet.getImages();images.forEach((image) => {  console.log(image, image.getId());});
Source: @univerjs/sheets-drawing

getUnitId

Get the workbook ID that owns the image.

TypeScript
getUnitId(): string

getSubUnitId

Get the worksheet ID that owns the image.

TypeScript
getSubUnitId(): string

getSource

Get the source of the image

Signature

TypeScript
getSource(): string

Returns

  • string — The source of the image

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const images = fWorksheet.getImages();images.forEach((image) => {  console.log(image, image.toBuilder().getSource());});
Source: @univerjs/sheets-drawing

getSourceType

Get the source type of the image

Signature

TypeScript
getSourceType(): ImageSourceType

Returns

  • ImageSourceType — The source type of the image

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const images = fWorksheet.getImages();images.forEach((image) => {  console.log(image, image.toBuilder().getSourceType());});
Source: @univerjs/sheets-drawing

getType

Get the drawing type of the image

Signature

TypeScript
getType(): DrawingTypeEnum

Returns

  • DrawingTypeEnum — The drawing type of the image

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const images = fWorksheet.getImages();images.forEach((image) => {  console.log(image, image.getType());});
Source: @univerjs/sheets-drawing

Setters & Modifiers

setAnchorType

Set the anchor type of the image, whether the position and size change with the cell

Signature

TypeScript
setAnchorType(anchorType: SheetDrawingAnchorType): FOverGridImageBuilder

Parameters

  • anchorType SheetDrawingAnchorType — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();// 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.const image1 = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(0)  .setRow(5)  .setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Position)  .buildAsync();// image2 position is start from C6 cell, anchor type is Both.// The size and position of the drawing follow the cell changes. When rows or columns are inserted or deleted, the size and position of the drawing change accordingly.const image2 = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(2)  .setRow(5)  .setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Both)  .buildAsync();// image3 position is start from E6 cell, anchor type is None.// The size and position of the drawing do not follow the cell changes. When rows or columns are inserted or deleted, the position and size of the drawing remain unchanged.const image3 = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(4)  .setRow(5)  .setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.None)  .buildAsync();// insert images into the sheetfWorksheet.insertImages([image1, image2, image3]);// after 2 seconds, set the row height of the 5th row to 100px and insert a row before the 5th row.// then observe the position and size changes of the images.setTimeout(() => {  fWorksheet.setRowHeight(5, 100).insertRowBefore(5);}, 2000);
Source: @univerjs/sheets-drawing

setBack

Move the image layer to the bottom layer

Signature

TypeScript
setBack(): boolean

Returns

  • boolean — true if the image is moved to the bottom layer successfully, otherwise false

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setBack();console.log(result);
Source: @univerjs/sheets-drawing

setBackward

Move the image layer backward by one level

Signature

TypeScript
setBackward(): boolean

Returns

  • boolean — true if the image is moved backward successfully, otherwise false

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setBackward();console.log(result);
Source: @univerjs/sheets-drawing

setColumn

Set the horizontal position of the image

Signature

TypeScript
setColumn(column: number): FOverGridImageBuilder

Parameters

  • column number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setColumnOffset

Set the horizontal offset of the image

Signature

TypeScript
setColumnOffset(offset: number): FOverGridImageBuilder

Parameters

  • offset number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setColumnOffset(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setCrop

Set the cropping region of the image by defining the top, bottom, left, and right edges, thereby displaying the specific part of the image you want.

Signature

TypeScript
setCrop(top?: number, left?: number, bottom?: number, right?: number): boolean

Parameters

  • top number (optional) — No description
  • left number (optional) — No description
  • bottom number (optional) — No description
  • right number (optional) — No description

Returns

  • boolean — true if the crop is set successfully, otherwise false

Examples

TypeScript
// set the crop of the image, top 10px, left 10px, bottom 10px, right 10px.const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setCrop(10, 10, 10, 10);console.log(result);
Source: @univerjs/sheets-drawing

setCropBottom

Set the cropping region of the image by defining the bottom edges, thereby displaying the specific part of the image you want.

Signature

TypeScript
setCropBottom(bottom: number): FOverGridImageBuilder

Parameters

  • bottom number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setCropBottom(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setCropLeft

Set the cropping region of the image by defining the left edges, thereby displaying the specific part of the image you want.

Signature

TypeScript
setCropLeft(left: number): FOverGridImageBuilder

Parameters

  • left number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setCropLeft(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setCropRight

Set the cropping region of the image by defining the right edges, thereby displaying the specific part of the image you want.

Signature

TypeScript
setCropRight(right: number): FOverGridImageBuilder

Parameters

  • right number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setCropRight(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setCropTop

Set the cropping region of the image by defining the top edges, thereby displaying the specific part of the image you want.

Signature

TypeScript
setCropTop(top: number): FOverGridImageBuilder

Parameters

  • top number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setCropTop(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setForward

Move the image layer forward by one level

Signature

TypeScript
setForward(): boolean

Returns

  • boolean — true if the image is moved forward successfully, otherwise false

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setForward();console.log(result);
Source: @univerjs/sheets-drawing

setFront

Move the image layer to the top layer

Signature

TypeScript
setFront(): boolean

Returns

  • boolean — true if the image is moved to the top layer successfully, otherwise false

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setFront();console.log(result);
Source: @univerjs/sheets-drawing

setHeight

Set the height of the image

Signature

TypeScript
setHeight(height: number): FOverGridImageBuilder

Parameters

  • height number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setWidth(120)  .setHeight(50)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setImage

Set the initial image configuration for the image builder.

Signature

TypeScript
setImage(image: ISheetImage): FOverGridImageBuilder

Parameters

  • image ISheetImage — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setImage({    drawingId: '123456',    drawingType: univerAPI.Enum.DrawingType.DRAWING_IMAGE,    imageSourceType: univerAPI.Enum.ImageSourceType.BASE64,    source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',    unitId: fWorkbook.getId(),    subUnitId: fWorksheet.getSheetId(),  })  .setColumn(5)  .setRow(5)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setPositionAsync

Signature

TypeScript
async setPositionAsync(row: number, column: number, rowOffset?: number, columnOffset?: number): Promise<boolean>

Parameters

  • row number — No description
  • column number — No description
  • rowOffset number (optional) — No description
  • columnOffset number (optional) — No description

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-drawing

setRotate

Set the rotation angle of the image

Signature

TypeScript
setRotate(angle: number): boolean

Parameters

  • angle number — No description

Returns

  • boolean — true if the rotation is set successfully, otherwise false

Examples

TypeScript
// set 90 degrees rotation of the imageconst fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setRotate(90);console.log(result);
Source: @univerjs/sheets-drawing

setRow

Set the vertical position of the image

Signature

TypeScript
setRow(row: number): FOverGridImageBuilder

Parameters

  • row number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setRowOffset

Set the vertical offset of the image

Signature

TypeScript
setRowOffset(offset: number): FOverGridImageBuilder

Parameters

  • offset number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setRowOffset(10)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

setSizeAsync

Set the size of the image

Signature

TypeScript
async setSizeAsync(width: number, height: number): Promise<boolean>

Parameters

  • width number — No description
  • height number — No description

Returns

  • Promise<boolean> — true if the size is set successfully, otherwise false

Examples

TypeScript
// set the image width 120px and height 50pxconst fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.setSizeAsync(120, 50);console.log(result);
Source: @univerjs/sheets-drawing

setSource

Signature

TypeScript
setSource(source: string, sourceType?: ImageSourceType): boolean

Parameters

  • source string — No description
  • sourceType ImageSourceType (optional) — No description

Returns

  • boolean — See signature above.
Source: @univerjs/sheets-drawing

setSubUnitId

Signature

TypeScript
setSubUnitId(subUnitId: string): FOverGridImageBuilder

Parameters

  • subUnitId string — No description

Returns

  • FOverGridImageBuilder — See signature above.
Source: @univerjs/sheets-drawing

setUnitId

Signature

TypeScript
setUnitId(unitId: string): FOverGridImageBuilder

Parameters

  • unitId string — No description

Returns

  • FOverGridImageBuilder — See signature above.
Source: @univerjs/sheets-drawing

setWidth

Set the width of the image

Signature

TypeScript
setWidth(width: number): FOverGridImageBuilder

Parameters

  • width number — No description

Returns

  • FOverGridImageBuilder — The FOverGridImageBuilder for chaining

Examples

TypeScript
// 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 image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setWidth(120)  .setHeight(50)  .buildAsync();fWorksheet.insertImages([image]);
Source: @univerjs/sheets-drawing

Actions & Operations

remove

Remove the image from the sheet

Signature

TypeScript
remove(): boolean

Returns

  • boolean — true if the image is removed successfully, otherwise false

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const image = fWorksheet.getImages()[0];const result = image?.remove();console.log(result);
Source: @univerjs/sheets-drawing

Miscellaneous

toBuilder

Convert the image to a FOverGridImageBuilder

Signature

TypeScript
toBuilder(): FOverGridImageBuilder

Returns

  • FOverGridImageBuilder — The builder FOverGridImageBuilder

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();const images = fWorksheet.getImages();images.forEach((image) => {  console.log(image, image.toBuilder().getSource());});
Source: @univerjs/sheets-drawing

How is this guide?

© 2026 DreamNum Co., Ltd.