# Shape - Human documentation: [https://docs.univer.ai/reference/facade/shape](https://docs.univer.ai/reference/facade/shape) - Agent Markdown: [https://docs.univer.ai/reference/facade/shape.md](https://docs.univer.ai/reference/facade/shape.md) - Requested language: `en-US` - Content language: `en-US` - Documentation version: `1.0.0-rc.0` - Source: [facade/shape.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/shape.mdx) --- | Packages | `@univerjs-pro/engine-shape`, `@univerjs-pro/sheets-shape`, `@univerjs-pro/docs-shape`, `@univerjs-pro/slides`, `@univerjs-pro/shape-editor` | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | Host-neutral Shape Facade APIs shared by Sheets, Docs, Slides, and Boards. > Import the matching host facade and `@univerjs-pro/engine-shape/facade`. Formula-backed methods additionally require `@univerjs-pro/shape-editor/facade`. ## Host entry points Sheets and Docs expose the same lifecycle and return `FConnectorShape` for connector geometry: ```typescript // FWorksheet insertShape(input: IShapeCreateInput): FSheetShape | FConnectorShape | null getShape(shapeId: string): FSheetShape | FConnectorShape | null getShapes(): Array // FDocument insertShape(input: IDocShapeCreateInput): FShape | FConnectorShape | null getShape(shapeId: string): FShape | FConnectorShape | null getShapes(): Array // FSlide insertShape(input: IShapeCreateInput): FShape | FConnectorShape | null insertSmartArt(layoutId: string, transform?: IShapeCreateInput['transform']): FShape | FConnectorShape | null getShape(shapeId: string): FShape | FConnectorShape | null getShapes(): Array ``` `FSheetShape` adds `setPosition(anchorRowPos, anchorColPos, rowOffset, columnOffset)` for cell-relative placement. The shared `setAbsolutePosition(left, top)` remains available. ```ts const worksheet = univerAPI.getActiveWorkbook().getActiveSheet() const shape = worksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect, transform: { left: 120, top: 80, width: 240, height: 120 }, shapeData: { fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#dbeafe', }, }, }) shape?.getText().setText('Quarterly review') ``` ## FShape | Category | Methods | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Identity and metadata | `getId`, `getName`, `setName`, `getDescription`, `setDescription`, `getHostType` | | Inspection | `isConnectorShape`, `getShapeType`, `getShapeData`, `getSnapshot`, `getTransform`, `isVisible`, `isSelectable` | | Geometry | `setShapeType`, `setShapeData`, `setTransform`, `setSize`, `setRotation`, `setAbsolutePosition` | | Custom shapes | `isCustomShape`, `getCustomGeometry`, `setCustomGeometry`, `getConnectionSites`, `getAdjustHandles`, `setAdjustValues`, `resetAdjustValues` | | SmartArt | `isSmartArt`, `getSmartArtData`, `setSmartArtData`, node editing, layout, direction, and conversion APIs | | Fill and stroke | `setSolidFill`, `setGradientFill`, `setImageFill`, `setNoneFill`, `setStroke`, `setStrokeColor`, `setStrokeWidth`, `setStrokeOpacity`, `setStrokeLineDashType`, `setStrokeLineJoinType`, `setStrokeLineCapType`, `setStrokeLineType` | | Text | `getText` | | Lifecycle and order | `update`, `remove`, `setZOrder`, `bringToFront`, `bringForward`, `sendBackward`, `sendToBack` | Every setter except `remove` is chainable and returns the same live facade. ## FShapeText Call `shape.getText()` to access text content and text-box styling. ```typescript getRichText(): RichTextValue | null getPlainText(): string | null setRichText(value: RichTextValue): this setText(text: string): this setTextStyle(style: ITextStyle): this setColor(color: string, opacity?: number): this setNoneFill(): this setGradientFill(type: ShapeGradientTypeEnum, stops: IShapeGradientStop[], angle?: number): this setImageFill(source: string, imageSourceType?: ImageSourceTypeEnum, options?: IShapeImageFillOptions): this setFontSize(fontSize: number): this setFontFamily(fontFamily: string): this setBold(bold: boolean): this setItalic(italic: boolean): this setUnderline(underline: boolean): this setStrikethrough(strikethrough: boolean): this setHorizontalAlign(align: HorizontalAlign): this setVerticalAlign(align: VerticalAlign): this getTextBoxOptions(): IResolvedShapeTextBoxOptions | null setTextBoxOptions(options: IShapeTextBoxOptions): this ``` Shape text uses the same rich-text link builder as Docs: ```ts const richText = univerAPI.newRichText().text('Open ').link('the project brief', 'https://example.com/project-brief') shape.getText().setRichText(richText) ``` ## SmartArt Slides can insert an editable SmartArt composite from a built-in layout id. The returned `FShape` keeps stable logical nodes while layouts and presentation shapes change. ```typescript isSmartArt(): boolean getSmartArtData(): ISmartArtData | null setSmartArtData(data: ISmartArtData): this insertSmartArtNode(options: IInsertSmartArtNodeOptions): this updateSmartArtNode(nodeId: string, update: Partial>): this deleteSmartArtNode(nodeId: string): this moveSmartArtNode(options: IMoveSmartArtNodeOptions): this promoteSmartArtNode(nodeId: string): this demoteSmartArtNode(nodeId: string): this setSmartArtLayout(layoutId: string): this setSmartArtDirection(direction: SmartArtDirectionEnum): this updateSmartArtPresentationShape(presentationShapeId: string, update: Partial>): this convertSmartArtToShapes(): FShape[] ``` ```ts import { SmartArtDirectionEnum } from '@univerjs-pro/engine-shape' const slide = univerAPI.getActivePresentation()?.getActiveSlide() if (!slide) throw new Error('No active slide') const basicBlockListLayout = 'urn:microsoft.com/office/officeart/2005/8/layout/default' const smartArt = slide.insertSmartArt(basicBlockListLayout, { left: 80, top: 80, width: 640, height: 360 }) if (!smartArt) throw new Error('Unknown SmartArt layout') smartArt.setSmartArtDirection(SmartArtDirectionEnum.RightToLeft).setZOrder(1) ``` ## FConnectorShape `FConnectorShape` extends `FShape` with endpoint binding, route, and arrow APIs. ```typescript getStartEndpoint(): IConnectorEndpoint | null getEndEndpoint(): IConnectorEndpoint | null getRoutePoints(): IShapePoint[] | null getStartArrow(): IConnectorArrow | null getEndArrow(): IConnectorArrow | null bindStart(targetShapeId: string, connectionSiteIndex: number): this bindEnd(targetShapeId: string, connectionSiteIndex: number): this unbindStart(): this unbindEnd(): this setStartPoint(point: IShapePoint): this setEndPoint(point: IShapePoint): this setRoutePoints(points: IShapePoint[]): this setStartArrow(type: ShapeArrowTypeEnum, size?: ShapeArrowSizeEnum): this setEndArrow(type: ShapeArrowTypeEnum, size?: ShapeArrowSizeEnum): this ``` ## Formula-backed shapes Import `@univerjs-pro/shape-editor/facade` to add formula methods to every host-neutral `FShape`. ```typescript isFormulaShape(): boolean getFormula(): string | null setFormula(options: ISetShapeFormulaOptions): this removeFormula(): this getFormulaResult(): IFormulaShapeResult | null getFormulaNumberFormat(): string | null setFormulaNumberFormat(pattern: string): this isFormulaAnimationEnabled(): boolean setFormulaAnimationEnabled(enabled: boolean): this ``` `setFormula` always requires `externalReferences`. Pass `[]` only when the formula has no external Unit qualifier. ```ts shape ?.setFormula({ formula: '=SUM(A1:B10)', externalReferences: [], }) .setFormulaNumberFormat('$#,##0.00') ``` Listen for calculated display changes through `univerAPI.Event.FormulaShapeResultChanged`. Result states are available from `univerAPI.Enum.FormulaShapeResultStatus`. Source: `@univerjs-pro/engine-shape`, `@univerjs-pro/sheets-shape`, `@univerjs-pro/docs-shape`, `@univerjs-pro/slides`, `@univerjs-pro/shape-editor`