FBoard

The facade class for a board unit.

This facade is the recommended entry point for agents and integrations that create or edit board content. Prefer element ids for later references and batch APIs when creating or updating multiple elements. Facade mutations go through the board command layer, so collaboration, undo/redo, validation, and container invariants follow the same path as UI operations.

Persist returned element ids in the caller's own state when later edits need to address the same elements. The facade does not provide semantic-key indexes or implicit idempotent creation. Avoid chaining many single-element mutations when generating diagrams. Prefer insertShapes(), insertConnectors(), and other batch helpers so related edits travel as compact batch mutations with compact undo/redo history.

Access

Access through:

• FUniver.createBoard()
• FUniver.getActiveBoard()
• FUniver.getBoard()
• FCollaboration.loadBoardAsync()

Setup

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

@univerjs-pro/boards

FBoard.addElement

Adds one fully constructed board element through the command layer.

This is a low-level escape hatch for code that already has an IBoardPageElement. Agent scripts should prefer insertShapes(), insertConnector(), createContainer(), or createSwimlane() because those APIs are more higher-level and harder to misuse.

addElement(element: IBoardPageElement, options?: IBoardFacadeAddElementOptions): boolean

Parameters

• element — Required. Fully constructed board element.
• options — Optional. Default: {}. Insert options such as insertIndex.

Returns

true when the element passes local invariants and the command succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const seed = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 120 },  name: 'Seed',})if (!seed) throw new Error('Cannot create seed shape')const source = board.getElement(seed.getId())if (!source) throw new Error('Cannot read seed shape')const rawId = `${source.id}-copy`const added = board.addElement({  ...source,  id: rawId,  transform: { ...source.transform, left: 320 },})if (!added) throw new Error('Cannot add raw shape')console.log(rawId)

Types: IBoardPageElement · IBoardFacadeAddElementOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.addElements

Adds multiple fully constructed board elements in one command.

This keeps collaboration traffic and undo history compact when callers already own valid element models. Agent scripts that are creating new shapes or connectors should prefer insertShapes() and insertConnectors().

addElements(elements: IBoardPageElement[], options?: IBoardFacadeAddElementsOptions): boolean

Parameters

• elements — Required. Fully constructed board elements.
• options — Optional. Default: {}. Batch insert options such as insertIndex, fitContainerId.

Returns

true when all elements pass local invariants and the command succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },])const elements = shapes  ?.map((shape) => board.getElement(shape.getId()))  .filter((element) => element !== null)if (  !shapes ||  !elements ||  elements.length !== shapes.length ||  !board.removeElements(shapes.map((shape) => shape.getId()))) {  throw new Error('Cannot prepare elements')}if (!board.addElements(elements)) throw new Error('Cannot add elements')

Types: IBoardPageElement · IBoardFacadeAddElementsOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.addSwimlaneLane

Adds a lane to a swimlane container.

The lane is inserted at options.insertIndex or appended when omitted. Lane order is normalized after insertion.

addSwimlaneLane(containerId: string, lane: IBoardFacadeSwimlaneLane, options?: IBoardFacadeAddSwimlaneLaneOptions): boolean

Parameters

• containerId — Required. Swimlane container id.
• lane — Required. Lane model to add.
• options — Optional. Default: {}. Optional insert index.

Returns

true when the lane is added.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const swimlaneId = `swimlane-${Date.now()}`if (  !board.createSwimlane({    id: swimlaneId,    left: 80,    top: 80,    lanes: [{ id: 'todo', title: 'Todo' }],  }) ||  !board.addSwimlaneLane(swimlaneId, { id: 'done', title: 'Done', size: 200, order: 1 })) {  throw new Error('Cannot add lane')}

Types: IBoardFacadeSwimlaneLane · IBoardFacadeAddSwimlaneLaneOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.alignElements

Aligns at least two elements against their combined resolved bounds.

alignElements(elementIds: string[], alignment: BoardFacadeElementAlignment): boolean

Parameters

• elementIds — Required. Existing element ids.
• alignment — Required. Edge or center alignment mode.

