Shape
| 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:
// FWorksheetinsertShape(input: IShapeCreateInput): FSheetShape | FConnectorShape | nullgetShape(shapeId: string): FSheetShape | FConnectorShape | nullgetShapes(): Array<FSheetShape | FConnectorShape>// FDocumentinsertShape(input: IDocShapeCreateInput): FShape | FConnectorShape | nullgetShape(shapeId: string): FShape | FConnectorShape | nullgetShapes(): Array<FShape | FConnectorShape>// FSlideinsertShape(input: IShapeCreateInput): FShape | FConnectorShape | nullinsertSmartArt(layoutId: string, transform?: IShapeCreateInput['transform']): FShape | FConnectorShape | nullgetShape(shapeId: string): FShape | FConnectorShape | nullgetShapes(): Array<FShape | FConnectorShape>FSheetShape adds setPosition(anchorRowPos, anchorColPos, rowOffset, columnOffset) for cell-relative placement. The shared setAbsolutePosition(left, top) remains available.
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.
getRichText(): RichTextValue | nullgetPlainText(): string | nullsetRichText(value: RichTextValue): thissetText(text: string): thissetTextStyle(style: ITextStyle): thissetColor(color: string, opacity?: number): thissetNoneFill(): thissetGradientFill(type: ShapeGradientTypeEnum, stops: IShapeGradientStop[], angle?: number): thissetImageFill(source: string, imageSourceType?: ImageSourceTypeEnum, options?: IShapeImageFillOptions): thissetFontSize(fontSize: number): thissetFontFamily(fontFamily: string): thissetBold(bold: boolean): thissetItalic(italic: boolean): thissetUnderline(underline: boolean): thissetStrikethrough(strikethrough: boolean): thissetHorizontalAlign(align: HorizontalAlign): thissetVerticalAlign(align: VerticalAlign): thisgetTextBoxOptions(): IResolvedShapeTextBoxOptions | nullsetTextBoxOptions(options: IShapeTextBoxOptions): thisShape text uses the same rich-text link builder as Docs:
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.
isSmartArt(): booleangetSmartArtData(): ISmartArtData | nullsetSmartArtData(data: ISmartArtData): thisinsertSmartArtNode(options: IInsertSmartArtNodeOptions): thisupdateSmartArtNode(nodeId: string, update: Partial<Pick<ISmartArtDataNode, 'fontSizeMode' | 'role' | 'text'>>): thisdeleteSmartArtNode(nodeId: string): thismoveSmartArtNode(options: IMoveSmartArtNodeOptions): thispromoteSmartArtNode(nodeId: string): thisdemoteSmartArtNode(nodeId: string): thissetSmartArtLayout(layoutId: string): thissetSmartArtDirection(direction: SmartArtDirectionEnum): thisupdateSmartArtPresentationShape(presentationShapeId: string, update: Partial<Pick<ISmartArtPresentationShape, 'shapeData' | 'transform'>>): thisconvertSmartArtToShapes(): FShape[]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.
getStartEndpoint(): IConnectorEndpoint | nullgetEndEndpoint(): IConnectorEndpoint | nullgetRoutePoints(): IShapePoint[] | nullgetStartArrow(): IConnectorArrow | nullgetEndArrow(): IConnectorArrow | nullbindStart(targetShapeId: string, connectionSiteIndex: number): thisbindEnd(targetShapeId: string, connectionSiteIndex: number): thisunbindStart(): thisunbindEnd(): thissetStartPoint(point: IShapePoint): thissetEndPoint(point: IShapePoint): thissetRoutePoints(points: IShapePoint[]): thissetStartArrow(type: ShapeArrowTypeEnum, size?: ShapeArrowSizeEnum): thissetEndArrow(type: ShapeArrowTypeEnum, size?: ShapeArrowSizeEnum): thisFormula-backed shapes
Import @univerjs-pro/shape-editor/facade to add formula methods to every host-neutral FShape.
isFormulaShape(): booleangetFormula(): string | nullsetFormula(options: ISetShapeFormulaOptions): thisremoveFormula(): thisgetFormulaResult(): IFormulaShapeResult | nullgetFormulaNumberFormat(): string | nullsetFormulaNumberFormat(pattern: string): thisisFormulaAnimationEnabled(): booleansetFormulaAnimationEnabled(enabled: boolean): thissetFormula always requires externalReferences. Pass [] only when the formula has no external Unit qualifier.
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
How is this guide?