# FPdfImageBuilder

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Detached builder for creating or updating a PDF image.

## Access

Access through:

* [`FPdfImage.toBuilder()`](https://docs.univer.ai/zh-CN/reference/facade/pdf-image.md#tobuilder)
* [`FPdfPage.newImage()`](https://docs.univer.ai/zh-CN/reference/facade/pdf-page.md#newimage)

## Example

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setAbsolutePosition(36, 72)
  .setSize(240, 135)
  .setRotation(15)
  .setCrop({ left: 0, top: 0, right: 100, bottom: 100 })
  .setOpacity(0.75)
  .build()
page.insertImage(imageInfo)
```

## Setup

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

## `@univerjs-pro/pdfs`

### `FPdfImageBuilder.build`

Build detached image information without modifying the PDF.

```typescript
build(): IPdfImageBuilderInfo
```

**Returns**

Detached information for `insertImage` or `updateImage`.

**Throws**

If no image source has been set.

If a placement, crop, or opacity value is invalid.

If the image source does not match its source type.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setAbsolutePosition(36, 72)
  .setSize(240, 135)
  .setRotation(15)
  .setCrop({ left: 0, top: 0, right: 100, bottom: 100 })
  .setOpacity(0.75)
  .build()
page.insertImage(imageInfo)
```

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

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

### `FPdfImageBuilder.setAbsolutePosition`

Set the absolute position in PDF points.

```typescript
setAbsolutePosition(left: number, top: number): this
```

**Parameters**

* `left` — Required. The left position in points.
* `top` — Required. The top position in points.

**Returns**

This builder for chaining.

**Throws**

If either position is not finite.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setAbsolutePosition(36, 72)
  .build()
page.insertImage(imageInfo)
```

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

### `FPdfImageBuilder.setCrop`

Set the detached crop descriptor.

```typescript
setCrop(crop: IPdfImageCrop): this
```

**Parameters**

* `crop` — Required. The crop offsets.

**Returns**

This builder for chaining.

**Throws**

If a crop value is not finite or the crop rectangle is empty.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setCrop({ left: 0, top: 0, right: 100, bottom: 100 })
  .build()
page.insertImage(imageInfo)
```

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

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

### `FPdfImageBuilder.setOpacity`

Set the detached image opacity.

```typescript
setOpacity(opacity: number): this
```

**Parameters**

* `opacity` — Required. The opacity from 0 through 1.

**Returns**

This builder for chaining.

**Throws**

If opacity is outside the inclusive 0-through-1 range.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setOpacity(0.75)
  .build()
page.insertImage(imageInfo)
```

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

### `FPdfImageBuilder.setRotation`

Set image rotation in degrees.

```typescript
setRotation(rotation: number): this
```

**Parameters**

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

**Returns**

This builder for chaining.

**Throws**

If the rotation is not finite.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .setSize(240, 135)
  .setRotation(15)
  .build()
page.insertImage(imageInfo)
```

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

### `FPdfImageBuilder.setSize`

Set image width and height in PDF points.

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

**Parameters**

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

**Returns**

This builder for chaining.

**Throws**

If either size is non-finite or not positive.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const builder = pdf?.getPageByIndex(0)?.newImage().setSize(288, 162)
```

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

### `FPdfImageBuilder.setSource`

Set the URL, UUID, or base64 image source.

```typescript
setSource(source: string, imageSourceType?: ImageSourceType): this
```

**Parameters**

* `source` — Required. The image source.
* `imageSourceType` — Optional. The explicit source type, or omit it to infer the type.

**Returns**

This builder for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const imageInfo = page
  .newImage()
  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')
  .build()
page.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/pdfs`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/pdfs.md) · [Type definitions](https://unpkg.com/@univerjs-pro/pdfs@1.0.0-rc.0/lib/types/facade/f-pdf-image.d.ts)