Returns

true when at least one element moves and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const nodes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 160 } },])if (  !nodes ||  !board.alignElements(    nodes.map((node) => node.getId()),    'left',  )) {  throw new Error('Cannot align nodes')}

Types: BoardFacadeElementAlignment

Package: @univerjs-pro/boards · Type definitions

FBoard.analyzeModelLayout

Detects model-visible Board layout conflicts on the active page.

Model analysis can inspect persisted manual connector paths. Auto-routed connectors without persisted route points are reported as unresolved; a UI host can use rendered analysis for their final paths.

analyzeModelLayout(focusPadding?: number): AnalyzeBoardModelLayoutResult

Parameters

• focusPadding — Optional. Padding added to each issue's suggested screenshot bounds.

Returns

Structured layout issues, or false when the command cannot run.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const analysis = board.analyzeModelLayout(48)if (!analysis) throw new Error('Cannot analyze the active board')const blockingIssues = analysis.issues.filter((issue) => issue.severity === 'error')console.log({ blockingIssues, unresolved: analysis.summary.unresolvedConnectorCount })

Types: AnalyzeBoardModelLayoutResult

Package: @univerjs-pro/boards · Type definitions

FBoard.arrangeElements

Arranges elements in their supplied order, preserving their current sizes.

arrangeElements(elementIds: string[], options: IBoardFacadeArrangeElementsOptions): boolean

Parameters

• elementIds — Required. Existing element ids in visual order.
• options — Required. Direction, gap, and optional starting point.

Returns

true when at least one element moves and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },])if (  !shapes ||  !board.arrangeElements(    shapes.map((shape) => shape.getId()),    { direction: 'horizontal', gap: 60 },  )) {  throw new Error('Cannot arrange shapes')}

Types: IBoardFacadeArrangeElementsOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.arrangeElementsInCircle

Arranges elements around a circle in their supplied order.

arrangeElementsInCircle(elementIds: string[], options: IBoardFacadeArrangeElementsInCircleOptions): boolean

Parameters

• elementIds — Required. Existing element ids in circular order.
• options — Required. Circle center, radius, start angle, and direction.

Returns

true when the geometry is valid and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 280, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 480, top: 80 } },])if (  !shapes ||  !board.arrangeElementsInCircle(    shapes.map((shape) => shape.getId()),    {      center: { x: 400, y: 300 },      radius: 180,    },  ))  throw new Error('Cannot arrange circle')

Types: IBoardFacadeArrangeElementsInCircleOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.arrangeElementsInGrid

Arranges elements in their supplied order into a row-major grid.

arrangeElementsInGrid(elementIds: string[], options: IBoardFacadeArrangeElementsInGridOptions): boolean

Parameters

• elementIds — Required. Existing element ids in row-major order.
• options — Required. Column count, gaps, and optional starting point.

Returns

true when at least one element moves and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 280 } },])if (  !shapes ||  !board.arrangeElementsInGrid(    shapes.map((shape) => shape.getId()),    { columns: 2 },  )) {  throw new Error('Cannot arrange grid')}

Types: IBoardFacadeArrangeElementsInGridOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.arrangeElementsInLayers

Arranges explicitly supplied element layers for flowcharts and dependency diagrams.

Each inner array is rendered in its supplied visual order. Layers flow top-to-bottom by default, or left-to-right when direction is horizontal.

arrangeElementsInLayers(layers: string[][], options?: IBoardFacadeArrangeElementsInLayersOptions): boolean

Parameters

• layers — Required. Element ids grouped into ordered visual layers.
• options — Optional. Default: {}. Flow direction, layer/item gaps, alignments, and optional starting point.

Returns

true when all ids are unique and valid and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const nodes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Diamond, transform: { left: 280, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 40 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 180 } },])if (!nodes) throw new Error('Cannot insert flowchart nodes')const [start, decision, approved, rejected] = nodesconst arranged = board.arrangeElementsInLayers(  [[start.id], [decision.id], [approved.id, rejected.id]],  { direction: 'horizontal', layerGap: 140, itemGap: 100 },)if (!arranged) throw new Error('Cannot arrange flowchart')

