# FShape

> Language fallback: requested `ko-KR`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/ko-KR/reference/facade/shape](https://docs.univer.ai/ko-KR/reference/facade/shape)

- Agent Markdown: [https://docs.univer.ai/ko-KR/reference/facade/shape.md](https://docs.univer.ai/ko-KR/reference/facade/shape.md)

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

Controls an individual shape in Docs, Slides, or Boards. In Sheets, [`FSheetShape`](https://docs.univer.ai/ko-KR/reference/facade/sheet-shape.md) 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()`](#gettext) to obtain [`FShapeText`](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md). Use [`setText()`](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md#settext) to replace plain text, [`setRichText()`](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md#setrichtext) to write rich text, and [`setTextStyle()`](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md#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:

```ts
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()`](https://docs.univer.ai/ko-KR/reference/facade/document.md#insertshape)
* [`FDocument.getShape()`](https://docs.univer.ai/ko-KR/reference/facade/document.md#getshape)
* [`FDocument.getShapes()`](https://docs.univer.ai/ko-KR/reference/facade/document.md#getshapes)
* [`FSlide.insertShape()`](https://docs.univer.ai/ko-KR/reference/facade/slide.md#insertshape)
* [`FSlide.insertSmartArt()`](https://docs.univer.ai/ko-KR/reference/facade/slide.md#insertsmartart)
* [`FSlide.getShape()`](https://docs.univer.ai/ko-KR/reference/facade/slide.md#getshape)
* [`FSlide.getShapes()`](https://docs.univer.ai/ko-KR/reference/facade/slide.md#getshapes)
* [`FBoard.insertShape()`](https://docs.univer.ai/ko-KR/reference/facade/board.md#insertshape)

## Example

Sheet

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

Doc

```ts
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

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

Board

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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) 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](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-shape`

### `FShape.bringForward`

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

```typescript
bringForward(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.bringForward()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.bringToFront`

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

```typescript
bringToFront(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.bringToFront()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
convertSmartArtToShapes(): FShape[]
```

**Returns**

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

**Examples**

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

**Types:** [`FShape`](https://docs.univer.ai/ko-KR/reference/facade/shape.md)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.deleteSmartArtNode`

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

```typescript
deleteSmartArtNode(nodeId: string): this
```

**Parameters**

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

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.demoteSmartArtNode`

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

```typescript
demoteSmartArtNode(nodeId: string): this
```

**Parameters**

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

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getAdjustHandles`

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

```typescript
getAdjustHandles(): IShapeAdjustItemResolved[]
```

**Returns**

Detached resolved adjustment handles in preset order.

**Examples**

```ts
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`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
getConnectionSites(): IShapeConnectionSite[]
```

**Returns**

The sites where Connector endpoints can attach to this Shape.

**Examples**

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

**Types:** [`IShapeConnectionSite`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getCustomGeometry`

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

```typescript
getCustomGeometry(): IPresetShapeConfig | null
```

**Returns**

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

**Examples**

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

**Types:** [`IPresetShapeConfig`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getDescription`

Returns the user-facing Shape description.

```typescript
getDescription(): string | undefined
```

**Returns**

The Shape description, or `undefined` when none is configured.

**Examples**

```ts
console.log(fShape.getDescription())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getEndConnectInfo`

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

```typescript
getEndConnectInfo(): IShapeRelationItem | null
```

**Returns**

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

**Examples**

```ts
console.log(fShape.getEndConnectInfo())
```

**Types:** [`IShapeRelationItem`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getHostType`

Returns the Univer host type that owns this Shape.

```typescript
getHostType(): ShapeHostType
```

**Returns**

The Univer host type that owns this Shape.

**Examples**

```ts
console.log(fShape.getHostType())
```

**Types:** [`ShapeHostType`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getId`

Returns the stable Shape identifier.

```typescript
getId(): string
```

**Returns**

The stable Shape identifier.

**Examples**

```ts
console.log(fShape.getId())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getName`

Returns the user-facing Shape name.

```typescript
getName(): string | undefined
```

**Returns**

The Shape name, or `undefined` when none is configured.

**Examples**

```ts
console.log(fShape.getName())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getShapeData`

Returns a detached copy of the current Shape data.

```typescript
getShapeData(): IShapeData | null
```

**Returns**

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

**Examples**

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

**Types:** [`IShapeData`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getShapeType`

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

```typescript
getShapeType(): ShapeTypeEnum | null
```

**Returns**

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

**Examples**

```ts
console.log(fShape.getShapeType())
```

**Types:** [`ShapeTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
getSmartArtData(): ISmartArtData | null
```

**Returns**

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

**Examples**

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

**Types:** [`ISmartArtData`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getSnapshot`

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

```typescript
getSnapshot(): IShapeSnapshot | null
```

**Returns**

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

**Examples**

```ts
console.log(fShape.getSnapshot())
```

**Types:** [`IShapeSnapshot`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getStartConnectInfo`

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

```typescript
getStartConnectInfo(): IShapeRelationItem | null
```

**Returns**

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

**Examples**

```ts
console.log(fShape.getStartConnectInfo())
```

**Types:** [`IShapeRelationItem`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getText`

Returns the text facade associated with this Shape.

```typescript
getText(): FShapeText
```

**Returns**

The text facade associated with this Shape.

**Examples**

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

**Types:** [`FShapeText`](https://docs.univer.ai/ko-KR/reference/facade/shape-text.md)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.getTransform`

Returns a detached copy of the current Shape transform.

```typescript
getTransform(): IShapeTransform | null
```

**Returns**

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

**Examples**

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

**Types:** [`IShapeTransform`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
insertSmartArtNode(options: IInsertSmartArtNodeOptions): this
```

**Parameters**

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

**Returns**

This SmartArt facade for chaining.

**Examples**

```ts
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`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/smart-art/smart-art-model.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.isConnectorShape`

Whether this Shape is a Connector preset type.

```typescript
isConnectorShape(): boolean
```

**Returns**

Whether this Shape is a Connector preset type.

**Examples**

```ts
console.log(fShape.isConnectorShape())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.isCustomShape`

Returns whether this Shape uses custom geometry.

```typescript
isCustomShape(): boolean
```

**Returns**

Whether this Shape uses custom geometry.

**Examples**

```ts
console.log(fShape.isCustomShape())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.isSelectable`

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

```typescript
isSelectable(): boolean
```

**Returns**

Whether the Shape can be selected.

**Examples**

```ts
console.log(fShape.isSelectable())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.isSmartArt`

Returns whether this Shape is an editable SmartArt composite.

```typescript
isSmartArt(): boolean
```

**Returns**

Whether this Shape is SmartArt.

**Examples**

Slide — executable with `univer execute`

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.isVisible`

Returns whether the Shape is visible in its host.

```typescript
isVisible(): boolean
```

**Returns**

Whether the Shape is visible.

**Examples**

```ts
console.log(fShape.isVisible())
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.moveSmartArtNode`

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

```typescript
moveSmartArtNode(options: IMoveSmartArtNodeOptions): this
```

**Parameters**

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

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Types:** [`IMoveSmartArtNodeOptions`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/smart-art/smart-art-model.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.promoteSmartArtNode`

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

```typescript
promoteSmartArtNode(nodeId: string): this
```

**Parameters**

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

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.remove`

Removes the Shape and returns whether the host mutation succeeded.

```typescript
remove(): boolean
```

**Returns**

Whether the shape was successfully removed from its host.

**Examples**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.resetAdjustValues`

Removes all Shape adjustment overrides and restores preset defaults.

```typescript
resetAdjustValues(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.sendBackward`

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

```typescript
sendBackward(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.sendBackward()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.sendToBack`

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

```typescript
sendToBack(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.sendToBack()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
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**

```ts
fShape.setAbsolutePosition(160, 96)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setAdjustValues`

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

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

**Parameters**

* `adjustValues` — Required. Adjustment names and values to update.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setShapeType(univerAPI.Enum.ShapeTypeEnum.RoundRect).setAdjustValues({ adj: 75000 })

const [handle] = fShape.getAdjustHandles()
console.log(handle.currentAdjustValues.adj) // 50000
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setCustomGeometry`

Sets detached custom geometry and marks this Shape as custom.

```typescript
setCustomGeometry(customGeometry: IPresetShapeConfig): this
```

**Parameters**

* `customGeometry` — Required. The new custom geometry.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
// 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`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
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`

```ts
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`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setDescription`

Sets or clears the user-facing Shape description.

```typescript
setDescription(description?: string): this
```

**Parameters**

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

**Returns**

This Shape facade for chaining.

**Examples**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setGradientFill`

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

```typescript
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**

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

**Types:** [`ShapeGradientTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts) · [`IShapeGradientStop`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setImageFill`

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

```typescript
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**

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

**Types:** [`ImageSourceTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts) · [`IShapeImageFillOptions`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setName`

Sets or clears the user-facing Shape name.

```typescript
setName(name?: string): this
```

**Parameters**

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

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setName('Revenue forecast')
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setNoneFill`

Removes the visible fill from this Shape.

```typescript
setNoneFill(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setNoneFill()
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setRotation`

Sets the clockwise Shape rotation in degrees.

```typescript
setRotation(rotation: number): this
```

**Parameters**

* `rotation` — Required. The clockwise Shape rotation in degrees.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setRotation(30)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setSelectable`

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

```typescript
setSelectable(selectable: boolean): this
```

**Parameters**

* `selectable` — Required. Whether the Shape should be selectable.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setSelectable(false)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setShapeData`

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

```typescript
setShapeData(shapeData: IShapeData): this
```

**Parameters**

* `shapeData` — Required. The new Shape data.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`IShapeData`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setShapeType`

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

```typescript
setShapeType(shapeType: ShapeTypeEnum): this
```

**Parameters**

* `shapeType` — Required. The new Shape preset type.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`ShapeTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setSize`

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

```typescript
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**

```ts
fShape.setSize(240, 120)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
setSmartArtData(data: ISmartArtData): this
```

**Parameters**

* `data` — Required. The complete normalized SmartArt model.

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Types:** [`ISmartArtData`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setSmartArtDirection`

Sets the SmartArt reading and layout direction.

```typescript
setSmartArtDirection(direction: SmartArtDirectionEnum): this
```

**Parameters**

* `direction` — Required. The new left-to-right or right-to-left direction.

**Returns**

This SmartArt facade for chaining.

**Examples**

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

**Types:** [`SmartArtDirectionEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/smart-art/smart-art-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
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**

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

**Types:** [`SmartArtCategoryEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/smart-art/smart-art-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setSolidFill`

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

```typescript
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**

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

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStroke`

Replaces the complete Shape stroke configuration.

```typescript
setStroke(stroke: IShapeLineStyle): this
```

**Parameters**

* `stroke` — Required. The new Shape stroke configuration.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`IShapeLineStyle`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeColor`

Sets the stroke color while preserving other stroke properties.

```typescript
setStrokeColor(color: string): this
```

**Parameters**

* `color` — Required. The new stroke color.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setStrokeColor('#1e3a8a')
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeLineCapType`

Sets the stroke line-cap preset.

```typescript
setStrokeLineCapType(lineCapType: ShapeLineCapEnum): this
```

**Parameters**

* `lineCapType` — Required. The new stroke line-cap preset.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`ShapeLineCapEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeLineDashType`

Sets the stroke dash preset.

```typescript
setStrokeLineDashType(lineDashType: ShapeLineDashEnum): this
```

**Parameters**

* `lineDashType` — Required. The new stroke dash preset.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`ShapeLineDashEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeLineJoinType`

Sets the stroke line-join preset.

```typescript
setStrokeLineJoinType(lineJoinType: ShapeLineJoinEnum): this
```

**Parameters**

* `lineJoinType` — Required. The new stroke line-join preset.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`ShapeLineJoinEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeLineType`

Sets the stroke line type.

```typescript
setStrokeLineType(lineType: ShapeLineTypeEnum): this
```

**Parameters**

* `lineType` — Required. The new stroke line type.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`ShapeLineTypeEnum`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-enum.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeOpacity`

Sets the stroke opacity while preserving other stroke properties.

```typescript
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**

```ts
fShape.setStrokeOpacity(0.6)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setStrokeWidth`

Sets the stroke width while preserving other stroke properties.

```typescript
setStrokeWidth(width: number): this
```

**Parameters**

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

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setStrokeWidth(3)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
setTransform(transform: Partial<IShapeTransform>): this
```

**Parameters**

* `transform` — Required. A partial Shape transform update.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IShapeTransform`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.setVisible`

Sets whether the Shape is visible in its host.

```typescript
setVisible(visible: boolean): this
```

**Parameters**

* `visible` — Required. Whether the Shape should be visible.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setVisible(false)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
setZOrder(index: number): this
```

**Parameters**

* `index` — Required. The zero-based target order index.

**Returns**

This Shape facade for chaining.

**Examples**

```ts
fShape.setZOrder(2)
```

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.update`

Applies a partial Shape update through the registered host adapter.

```typescript
update(input: IShapeUpdateInput): this
```

**Parameters**

* `input` — Required. A partial Shape update.

**Returns**

This Shape facade for chaining.

**Examples**

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

**Types:** [`IShapeUpdateInput`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/services/shape-host-adapter.service.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.updateSmartArtNode`

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

```typescript
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**

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

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Pick`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISmartArtDataNode`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

### `FShape.updateSmartArtPresentationShape`

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

```typescript
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**

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Pick`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ISmartArtPresentationShape`](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/shape-type.d.ts)

**Package:** [`@univerjs-pro/engine-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/engine-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-shape/lib/types/facade/f-shape.d.ts)

## `@univerjs-pro/shape-editor`

### `FShape.getFormula`

Returns the Formula Shape formula string.

```typescript
getFormula(): string | null
```

**Returns**

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

**Examples**

Read a formula from the active worksheet

```ts
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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.getFormulaNumberFormat`

Returns the configured Formula Shape number-format pattern.

```typescript
getFormulaNumberFormat(): string | null
```

**Returns**

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

**Examples**

Read a number format in the active worksheet

```ts
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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.getFormulaResult`

Returns the latest calculated and formatted Formula Shape result.

```typescript
getFormulaResult(): IFormulaShapeResult | null
```

**Returns**

Result snapshot, or `null` when unavailable.

**Examples**

Read the currently available result

```ts
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

```ts
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 applied
console.log(shape.getFormulaResult())
```

**Types:** [`IFormulaShapeResult`](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/services/shape-formula.service.d.ts)

**Package:** [`@univerjs-pro/shape-editor`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.isFormulaAnimationEnabled`

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

```typescript
isFormulaAnimationEnabled(): boolean
```

**Returns**

`true` when enabled; Formula Shapes default to enabled.

**Examples**

Check animation in the active worksheet

```ts
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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.isFormulaShape`

Returns whether this Shape has a Formula Shape binding.

```typescript
isFormulaShape(): boolean
```

**Returns**

`true` when the Shape is a Formula Shape.

**Examples**

Check a Shape in the active worksheet

```ts
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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.removeFormula`

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

```typescript
removeFormula(): this
```

**Returns**

This Shape facade for chaining.

**Examples**

Remove a formula in the active worksheet

```ts
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

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `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.

```typescript
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

```ts
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

```ts
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

```ts
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,
    },
  ],
})
```

**Types:** [`ISetShapeFormulaOptions`](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/shape-editor`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.setFormulaAnimationEnabled`

Enables or disables Formula Shape value-change animation.

```typescript
setFormulaAnimationEnabled(enabled: boolean): this
```

**Parameters**

* `enabled` — Required. Whether value changes should animate.

**Returns**

This Shape facade for chaining.

**Examples**

Disable animation in the active Document

```ts
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document.')
const shape = document.getShape('formula-shape-1')
if (!shape?.isFormulaShape()) throw new Error('Formula Shape not found.')
shape.setFormulaAnimationEnabled(false)
```

Set a local formula and keep animation enabled in the active worksheet

```ts
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.')
shape
  .setFormula({
    formula: '=SUM(B2:B10)',
    externalReferences: [], // Required; empty only because this formula has no external Unit.
  })
  .setFormulaAnimationEnabled(true)
```

**Package:** [`@univerjs-pro/shape-editor`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

### `FShape.setFormulaNumberFormat`

Sets the Formula Shape number-format pattern.

```typescript
setFormulaNumberFormat(pattern: string): this
```

**Parameters**

* `pattern` — Required. Univer number-format pattern. An empty string resets it to `General`.

**Returns**

This Shape facade for chaining.

**Examples**

Apply a currency format in the active worksheet

```ts
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.')
shape.setFormulaNumberFormat('$#,##0.00')
```

Apply a custom colored format in the active Board

```ts
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.')
shape.setFormulaNumberFormat('[Red]#,##0;[Blue]-#,##0')
```

**Package:** [`@univerjs-pro/shape-editor`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-editor.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-editor/lib/types/facade/f-shape.d.ts)

## `@univerjs-pro/shape-thread-comment`

### `FShape.createCommentAsync`

Creates a comment on this Shape using the host product's stable element anchor.

```typescript
createCommentAsync(content: ThreadComment.ThreadCommentContent, options?: IShapeCommentCreateOptions): Promise<boolean>
```

**Parameters**

* `content` — Required. Plain text or a Univer document body for rich comment content.
* `options` — Optional. Default: `{}`. Optional stable IDs, author, attachments, and creation time.

**Returns**

`true` when the create command succeeds; otherwise, `false`.

**Throws**

If the Shape host is not Sheets, Docs, Slides, or Board.

If the content is empty.

**Examples**

```ts
const shape = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getShapes()[0]
await shape?.createCommentAsync('Align this shape with the title.')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment/lib/types/services/thread-comment-api.service.d.ts) · [`IShapeCommentCreateOptions`](https://unpkg.com/@univerjs-pro/shape-thread-comment/lib/types/facade/f-shape.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment/lib/types/facade/f-shape.d.ts)

### `FShape.getComments`

Returns locally loaded comments anchored to this Shape's stable ID.

```typescript
getComments(): ThreadComment.IFacadeThreadCommentInfo[]
```

**Returns**

Matching comment threads in the Shape's host product.

**Examples**

```ts
const shape = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getShapes()[0]
console.log(shape?.getComments().length ?? 0)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment/lib/types/services/thread-comment-api.service.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment/lib/types/facade/f-shape.d.ts)

### `FShape.listCommentsAsync`

Synchronizes known threads and returns comments anchored to this Shape's stable ID.

```typescript
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Returns**

A promise resolving to matching synchronized comment threads.

**Examples**

```ts
const shape = univerAPI.getActivePresentation()?.getSlideByIndex(0)?.getShapes()[0]
const comments = shape ? await shape.listCommentsAsync() : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/shape-thread-comment`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/shape-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/shape-thread-comment/lib/types/facade/f-shape.d.ts)