# FImageBuilder

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

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:

* [`FSlide.newImage()`](https://docs.univer.ai/reference/facade/slide.md#newimage)
* [`FImage.toBuilder()`](https://docs.univer.ai/reference/facade/image.md#tobuilder)

## Example

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/slides.md) 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](https://docs.univer.ai/guides/slides/getting-started/facade.md).

## `@univerjs-pro/slides`

### `FImageBuilder.adjustValues`

```ts
adjustValues: Record<string, number>
```

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

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

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

```ts
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`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/facade/f-image.d.ts)

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

### `FImageBuilder.crop`

```ts
crop: ISlideImageElement['crop']
```

**Types:** [`ISlideImageElement`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

### `FImageBuilder.elementId`

```ts
elementId: string
```

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

### `FImageBuilder.imageSourceType`

```ts
imageSourceType: ImageSourceType
```

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

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

### `FImageBuilder.prstGeom`

```ts
prstGeom: ShapeTypeEnum
```

**Types:** [`ShapeTypeEnum`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/facade/f-image.d.ts)

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

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

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

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

```ts
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`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/facade/f-image.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

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

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

```ts
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`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

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

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

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

```ts
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`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

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

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

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

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

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

### `FImageBuilder.shapeData`

```ts
shapeData: ISlideImageElement['shapeData']
```

**Types:** [`ISlideImageElement`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

### `FImageBuilder.source`

```ts
source: string
```

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

### `FImageBuilder.subUnitId`

```ts
subUnitId: string
```

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

### `FImageBuilder.transform`

```ts
transform: ISlideDrawingTransform
```

**Types:** [`ISlideDrawingTransform`](https://unpkg.com/@univerjs-pro/slides@1.0.0-rc.0/lib/types/slide.type.d.ts)

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

### `FImageBuilder.unitId`

```ts
unitId: string
```

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