FDocumentImage

Facade API for an image in a document.

Access

Access through:

• FDocument.insertImage()
• FDocument.getImage()
• FDocument.getImages()

Setup

Register @univerjs/docs-drawing 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.

@univerjs/docs-drawing

FDocumentImage.getAngle

Gets the current clockwise rotation angle.

getAngle(): number | undefined

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getAngle())}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getId

Gets the drawing id of the image.

getId(): string

Returns

The drawing id.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getId())}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getImageData

Gets the current raw document image data.

getImageData(): IDocImage | null

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getImageData())}

Types: IDocImage

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getPositionH

Gets the current horizontal position.

getPositionH(): IObjectPositionH | null

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getPositionH())}

Types: IObjectPositionH

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getPositionV

Gets the current vertical position.

getPositionV(): IObjectPositionV | null

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getPositionV())}

Types: IObjectPositionV

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getSize

Gets the current image size.

getSize(): ISize | null

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getSize())}

Types: ISize

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getSource

Gets the image source supplied at insertion time.

getSource(): string | undefined

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getSource())}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getSourceType

Gets the image source type supplied at insertion time.

getSourceType(): ImageSourceType | undefined

Returns

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

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getSourceType())}

Types: ImageSourceType

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.getUnitId

Gets the id of the document containing the image.

getUnitId(): string

Returns

The document unit id.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  console.log(image.getUnitId())}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.remove

Removes the image and its document placeholder.

remove(): boolean

Returns

true when the remove command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.remove()  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setBack

Moves the image to the back of the drawing order.

setBack(): boolean

Returns

true when the arrange command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setBack()  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setBackward

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

setBackward(): boolean

Returns

true when the arrange command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setBackward()  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setForward

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

setForward(): boolean

Returns

true when the arrange command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setForward()  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setFront

Moves the image to the front of the drawing order.

setFront(): boolean

Returns

true when the arrange command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setFront()  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

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.

setPositionH(positionH: IObjectPositionH): boolean

Parameters

• positionH — Required. The horizontal position relative to the document.

Returns

true when the update command succeeds; otherwise, false.

Examples

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

Package: @univerjs/docs-drawing · Type definitions

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.

setPositionV(positionV: IObjectPositionV): boolean

Parameters

• positionV — Required. The vertical position relative to the document.

Returns

true when the update command succeeds; otherwise, false.

Examples

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

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setRotate

Sets the clockwise rotation angle.

setRotate(angle: number): boolean

Parameters

• angle — Required. The rotation angle in degrees.

Returns

true when the update command succeeds; otherwise, false.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setRotate(45)  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

FDocumentImage.setSize

Sets the image size.

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

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImages()[0]if (image) {  const success = image.setSize(400, 300)  console.log(success)}

Package: @univerjs/docs-drawing · Type definitions

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.

setWrappingStyle(wrappingStyle: TextWrappingStyle): boolean

Parameters

• wrappingStyle — Required. The wrapping style to apply.

Returns

true when the update command succeeds; otherwise, false.

Examples

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

Package: @univerjs/docs-drawing · Type definitions

@univerjs-pro/shape-thread-comment

FDocumentImage.createCommentAsync

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

Types: Promise · ThreadComment.ThreadCommentContent · ElementComment.IFloatingElementCommentCreateOptions

Package: @univerjs-pro/shape-thread-comment · Type definitions

FDocumentImage.getComments

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

getComments(): ThreadComment.IFacadeThreadCommentInfo[]

Returns

Matching comment threads in the current document.

Examples

const image = univerAPI.getActiveDocument()?.getImages()[0]console.log(image?.getComments().length ?? 0)

Types: ThreadComment.IFacadeThreadCommentInfo

Package: @univerjs-pro/shape-thread-comment · Type definitions

FDocumentImage.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.getActiveDocument()?.getImages()[0]const comments = image ? await image.listCommentsAsync() : []console.log(comments.length)

Types: ThreadComment.IFacadeThreadCommentInfo · Promise

Package: @univerjs-pro/shape-thread-comment · Type definitions