FShape

Controls an individual shape in Docs, Slides, or Boards. In Sheets, FSheetShape inherits these methods and adds cell anchoring.

SmartArt, formulas, and comments are operated on the same shape object. Formula and comment methods require the plugin packages listed below.

Editing shape text

Call getText() to obtain FShapeText. Use setText() to replace plain text, setRichText() to write rich text, and setTextStyle() or the individual font/color methods to format it. The same API is inherited by FSheetShape.

The following assumes shape is an existing FShape or FSheetShape returned by the host's shape API:

shape.getText().setText('Quarterly review').setColor('#2563eb').setFontSize(18).setBold(true)

getRichText() returns a detached value. Call copy() to obtain an editable builder, then pass that builder to setRichText() to apply the changes; editing it alone does not update the shape.

Access

Access through:

• FDocument.insertShape()
• FDocument.getShape()
• FDocument.getShapes()
• FSlide.insertShape()
• FSlide.insertSmartArt()
• FSlide.getShape()
• FSlide.getShapes()
• FBoard.insertShape()

Example

Sheet

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')const fShape = fWorksheet.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,})

Doc

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]const fShape = fDocument.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  placement: {    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,    anchor: {      paragraphId: paragraph.getId(),      segmentId: paragraph.getSegmentId(),    },  },})

Slide

const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const fShape = fSlide.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,})

Board

const fBoard = univerAPI.getActiveBoard()const fShape = fBoard.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,})

const snapshot = fShape.getSnapshot()console.log(snapshot)fShape  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Ellipse)  .setSolidFill('#FF0000', 0.5)  .setSize(200, 100)  .setRotation(45)  .setAbsolutePosition(100, 100)  .setStroke({    color: '#000000',    width: 2,    lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,    dashType: univerAPI.Enum.ShapeLineDashEnum.Solid,    capType: univerAPI.Enum.ShapeLineCapEnum.Round,    lineJoinType: univerAPI.Enum.ShapeLineJoinEnum.Round,  })

Setup

Register @univerjs-pro/engine-shape or a preset that includes it. In plugin mode, import @univerjs-pro/engine-shape/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/engine-shape

FShape.bringForward

Moves the Shape forward by one position in its host drawing order.

bringForward(): this

Returns

This Shape facade for chaining.

Examples

fShape.bringForward()

Package: @univerjs-pro/engine-shape · Type definitions

FShape.bringToFront

Moves the Shape to the front of its host drawing order.

bringToFront(): this

Returns

This Shape facade for chaining.

Examples

fShape.bringToFront()

Package: @univerjs-pro/engine-shape · Type definitions

FShape.convertSmartArtToShapes

Converts this SmartArt composite into independently editable host-native Shapes in one undoable command. The returned facades point to the converted Shapes; the original SmartArt Shape no longer exists after success.

convertSmartArtToShapes(): FShape[]

Returns

The converted ordinary Shape facades, or an empty array when conversion fails.

Examples

const convertedShapes = fSmartArt.convertSmartArtToShapes()convertedShapes.forEach((shape) => shape.setName(`Converted ${shape.getId()}`))

Types: FShape

Package: @univerjs-pro/engine-shape · Type definitions

FShape.deleteSmartArtNode

Deletes one logical Text Pane node and its entire descendant subtree.

deleteSmartArtNode(nodeId: string): this

Parameters

• nodeId — Required. The stable id of the node to delete.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const nodeId = data?.rootNodeIds.at(-1)if (nodeId) fSmartArt.deleteSmartArtNode(nodeId)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.demoteSmartArtNode

Demotes one logical node below its preceding sibling when the current layout permits it.

demoteSmartArtNode(nodeId: string): this

Parameters

• nodeId — Required. The stable id of the node to demote.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const nodeId = data?.rootNodeIds[1]if (nodeId) fSmartArt.demoteSmartArtNode(nodeId)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getAdjustHandles

Returns complete information for every adjustment handle exposed by this Shape.

getAdjustHandles(): IShapeAdjustItemResolved[]

Returns

Detached resolved adjustment handles in preset order.

Examples

fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.BlockArc)const handle = fShape.getAdjustHandles().find(({ gdRefR }) => gdRefR === 'adj3')console.log(handle?.type) // 'ahPolar'console.log(handle?.gdRefAng, handle?.gdRefR) // 'adj2', 'adj3'console.log(handle?.currentAdjustValues) // { adj2: 0, adj3: 25000 }console.log(handle?.resolvedMinR, handle?.resolvedMaxR) // 0, 50000

