Référence de l’API

FImageBuilder

Cette page API est actuellement disponible en anglais. Les signatures et identifiants restent identiques dans toutes les langues.

The slide image builder. It is used to create or update an image in a slide. Unlike UI insertion, this builder requires an explicit image source and does not open a file picker.

Access

Access through:

Example

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setAbsolutePosition(80, 120)  .setSize(320, 180)  .setRotation(15)  .setCrop({    left: 10,    top: 10,    right: 10,    bottom: 10,  })  .setClipShape(univerAPI.Enum.ShapeTypeEnum.RoundRect, { adj1: 5000 })  .build()fSlide.insertImage(imageInfo)

Setup

Register @univerjs-pro/slides or a preset that includes it. In plugin mode, import @univerjs-pro/slides/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/slides

FImageBuilder.adjustValues

The adjust values of the image clip shape.

TypeScript
adjustValues: Record<string, number>

Types: Record

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.build

Builds the image builder info. This method does not automatically draw the image on the slide. A new image must be inserted via fSlide.insertImage(imageInfo), and an existing image should be updated via fSlide.updateImage(imageInfo).

TypeScript
build(): ISlideImageBuilderInfo

Returns

The image builder info.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png')  .setAbsolutePosition(80, 120)  .setSize(320, 180)  .build()fSlide.insertImage(imageInfo)

Types: ISlideImageBuilderInfo

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.crop

The crop rectangle of the image.

TypeScript
crop: ISlideImageElement['crop']

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.elementId

The image element id.

TypeScript
elementId: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.imageSourceType

The image source type.

TypeScript
imageSourceType: ImageSourceType

Types: ImageSourceType

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.prstGeom

The preset shape used to clip the image.

TypeScript
prstGeom: ShapeTypeEnum

Types: ShapeTypeEnum

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setAbsolutePosition

Sets the position by absolute slide coordinates.

TypeScript
setAbsolutePosition(left: number, top: number): this

Parameters

  • left — Required. The x-coordinate of the image's top-left corner.
  • top — Required. The y-coordinate of the image's top-left corner.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setAbsolutePosition(80, 120)  .build()fSlide.insertImage(imageInfo)

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setClipShape

Sets the preset shape used to clip the image.

TypeScript
setClipShape(prstGeom?: ShapeTypeEnum, adjustValues?: Record<string, number>): this

Parameters

  • prstGeom — Optional. The preset shape type.
  • adjustValues — Optional. Optional adjust values for the clip shape.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setClipShape(univerAPI.Enum.ShapeTypeEnum.RoundRect, { adj1: 5000 })  .build()fSlide.insertImage(imageInfo)

Types: ShapeTypeEnum · Record

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setCrop

Sets the crop rectangle of the image.

TypeScript
setCrop(crop: ISlideImageElement['crop']): this

Parameters

  • crop — Required. The crop rectangle.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setCrop({    left: 10,    top: 10,    right: 10,    bottom: 10,  })  .build()fSlide.insertImage(imageInfo)

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setRotation

Sets the rotation of the image in degrees.

TypeScript
setRotation(rotation: number): this

Parameters

  • rotation — Required. The rotation in degrees.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setRotation(15)  .build()fSlide.insertImage(imageInfo)

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setShapeData

Sets shape-style data for the image frame, such as picture border.

TypeScript
setShapeData(shapeData: ISlideImageElement['shapeData']): this

Parameters

  • shapeData — Required. Shape-style data reused from the shape model.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setShapeData({    stroke: {      color: '#FF0000',      width: 2,      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,    },  })  .build()fSlide.insertImage(imageInfo)

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setSize

Sets the image size in slide pixels.

TypeScript
setSize(width: number, height: number): this

Parameters

  • width — Required. The image width.
  • height — Required. The image height.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .setSize(320, 180)  .build()fSlide.insertImage(imageInfo)

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.setSource

Sets the image source.

TypeScript
setSource(source: string, imageSourceType?: ImageSourceType): this

Parameters

  • source — Required. The image URL, base64 data URI, or image id.
  • imageSourceType — Optional. The image source type. Which can be found from ImageSourceType.

Returns

This builder, for chaining.

Examples

TypeScript
const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const imageInfo = fSlide  .newImage()  .setSource('https://example.com/image.png', univerAPI.Enum.ImageSourceType.URL)  .build()fSlide.insertImage(imageInfo)

Types: ImageSourceType

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.shapeData

Shape-style data for the image frame.

TypeScript
shapeData: ISlideImageElement['shapeData']

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.source

The image URL, base64 data URI, or image id.

TypeScript
source: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.subUnitId

The slide id where the image is located.

TypeScript
subUnitId: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.transform

The shape transform containing position, size, rotation, and flip values.

TypeScript
transform: ISlideDrawingTransform

Types: ISlideDrawingTransform

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.unitId

The presentation id where the image is located.

TypeScript
unitId: string

Package: @univerjs-pro/slides · Type definitions

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.