# Images

Images are workbook-local worksheet resources. Use `univer run` to create or maintain floating images through the Sheets Drawing facade, then use facade readback to verify command-line results.

This topic covers floating images only. It does not cover cell images, floating DOM, screenshot export, local image upload helpers, or a top-level `univer image` command.

For visual verification, open the workbook with `univer view`.

## Core Workflow

Look up the workbook and worksheet, configure a floating image builder with `newOverGridImage()`, call `buildAsync()`, then pass the result to `insertImages([image])`.

```bash
univer run ./report.univer --code 'async () => {
  const workbook = univerAPI.getActiveWorkbook();
  const sheet = workbook.getSheetByName("Sheet1");
  if (!sheet) return { success: false, error: "Sheet1 not found" };

  const image = await sheet
    .newOverGridImage()
    .setSource("https://example.com/logo.png", univerAPI.Enum.ImageSourceType.URL)
    .setColumn(5)
    .setRow(5)
    .setColumnOffset(10)
    .setRowOffset(10)
    .setWidth(240)
    .setHeight(120)
    .setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Position)
    .buildAsync();

  sheet.insertImages([image]);
  const [inserted] = sheet.getImages();

  return {
    success: true,
    imageCount: sheet.getImages().length,
    imageId: inserted?.getId()
  };
}'
```

`ImageSourceType.URL` is the common source type for web and data URLs. Other enum values are available from `univerAPI.Enum.ImageSourceType`.

## Image Builder

Common builder calls:

- `setSource(source, univerAPI.Enum.ImageSourceType.URL)` sets the image source.
- `setColumn(column)` and `setRow(row)` set the zero-based grid anchor.
- `setColumnOffset(offset)` and `setRowOffset(offset)` set pixel offsets from the anchor cell.
- `setWidth(width)` and `setHeight(height)` set the rendered image size in pixels.
- `setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Position)` controls whether position or size follows row and column changes.
- `setCropTop(top)`, `setCropLeft(left)`, `setCropBottom(bottom)`, and `setCropRight(right)` crop the visible source region.
- `setRotate(angle)` rotates the image.

The builder only prepares image metadata. `buildAsync()` resolves the image data needed by Univer; insert a new image with `insertImages([image])` or update an existing image with `updateImages([newImage])`.

## Enum Usage

Use the source enum to describe how Univer should interpret the `source` argument:

- `univerAPI.Enum.ImageSourceType.URL`: use for HTTP(S) image URLs and full data URLs such as `data:image/png;base64,...` or `data:image/svg+xml;base64,...`.
- `univerAPI.Enum.ImageSourceType.BASE64`: use when `source` is the raw base64 payload without a `data:image/...;base64,` prefix.
- `univerAPI.Enum.ImageSourceType.UUID`: use when the image is already managed by Univer storage and the `source` is the existing image/file UUID. Do not use it for web URLs, data URLs, or raw base64 strings.

Source examples:

```javascript
builder.setSource("https://example.com/logo.png", univerAPI.Enum.ImageSourceType.URL);
builder.setSource("data:image/png;base64,iVBORw0KGgo...", univerAPI.Enum.ImageSourceType.URL);
builder.setSource("iVBORw0KGgo...", univerAPI.Enum.ImageSourceType.BASE64);
builder.setSource("existing-image-file-uuid", univerAPI.Enum.ImageSourceType.UUID);
```

Use the anchor enum to describe how the image follows sheet layout changes:

- `univerAPI.Enum.SheetDrawingAnchorType.Position`: keep the explicit position anchor. Use this for dashboards, logos, stamps, and screenshots where the image should stay at a chosen grid position with its configured size.
- `univerAPI.Enum.SheetDrawingAnchorType.Both`: follow both position and size changes from the surrounding sheet layout. Use this when the image should resize with row or column changes around its anchor area.
- `univerAPI.Enum.SheetDrawingAnchorType.None`: keep the image independent from row and column layout changes. Use this for absolute overlays or decorative assets that should not move or resize when the grid layout changes.

