# FEmbed

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

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

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

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

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()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#createembed)
* [`FUniver.getEmbed()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getembed)
* [`FUniver.listEmbeds()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#listembeds)

## Setup

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

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

```typescript
getBounds(): IGroupBaseBound | null
```

**Returns**

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

**Examples**

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

**Types:** [`IGroupBaseBound`](https://unpkg.com/@univerjs/core/lib/types/shared/shape.d.ts)

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

### `FEmbed.getChildType`

Get the embedded child unit type.

```typescript
getChildType(): UniverInstanceType | undefined
```

**Returns**

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

**Examples**

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

**Types:** [`UniverInstanceType`](https://unpkg.com/@univerjs/protocol/lib/types/ts/univer/constants/univer.d.ts)

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

### `FEmbed.getChildUnitId`

Get the embedded child unit id.

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

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

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

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

```typescript
getDescriptor(): IEmbedDescriptorSnapshot
```

**Returns**

The descriptor and live host context.

**Examples**

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

**Types:** [`IEmbedDescriptorSnapshot`](https://unpkg.com/@univerjs-pro/embed/lib/types/types/host-context.d.ts)

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

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

```typescript
getDisplayTarget(): EmbedDisplayTarget | undefined
```

**Returns**

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

**Examples**

```ts
const embed = univerAPI.getEmbed({
  hostUnitId: 'board-unit-id',
  embedId: 'base-calendar',
})

console.log(embed?.getDisplayTarget())
// { tableId: 'events', viewId: 'calendar' }
```

**Types:** [`EmbedDisplayTarget`](https://unpkg.com/@univerjs-pro/embed/lib/types/types/embed.d.ts)

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

### `FEmbed.getEntry`

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

```typescript
getEntry(): EmbedHostEntry
```

**Returns**

The host entry.

**Examples**

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

**Types:** [`EmbedHostEntry`](https://unpkg.com/@univerjs-pro/embed/lib/types/types/embed.d.ts)

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

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

```typescript
getHostAnchorId(): string
```

**Returns**

The host anchor id.

**Examples**

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

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

### `FEmbed.getHostType`

Get the host unit type.

```typescript
getHostType(): UniverInstanceType
```

**Returns**

The host `UniverInstanceType`.

**Examples**

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

**Types:** [`UniverInstanceType`](https://unpkg.com/@univerjs/protocol/lib/types/ts/univer/constants/univer.d.ts)

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

### `FEmbed.getHostUnitId`

Get the host unit id that owns this embed.

```typescript
getHostUnitId(): string
```

**Returns**

The host unit id.

**Examples**

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

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

### `FEmbed.getId`

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

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

**Returns**

The embed id.

**Examples**

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

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

### `FEmbed.getPlacement`

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

```typescript
getPlacement(): ISheetDrawingPlacement | null
```

**Returns**

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

**Examples**

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

**Types:** [`ISheetDrawingPlacement`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts)

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

### `FEmbed.loadAsync`

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

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

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

```ts
const embed = univerAPI.listEmbeds()[0]

const childDocument = await embed.loadAsync<UniverFacadeTypes.FDocument>()
```

JavaScript

```ts
const embed = univerAPI.listEmbeds()[0]

const childDocument = await embed.loadAsync()
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`ILoadEmbedOptions`](https://unpkg.com/@univerjs-pro/embed/lib/types/facade/f-embed.d.ts)

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

### `FEmbed.remove`

Remove this embed from its host unit.

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

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

**Returns**

`true` when the command succeeds.

**Examples**

Browser console

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

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

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

```typescript
setBounds(bounds: IGroupBaseBound): boolean
```

**Parameters**

* `bounds` — Required. Bounds in the host model coordinate system.

**Returns**

Whether the command succeeded.

**Examples**

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

**Types:** [`IGroupBaseBound`](https://unpkg.com/@univerjs/core/lib/types/shared/shape.d.ts)

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

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

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

```ts
const embed = univerAPI.getEmbed({
  hostUnitId: 'board-unit-id',
  embedId: 'sheet-embed',
})

embed?.setDisplayTarget({ subUnitId: 'sheet-2' })
```

Slide

```ts
const embed = univerAPI.getEmbed({
  hostUnitId: 'board-unit-id',
  embedId: 'slide-embed',
})

embed?.setDisplayTarget({ pageId: 'page-2' })
```

Base

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

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

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

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

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

Position with an exact marker

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

Both inferred from bounds

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

Both with exact markers

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

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

**Types:** [`ISheetDrawingPlacementInput`](https://unpkg.com/@univerjs/sheets-drawing/lib/types/services/sheet-drawing-placement.d.ts)

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