Types: IShapeAdjustItemResolved

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getConnectionSites

Returns the sites where Connector endpoints can attach to this Shape. Coordinates are local to the unrotated Shape bounds. Shapes without connection-site geometry, including Connector Shapes, return an empty array.

getConnectionSites(): IShapeConnectionSite[]

Returns

The sites where Connector endpoints can attach to this Shape.

Examples

const sites = fShape.getConnectionSites()console.log(sites.map(({ index, x, y }) => ({ index, x, y })))

Types: IShapeConnectionSite

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getCustomGeometry

Returns a detached copy of the custom geometry, or null when none is configured.

getCustomGeometry(): IPresetShapeConfig | null

Returns

A detached copy of the custom geometry, or null when none is configured.

Examples

const geometry = fShape.getCustomGeometry()console.log(geometry?.pathLst)

Types: IPresetShapeConfig

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getDescription

Returns the user-facing Shape description.

getDescription(): string | undefined

Returns

The Shape description, or undefined when none is configured.

Examples

console.log(fShape.getDescription())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getEndConnectInfo

Returns the Shape and connection-site index bound to a Connector's end point, or null when unbound.

getEndConnectInfo(): IShapeRelationItem | null

Returns

The Shape and connection-site index bound to a Connector's end point, or null when unbound.

Examples

console.log(fShape.getEndConnectInfo())

Types: IShapeRelationItem

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getHostType

Returns the Univer host type that owns this Shape.

getHostType(): ShapeHostType

Returns

The Univer host type that owns this Shape.

Examples

console.log(fShape.getHostType())

Types: ShapeHostType

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getId

Returns the stable Shape identifier.

getId(): string

Returns

The stable Shape identifier.

Examples

console.log(fShape.getId())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getName

Returns the user-facing Shape name.

getName(): string | undefined

Returns

The Shape name, or undefined when none is configured.

Examples

console.log(fShape.getName())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getShapeData

Returns a detached copy of the current Shape data.

getShapeData(): IShapeData | null

Returns

A detached copy of the current Shape data, or null when the Shape is unavailable.

Examples

const shapeData = fShape.getShapeData()console.log(shapeData?.fill, shapeData?.stroke)

Types: IShapeData

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getShapeType

Returns the current Shape preset type, or null when the Shape is unavailable.

getShapeType(): ShapeTypeEnum | null

Returns

The current Shape preset type, or null when the Shape is unavailable.

Examples

console.log(fShape.getShapeType())

Types: ShapeTypeEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getSmartArtData

Returns a detached copy of the normalized SmartArt content tree, layout, style, and presentation Shapes. Mutating the returned value does not update the slide; call setSmartArtData to replace the model.

getSmartArtData(): ISmartArtData | null

Returns

The detached SmartArt model, or null when this Shape is not SmartArt.

Examples

const data = fSmartArt.getSmartArtData()console.log(data?.layout.id, data?.rootNodeIds)

Types: ISmartArtData

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getSnapshot

Returns a detached snapshot of the Shape and its host identity.

getSnapshot(): IShapeSnapshot | null

Returns

A detached snapshot of the Shape and its host identity, or null when the Shape is unavailable.

Examples

console.log(fShape.getSnapshot())

Types: IShapeSnapshot

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getStartConnectInfo

Returns the Shape and connection-site index bound to a Connector's start point, or null when unbound.

getStartConnectInfo(): IShapeRelationItem | null

Returns

The Shape and connection-site index bound to a Connector's start point, or null when unbound.

Examples

console.log(fShape.getStartConnectInfo())

Types: IShapeRelationItem

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getText

Returns the text facade associated with this Shape.

getText(): FShapeText

Returns

The text facade associated with this Shape.

Examples

fShape.getText().setText('Quarterly review')

Types: FShapeText

Package: @univerjs-pro/engine-shape · Type definitions

FShape.getTransform

Returns a detached copy of the current Shape transform.

getTransform(): IShapeTransform | null

Returns

A detached copy of the current Shape transform, or null when the Shape is unavailable.

Examples

const transform = fShape.getTransform()console.log(transform?.left, transform?.top, transform?.width, transform?.height)

Types: IShapeTransform

Package: @univerjs-pro/engine-shape · Type definitions

FShape.insertSmartArtNode

Inserts one logical Text Pane node relative to an existing node. The new node must have a unique id and an empty childIds array.

insertSmartArtNode(options: IInsertSmartArtNodeOptions): this

Parameters

