# Univer Embed

> Embed one Univer Unit inside another through DSH tools and the Lite Interface. Use proactively when a Sheet, Doc, Slide, Base, Board, dashboard, report, presentation, database, or canvas should display or interact with content from another accessible Univer Workspace Unit.

- Skill: `dream-num/univer-embed` (Agent Skill)
- Install (CLI): `npx get-skill add dream-num/univer-embed`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dream-num/univer-embed/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: dream-num (https://skillmd.com/u/dream-num)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/dream-num/univer-embed

---


# Embed Units

Load `univer` plus the host and child Unit skills first. Resolve host and child as Univer Workspace Units and address each by exact `unitId`. Author changes in a draft worktree. Verify that the runtime can resolve the referenced child; access to a Unit does not by itself guarantee it is loaded.

The Viewer supports one Embed level only. A host may contain multiple sibling Embeds, but do not embed a Unit that itself contains an Embed. Keep those Units as siblings or link them instead.

Use `univer_api` to show `FUniver.createEmbed`, `FEmbed`, `FEmbedHostSurface`, `ICreateEmbedParams`, and `IEmbedDescriptor` before authoring unfamiliar Embed code.

Create and verify the child Unit first. Use its exact `unitId` and actual Unit type in the ResourceRef. For a `SheetFloating` host, `context` requires explicit drawing placement. Absolute canvas bounds use `{ kind: univerAPI.Enum.SheetDrawingAnchorType.None, bounds: { left, top, width, height } }`.

Example: embed a Doc as a Sheet tab through `univer_execute` targeting the host Sheet Unit:

```js
const hostUnitId = "<host-unit-id>";
const childUnitId = "<child-unit-id>";
const sourceRef = "#unit=" + childUnitId + "&type=doc";
const embed = univerAPI.createEmbed({
  embedId: "<embed-id>",
  host: {
    unitId: hostUnitId,
    surface: univerAPI.Enum.FEmbedHostSurface.SheetTab,
  },
  content: {
    unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC,
    ref: sourceRef,
  },
  interaction: "interactive",
});
const child = await embed.loadAsync();
if (!child || child.getId() !== childUnitId) {
  throw new Error("Embedded child mismatch");
}
const descriptor = embed.getDescriptor();
if (descriptor.source?.ref !== sourceRef) {
  throw new Error("Embedded ResourceRef mismatch");
}
return { childUnitId: child.getId(), descriptor };
```

For another child type, change both `unitType` and the ResourceRef `type` to the same actual type.

After mutation:

1. Re-read the returned child Facade and descriptor in a fresh `univer_execute`.
2. Verify the exact child Unit ID/type, ResourceRef, host surface, interaction mode, and host anchor/placement.
3. Inspect both host and child Units with `univer_inspect` where useful.
4. Follow the Host Unit Skill's `univer_screenshot` workflow and inspect the returned PNG to confirm the child renders inside its host. Structural ResourceRef readback remains required because a screenshot alone does not prove the child ID/type binding.
5. Follow the `univer` ready/status workflow.

## Referencing another Unit's data from a Chart

When a Chart on a Slide, Doc, or Board should reflect a range in a different Unit, bind it as a
ResourceRef instead of pasting the values. Values are a snapshot: a source edit will not change the
Chart. A ResourceRef keeps the Chart live.

The source and host are authorized Units in the same Workspace deployment, addressed by `unitId`. Resolve
the exact source object with `univer_api` (`action: "show"`, `queries: ["IResourceRefChartDataSourceInput"]`),
then pass it straight
to the host Chart's `setSource` — it accepts the ref contents (`{ file?, unit, part }`) directly.
Wrapping it as `{ source: { kind, ref } }` fails normalization with `RESOURCE_REF_INVALID_UNIT`.

Verify the stored source is a reference (its `dataSource.source.kind` is `resource-ref`), and confirm
the Chart reads the referenced range through `univer_edit` with `mode: "read"`. A cross-Unit reference resolves only when
the source Unit is loaded in the same runtime as the host — in the Viewer both are open together (for
example both embedded in a Board). If the source is not loaded, the headless read or `univer_screenshot` can show a placeholder;
review the Chart in the Workspace Viewer.

Live refresh works when the runtime registers a referenced-source data provider (`watchData`) that
watches the source range. A runtime without this provider never updates the Chart on a source edit. Verify provider support
in the Workspace Viewer; headless reads and `univer_screenshot` do not drive this refresh.