Types: IBoardFacadeArrangeElementsInLayersOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.beginExport

Starts the host-configured Board export flow for this board.

Export rendering and file delivery are owned by the registered export adapter. This facade method only supplies stable board context and an optional target hint, so UI, service, and SDK callers share the same operation.

beginExport(targetType?: 'image' | 'pdf' | string): boolean

Parameters

• targetType — Optional. Optional adapter target such as image, pdf, or a host-supported format.

Returns

true when a registered adapter accepts the request.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const opened = board.beginExport('image')console.log(opened)

Package: @univerjs-pro/boards · Type definitions

FBoard.beginImport

Starts the host-configured Board import flow for this board.

This method delegates to the registered import adapter; it does not parse files in the model package. Hosts may open a picker, display an import dialog, or route to an exchange service. Agents that already own structured Board content should use the element insertion APIs instead of this interactive adapter entry point.

beginImport(sourceType?: string): boolean

Parameters

• sourceType — Optional. Optional adapter hint such as mermaid, pptx, or another host-supported source type.

Returns

true when a registered adapter accepts the request.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const opened = board.beginImport('mermaid')console.log(opened)

Package: @univerjs-pro/boards · Type definitions

FBoard.bringElementsForward

Moves elements one z-order step forward.

bringElementsForward(elementIds: string[]): boolean

Parameters

• elementIds — Required. Existing element ids.

Returns

true when the order changes successfully.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },])if (!shapes || !board.bringElementsForward([shapes[0].getId()]))  throw new Error('Cannot move shape forward')

Package: @univerjs-pro/boards · Type definitions

FBoard.bringElementsToFront

Brings elements to the front.

bringElementsToFront(elementIds: string[]): boolean

Parameters

• elementIds — Required. Existing element ids.

Returns

true when the order changes successfully.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },])if (!shapes || !board.bringElementsToFront([shapes[0].getId()]))  throw new Error('Cannot bring shape to front')

Package: @univerjs-pro/boards · Type definitions

FBoard.checkElementIds

Checks a list of generated board element ids and returns a structured preflight result.

Use this when an integration starts from UI selection ids or event payload ids and wants to verify all referenced elements still exist before mapping them back to generated ids or running low-level commands.

checkElementIds(elementIds: string[]): IBoardFacadeElementIdCheckResult

Parameters

• elementIds — Required. Generated board element ids.

Returns

Requested ids, existing ids, missing ids, and an allExist boolean.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.checkElementIds([shape.getId(), 'missing-element']))

Types: IBoardFacadeElementIdCheckResult

Package: @univerjs-pro/boards · Type definitions

FBoard.checkElementIdTypes

Checks generated board element ids against expected board element types.

Use this before type-specific low-level integrations that start from UI selection ids. It separates missing ids from ids that still exist but point to the wrong element type.

checkElementIdTypes(elementIds: string[], expectedTypes: BoardElementType | BoardElementType[]): IBoardFacadeElementIdTypeCheckResult

Parameters

• elementIds — Required. Generated board element ids.
• expectedTypes — Required. Allowed board element type or types.

Returns

Requested ids, matching ids, missing ids, mismatched ids, and an allMatch boolean.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.checkElementIdTypes([shape.getId()], univerAPI.Enum.BoardElementType.Shape))

Types: IBoardFacadeElementIdTypeCheckResult · BoardElementType

Package: @univerjs-pro/boards · Type definitions

FBoard.clearBackground

Clears the active Board page background and restores the theme-aware canvas fill.

clearBackground(): this

Returns

This board, for chaining.

Package: @univerjs-pro/boards · Type definitions

FBoard.createContainer

Creates a generic, UML package, or system-boundary container.

Containers can group elements and optionally auto-capture/membership-lock children depending on the provided container options. Give agent-created containers generated ids so later scripts can move children into them.

createContainer(options: IBoardFacadeCreateContainerOptions): boolean

Parameters

• options — Required. Container creation options.

Returns

