# FPdfImage

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade for one editable managed PDF image.

## Access

Access through:

* [`FPdfPage.getImages()`](https://docs.univer.ai/reference/facade/pdf-page.md#getimages)
* [`FPdfPage.insertImage()`](https://docs.univer.ai/reference/facade/pdf-page.md#insertimage)
* [`FPdfPage.insertImageAsync()`](https://docs.univer.ai/reference/facade/pdf-page.md#insertimageasync)

## Inheritance

Extends [`FPdfPageElement`](https://docs.univer.ai/reference/facade/pdf-page-element.md). Its inherited members are available on this object.

## 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')
  .setSize(240, 135)
  .build()
const image = page.insertImage(imageInfo)
console.log(image.getSource())
console.log(image.getImageSourceType())

image
  .setPosition(36, 72)
  .setRotation(15)
  .setCrop({ left: 0, top: 0, right: 100, bottom: 100 })
  .setOpacity(0.75)
```

## Setup

Register [`@univerjs-pro/pdfs`](https://docs.univer.ai/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/guides/pdfs/getting-started/facade.md).

## `@univerjs-pro/pdfs`

### `FPdfImage.getCrop`

Return a detached crop descriptor.

```typescript
getCrop(): Readonly<IPdfImageCrop> | null
```

**Returns**

The crop offsets, or `null` when uncropped.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
console.log(image?.getCrop())
```

**Types:** [`Readonly`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`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/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)

### `FPdfImage.getImageSourceType`

Return the durable image source kind.

```typescript
getImageSourceType(): ImageSourceType
```

**Returns**

The image source type.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
console.log(image?.getImageSourceType())
```

**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/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)

### `FPdfImage.getOpacity`

Return the current image opacity.

```typescript
getOpacity(): number
```

**Returns**

The opacity from 0 through 1.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
console.log(image?.getOpacity())
```

**Package:** [`@univerjs-pro/pdfs`](https://docs.univer.ai/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)

### `FPdfImage.getSource`

Return the durable image source string.

```typescript
getSource(): string
```

**Returns**

The URL, UUID, or base64 image source.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
console.log(image?.getSource())
```

**Package:** [`@univerjs-pro/pdfs`](https://docs.univer.ai/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)

### `FPdfImage.remove`

Remove this placement and release its managed resource when unreferenced.

```typescript
remove(): void
```

**Throws**

If the image is stale or the durable command is rejected.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
if (image) {
  image.remove()
}
```

**Package:** [`@univerjs-pro/pdfs`](https://docs.univer.ai/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)

### `FPdfImage.setCrop`

Set the visible image crop window.

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

**Parameters**

* `crop` — Required. The crop offsets.

**Returns**

This image Facade for chaining.

**Throws**

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

If the image is stale or the durable command is rejected.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
if (image) {
  image.setCrop({ left: 0, top: 0, right: 100, bottom: 100 })
}
```

**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/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)

### `FPdfImage.setOpacity`

Set image opacity from zero through one.

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

**Parameters**

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

**Returns**

This image Facade for chaining.

**Throws**

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

If the image is stale or the durable command is rejected.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
if (image) {
  image.setOpacity(0.75)
}
```

**Package:** [`@univerjs-pro/pdfs`](https://docs.univer.ai/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)

### `FPdfImage.setSource`

Replace the managed image source atomically.

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

**Parameters**

* `source` — Required. The new URL, UUID, or base64 source.
* `imageSourceType` — Optional. The explicit source type, or omit it to infer the type.

**Returns**

This image Facade for chaining.

**Throws**

If the image source does not match its source type.

If the image is stale or the durable command is rejected.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
if (image) {
  image.setSource('https://example.com/new-image.png')
}
```

**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/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)

### `FPdfImage.toBuilder`

Return a detached builder initialized from this live image.

```typescript
toBuilder(): FPdfImageBuilder
```

**Returns**

A detached builder for this image.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const image = page.getImages()[0]
const info = image?.toBuilder().setSize(320, 180).build()
```

**Types:** [`FPdfImageBuilder`](https://docs.univer.ai/reference/facade/pdf-image-builder.md)

**Package:** [`@univerjs-pro/pdfs`](https://docs.univer.ai/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)