FEmbed

Facade object for one embed descriptor.

FEmbed is intentionally small: it exposes stable identity fields for agents and delegates write actions back to commands.

Access

Access through:

• FUniver.createEmbed()
• FUniver.getEmbed()
• FUniver.listEmbeds()

Setup

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

@univerjs-pro/embed

FEmbed.getBounds

Returns the current rectangle for a floating Embed in its host model coordinate system.

Sheet, Slide, and Board each retain their own coordinate system. This API does not apply viewport scroll, zoom, or screen transforms.

getBounds(): IGroupBaseBound | null

Returns

Current bounds, or null for a non-floating or unresolved host anchor.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getBounds())

Types: IGroupBaseBound

Package: @univerjs-pro/embed · Type definitions

FEmbed.getChildType

Get the embedded child unit type.

getChildType(): UniverInstanceType | undefined

Returns

The child UniverInstanceType, or undefined only when the descriptor does not declare a child type.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getChildType())

Types: UniverInstanceType

Package: @univerjs-pro/embed · Type definitions

FEmbed.getChildUnitId

Get the embedded child unit id.

getChildUnitId(): string | undefined

Returns

The child unit id, or undefined when the descriptor points to a remote resource that has not been resolved locally.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getChildUnitId())

Package: @univerjs-pro/embed · Type definitions

FEmbed.getDescriptor

Returns a detached descriptor snapshot with the Embed's current host context.

The persisted descriptor contains identity and child configuration only. context is resolved from the current host model on every call. When the host anchor no longer exists, context.resolved is false; stale creation geometry is never returned as current geometry.

getDescriptor(): IEmbedDescriptorSnapshot

Returns

The descriptor and live host context.

Examples

const embed = univerAPI.listEmbeds()[0]const descriptor = embed.getDescriptor()if (descriptor.context.resolved) {  console.log(descriptor.context)}

Types: IEmbedDescriptorSnapshot

Package: @univerjs-pro/embed · Type definitions

FEmbed.getDisplayTarget

Get the persisted child subview selected for this embed.

This value is the author- or Agent-selected default stored in the host embed resource. A user's local worksheet, page, table, view, or dashboard navigation does not change it. The returned IDs are stable resource IDs rather than display names.

getDisplayTarget(): EmbedDisplayTarget | undefined

Returns

The display target, or undefined when the child uses its default view.

Examples

const embed = univerAPI.getEmbed({  hostUnitId: 'board-unit-id',  embedId: 'base-calendar',})console.log(embed?.getDisplayTarget())// { tableId: 'events', viewId: 'calendar' }

Types: EmbedDisplayTarget

Package: @univerjs-pro/embed · Type definitions

FEmbed.getEntry

Get the host entry used by this embed, such as docs-custom-block or sheets-sheet-tab.

getEntry(): EmbedHostEntry

Returns

The host entry.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getEntry())

Types: EmbedHostEntry

Package: @univerjs-pro/embed · Type definitions

FEmbed.getHostAnchorId

Get the host anchor id. The host product uses this id to place the embed in a doc custom block, sheet tab, sheet floating object, and so on.

getHostAnchorId(): string

Returns

The host anchor id.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getHostAnchorId())

Package: @univerjs-pro/embed · Type definitions

FEmbed.getHostType

Get the host unit type.

getHostType(): UniverInstanceType

Returns

The host UniverInstanceType.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getHostType())

Types: UniverInstanceType

Package: @univerjs-pro/embed · Type definitions

FEmbed.getHostUnitId

Get the host unit id that owns this embed.

getHostUnitId(): string

Returns

The host unit id.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getHostUnitId())

Package: @univerjs-pro/embed · Type definitions

FEmbed.getId

Get the embed id. This id is stable inside the host unit.

getId(): string

Returns

The embed id.

Examples

const embed = univerAPI.listEmbeds()[0]console.log(embed.getId())

Package: @univerjs-pro/embed · Type definitions

FEmbed.getPlacement

Returns a Sheet floating Embed's normalized OneCell, TwoCell, or Absolute placement.

getPlacement(): ISheetDrawingPlacement | null

Returns

Current Sheet placement, or null when this is not a resolved Sheet floating Embed.

Examples

const placement = embed.getPlacement()console.log(placement)

Types: ISheetDrawingPlacement

Package: @univerjs-pro/embed · Type definitions

FEmbed.loadAsync

Load this embed's referenced child unit into the current runtime.

loadAsync<TLoadFacade = TUnitFacade>(options?: ILoadEmbedOptions): Promise<TLoadFacade>

Parameters

• options — Optional. Default: {}. Optional request controls.

Returns

A promise resolving to the loaded child unit facade instance.

Examples

TypeScript