true when the container is created through the command layer.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (  !board.createContainer({    id: containerId,    kind: univerAPI.Enum.BoardContainerKind.SystemBoundary,    left: 80,    top: 80,    title: 'Planning',  })) {  throw new Error('Cannot create container')}

Types: IBoardFacadeCreateContainerOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.createSwimlane

Creates a swimlane container.

Use this for process maps, responsibility diagrams, or timelines. Provide lane ids that are meaningful to the agent, such as todo, doing, and done, so later lane operations are readable.

createSwimlane(options: IBoardFacadeCreateSwimlaneOptions): boolean

Parameters

• options — Required. Swimlane creation options.

Returns

true when the swimlane is created through the command layer.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const swimlaneId = `swimlane-${Date.now()}`if (  !board.createSwimlane({    id: swimlaneId,    left: 80,    top: 80,    title: 'Workflow',    lanes: [      { id: 'todo', title: 'Todo' },      { id: 'done', title: 'Done' },    ],  }))  throw new Error('Cannot create swimlane')

Types: IBoardFacadeCreateSwimlaneOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.describeElement

Describes one board element as a compact agent-friendly summary.

Use this when an agent needs to inspect an element without depending on the full internal model. The descriptor includes generated element id, resolved metadata, parent id, local transform, and world bounds, but it does not include heavy payloads such as shapeData or connectorData.

Agent scripts should prefer describeElement() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

describeElement(elementId: string): IBoardFacadeElementDescriptor | null

Parameters

• elementId — Required. Generated board element id.

Returns

Compact element descriptor, or null when the element is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.describeElement(shape.getId()))

Types: IBoardFacadeElementDescriptor

Package: @univerjs-pro/boards · Type definitions

FBoard.describeElements

Describes matching board elements as compact agent-friendly summaries.

This is the recommended discovery API for agents before they modify a board. It returns descriptors in board z-order, supports the same filters as findElements(), and avoids exposing large internal element payloads in prompts or tool results.

describeElements(query?: IBoardFacadeElementQuery): IBoardFacadeElementDescriptor[]

Parameters

• query — Optional. Default: {}. Optional type and visibility filters.

Returns

Compact descriptors in board z-order.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')console.log(board.describeElements({ elementType: univerAPI.Enum.BoardElementType.Shape }))

Types: IBoardFacadeElementDescriptor · IBoardFacadeElementQuery

Package: @univerjs-pro/boards · Type definitions

FBoard.describeElementsByIds

Describes multiple board elements addressed by generated ids.

Use this when an integration starts from UI selection ids or event payload ids and the agent needs compact descriptors before deciding which id-based mutation APIs to call. The returned object preserves every normalized requested id and uses null when an element is missing.

describeElementsByIds(elementIds: string[]): Record<string, IBoardFacadeElementDescriptor | null>

Parameters

• elementIds — Required. Generated board element ids.

Returns

An id-to-descriptor map that preserves requested ids and uses null for missing elements.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.describeElementsByIds([shape.getId()]))

Types: IBoardFacadeElementDescriptor · Record

Package: @univerjs-pro/boards · Type definitions

FBoard.disbandContainer

Disbands a container while preserving its children.

This is useful when an agent decides a grouping container is no longer semantically meaningful. The method refuses blocked containers and containers whose parent membership rules prevent disbanding.

disbandContainer(containerId: string): boolean

Parameters

• containerId — Required. Container id to disband.

Returns

true when the disband command succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (  !board.createContainer({ id: containerId, left: 80, top: 80 }) ||  !board.disbandContainer(containerId)) {  throw new Error('Cannot disband container')}

Package: @univerjs-pro/boards · Type definitions

FBoard.distributeElements

Distributes at least three elements with equal horizontal or vertical gaps.

distributeElements(elementIds: string[], distribution: BoardFacadeElementDistribution): boolean

Parameters

• elementIds — Required. Existing element ids.
• distribution — Required. Distribution axis.

Returns