• options — Required. The new node, target node, and insertion position.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const targetNodeId = data?.rootNodeIds[0]if (!targetNodeId) throw new Error('SmartArt has no root node')fSmartArt.insertSmartArtNode({  targetNodeId,  position: univerAPI.Enum.SmartArtInsertPositionEnum.After,  node: {    id: crypto.randomUUID(),    childIds: [],    role: univerAPI.Enum.SmartArtNodeRoleEnum.Content,    text: { isRichText: false, isHorizontal: true, text: 'New item' },  },})

Types: IInsertSmartArtNodeOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShape.isConnectorShape

Whether this Shape is a Connector preset type.

isConnectorShape(): boolean

Returns

Whether this Shape is a Connector preset type.

Examples

console.log(fShape.isConnectorShape())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.isCustomShape

Returns whether this Shape uses custom geometry.

isCustomShape(): boolean

Returns

Whether this Shape uses custom geometry.

Examples

console.log(fShape.isCustomShape())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.isSelectable

Returns whether the Shape can be selected from the host canvas.

isSelectable(): boolean

Returns

Whether the Shape can be selected.

Examples

console.log(fShape.isSelectable())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.isSmartArt

Returns whether this Shape is an editable SmartArt composite.

isSmartArt(): boolean

Returns

Whether this Shape is SmartArt.

Examples

Slide — executable with univer execute

const presentation = univerAPI.getActivePresentation()const slide = presentation?.getActiveSlide()if (!slide) throw new Error('No active slide')const smartArt = slide.insertSmartArt('urn:microsoft.com/office/officeart/2005/8/layout/default')if (!smartArt) throw new Error('Cannot insert SmartArt')console.log(smartArt.isSmartArt()) // true

Package: @univerjs-pro/engine-shape · Type definitions

FShape.isVisible

Returns whether the Shape is visible in its host.

isVisible(): boolean

Returns

Whether the Shape is visible.

Examples

console.log(fShape.isVisible())

Package: @univerjs-pro/engine-shape · Type definitions

FShape.moveSmartArtNode

Moves one logical node relative to another node without changing its stable identity or descendants.

moveSmartArtNode(options: IMoveSmartArtNodeOptions): this

Parameters

• options — Required. The node to move, target node, and relative position.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const [targetNodeId, nodeId] = data?.rootNodeIds ?? []if (nodeId && targetNodeId) {  fSmartArt.moveSmartArtNode({    nodeId,    targetNodeId,    position: univerAPI.Enum.SmartArtInsertPositionEnum.Before,  })}

Types: IMoveSmartArtNodeOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShape.promoteSmartArtNode

Promotes one logical node by one Text Pane hierarchy level when the current layout permits it.

promoteSmartArtNode(nodeId: string): this

Parameters

• nodeId — Required. The stable id of the node to promote.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const childNodeId = Object.values(data?.nodes ?? {}).find((node) => node.parentId)?.idif (childNodeId) fSmartArt.promoteSmartArtNode(childNodeId)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.remove

Removes the Shape and returns whether the host mutation succeeded.

remove(): boolean

Returns

Whether the shape was successfully removed from its host.

Examples

const removed = fShape.remove()console.log(removed)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.resetAdjustValues

Removes all Shape adjustment overrides and restores preset defaults.

resetAdjustValues(): this

Returns

This Shape facade for chaining.

Examples

fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect).setAdjustValues({ adj: 40000 })fShape.resetAdjustValues()const [handle] = fShape.getAdjustHandles()console.log(handle.currentAdjustValues.adj) // 16667

Package: @univerjs-pro/engine-shape · Type definitions

FShape.sendBackward

Moves the Shape backward by one position in its host drawing order.

sendBackward(): this

Returns

This Shape facade for chaining.

Examples

fShape.sendBackward()

Package: @univerjs-pro/engine-shape · Type definitions

FShape.sendToBack

Moves the Shape to the back of its host drawing order.

sendToBack(): this

Returns

This Shape facade for chaining.

Examples

fShape.sendToBack()

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setAbsolutePosition

Sets the absolute host-document position of the Shape.

In Docs, this changes the configured horizontal and vertical offsets only for non-inline Shapes. Inline Shapes remain positioned by their document text range. The horizontal offset is page-relative and the vertical offset is relative to the anchor paragraph.

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

Parameters

• left — Required. The new Shape left position in host-document units.
• top — Required. The new Shape top position in host-document units.

Returns

This Shape facade for chaining.

Examples

fShape.setAbsolutePosition(160, 96)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setAdjustValues

Updates only the supplied Shape adjustment values and clamps them to their handle ranges.