Anchor examples:

```javascript
builder.setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Position); // common reports, logos, stamps
builder.setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.Both); // resize with the sheet layout
builder.setAnchorType(univerAPI.Enum.SheetDrawingAnchorType.None); // absolute overlay independent of grid layout
```

For most CLI-created floating images, start with `ImageSourceType.URL` for web or data URLs and `SheetDrawingAnchorType.Position` for predictable placement.

## Simple Insert Shortcut

For simple URL images, `insertImage(url, column, row, offsetX, offsetY)` inserts directly and returns a boolean result.

```javascript
const inserted = await sheet.insertImage("https://example.com/logo.png", 5, 5, 10, 10);
```

Use `newOverGridImage()` when you need width, height, anchor, crop, rotate, or deterministic builder readback.

## Readback And Maintenance

Use public facade APIs for stable command-line verification:

```javascript
const images = sheet.getImages();
const image = images[0];

return {
  imageCount: images.length,
  imageId: image?.getId(),
  source: image?.toBuilder().getSource(),
  sourceType: image?.toBuilder().getSourceType()
};
```

Useful readback and lookup APIs include:

- `getImages()` returns all floating images on the worksheet.
- `getImageById(id)` returns a single floating image facade object or `null`.
- `getActiveImages()` returns selected images when a selection exists.
- `image.getId()` returns the image drawing id.
- `image.toBuilder().getSource()` returns the current source.
- `image.toBuilder().getSourceType()` returns the current source type.

Avoid asserting private workbook resource storage. Prefer facade evidence such as image count, id, source, source type, and update results.

## Update Image

To update via builder state, initialize from an existing image with `toBuilder()`, then call `updateImages([newImage])`.

```bash
univer run ./report.univer --code 'async () => {
  const workbook = univerAPI.getActiveWorkbook();
  const sheet = workbook.getSheetByName("Sheet1");
  if (!sheet) return { success: false, error: "Sheet1 not found" };

  const image = sheet.getImages()[0];
  if (!image) return { success: false, error: "No floating image found" };

  const newImage = await image
    .toBuilder()
    .setWidth(120)
    .setHeight(60)
    .buildAsync();
  sheet.updateImages([newImage]);

  return {
    success: true,
    imageId: image.getId(),
    imageCount: sheet.getImages().length
  };
}'
```

For direct updates, use methods on `FOverGridImage`:

```javascript
const image = sheet.getImages()[0];
const resized = await image.setSizeAsync(120, 60);
const moved = await image.setPositionAsync(5, 5, 10, 10);
const sourceChanged = image.setSource(
  "https://example.com/updated-logo.png",
  univerAPI.Enum.ImageSourceType.URL
);
```

## Delete Image

To delete images in bulk, pass facade image objects to `deleteImages([image])`.

```bash
univer run ./report.univer --code 'async () => {
  const workbook = univerAPI.getActiveWorkbook();
  const sheet = workbook.getSheetByName("Sheet1");
  if (!sheet) return { success: false, error: "Sheet1 not found" };

  const image = sheet.getImages()[0];
  if (!image) {
    return {
      success: true,
      removed: false,
      remaining: 0
    };
  }

  sheet.deleteImages([image]);

  return {
    success: true,
    removed: true,
    remaining: sheet.getImages().length
  };
}'
```

You can also call `remove()` on a single `FOverGridImage`:

```javascript
const removed = sheet.getImages()[0]?.remove() ?? false;
```

## Headless And Viewer Boundary

Headless `univer run` scripts should verify floating images by reading facade state: `getImages()`, `getImageById(id)`, `getId()`, `toBuilder().getSource()`, and update or delete return values.

Browser rendering belongs to `univer view`, where the readonly workbook viewer loads Drawing UI plugins and paints the visible floating image surface.
