Workspace Embed
Load core plus the Host and child Unit Skills. The command targets the Host Unit; the embedded
child is a read-only Source selected by a ResourceRef.
Use api show for FUniver.createEmbed, FEmbed, FEmbedHostSurface, ICreateEmbedParams, and IEmbedDescriptor. Use api find with keywords embed host surface.
Identity contract
- Build a self ResourceRef from the exact stable child
unitIdand its Unit type:#unit=<source-unit-id>&type=<sheet|doc|slide|base|board>. - Obtain the Source identity from the caller, an existing Host descriptor, or an already selected
identity workflow. A display name, Workspace URL, share link, Node ID, and Resource ID are not
substitutes for
unitId. - Do not add the child to the task Worktree merely so Embed can read it, and do not preload it. The
Workspace Provider materializes an authorized child when
loadAsync()first needs it. - One Host may have sibling Embeds. Do not create a nested Embed graph unless the selected Viewer explicitly supports it.
Choose the Host surface and required context from the Host Unit Skill. For a Sheet floating object, provide an explicit drawing placement; a Sheet tab needs no placement:
const sourceUnitId = "<source-unit-id>";
const embed = api.createEmbed({
embedId: "<stable-embed-id>",
host: {
unitId: workbook.getId(),
surface: api.Enum.FEmbedHostSurface.SheetTab,
},
content: {
unitType: api.Enum.UniverInstanceType.UNIVER_DOC,
ref: "#unit=" + sourceUnitId + "&type=doc",
},
interaction: "interactive",
});
const child = await embed.loadAsync();
if (child?.getId?.() !== sourceUnitId) {
throw new Error("Embedded child identity mismatch.");
}
return {
embedId: embed.getId(),
childId: child.getId(),
descriptor: embed.getDescriptor(),
};
Verify the exact persisted ResourceRef, loaded child ID/type, and Host anchor in a later read-only
execute, then follow the Host screenshot and review flow. An inaccessible, missing, malformed, or
type-incompatible Source is a load failure; do not fall back to name search or silently replace it.
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 the range as a ResourceRef instead of copying its current values. Copied values are a snapshot; a ResourceRef keeps the Chart connected to the Source.
The Host and Source are Univer Units in the same Workspace deployment and are addressed by stable
unitId. Resolve the exact input with:
Use api show for IResourceRefChartDataSourceInput.
Pass the ref contents ({ file?, unit, part }) directly to
newChart(...).setSource(ref). For an existing live Chart, use
await chart.setDataSource(ref). Wrapping the ref as { source: { kind, ref } } fails normalization
with RESOURCE_REF_INVALID_UNIT.
For a Worktree Host, an authorized Source staged in the same Worktree resolves from that Worktree; otherwise the Workspace reference policy resolves the authorized trunk Source. Do not stage a read-only Source merely to make the reference load.
Verify that the stored dataSource.source.kind is resource-ref, then confirm the exact Source
Unit, Sheet/Table selector, and range in a fresh readback. Workspace Viewer and execute runtimes
materialize an authorized Source on demand; the Viewer also watches the Source data and refreshes a
live Chart when it changes. The screenshot renderer does not currently preload a Source referenced
only by a Chart, so that case can render a placeholder there; finish its visual review in the
Workspace Viewer.