FOverGridImage
Access
Access through:
Setup
Register @univerjs/sheets-drawing or a preset that includes it. In plugin mode, import @univerjs/sheets-drawing/facade. Additional methods below require their listed plugin packages. See Facade setup.
@univerjs/sheets-drawing
FOverGridImage.getId
Get the id of the image
getId(): stringReturns
The id of the image
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const images = fWorksheet.getImages()images.forEach((image) => { console.log(image, image.getId())})Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.getPlacement
Get this image's explicit placement.
getPlacement(): ISheetDrawingPlacementReturns
OneCell, TwoCell, or Absolute placement.
Examples
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]console.log(image.getPlacement())Types: ISheetDrawingPlacement
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.getSubUnitId
Returns the worksheet id that owns this image.
getSubUnitId(): stringPackage: @univerjs/sheets-drawing · Type definitions
FOverGridImage.getType
Get the drawing type of the image
getType(): DrawingTypeEnumReturns
The drawing type of the image
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const images = fWorksheet.getImages()images.forEach((image) => { console.log(image, image.getType())})Types: DrawingTypeEnum
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.getUnitId
Returns the workbook unit id that owns this image.
getUnitId(): stringPackage: @univerjs/sheets-drawing · Type definitions
FOverGridImage.remove
Remove the image from the sheet
remove(): booleanReturns
true if the image is removed successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.remove()console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setBack
Move the image layer to the bottom layer
setBack(): booleanReturns
true if the image is moved to the bottom layer successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setBack()console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setBackward
Move the image layer backward by one level
setBackward(): booleanReturns
true if the image is moved backward successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setBackward()console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.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.
setCrop(top?: number, left?: number, bottom?: number, right?: number): booleanParameters
top— Optional. The number of pixels to crop from the top of the imageleft— Optional. The number of pixels to crop from the left side of the imagebottom— Optional. The number of pixels to crop from the bottom of the imageright— Optional. The number of pixels to crop from the right side of the image
Returns
true if the crop is set successfully, otherwise false
Examples
// set the crop of the image, top 10px, left 10px, bottom 10px, right 10px.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setCrop(10, 10, 10, 10)console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setForward
Move the image layer forward by one level
setForward(): booleanReturns
true if the image is moved forward successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setForward()console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setFront
Move the image layer to the top layer
setFront(): booleanReturns
true if the image is moved to the top layer successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setFront()console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setPlacement
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
visual bounds; exact markers are for user-selected cells and offsets.
setPlacement(placement: ISheetDrawingPlacementInput): booleanParameters
placement— Required. Exact placement or bounds with an explicit anchor type.
Returns
true when the command succeeds.
Examples
OneCell
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]image.setPlacement({ kind: univerAPI.Enum.SheetDrawingAnchorType.Position, from: { row: 4, column: 3, rowOffset: 8, columnOffset: 8 }, width: 320, height: 180,})Infer TwoCell markers while preserving current model-space bounds
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]image.setPlacement({ kind: univerAPI.Enum.SheetDrawingAnchorType.Both, bounds: { left: 120, top: 80, width: 320, height: 160 },})TwoCell
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]image.setPlacement({ kind: univerAPI.Enum.SheetDrawingAnchorType.Both, from: { row: 4, column: 3, rowOffset: 8, columnOffset: 8 }, to: { row: 10, column: 8, rowOffset: 0, columnOffset: 0 },})Absolute
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]image.setPlacement({ kind: univerAPI.Enum.SheetDrawingAnchorType.None, left: 640, top: 96, width: 320, height: 180,})Types: ISheetDrawingPlacementInput
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setPositionAsync
Set the position of the image
setPositionAsync(row: number, column: number): Promise<boolean>setPositionAsync(row: number, column: number, rowOffset?: number, columnOffset?: number): Promise<boolean>Parameters
row— Required. The row index of the image start positioncolumn— Required. The column index of the image start positionrowOffset— Optional. The row offset of the image start position, pixel unitcolumnOffset— Optional. The column offset of the image start position, pixel unit
Returns
true if the position is set successfully, otherwise false
Examples
// set the position of the image, the start position is F6 cell.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setPositionAsync(5, 5)console.log(result)// set the position of the image, the start position is F6 cell, and the offset is 10px.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setPositionAsync(5, 5, 10, 10)console.log(result)Types: Promise
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setRotate
Set the rotation angle of the image
setRotate(angle: number): booleanParameters
angle— Required. Degree of rotation of the image, for example, 90, 180, 270, etc.
Returns
true if the rotation is set successfully, otherwise false
Examples
// set 90 degrees rotation of the imageconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setRotate(90)console.log(result)Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setSizeAsync
Set the size of the image
setSizeAsync(width: number, height: number): Promise<boolean>Parameters
width— Required. The width of the image, pixel unitheight— Required. The height of the image, pixel unit
Returns
true if the size is set successfully, otherwise false
Examples
// set the image width 120px and height 50pxconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setSizeAsync(120, 50)console.log(result)Types: Promise
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.setSource
Set the source of the image
setSource(source: string): booleansetSource(source: string, sourceType?: ImageSourceType): booleanParameters
source— Required. The source of the imagesourceType— Optional. The source type of the image, default is URL
Returns
true if the source is set successfully, otherwise false
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const image = fWorksheet.getImages()[0]const result = image?.setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')console.log(result)const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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)Types: ImageSourceType
Package: @univerjs/sheets-drawing · Type definitions
FOverGridImage.toBuilder
Convert the image to a FOverGridImageBuilder
toBuilder(): FOverGridImageBuilderReturns
The builder FOverGridImageBuilder
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const images = fWorksheet.getImages()images.forEach((image) => { console.log(image, image.toBuilder().getSource())})Types: FOverGridImageBuilder
Package: @univerjs/sheets-drawing · Type definitions
@univerjs-pro/shape-thread-comment
FOverGridImage.createCommentAsync
Creates a comment anchored to this over-grid image.
createCommentAsync(content: ThreadComment.ThreadCommentContent, options?: ElementComment.IFloatingElementCommentCreateOptions): Promise<boolean>Parameters
content— Required. Plain text or a Univer document body for rich comment content.options— Optional. Default:{}. Optional stable IDs, author, attachments, and creation time.
Returns
true when the create command succeeds; otherwise, false.
Throws
If the content is empty.
Examples
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]await image?.createCommentAsync('Replace this image.')Types: Promise · ThreadComment.ThreadCommentContent · ElementComment.IFloatingElementCommentCreateOptions
Package: @univerjs-pro/shape-thread-comment · Type definitions
FOverGridImage.getComments
Returns locally loaded comments anchored to this image's drawing ID.
getComments(): ThreadComment.IFacadeThreadCommentInfo[]Returns
Matching comment threads in the current worksheet.
Examples
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]console.log(image?.getComments().length ?? 0)Types: ThreadComment.IFacadeThreadCommentInfo
Package: @univerjs-pro/shape-thread-comment · Type definitions
FOverGridImage.listCommentsAsync
Synchronizes known threads and returns comments anchored to this image's drawing ID.
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>Returns
A promise resolving to matching synchronized comment threads.
Examples
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]const comments = image ? await image.listCommentsAsync() : []console.log(comments.length)Types: ThreadComment.IFacadeThreadCommentInfo · Promise
Package: @univerjs-pro/shape-thread-comment · Type definitions
How is this guide?