true when at least one element moves and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 260, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 560, top: 80 } },])if (  !shapes ||  !board.distributeElements(    shapes.map((shape) => shape.getId()),    'horizontal',  )) {  throw new Error('Cannot distribute shapes')}

Types: BoardFacadeElementDistribution

Package: @univerjs-pro/boards · Type definitions

FBoard.findElements

Finds board elements by type and visibility.

Agent examples should use univerAPI.Enum.BoardElementType constants for type filters so scripts remain discoverable and typo-resistant.

findElements(query?: IBoardFacadeElementQuery): IBoardPageElement[]

Parameters

• query — Optional. Default: {}. Query options. Omit it to list all visible elements on the active page.

Returns

Matching elements in board z-order.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.findElements({ elementType: univerAPI.Enum.BoardElementType.Shape })console.log(shapes.map((shape) => shape.id))

Types: IBoardPageElement · IBoardFacadeElementQuery

Package: @univerjs-pro/boards · Type definitions

FBoard.fitContainerToContent

Fits a container bounds to its current content.

Use this after an agent moves elements into a container or changes child geometry. The operation goes through the same command path as the UI action.

fitContainerToContent(containerId: string): boolean

Parameters

• containerId — Required. Container id.

Returns

true when the fit command succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (!board.createContainer({ id: containerId, left: 80, top: 80 }))  throw new Error('Cannot create container')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 120 },})if (!shape || !board.reparentElements([shape.getId()], containerId))  throw new Error('Cannot insert shape')if (!board.fitContainerToContent(containerId)) throw new Error('Cannot fit container')

Package: @univerjs-pro/boards · Type definitions

FBoard.fitElementsIntoBounds

Fits an element group into a rectangle while optionally preserving its aspect ratio.

fitElementsIntoBounds(elementIds: string[], bounds: IBoardRect, options?: IBoardFacadeFitElementsIntoBoundsOptions): boolean

Parameters

• elementIds — Required. Existing element ids.
• bounds — Required. Target board-coordinate rectangle.
• options — Optional. Default: {}. Aspect-ratio behavior.

Returns

true when source and target bounds are valid and the batch succeeds.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },])if (  !shapes ||  !board.fitElementsIntoBounds(    shapes.map((shape) => shape.getId()),    {      left: 100,      top: 100,      width: 640,      height: 360,    },  ))  throw new Error('Cannot fit shapes')

Types: IBoardRect · IBoardFacadeFitElementsIntoBoundsOptions

Package: @univerjs-pro/boards · Type definitions

FBoard.getBackground

Gets the active Board page background as detached data.

getBackground(): IBoardBackgroundData | undefined

Returns

The explicit background, or undefined when the page uses the default canvas background.

Types: IBoardBackgroundData

Package: @univerjs-pro/boards · Type definitions

FBoard.getConnectorConnection

Returns detached endpoint and routing data for one connector.

getConnectorConnection(elementId: string): IBoardFacadeConnectorConnection | null

Parameters

• elementId — Required. Existing connector id.

Returns

Detached connection data, or null when the id is missing or not a connector.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },])if (!shapes) throw new Error('Cannot insert shapes')const connector = board.insertConnector({  fromElementId: shapes[0].getId(),  toElementId: shapes[1].getId(),})if (!connector) throw new Error('Cannot insert connector')console.log(board.getConnectorConnection(connector.id))

Types: IBoardFacadeConnectorConnection

Package: @univerjs-pro/boards · Type definitions

FBoard.getConnectorLabels

Returns a detached copy of connector labels in rendering order, including rich document content. Mutating the result does not change the Board; use setConnectorLabels or updateConnectorLabel to write.

getConnectorLabels(elementId: string): IBoardConnectorLabel[]

Parameters

• elementId — Required. Connector id on the active page.

Returns

Labels synchronously, or an empty array if there are none or the id is not a connector.

Examples

const labels = board.getConnectorLabels(connectorId)const labelIds = labels.map((label) => label.id)

Types: IBoardConnectorLabel

Package: @univerjs-pro/boards · Type definitions

FBoard.getConnectorLabelStyle

Gets the detached visual style of one connector label.

