# FDocumentImage

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade API for an image in a document.

## Access

Access through:

* [`FDocument.insertImage()`](https://docs.univer.ai/reference/facade/document.md#insertimage)
* [`FDocument.getImage()`](https://docs.univer.ai/reference/facade/document.md#getimage)
* [`FDocument.getImages()`](https://docs.univer.ai/reference/facade/document.md#getimages)

## Setup

Register [`@univerjs/docs-drawing`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs-drawing.md) or a preset that includes it. In plugin mode, import `@univerjs/docs-drawing/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/docs/getting-started/facade.md).

## `@univerjs/docs-drawing`

### `FDocumentImage.getAngle`

Gets the current clockwise rotation angle.

```typescript
getAngle(): number | undefined
```

**Returns**

The rotation angle in degrees, or `undefined` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getAngle())
}
```

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

### `FDocumentImage.getId`

Gets the drawing id of the image.

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

**Returns**

The drawing id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getId())
}
```

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

### `FDocumentImage.getImageData`

Gets the current raw document image data.

```typescript
getImageData(): IDocImage | null
```

**Returns**

The image data, or `null` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getImageData())
}
```

**Types:** [`IDocImage`](https://unpkg.com/@univerjs/docs-drawing@1.0.0-rc.0/lib/types/services/doc-drawing.service.d.ts)

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

### `FDocumentImage.getPositionH`

Gets the current horizontal position.

```typescript
getPositionH(): IObjectPositionH | null
```

**Returns**

The horizontal position, or `null` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getPositionH())
}
```

**Types:** [`IObjectPositionH`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentImage.getPositionV`

Gets the current vertical position.

```typescript
getPositionV(): IObjectPositionV | null
```

**Returns**

The vertical position, or `null` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getPositionV())
}
```

**Types:** [`IObjectPositionV`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentImage.getSize`

Gets the current image size.

```typescript
getSize(): ISize | null
```

**Returns**

The width and height in pixels, or `null` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getSize())
}
```

**Types:** [`ISize`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/shared/shape.d.ts)

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

### `FDocumentImage.getSource`

Gets the image source supplied at insertion time.

```typescript
getSource(): string | undefined
```

**Returns**

The image source, or `undefined` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getSource())
}
```

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

### `FDocumentImage.getSourceType`

Gets the image source type supplied at insertion time.

```typescript
getSourceType(): ImageSourceType | undefined
```

**Returns**

The image source type, or `undefined` when the image no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getSourceType())
}
```

**Types:** [`ImageSourceType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/services/image-io/image-io.service.d.ts)

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

### `FDocumentImage.getUnitId`

Gets the id of the document containing the image.

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

**Returns**

The document unit id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  console.log(image.getUnitId())
}
```

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

### `FDocumentImage.remove`

Removes the image and its document placeholder.

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

**Returns**

`true` when the remove command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.remove()
  console.log(success)
}
```

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

### `FDocumentImage.setBack`

Moves the image to the back of the drawing order.

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

**Returns**

`true` when the arrange command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setBack()
  console.log(success)
}
```

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

### `FDocumentImage.setBackward`

Moves the image backward by one level in the drawing order.

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

**Returns**

`true` when the arrange command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setBackward()
  console.log(success)
}
```

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

### `FDocumentImage.setForward`

Moves the image forward by one level in the drawing order.

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

**Returns**

`true` when the arrange command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setForward()
  console.log(success)
}
```

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

### `FDocumentImage.setFront`

Moves the image to the front of the drawing order.

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

**Returns**

`true` when the arrange command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setFront()
  console.log(success)
}
```

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

### `FDocumentImage.setPositionH`

Sets the horizontal position of the image.
Inline images are positioned by their document placeholder, so this has a visible effect only when the image
wrapping style is not `TextWrappingStyle.INLINE`.

```typescript
setPositionH(positionH: IObjectPositionH): boolean
```

**Parameters**

* `positionH` — Required. The horizontal position relative to the document.

**Returns**

`true` when the update command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setPositionH({
    relativeFrom: univerAPI.Enum.DocsImageRelativeFromH.MARGIN,
    posOffset: 100,
  })
  console.log(success)
}
```

**Types:** [`IObjectPositionH`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentImage.setPositionV`

Sets the vertical position of the image.
Inline images are positioned by their document placeholder, so this has a visible effect only when the image
wrapping style is not `TextWrappingStyle.INLINE`.

```typescript
setPositionV(positionV: IObjectPositionV): boolean
```

**Parameters**

* `positionV` — Required. The vertical position relative to the document.

**Returns**

`true` when the update command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setPositionV({
    relativeFrom: univerAPI.Enum.DocsImageRelativeFromV.MARGIN,
    posOffset: 100,
  })
  console.log(success)
}
```

**Types:** [`IObjectPositionV`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentImage.setRotate`

Sets the clockwise rotation angle.

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

**Parameters**

* `angle` — Required. The rotation angle in degrees.

**Returns**

`true` when the update command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setRotate(45)
  console.log(success)
}
```

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

### `FDocumentImage.setSize`

Sets the image size.

```typescript
setSize(width: number, height: number): boolean
```

**Parameters**

* `width` — Required. The width in pixels.
* `height` — Required. The height in pixels.

**Returns**

`true` when the update command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  const success = image.setSize(400, 300)
  console.log(success)
}
```

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

### `FDocumentImage.setWrappingStyle`

Sets the image wrapping style.

Use `INLINE` to place the image in the text flow, `WRAP_SQUARE` to flow text beside it, or
`WRAP_TOP_AND_BOTTOM` to keep text above and below it. `BEHIND_TEXT` and `IN_FRONT_OF_TEXT` do not reserve space
in the text layout and can overlap text.

When switching from inline to a floating style in a UI environment, the current visual position is preserved.

```typescript
setWrappingStyle(wrappingStyle: TextWrappingStyle): boolean
```

**Parameters**

* `wrappingStyle` — Required. The wrapping style to apply.

**Returns**

`true` when the update command succeeds; otherwise, `false`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const image = fDocument.getImages()[0]

if (image) {
  // Float the image beside body text without covering it.
  const success = image.setWrappingStyle(univerAPI.Enum.TextWrappingStyle.WRAP_SQUARE)
  console.log(success)
}
```

**Types:** [`TextWrappingStyle`](https://unpkg.com/@univerjs/docs-drawing@1.0.0-rc.0/lib/types/commands/commands/update-doc-drawing-wrapping-style.command.d.ts)

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

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

### `FDocumentImage.createCommentAsync`

Creates a comment anchored to this document 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.getActiveDocument()?.getImages()[0]
await image?.createCommentAsync('Add alternative text.')
```

**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-doc-image.d.ts)

### `FDocumentImage.getComments`

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

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

**Returns**

Matching comment threads in the current document.

**Examples**

```ts
const image = univerAPI.getActiveDocument()?.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-doc-image.d.ts)

### `FDocumentImage.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.getActiveDocument()?.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-doc-image.d.ts)