Images

AnchoredImage

_interface

An image pinned to a worksheet: which workbook media it shows (imageId), where, and the picture's own properties.

interface AnchoredImage extends PictureProperties {
  /** Index into the workbook's media registry (the id {@link Workbook.addImage} returned). */
  readonly imageId: number;
  readonly anchor: ImageAnchor;
}

---

AnchorPoint

_interface

A point in the drawing grid: a 0-based column and row, plus an EMU offset into that cell. The offsets default to zero, pinning the point to the cell's top-left corner.

interface AnchorPoint {
  /** 0-based column index (column A is 0). */
  readonly col: number;
  /** 0-based row index (row 1 is 0). */
  readonly row: number;
  /** Horizontal offset into the cell, in EMUs (914400 per inch). Defaults to 0. */
  readonly colOff?: number;
  /** Vertical offset into the cell, in EMUs. Defaults to 0. */
  readonly rowOff?: number;
}

---

Extent

_interface

A fixed image size in EMUs: the extent of a one-cell anchor, which pixel dimensions convert into via PX_TO_EMU.

interface Extent {
  readonly cx: number;
  readonly cy: number;
}

---

ImageAnchor

_type

Where an image sits on the grid: a rectangle between two cells, or a point plus a fixed extent.

type ImageAnchor = TwoCellAnchor | OneCellAnchor;

---

ImageCrop

_interface

How much of a picture is cut away at each edge, as a fraction of the picture's own size: 0.1 crops a tenth, and a negative value pads the picture out. An absent edge is not cropped.

interface ImageCrop {
  readonly left?: number;
  readonly top?: number;
  readonly right?: number;
  readonly bottom?: number;
}

---

ImageEditAs

_type

How a two-cell-anchored image tracks edits to the cells it spans. twoCell moves and resizes with them; oneCell moves but keeps its size; absolute is pinned to the page and does neither. The schema default, which a file omitting the attribute means, is twoCell; an image authored here without one is written as oneCell, which is this library's own default.

type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';

---

ImageHyperlink

_interface

Where clicking a picture goes: a URL, or a #-prefixed place in this workbook (#Sheet1!C3), as a sheet hyperlink's target spells one.

interface ImageHyperlink {
  readonly target: string;
  /** The text shown when the pointer rests on the picture. */
  readonly tooltip?: string;
}

---

isImageEditAs

_const

Narrow a raw <xdr:twoCellAnchor editAs> token to a known ImageEditAs.

const isImageEditAs: (value: string) => value is ImageEditAs

---

isOneCellAnchor

_function

Narrow an anchor to its one-cell (fixed-extent) form; the complement is TwoCellAnchor.

function isOneCellAnchor(anchor: ImageAnchor): anchor is OneCellAnchor;

---

OneCellAnchor

_interface

A one-cell anchor: a single top-left grid point plus a fixed extent. The image keeps its size as the grid resizes, moving only with its anchor cell. editAs is a two-cell-only attribute and has no place here.

interface OneCellAnchor {
  readonly from: AnchorPoint;
  readonly ext: Extent;
  /** Clockwise rotation in 1/60000 of a degree (`2700000` = 45°), preserved from a loaded file. */
  readonly rotation?: number;
}

---

PictureProperties

_interface

What a picture says about itself beyond which image it shows and where.

interface PictureProperties {
  /** Alternative text: what a screen reader says in place of the picture. */
  readonly description?: string;
  /** The picture's title, shown with its alternative text. */
  readonly title?: string;
  readonly crop?: ImageCrop;
  readonly hyperlink?: ImageHyperlink;
}

---

PortableImage

_interface

An anchored image in workbook-independent form: the picture's own bytes rather than a media id into one particular workbook's registry.

An AnchoredImage means nothing away from that registry: its imageId is an index, and the same index names a different picture (or none) in the next workbook. Attaching the picture itself is what lets an anchor cross that boundary, which is why the transfer form carries bytes where the stored form carries an id.

interface PortableImage extends PictureProperties {
  readonly image: WorkbookImage;
  readonly anchor: ImageAnchor;
}

---

PX_TO_EMU

_const

EMUs per pixel at Excel's notional 96 DPI (914400 EMU/inch ÷ 96 px/inch). The conversion is DPI-independent by construction: a pixel extent is a fixed physical size regardless of screen.

const PX_TO_EMU: 9525

---

TwoCellAnchor

_interface

A two-cell anchor: the image's top-left (from) and bottom-right (to) grid points. The image fills the rectangle between them and reflows as the intervening rows/columns resize; editAs selects how strictly it follows.

interface TwoCellAnchor {
  readonly from: AnchorPoint;
  readonly to: AnchorPoint;
  readonly editAs?: ImageEditAs;
  /** Clockwise rotation in 1/60000 of a degree (`2700000` = 45°), preserved from a loaded file. */
  readonly rotation?: number;
}

---

WorkbookImage

_interface

A picture's bytes and its file kind, as held in the workbook's media registry.

interface WorkbookImage {
  /** Lower-case file extension without a dot: `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
   * name and content type. */
  readonly extension: string;
  readonly data: Uint8Array;
}

---

WorksheetImages

_interface

Every picture a worksheet shows, in the workbook-independent form of PortableImage: the images anchored to the grid, in the order they were added, and the background tiled behind it. Workbook.exportImages produces one, Workbook.importImages applies one.

interface WorksheetImages {
  readonly anchored: readonly PortableImage[];
  readonly background: WorkbookImage | undefined;
}