# FOverGridImage

- Human documentation: [https://docs.univer.ai/reference/facade/over-grid-image](https://docs.univer.ai/reference/facade/over-grid-image)

- Agent Markdown: [https://docs.univer.ai/reference/facade/over-grid-image.md](https://docs.univer.ai/reference/facade/over-grid-image.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/over-grid-image.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/over-grid-image.mdx)

---

## Access

Access through:

* [`FWorksheet.getImages()`](https://docs.univer.ai/reference/facade/worksheet.md#getimages)
* [`FWorksheet.getImageById()`](https://docs.univer.ai/reference/facade/worksheet.md#getimagebyid)
* [`FWorksheet.getActiveImages()`](https://docs.univer.ai/reference/facade/worksheet.md#getactiveimages)

## Setup

Register [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) 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](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@univerjs/sheets-drawing`

### `FOverGridImage.getId`

Get the id of the image

```typescript
getId(): string
```

**Returns**

The id of the image

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.getPlacement`

Get this image's explicit placement.

```typescript
getPlacement(): ISheetDrawingPlacement
```

**Returns**

OneCell, TwoCell, or Absolute placement.

**Examples**

```ts
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]
console.log(image.getPlacement())
```

**Types:** [`ISheetDrawingPlacement`](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/services/sheet-drawing-placement.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.getSubUnitId`

Returns the worksheet id that owns this image.

```typescript
getSubUnitId(): string
```

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.getType`

Get the drawing type of the image

```typescript
getType(): DrawingTypeEnum
```

**Returns**

The drawing type of the image

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-drawing.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.getUnitId`

Returns the workbook unit id that owns this image.

```typescript
getUnitId(): string
```

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.remove`

Remove the image from the sheet

```typescript
remove(): boolean
```

**Returns**

true if the image is removed successfully, otherwise false

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setBack`

Move the image layer to the bottom layer

```typescript
setBack(): boolean
```

**Returns**

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

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setBackward`

Move the image layer backward by one level

```typescript
setBackward(): boolean
```

**Returns**

true if the image is moved backward successfully, otherwise false

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `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.

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

**Parameters**

* `top` — Optional. The number of pixels to crop from the top of the image
* `left` — Optional. The number of pixels to crop from the left side of the image
* `bottom` — Optional. The number of pixels to crop from the bottom of the image
* `right` — 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**

```ts
// 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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setForward`

Move the image layer forward by one level

```typescript
setForward(): boolean
```

**Returns**

true if the image is moved forward successfully, otherwise false

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setFront`

Move the image layer to the top layer

```typescript
setFront(): boolean
```

**Returns**

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

**Examples**

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `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.

```typescript
setPlacement(placement: ISheetDrawingPlacementInput): boolean
```

**Parameters**

* `placement` — Required. Exact placement or bounds with an explicit anchor type.

**Returns**

`true` when the command succeeds.

**Examples**

OneCell

```ts
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

```ts
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]
image.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,
  bounds: { left: 120, top: 80, width: 320, height: 160 },
})
```

TwoCell

```ts
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

```ts
const image = univerAPI.getActiveWorkbook().getActiveSheet().getImages()[0]
image.setPlacement({
  kind: univerAPI.Enum.SheetDrawingAnchorType.None,
  left: 640,
  top: 96,
  width: 320,
  height: 180,
})
```

**Types:** [`ISheetDrawingPlacementInput`](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/services/sheet-drawing-placement.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setPositionAsync`

Set the position of the image

```typescript
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 position
* `column` — Required. The column index of the image start position
* `rowOffset` — Optional. The row offset of the image start position, pixel unit
* `columnOffset` — Optional. The column offset of the image start position, pixel unit

**Returns**

true if the position is set successfully, otherwise false

**Examples**

```ts
// 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)
```

```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.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`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setRotate`

Set the rotation angle of the image

```typescript
setRotate(angle: number): boolean
```

**Parameters**

* `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**

```ts
// set 90 degrees rotation of the image
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?.setRotate(90)
console.log(result)
```

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setSizeAsync`

Set the size of the image

```typescript
setSizeAsync(width: number, height: number): Promise<boolean>
```

**Parameters**

* `width` — Required. The width of the image, pixel unit
* `height` — Required. The height of the image, pixel unit

**Returns**

true if the size is set successfully, otherwise false

**Examples**

```ts
// set the image width 120px and height 50px
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?.setSizeAsync(120, 50)
console.log(result)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.setSource`

Set the source of the image

```typescript
setSource(source: string): boolean
setSource(source: string, sourceType?: ImageSourceType): boolean
```

**Parameters**

* `source` — Required. The source of the image
* `sourceType` — Optional. The source type of the image, default is URL

**Returns**

true if the source is set successfully, otherwise false

**Examples**

```ts
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)
```

```ts
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`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/services/image-io/image-io.service.d.ts)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

### `FOverGridImage.toBuilder`

Convert the image to a FOverGridImageBuilder

```typescript
toBuilder(): FOverGridImageBuilder
```

**Returns**

The builder FOverGridImageBuilder

**Examples**

```ts
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`](https://docs.univer.ai/reference/facade/over-grid-image-builder.md)

**Package:** [`@univerjs/sheets-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/sheets-drawing.md) · [Type definitions](https://unpkg.com/@univerjs/sheets-drawing@1.0.0-rc.0/lib/types/facade/f-over-grid-image.d.ts)

## `@univerjs-pro/shape-thread-comment`

### `FOverGridImage.createCommentAsync`

Creates a comment anchored to this over-grid image.

```typescript
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**

```ts
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]
await image?.createCommentAsync('Replace this image.')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`ElementComment.IFloatingElementCommentCreateOptions`](https://unpkg.com/@univerjs-pro/shape-thread-comment@1.0.0-rc.0/lib/types/facade/element-comment.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment@1.0.0-rc.0/lib/types/facade/f-sheet-image.d.ts)

### `FOverGridImage.getComments`

Returns locally loaded comments anchored to this image's drawing ID.

```typescript
getComments(): ThreadComment.IFacadeThreadCommentInfo[]
```

**Returns**

Matching comment threads in the current worksheet.

**Examples**

```ts
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]
console.log(image?.getComments().length ?? 0)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment@1.0.0-rc.0/lib/types/facade/f-sheet-image.d.ts)

### `FOverGridImage.listCommentsAsync`

Synchronizes known threads and returns comments anchored to this image's drawing ID.

```typescript
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Returns**

A promise resolving to matching synchronized comment threads.

**Examples**

```ts
const image = univerAPI.getActiveWorkbook()?.getActiveSheet()?.getImages()[0]
const comments = image ? await image.listCommentsAsync() : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment@1.0.0-rc.0/lib/types/facade/f-sheet-image.d.ts)