const embed = univerAPI.createEmbed<UniverFacadeTypes.FDocument>({  embedId: 'doc-in-sheet',  host: {    unitId: 'host-unit-id',    surface: univerAPI.Enum.FEmbedHostSurface.SheetFloating,    context: {      subUnitId: 'host-sheet-id',      placement: {        kind: univerAPI.Enum.SheetDrawingAnchorType.Position,        bounds: { left: 80, top: 80, width: 640, height: 360 },      },    },  },  content: {    unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC,    ref: '#unit=another-unit-id&type=doc',  },})const childDocument = await embed.loadAsync()

TypeScript descriptor read type fallback

const embed = univerAPI.listEmbeds()[0]const childDocument = await embed.loadAsync<UniverFacadeTypes.FDocument>()

JavaScript

const embed = univerAPI.listEmbeds()[0]const childDocument = await embed.loadAsync()

Types: Promise · ILoadEmbedOptions

Package: @univerjs-pro/embed · Type definitions

FEmbed.remove

Remove this embed from its host unit.

This method executes RemoveEmbedCommand; it does not edit the embed model directly.

remove(): boolean

Returns

true when the command succeeds.

Examples

Browser console

const embed = univerAPI.listEmbeds()[0]console.log(embed.remove())

Package: @univerjs-pro/embed · Type definitions

FEmbed.setBounds

Updates a floating Embed's bounds through the host adapter mutation plan.

For a Sheet floating Embed this preserves the current Position, Both, or None anchor kind and rematerializes the required markers. The update participates in Undo/Redo.

setBounds(bounds: IGroupBaseBound): boolean

Parameters

• bounds — Required. Bounds in the host model coordinate system.

Returns

Whether the command succeeded.

Examples

embed.setBounds({ left: 120, top: 80, width: 640, height: 360 })

Types: IGroupBaseBound

Package: @univerjs-pro/embed · Type definitions

FEmbed.setDisplayTarget

Persist the child subview displayed by this embed.

The target shape is determined by the child type: Sheet uses subUnitId, Slide uses pageId, and Base uses tableId with an optional viewId. Pass stable resource IDs, not display names.

The command updates the host embed resource, participates in Undo/Redo, and is synchronized through the existing collaboration mutation stream. Normal in-child navigation remains local to each collaborator.

The command validates the target shape but does not require the referenced worksheet, page, table, view, or dashboard to be loaded. When the child mounts, a missing target ID falls back to its first available subview.

setDisplayTarget(displayTarget?: EmbedDisplayTarget): boolean

Parameters

• displayTarget — Optional. The next target, or undefined to restore default selection.

Returns

true when the value is accepted (including an unchanged value); false when the embed is missing or soft-deleted. A true result does not assert that the referenced child ID currently exists.

Examples

Sheet

const embed = univerAPI.getEmbed({  hostUnitId: 'board-unit-id',  embedId: 'sheet-embed',})embed?.setDisplayTarget({ subUnitId: 'sheet-2' })

Slide

const embed = univerAPI.getEmbed({  hostUnitId: 'board-unit-id',  embedId: 'slide-embed',})embed?.setDisplayTarget({ pageId: 'page-2' })

Base

const embed = univerAPI.getEmbed({  hostUnitId: 'board-unit-id',  embedId: 'base-calendar',})embed?.setDisplayTarget({ tableId: 'events', viewId: 'calendar', dashboardId: 'operations' })embed?.setDisplayTarget(undefined) // Restore the child's default view.

Types: EmbedDisplayTarget

Package: @univerjs-pro/embed · Type definitions

FEmbed.setPlacement

Updates a Sheet floating Embed's placement through a command and host mutations.

Use exact markers when the caller owns the cell relationship. Use { kind, bounds } when the caller owns a rectangle and wants Univer to infer markers from the current Sheet grid. Position keeps a fixed size while moving with its start cell; Both follows grid changes in position and size; None remains an absolute Sheet rectangle.

setPlacement(placement: ISheetDrawingPlacementInput): boolean

Parameters

• placement — Required. Exact markers or bounds with an explicit anchor kind.

Returns

Whether the command succeeded.

Examples

Position inferred from bounds

embed.setPlacement({  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,  bounds: { left: 120, top: 80, width: 640, height: 360 },})

Position with an exact marker

embed.setPlacement({  kind: univerAPI.Enum.SheetDrawingAnchorType.Position,  from: { row: 2, column: 1, rowOffset: 8, columnOffset: 12 },  width: 640,  height: 360,})

Both inferred from bounds

embed.setPlacement({  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,  bounds: { left: 120, top: 80, width: 640, height: 360 },})

Both with exact markers

embed.setPlacement({  kind: univerAPI.Enum.SheetDrawingAnchorType.Both,  from: { row: 2, column: 1, rowOffset: 8, columnOffset: 12 },  to: { row: 14, column: 8, rowOffset: 0, columnOffset: 0 },})

Absolute

embed.setPlacement({  kind: univerAPI.Enum.SheetDrawingAnchorType.None,  left: 120,  top: 80,  width: 640,  height: 360,})

Types: ISheetDrawingPlacementInput

Package: @univerjs-pro/embed · Type definitions