Label appearance is separate from rich-text formatting. fill and stroke style the label box, while interruptLine controls whether the connector route is visually interrupted behind the label. Missing fill means transparent, missing stroke means no border, and missing interruptLine means the route is interrupted.

getConnectorLabelStyle(elementId: string): IBoardConnectorLabelStyle | null

Parameters

• elementId — Required. Existing connector id.

Returns

Detached label style, or null when the connector or label is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const style = board.getConnectorLabelStyle('connector-id')if (style) console.log(style.fill?.color, style.stroke?.color, style.interruptLine ?? true)

Types: IBoardConnectorLabelStyle

Package: @univerjs-pro/boards · Type definitions

FBoard.getConnectorLabelText

Gets one connector label as a detached rich-text value.

The returned value never mutates the Board directly. Call copy() to obtain the shared Univer RichTextBuilder, update the builder, and pass it to setConnectorLabelText() to commit the change through the Board command layer. This is the same value/builder flow used by other Univer rich-text facade APIs.

getConnectorLabelText(elementId: string): RichTextValue | null

Parameters

• elementId — Required. Existing connector id.

Returns

Detached label text, or null when the connector or label is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },])if (!shapes) throw new Error('Cannot insert shapes')const connector = board.insertConnector({  fromElementId: shapes[0].getId(),  toElementId: shapes[1].getId(),  labelText: 'Next',})if (!connector) throw new Error('Cannot insert connector')const value = board.getConnectorLabelText(connector.id)const builder = value?.copy()if (!builder) throw new Error('Connector label is missing')builder.setStyle(0, builder.toPlainText().length, {  fs: 16,  bl: univerAPI.Enum.BooleanNumber.TRUE,  cl: { rgb: '#2563eb' },})if (!board.setConnectorLabelText(connector.id, builder)) throw new Error('Cannot style label')

Types: RichTextValue

Package: @univerjs-pro/boards · Type definitions

FBoard.getConnectorStyle

Returns a detached connector style snapshot.

getConnectorStyle(elementId: string): IBoardFacadeConnectorStylePatch | null

Parameters

• elementId — Required. Existing connector id.

Returns

Editable connector style, or null when the id is missing or not a connector.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shapes = board.insertShapes([  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },])if (!shapes) throw new Error('Cannot insert shapes')const connector = board.insertConnector({  fromElementId: shapes[0].getId(),  toElementId: shapes[1].getId(),})if (!connector) throw new Error('Cannot insert connector')console.log(board.getConnectorStyle(connector.id))

Types: IBoardFacadeConnectorStylePatch

Package: @univerjs-pro/boards · Type definitions

FBoard.getContainerChildren

Gets direct children of a container in board z-order.

This only returns direct members whose parentId equals containerId. Use getContainerDescendants() when an agent needs nested container content.

Agent scripts should prefer getContainerChildren() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getContainerChildren(containerId: string): IBoardPageElement[]

Parameters

• containerId — Required. Container element id.

Returns

Direct child elements. Returns an empty array for missing or non-container elements.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (!board.createContainer({ id: containerId, left: 80, top: 80 }))  throw new Error('Cannot create container')const child = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 120 },})if (!child || !board.reparentElements([child.getId()], containerId))  throw new Error('Cannot insert child')console.log(board.getContainerChildren(containerId))

Types: IBoardPageElement

Package: @univerjs-pro/boards · Type definitions

FBoard.getContainerDescendants

Gets all nested descendants of a container in traversal order.

The traversal follows direct children in board z-order and then walks nested containers. It guards against cycles so agent scripts can inspect imperfect imported content without hanging.

Agent scripts should prefer getContainerDescendants() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getContainerDescendants(containerId: string): IBoardPageElement[]

Parameters

• containerId — Required. Container element id.

Returns

Nested child elements. Returns an empty array for missing or empty containers.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (!board.createContainer({ id: containerId, left: 80, top: 80 }))  throw new Error('Cannot create container')const child = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 120 },})if (!child || !board.reparentElements([child.getId()], containerId))  throw new Error('Cannot insert child')console.log(board.getContainerDescendants(containerId))

