Shape

Shape:

{
  type: "shape";
  extent(): Extent;
  setExtent(extent: Partial<Extent>): void;
  geometry(): ShapeGeometry;
  setGeometry(geometry: ShapeGeometry): void;
  fill(): ShapeFill | null;
  setFill(fill: ShapeFill | null): void;
  outline(): ShapeOutline | null;
  setOutline(outline: ShapeOutline | null): void;
  text(): BlockLevelContainer | null;
  ensureText(): BlockLevelContainer;
}

Represents a shape element within a document.

Remarks

Shape is one of the inline element types that can appear within text content, alongside text and Image elements. A shape has a preset geometry (ShapePreset), a display size, an optional fill and outline, and an optional text body. You obtain Shape objects by iterating through inline elements and checking their type discriminator.

For sizing, a shape exposes only Shape.extent and Shape.setExtent, like Image; rotation and position are not exposed.

Properties

type

type: "shape"

Type discriminator for inline elements.

Remarks

Always has the value 'shape'. Use this property to narrow the inline element type and access shape-specific methods.

Methods

extent()

extent(): Extent

Gets the current display dimensions of the shape, in points

Returns

Extent

An Extent object containing the shape’s width and height

Example

if (inline.type === 'shape') {
  const extent = inline.extent();
  console.log(`Shape: ${extent.width} x ${extent.height}`);
}

---

setExtent()

setExtent(extent): void

Sets the display dimensions of the shape, in points (1 point = 1/72 inch).

Parameters

extent

Partial<Extent>

Partial extent object with width and/or height to set

Returns

void

Remarks

When specifying only one dimension, the other remains unchanged (aspect ratio is not maintained automatically).

Example

shape.setExtent({ width: 120, height: 80 });

---

geometry()

geometry(): ShapeGeometry

Gets the shape’s geometry as a ShapeGeometry.

Returns

ShapeGeometry

Example

const geometry = shape.geometry();
if (geometry.type === 'preset') {
  console.log('preset:', geometry.preset);
}

---

setGeometry()

setGeometry(geometry): void

Sets the shape’s geometry.

Parameters

geometry

ShapeGeometry

A ShapeGeometry (common shapes are listed first in ShapePreset).

Returns

void

Example

shape.setGeometry({ type: 'preset', preset: 'star5' });

---

fill()

fill(): ShapeFill | null

Gets the shape’s fill: null if the shape has no fill, otherwise a ShapeFill whose color is the fill color (or null for a transparent interior).

Returns

ShapeFill | null

Example

const fill = shape.fill();
console.log('fill color:', fill?.color ?? 'none');

---

setFill()

setFill(fill): void

Sets the shape’s fill. Pass null or { color: null } for no fill (a transparent interior), or a ShapeFill with a color to fill it.

Parameters

fill

ShapeFill | null

Returns

void

Example

shape.setFill({ color: '#ff0000' });
shape.setFill(null); // no fill

---

outline()

outline(): ShapeOutline | null

Gets the shape’s outline: null if the shape has no outline, otherwise a ShapeOutline. The outline is drawn only when both its color and width are non-null.

Returns

ShapeOutline | null

Example

const outline = shape.outline();
console.log('outline width:', outline?.width ?? 'none');

---

setOutline()

setOutline(outline): void

Sets the shape’s outline. Pass null — or a ShapeOutline with a null color or width — for no outline, or a ShapeOutline with both a color and a width to draw it.

Parameters

outline

ShapeOutline | null

Returns

void

Example

shape.setOutline({ color: '#000000', width: 1.5 });
shape.setOutline(null); // no outline

---

text()

text(): BlockLevelContainer | null

Gets the shape’s text body as a BlockLevelContainer, or null if the shape has no text body.

Returns

BlockLevelContainer | null

Remarks

Use the returned container to read and modify the paragraphs and tables inside the shape, the same way you would with a table cell or footnote.

This reflects the shape’s existing text body and does not create one: a shape with no text body returns null. Use Shape.ensureText to add a body to a shape that lacks one.

Example

const body = shape.text();
if (body !== null) {
  // read or modify the paragraphs inside the shape
}

---

ensureText()

ensureText(): BlockLevelContainer

Gets the shape’s text body, creating an empty one if the shape has no text body yet, and returns it as a BlockLevelContainer.

Returns

BlockLevelContainer

Remarks

Unlike Shape.text, this never returns null: a shape that had no body gets a new one seeded with a single empty paragraph, ready for content. A shape that already has a body is returned unchanged.

Example

const body = shape.ensureText();
body.blocklevels()[0].asTextView().setText('Label');