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:
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:
- Re-read the returned child Facade and descriptor in a fresh
univer_execute. - Verify the exact child Unit ID/type, ResourceRef, host surface, interaction mode, and host anchor/placement.
- Inspect both host and child Units with
univer_inspectwhere useful. - Follow the Host Unit Skill's
univer_screenshotworkflow 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. - Follow the
univerready/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.