Types: IBoardPageElement

Package: @univerjs-pro/boards · Type definitions

FBoard.getContainerStyle

Returns a detached container-style snapshot.

getContainerStyle(elementId: string): IBoardFacadeContainerStyle | null

Parameters

• elementId — Required. Existing container id.

Returns

Editable frame/title style, or null when the id is missing or not a container.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (!board.createContainer({ id: containerId, left: 80, top: 80 }))  throw new Error('Cannot create container')console.log(board.getContainerStyle(containerId))

Types: IBoardFacadeContainerStyle

Package: @univerjs-pro/boards · Type definitions

FBoard.getData

Gets the current in-memory board snapshot.

This does not force resource serialization. Use save() when you need a persisted snapshot with resource data. The returned serialization snapshot is detached: changing it cannot mutate the live board. For ordinary board inspection, prefer describeElements() or other id-based reads.

getData(): IBoardData

Returns

The current board data.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const data = board.getData()console.log(data.name, Object.keys(data.pages ?? {}).length)

Types: IBoardData

Package: @univerjs-pro/boards · Type definitions

FBoard.getElement

Gets one element by generated id.

This low-level read returns a detached model snapshot. Changing it cannot mutate the live board; use updateElement() or an intent-specific mutation method to apply changes.

getElement(elementId: string): IBoardPageElement | null

Parameters

• elementId — Required. Generated board element id.

Returns

The element, or null when it is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape || !board.getElement(shape.getId())) throw new Error('Cannot read inserted shape')

Types: IBoardPageElement

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementBounds

Reads one board element's resolved bounds by generated id.

Use this when code starts from a UI selection id and only needs board-coordinate bounds for layout, collision, or viewport calculations. This is lighter than describeElement() because it returns only the resolved bounds.

Agent scripts should prefer getElementBounds() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getElementBounds(elementId: string): IBoardRect | null

Parameters

• elementId — Required. Generated board element id.

Returns

Resolved board-coordinate bounds, or null when the element is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.getElementBounds(shape.getId()))

Types: IBoardRect

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementCenter

Reads one board element's center point by generated id.

Use this when code starts from a UI selection id and needs a stable board-coordinate point for connector endpoints, relative placement, or distance calculations. The center is derived from resolved world bounds, so it accounts for parent container transforms.

Agent scripts should prefer getElementCenter() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getElementCenter(elementId: string): IBoardFacadePoint | null

Parameters

• elementId — Required. Generated board element id.

Returns

Center point in board coordinates, or null when the element is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.getElementCenter(shape.getId()))

Types: IBoardFacadePoint

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementGeometry

Reads one board element's lightweight geometry by generated id.

Use this when code starts from a UI selection id and needs both resolved bounds and center point. It is lighter than describeElement() and avoids making agents call separate bounds and center APIs.

Agent scripts should prefer getElementGeometry() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getElementGeometry(elementId: string): IBoardFacadeElementGeometry | null

Parameters

• elementId — Required. Generated board element id.

Returns

Geometry snapshot, or null when the element is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.getElementGeometry(shape.getId()))

Types: IBoardFacadeElementGeometry

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementIdsInOrder

Gets generated board element ids in board z-order with optional facade filters.

Use this narrow helper when an id-based integration needs ordered ids but the script still wants the same type, visibility filters supported by findElements(). Prefer getElementIdsInOrder() for prompts and saved agent plans.

getElementIdsInOrder(query?: IBoardFacadeElementQuery): string[]

Parameters

• query — Optional. Default: {}. Optional type and visibility filters.

Returns

Generated element ids in board z-order.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const visibleShapeIds = board.getElementIdsInOrder({  elementTypes: [univerAPI.Enum.BoardElementType.Shape],})console.log(visibleShapeIds)

Types: IBoardFacadeElementQuery

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementLayout

Returns the active Board page's element layout in Board model coordinates.

This is a model-only query. It does not depend on a Scene, viewport, scroll position, zoom, Canvas, DOM, or a UI plugin. Because Board is an infinite canvas, the result intentionally has no finite container bounds.

