# Embed

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

| Packages | `@univerjs-pro/embed` |
| -------- | --------------------- |

The Embed Facade API creates and manages references between Univer units. Import the package facade before using these APIs.

```ts
import '@univerjs-pro/embed/facade'
```

## `FUniver` APIs

| Method                         | Description                                              |
| ------------------------------ | -------------------------------------------------------- |
| `createEmbed(params)`          | Create an embed descriptor and its host anchor.          |
| `getEmbed(params)`             | Get an embed by its host unit and embed ID.              |
| `listEmbeds(params?)`          | List active embeds, optionally limited to one host unit. |
| `removeEmbed(params)`          | Remove an embed by its host unit and embed ID.           |
| `loadUnitAsync(ref, options?)` | Load a referenced unit into the current runtime.         |

## Create and load an embed

The host unit must already be registered in the current runtime. The required `context` fields depend on the selected host surface.

```ts
const embed = univerAPI.createEmbed({
  embedId: 'doc-in-sheet',
  host: {
    unitId: 'host-workbook-id',
    surface: univerAPI.Enum.FEmbedHostSurface.SheetFloating,
    context: {
      subUnitId: 'host-sheet-id',
      left: 80,
      top: 80,
      width: 640,
      height: 360,
    },
  },
  content: {
    unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC,
    ref: '#unit=embedded-document-id&type=doc',
  },
})

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

For a known resource reference, load the unit without creating an embed:

```ts
const document = await univerAPI.loadUnitAsync(
  '#unit=embedded-document-id&type=doc',
  { unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC },
)
```

## `FEmbed` APIs

| Method                                  | Description                                                |
| --------------------------------------- | ---------------------------------------------------------- |
| `getId()`                               | Get the ID that is unique within the host unit.            |
| `getHostUnitId()` / `getHostAnchorId()` | Get the owning unit and host anchor IDs.                   |
| `getChildUnitId()`                      | Get the locally materialized child unit ID, if available.  |
| `getHostType()` / `getChildType()`      | Get the Univer instance types of the host and child units. |
| `getEntry()`                            | Get the host entry used to place the embed.                |
| `getDescriptor()`                       | Get a copy of the embed descriptor.                        |
| `loadAsync(options?)`                   | Materialize and load the referenced child unit.            |
| `remove()`                              | Remove this embed from its host unit.                      |

## Host surfaces

Use `univerAPI.Enum.FEmbedHostSurface` to choose the host placement:

| Value           | Host placement             |
| --------------- | -------------------------- |
| `DocBlock`      | Document custom block      |
| `SheetTab`      | Sheet tab                  |
| `SheetFloating` | Floating object in a sheet |
| `BaseTable`     | Base table-list block      |
| `SlidePage`     | Slide page-list block      |
| `SlideFloating` | Floating object in a slide |
| `BoardFloating` | Floating object on a board |

Source: 

`@univerjs-pro/embed/facade`