API 参考

FImageBuilder

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。

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

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

TypeScript
crop: ISlideImageElement['crop']

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.elementId

TypeScript
elementId: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.imageSourceType

TypeScript
imageSourceType: ImageSourceType

Types: ImageSourceType

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.prstGeom

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

TypeScript
shapeData: ISlideImageElement['shapeData']

Types: ISlideImageElement

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.source

TypeScript
source: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.subUnitId

TypeScript
subUnitId: string

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.transform

TypeScript
transform: ISlideDrawingTransform

Types: ISlideDrawingTransform

Package: @univerjs-pro/slides · Type definitions

FImageBuilder.unitId

TypeScript
unitId: string

Package: @univerjs-pro/slides · Type definitions

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.