getElementLayout(): IBoardFacadeElementLayoutResult

Returns

Ordered element bounds and their union.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const layout = board.getElementLayout()console.log(layout.subUnitId, layout.contentBounds)

Types: IBoardFacadeElementLayoutResult

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementMetadata

Gets resolved top-level metadata for an element.

The returned booleans use board defaults: visible and selectable default to true, while locked defaults to false. This is easier for agents than reading raw optional model fields.

Agent scripts should prefer getElementMetadata() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getElementMetadata(elementId: string): IBoardFacadeElementMetadata | null

Parameters

• elementId — Required. Generated board element id.

Returns

Resolved metadata, or null when the element is missing.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const shape = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 80, top: 80 },})if (!shape) throw new Error('Cannot insert shape')console.log(board.getElementMetadata(shape.getId()))

Types: IBoardFacadeElementMetadata

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementOrder

Gets generated element ids in the current board z-order.

This is a low-level order API. Use it when a UI integration or import/export pipeline must preserve the raw page order. Agent scripts should prefer getElementIdsInOrder() for generated element ids or describeElements() for type, metadata, and z-order in one descriptor list.

getElementOrder(): string[]

Returns

Ordered generated element ids. Returns an empty array when the page does not exist.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')console.log(board.getElementOrder())

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementParentChain

Gets the parent container chain for an element.

The first id is the direct parent, followed by ancestors. This is useful when an agent needs to understand whether an element is inside a group, generic container, or swimlane before moving or deleting it.

Agent scripts should prefer getElementParentChain() when element ids are known; use this id-based method only for UI selection ids, event payload ids, or low-level integrations.

getElementParentChain(elementId: string): string[]

Parameters

• elementId — Required. Element id to inspect.

Returns

Parent container ids from nearest to farthest.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')const containerId = `container-${Date.now()}`if (!board.createContainer({ id: containerId, left: 80, top: 80 }))  throw new Error('Cannot create container')const child = board.insertShape({  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,  transform: { left: 120, top: 120 },})if (!child || !board.reparentElements([child.getId()], containerId))  throw new Error('Cannot insert child')console.log(board.getElementParentChain(child.getId()))

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementPermission

Returns the permission facade for one stable Board element id.

The Board's single page id remains an internal address component and is resolved automatically.

getElementPermission(elementId: string): FBoardElementPermission

Parameters

• elementId — Required. Stable Board element id.

Returns

Permission facade combining the Board and Element Edit points.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active Board.')const element = Object.values(board.getElements())[0]if (!element) throw new Error('Board element not found.')await board.getElementPermission(element.id).setReadOnly()

Types: FBoardElementPermission

Package: @univerjs-pro/boards · Type definitions

FBoard.getElements

Gets all elements on the Board as an id-to-element map.

Use getElementOrder() when iteration order matters. This low-level read returns detached model snapshots. For agent reasoning over board content, prefer describeElements() or id-based descriptor APIs so scripts do not depend on internal element payloads.

getElements(): Record<string, IBoardPageElement>

Returns

Element map in Board z-order, or an empty object when the Board is empty.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')console.log(Object.keys(board.getElements()))

Types: IBoardPageElement · Record

Package: @univerjs-pro/boards · Type definitions

FBoard.getElementsBoundingRect

Reads the union bounds for all board elements matching a facade query.

Use this when an agent needs the overall occupied board rectangle for visible content, a group, a type subset, or another query without first collecting ids. It uses the same filters as describeElements(), including default hidden-element filtering.

getElementsBoundingRect(query?: IBoardFacadeElementQuery): IBoardRect | null

Parameters

• query — Optional. Default: {}. Optional type and visibility filters.

Returns

Union bounds for matching elements, or null when the query matches no bounded elements.

Examples

const board = univerAPI.getActiveBoard()if (!board) throw new Error('No active board')console.log(board.getElementsBoundingRect({ elementType: univerAPI.Enum.BoardElementType.Shape }))