setAdjustValues(adjustValues: Record<string, number>): this

Parameters

• adjustValues — Required. Adjustment names and values to update.

Returns

This Shape facade for chaining.

Examples

fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect).setAdjustValues({ adj: 75000 })const [handle] = fShape.getAdjustHandles()console.log(handle.currentAdjustValues.adj) // 50000

Types: Record

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setCustomGeometry

Sets detached custom geometry and marks this Shape as custom.

setCustomGeometry(customGeometry: IPresetShapeConfig): this

Parameters

• customGeometry — Required. The new custom geometry.

Returns

This Shape facade for chaining.

Examples

// Replace the preset geometry with an adjustable right arrow.fShape  .setCustomGeometry({    adjustValues: {      adj1: [univerAPI.Enum.ShapeOperatorEnum.Val, 32000],    },    gd: {      dx: [univerAPI.Enum.ShapeOperatorEnum.MulDiv, 'w', 'adj1', 100000],      ix: [univerAPI.Enum.ShapeOperatorEnum.AddSub, 'r', 0, 'dx'],    },    ahLst: [      {        type: 'ahXY',        gdRefX: 'adj1',        minX: 0,        maxX: 50000,        pos: { x: 'dx', y: 'hd2' },      },    ],    cxnLst: [      { ang: 0, x: 'r', y: 'hd2' },      { ang: 180, x: 0, y: 'hd2' },    ],    rect: { l: 'dx', t: 0, r: 'ix', b: 'b' },    pathLst: [      {        dataArray: [          { command: 'M', points: [0, 0] },          { command: 'L', points: ['ix', 0] },          { command: 'L', points: ['r', 'hd2'] },          { command: 'L', points: ['ix', 'b'] },          { command: 'L', points: [0, 'b'] },          { command: 'L', points: ['dx', 'hd2'] },          { command: 'z', points: [] },        ],      },    ],  })  .setSolidFill('#16a34a', 0.92)  .setStroke({    lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,    color: '#14532d',    width: 3,  })

Types: IPresetShapeConfig

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setCustomGeometryFromSvgPath

Replaces this Shape's geometry with one SVG path.

Use this method when the source is an SVG <path> d attribute. Do not pass complete <svg>/<path> markup, a data URL, CSS, transforms, fill colors, or stroke colors in options.pathData. Configure visual styles with Shape facade methods such as setSolidFill(), setNoneFill(), and setStroke().

All standard SVG path commands are supported: M/m, L/l, H/h, V/v, C/c, S/s, Q/q, T/t, A/a, and Z/z. Relative commands and repeated coordinate groups are converted to absolute engine-shape commands. SVG arcs are converted to cubic Bézier segments instead of being misinterpreted as engine-shape's semantically different OOXML A command.

Parsing finishes before the host Shape is updated. Invalid or unsupported path data throws a SyntaxError and leaves the existing Shape geometry unchanged.

setCustomGeometryFromSvgPath(options: IShapeSvgPathGeometryOptions): this

Parameters

• options — Required. SVG path geometry and optional virtual bounds.

Returns

This Shape facade for chaining.

Examples

