dream-num/dsh-univer-office/univer-embed

Embed Units

Load univer plus the host and child Unit skills first. Keep both Units in the same .univer file and same draft worktree, and address each by exact unitId.

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:

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 Units live in the same .univer target; each is 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 in a fresh read back. 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, univer_execute or univer_screenshot can show a placeholder; review the Chart in the Viewer.

Live refresh works when the runtime registers a referenced-source data provider (watchData) that watches the source range. The plugin Viewer registers one for Sheet ranges; a runtime without it never updates the Chart on a source edit, and headless univer_execute/univer_screenshot never drive this refresh.