Board — executable with univer execute

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 300, top: 100, width: 160, height: 200 },})if (!shape) throw new Error('Cannot insert shape')shape  .setCustomGeometryFromSvgPath({    // This is only the value of <path d="...">.    pathData: 'M 50,10 C 34,20 24,64 22,92 L 78,92 C 76,64 66,20 50,10 Z',    width: 100,    height: 100,    fill: 'none',    stroke: true,  })  .setNoneFill()  .setStroke({    lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,    color: '#F0509B',    width: 3,  })return {  id: shape.getId(),  pathCount: shape.getCustomGeometry()?.pathLst?.length ?? 0,}

Types: IShapeSvgPathGeometryOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setDescription

Sets or clears the user-facing Shape description.

setDescription(description?: string): this

Parameters

• description — Optional. The Shape description, or undefined to clear it.

Returns

This Shape facade for chaining.

Examples

fShape.setDescription('Shows the quarterly revenue forecast.')

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setGradientFill

Replaces the current fill with a gradient containing at least two color stops.

setGradientFill(gradientType: ShapeGradientTypeEnum, colorStops: IShapeGradientStop[], gradientAngle?: number): this

Parameters

• gradientType — Required. The new gradient type.
• colorStops — Required. An array of at least two gradient stops.
• gradientAngle — Optional. The new gradient angle in degrees, used only for linear gradients.

Returns

This Shape facade for chaining.

Examples

fShape.setGradientFill(  univerAPI.Enum.ShapeGradientTypeEnum.Linear,  [    { position: 0, color: '#2563eb' },    { position: 1, color: '#a855f7' },  ],  45,)

Types: ShapeGradientTypeEnum · IShapeGradientStop

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setImageFill

Replaces the current fill with an image source and optional image-fill settings.

setImageFill(source: string, imageSourceType?: ImageSourceTypeEnum, options?: IShapeImageFillOptions): this

Parameters

• source — Required. The image source, which can be a URL or base64 data URI.
• imageSourceType — Optional. The type of the image source, either URL or base64.
• options — Optional. Default: {}. Optional image-fill settings, including fill mode, opacity, and rotation behavior.

Returns

This Shape facade for chaining.

Examples

fShape.setImageFill(  'https://github.com/dream-num.png',  univerAPI.Enum.ShapeImageSourceTypeEnum.URL,  { imageOpacity: 0.9 },)

Types: ImageSourceTypeEnum · IShapeImageFillOptions

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setName

Sets or clears the user-facing Shape name.

setName(name?: string): this

Parameters

• name — Optional. The Shape name, or undefined to clear it.

Returns

This Shape facade for chaining.

Examples

fShape.setName('Revenue forecast')

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setNoneFill

Removes the visible fill from this Shape.

setNoneFill(): this

Returns

This Shape facade for chaining.

Examples

fShape.setNoneFill()

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setRotation

Sets the clockwise Shape rotation in degrees.

setRotation(rotation: number): this

Parameters

• rotation — Required. The clockwise Shape rotation in degrees.

Returns

This Shape facade for chaining.

Examples

fShape.setRotation(30)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSelectable

Sets whether the Shape can be selected from the host canvas. This does not change any host-specific hard-lock state.

setSelectable(selectable: boolean): this

Parameters

• selectable — Required. Whether the Shape should be selectable.

Returns

This Shape facade for chaining.

Examples

fShape.setSelectable(false)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setShapeData

Replaces the complete Shape data with a detached copy of the supplied value.

setShapeData(shapeData: IShapeData): this

Parameters

• shapeData — Required. The new Shape data.

Returns

This Shape facade for chaining.

Examples

fShape.setShapeData({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#4f90ff' },})

Types: IShapeData

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setShapeType

Changes the Shape preset type while preserving the remaining Shape data.

setShapeType(shapeType: ShapeTypeEnum): this

Parameters

• shapeType — Required. The new Shape preset type.

Returns

This Shape facade for chaining.

Examples

fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.Ellipse)

Types: ShapeTypeEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSize

Sets the Shape width and height. Both values must be greater than zero.

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

Parameters

• width — Required. The new Shape width in host-document units.
• height — Required. The new Shape height in host-document units.

Returns

This Shape facade for chaining.

Examples

fShape.setSize(240, 120)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSmartArtData

Replaces the complete normalized SmartArt model through the host Shape command. Use the node-specific methods when only one logical node needs to change.

setSmartArtData(data: ISmartArtData): this

Parameters

• data — Required. The complete normalized SmartArt model.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()if (!data) throw new Error('Shape is not SmartArt')fSmartArt.setSmartArtData({  ...data,  direction: univerAPI.Enum.SmartArtDirectionEnum.RightToLeft,})

Types: ISmartArtData

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSmartArtDirection

Sets the SmartArt reading and layout direction.

setSmartArtDirection(direction: SmartArtDirectionEnum): this

Parameters

• direction — Required. The new left-to-right or right-to-left direction.

Returns

This SmartArt facade for chaining.

Examples

fSmartArt.setSmartArtDirection(univerAPI.Enum.SmartArtDirectionEnum.RightToLeft)

Types: SmartArtDirectionEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSmartArtLayout

Switches the SmartArt layout while retaining the logical content tree. The optional category keeps the gallery classification when a custom layout id does not encode it.

setSmartArtLayout(id: string, category?: SmartArtCategoryEnum): this

Parameters

• id — Required. The built-in or imported SmartArt layout id.
• category — Optional. The optional gallery category for the layout.

Returns

This SmartArt facade for chaining.

Examples

fSmartArt.setSmartArtLayout(  'urn:microsoft.com/office/officeart/2005/8/layout/lProcess2',  univerAPI.Enum.SmartArtCategoryEnum.Process,)

Types: SmartArtCategoryEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setSolidFill

Replaces the current fill with a solid color and optional opacity.

setSolidFill(color: string, opacity?: number): this

Parameters

• color — Required. The new fill color.
• opacity — Optional. The new fill opacity, ranging from 0 (completely transparent) to 1 (completely opaque).

Returns

This Shape facade for chaining.

Examples

fShape.setSolidFill('#4f90ff', 0.85)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStroke

Replaces the complete Shape stroke configuration.

setStroke(stroke: IShapeLineStyle): this

Parameters

• stroke — Required. The new Shape stroke configuration.

Returns

This Shape facade for chaining.

Examples

fShape.setStroke({  color: '#1e3a8a',  width: 2,  lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,  dashType: univerAPI.Enum.ShapeLineDashEnum.Dash,})

Types: IShapeLineStyle

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeColor

Sets the stroke color while preserving other stroke properties.

setStrokeColor(color: string): this

Parameters

• color — Required. The new stroke color.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeColor('#1e3a8a')

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeLineCapType

Sets the stroke line-cap preset.

setStrokeLineCapType(lineCapType: ShapeLineCapEnum): this

Parameters

• lineCapType — Required. The new stroke line-cap preset.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeLineCapType(univerAPI.Enum.ShapeLineCapEnum.Round)

Types: ShapeLineCapEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeLineDashType

Sets the stroke dash preset.

setStrokeLineDashType(lineDashType: ShapeLineDashEnum): this

Parameters

• lineDashType — Required. The new stroke dash preset.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeLineDashType(univerAPI.Enum.ShapeLineDashEnum.DashDot)

Types: ShapeLineDashEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeLineJoinType

Sets the stroke line-join preset.

setStrokeLineJoinType(lineJoinType: ShapeLineJoinEnum): this

Parameters

• lineJoinType — Required. The new stroke line-join preset.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeLineJoinType(univerAPI.Enum.ShapeLineJoinEnum.Round)

Types: ShapeLineJoinEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeLineType

Sets the stroke line type.

setStrokeLineType(lineType: ShapeLineTypeEnum): this

Parameters

• lineType — Required. The new stroke line type.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeLineType(univerAPI.Enum.ShapeLineTypeEnum.SolidLine)

Types: ShapeLineTypeEnum

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeOpacity

Sets the stroke opacity while preserving other stroke properties.

setStrokeOpacity(opacity: number): this

Parameters

• opacity — Required. The new stroke opacity, ranging from 0 (completely transparent) to 1 (completely opaque).

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeOpacity(0.6)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setStrokeWidth

Sets the stroke width while preserving other stroke properties.

setStrokeWidth(width: number): this

Parameters

• width — Required. The new stroke width in host-document units.

Returns

This Shape facade for chaining.

Examples

fShape.setStrokeWidth(3)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setTransform

Applies a partial Shape transform update.

In Docs, width, height, and rotation apply to both inline and floating Shapes. Left and top affect only non-inline Shapes because inline placement is controlled by the document text range. Docs also does not currently support changing flipX or flipY.

setTransform(transform: Partial<IShapeTransform>): this

Parameters

• transform — Required. A partial Shape transform update.

Returns

This Shape facade for chaining.

Examples

fShape.setTransform({ left: 120, top: 80, rotation: 15 })

Types: Partial · IShapeTransform

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setVisible

Sets whether the Shape is visible in its host.

setVisible(visible: boolean): this

Parameters

• visible — Required. Whether the Shape should be visible.

Returns

This Shape facade for chaining.

Examples

fShape.setVisible(false)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.setZOrder

Moves the Shape to a zero-based index in its host's persisted drawing order. The host clamps an out-of-range index to its nearest valid position.

setZOrder(index: number): this

Parameters

• index — Required. The zero-based target order index.

Returns

This Shape facade for chaining.

Examples

fShape.setZOrder(2)

Package: @univerjs-pro/engine-shape · Type definitions

FShape.update

Applies a partial Shape update through the registered host adapter.

update(input: IShapeUpdateInput): this

Parameters

• input — Required. A partial Shape update.

Returns

This Shape facade for chaining.

Examples

fShape.update({ transform: { left: 240, top: 120, rotation: 20 } })

Types: IShapeUpdateInput

Package: @univerjs-pro/engine-shape · Type definitions

FShape.updateSmartArtNode

Updates Text Pane text, assistant/content role, or automatic/manual font-size behavior for one logical node.

updateSmartArtNode(nodeId: string, update: Partial<Pick<ISmartArtDataNode, 'fontSizeMode' | 'role' | 'text'>>): this

Parameters

• nodeId — Required. The stable id of the node to update.
• update — Required. The node fields to update.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const nodeId = data?.rootNodeIds[0]const node = nodeId ? data?.nodes[nodeId] : undefinedif (nodeId && node) {  fSmartArt.updateSmartArtNode(nodeId, {    text: { ...node.text, text: 'Updated item' },    fontSizeMode: univerAPI.Enum.SmartArtTextFontSizeModeEnum.Auto,  })}

Types: Partial · Pick · ISmartArtDataNode

Package: @univerjs-pro/engine-shape · Type definitions

FShape.updateSmartArtPresentationShape

Updates the geometry or ordinary Shape styling of one independently editable presentation Shape. This does not change the logical Text Pane tree.

updateSmartArtPresentationShape(presentationShapeId: string, update: Partial<Pick<ISmartArtPresentationShape, 'shapeData' | 'transform'>>): this

Parameters

• presentationShapeId — Required. The stable presentation Shape id.
• update — Required. The geometry or Shape data update.

Returns

This SmartArt facade for chaining.

Examples

const data = fSmartArt.getSmartArtData()const presentationShape = data?.presentationShapes[data.presentationShapeOrder[0]]if (presentationShape) {  fSmartArt.updateSmartArtPresentationShape(presentationShape.id, {    transform: { ...presentationShape.transform, left: presentationShape.transform.left + 12 },  })}

Types: Partial · Pick · ISmartArtPresentationShape

Package: @univerjs-pro/engine-shape · Type definitions

@univerjs-pro/shape-editor

FShape.getFormula

Returns the Formula Shape formula string.

getFormula(): string | null

Returns

Formula text, or null for a missing/non-formula Shape.

Examples

Read a formula from the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')console.log(shape?.getFormula())

Read a formula from the active Document

const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document.')const shape = document.getShape('formula-shape-1')console.log(shape?.getFormula())

Package: @univerjs-pro/shape-editor · Type definitions

FShape.getFormulaNumberFormat

Returns the configured Formula Shape number-format pattern.

getFormulaNumberFormat(): string | null

Returns

Pattern, or null for a missing/non-formula Shape.

Examples

Read a number format in the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')console.log(shape?.getFormulaNumberFormat())

Read a number format in the active Board

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board.')console.log(board.getShape('formula-shape-1')?.getFormulaNumberFormat())

Package: @univerjs-pro/shape-editor · Type definitions

FShape.getFormulaResult

Returns the latest calculated and formatted Formula Shape result.

getFormulaResult(): IFormulaShapeResult | null

Returns

Result snapshot, or null when unavailable.

Examples

Read the currently available result

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board.')const shape = board.getShape('formula-shape-1')if (!shape?.isFormulaShape()) throw new Error('Formula Shape not found.')console.log(shape.getFormulaResult())

Wait for calculation before reading the result

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')if (!shape?.isFormulaShape()) throw new Error('Formula Shape not found.')const formula = univerAPI.getFormula()const applied = formula.onCalculationResultApplied(30_000)shape.setFormula({  formula: '=SUM(A1:B10)',  externalReferences: [], // Required; empty only because this formula has no external Unit.})await appliedconsole.log(shape.getFormulaResult())

Types: IFormulaShapeResult

Package: @univerjs-pro/shape-editor · Type definitions

FShape.isFormulaAnimationEnabled

Returns whether value-change animation is enabled for this Formula Shape.

isFormulaAnimationEnabled(): boolean

Returns

true when enabled; Formula Shapes default to enabled.

Examples

Check animation in the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')console.log(shape?.isFormulaAnimationEnabled() ?? false)

List animated Formula Shapes in the active Board

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board.')const animated = board  .getShapes()  .filter((shape) => shape.isFormulaShape() && shape.isFormulaAnimationEnabled())console.log(animated.map((shape) => shape.getId()))

Package: @univerjs-pro/shape-editor · Type definitions

FShape.isFormulaShape

Returns whether this Shape has a Formula Shape binding.

isFormulaShape(): boolean

Returns

true when the Shape is a Formula Shape.

Examples

Check a Shape in the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')console.log(shape?.isFormulaShape() ?? false)

Find Formula Shapes in the active Board

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board.')const formulaShapes = board.getShapes().filter((shape) => shape.isFormulaShape())console.log(formulaShapes.map((shape) => shape.getId()))

Package: @univerjs-pro/shape-editor · Type definitions

FShape.removeFormula

Removes the Formula binding and converts the Shape to a regular Shape. Existing Shape text and visual styles are preserved.

removeFormula(): this

Returns

This Shape facade for chaining.

Examples

Remove a formula in the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')if (shape?.isFormulaShape()) shape.removeFormula()

Remove a formula in the active Document

const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document.')const shape = document.getShape('formula-shape-1')if (shape?.isFormulaShape()) shape.removeFormula()

Package: @univerjs-pro/shape-editor · Type definitions

FShape.setFormula

Synchronously writes every required Host External Reference and then sets the formula through the Shape host adapter. A regular Shape becomes a Formula Shape when this method is first called. Registering a new non-empty formula marks it dirty. With automatic calculation enabled, callers do not need to call formula.executeCalculation() and the result may finish later. Applications configured with notExecuteFormula: true intentionally use manual calculation and must trigger their calculation batch. If any External Reference cannot be written, the Shape formula is left unchanged. The setter does not parse formula text to guess bindings; an omitted mapping is reported by calculation as an unresolved reference.

A Shape hosted by a worksheet may use its Host-local A1 context, a qualified worksheet reference, or a local structured-table reference, for example =SUM(A1:B10), =SUM(Sheet1!A1:B10), or =SUM(Orders[Amount]). A Shape hosted by a Document, Slide, or Board has no local worksheet context, so references must include the workbook or Base qualifier, for example ='[Sales Workbook]Sheet1'!A1 or =[Sales Base]!Orders[Amount].

OtherFormula ownership does not provide an implicit reference target. Reference targets come only from these formula qualifiers. Prefer univerAPI.getFormula().buildReference(...) instead of assembling these strings manually. Use FormulaReferenceType.SHEET_RANGE for workbook references and FormulaReferenceType.TABLE_COLUMN for Base references; the helper quotes and escapes workbook, Base, worksheet, table, and column names as needed. A qualifier identifies the target but does not load it. externalReferences is therefore mandatory on every call. Every external qualifier used by this authoring operation must include its stable Source Unit binding in that array. externalReferences: [] is valid only when the formula has no external Unit qualifier. It is not a default value for an external formula. If formula.buildReference() already created the same binding, passing it here is still required and the repeated upsert is an idempotent no-op.

Authoring rule:

• Sheet-hosted formula with no external Unit: explicitly pass externalReferences: [].
• Cross-Unit Shape formula: use formula.buildReference() for safe syntax and pass the same stable Source identity in externalReferences.
• Hand-written Shape formula: put every qualifier-to-Unit mapping directly in externalReferences; do not call upsertExternalReference() separately.
• Never pass only a formula string. There is no string overload.

setFormula(options: ISetShapeFormulaOptions): this

Parameters

• options — Required. Formula text and the required, complete external binding list. Use [] only for a Host-local formula.

Returns

This Shape facade for chaining.

Examples

Set a current-workbook formula in the active worksheet

const workbook = univerAPI.getActiveWorkbook()if (!workbook) throw new Error('No active workbook.')const shape = workbook.getActiveSheet().getShape('formula-shape-1')if (!shape) throw new Error('Shape not found.')shape.setFormula({  formula: '=SUM(A1:B10)',  externalReferences: [], // Required; empty only because this formula has no external Unit.})

Set a cross-Unit Sheet formula in the active Board

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board.')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 80, width: 240, height: 72 },})if (!shape) throw new Error('Formula Shape could not be inserted.')const salesWorkbook = {  unitId: 'sales-workbook',  formulaQualifier: 'Sales Workbook',}const reference = univerAPI.getFormula().buildReference({  hostUnitId: board.getId(),  unit: salesWorkbook,  target: {    kind: univerAPI.Enum.FormulaReferenceType.SHEET_RANGE,    sheetName: 'Sales',    range: { startRow: 0, endRow: 9, startColumn: 1, endColumn: 1 },  },})shape.setFormula({  formula: `=SUM(${reference})`,  externalReferences: [    {      qualifier: salesWorkbook.formulaQualifier,      sourceUnitId: salesWorkbook.unitId,      sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,    },  ],})

Set a cross-Unit Base formula in the active Document

const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document.')const shape = document.getShape('formula-shape-1')if (!shape) throw new Error('Shape not found.')const salesBase = {  unitId: 'sales-base',  formulaQualifier: 'Sales Base',}const reference = univerAPI.getFormula().buildReference({  hostUnitId: document.getId(),  unit: salesBase,  target: {    kind: univerAPI.Enum.FormulaReferenceType.TABLE_COLUMN,    tableName: 'Orders',    columnName: 'Amount',  },})shape.setFormula({  formula: `=SUM(${reference})`,  externalReferences: [    {      qualifier: salesBase.formulaQualifier,      sourceUnitId: salesBase.unitId,      sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_BASE,    },  ],})