Univer Doc Units
Load univer first. univer_execute provides univerAPI, api (the same object), and doc (the FDocument selected by unitId). Do not redeclare them. A Doc Unit does not provide workbook or presentation; if one appears undefined, verify the selected Unit type.
Select paragraphs with doc.getParagraphs() and doc.getParagraph(paragraphId). Resolve exact signatures and enums with univer_api; do not guess or use Doc model internals.
Modern Docs through Markdown
For new Modern Docs, write a session Markdown file and call univer_compile_markdown once.
Read Markdown authoring with
univer_skill_resource({ skill: "univer-doc", path: "references/markdown.md" }) for valid syntax,
assets, and tool examples. The compiler is shared through the AI SDK; Workspace authentication,
target identities, session paths, and review remain this application's responsibility.
- Create a draft Worktree, then pass
sourceandworktreeIdtouniver_compile_markdown. It creates the Doc Unit; do not calluniver_unitto create a placeholder. Use returnedunit.unitIdand save the returned executionsourceMapas session JSON. - Preserve SDK default typography, line/paragraph spacing, and callout colors. Use plain
:::callout{#notice}. Modern columns use native ColumnGroup with 2–5 columns; do not use Traditional section breaks or replace requested columns with layout tables. - Before each partial update, call
univer_export_markdownfor selected explicit top-level IDs. It reads current native content, resources, a refreshed map, and the authoritative revision. Edit that fragment, retain its root IDs, then passunitId,sourceMapFile, and the sameblockIdstogether touniver_compile_markdown. The revision is read metadata. Save the new execution map on success. - Native content is authoritative; old Markdown misses subsequent editor changes. On conflicts, export again and replan. Unsupported content or diagnostic errors stop conversion; report the exact limitation instead of flattening content or overwriting the Doc.
- Keep all source/assets/map files inside the session workspace. Inspect and screenshot the result before the normal Worktree review handoff. Generation should finish after compilation and verification; avoid cosmetic Facade patches after conversion.
Model essentials
- A new Doc starts with one empty paragraph. Usually update it with
setTextor append withdoc.appendParagraph(text). - Paragraph editing methods live on
doc:appendParagraph,insertParagraph,insertText, anddeleteRange. - Paragraph IDs are stable across multi-step edits; indexes drift as content changes.
FDocumentParagraphsupportsgetText,setText,appendText,setStyle, andgetRange.- Lists and task helpers include
isListItem,isTask, andsetTaskChecked. - Native charts use the direct
doc.newChart(),doc.insertChart(),doc.getCharts(), anddoc.getChart()methods. - Colors must use
#RRGGBB. Docs do not support formulas or recalculation.
Data stream
The body is one dataStream string. Paragraphs are separated by \r, and the document ends with \r\n. body.paragraphs[i].startIndex identifies the terminating \r; offsets passed to insertText, deleteRange, and text-style operations address this stream. Preserve paragraph terminators.
Paragraph and text styles
Pass paragraph properties and textStyle together to paragraph.setStyle when the entire paragraph shares one style. Query IParagraphStyle rather than guessing enum values.
const paragraph = doc.appendParagraph("Section Title");
const changed = paragraph.setStyle({
namedStyleType: api.Enum.NamedStyleType?.HEADING_1 ?? "HEADING_1",
textStyle: { bl: api.Enum.BooleanNumber.TRUE },
});
if (!changed) throw new Error("paragraph style update failed");
Important paragraph fields include horizontalAlign, namedStyleType, headingId, indentStart, and indentFirstLine. Text style uses compact fields such as bl, it, cl: { rgb }, and bg: { rgb }. Later style writes can replace earlier fields, so merge base font family, size, spacing, and color with local overlays deliberately.
Native images
Use a stable Base64 data URI for local reproducible authoring. In the headless authoring runtime, always provide both width and height. Set wrapping explicitly and use a body range rather than a transient selection.
const anchor = doc.getParagraphs()[0];
if (!anchor) throw new Error("image anchor missing");
const range = anchor.getRange();
const image = await doc.insertImage({
source: imageDataUri,
imageSourceType: api.Enum.ImageSourceType.BASE64,
width: 320,
height: 180,
wrappingStyle: api.Enum.DocsImageWrappingStyle.INLINE,
textRange: {
startOffset: range.startOffset,
endOffset: range.startOffset,
collapsed: true,
segmentId: anchor.getSegmentId(),
},
});
if (!image) throw new Error("image insert failed");
Use INLINE for normal content, WRAP_SQUARE or WRAP_TOP_AND_BOTTOM when text should reflow, and reserve BEHIND_TEXT / IN_FRONT_OF_TEXT for intentional overlays. Never persist temporary signed URLs, install global image polyfills, or write drawing storage directly. Verify doc.getImages() and docx export when requested.
Document flavor and pagination
Check doc.getDocumentFlavor() or doc.isTraditional() before page-specific work. A new Doc is Modern and pageless. Traditional section/page APIs reject Modern Docs; do not simulate pages with large spacers.
For a Traditional Doc, insert a hard page boundary with one atomic section command:
if (!doc.isTraditional()) throw new Error("Traditional Doc required for physical pagination");
const chapter = doc.findParagraphByText("Chapter 2");
if (!chapter) throw new Error("chapter heading missing");
const section = doc.insertSectionBreak(chapter.getInfo().startOffset, {
nextSectionType: api.Enum.SectionType.NEXT_PAGE,
});
if (!section) throw new Error("section break insert failed");
Use section.getEffectivePageSetup() for resolved geometry. keepNext, keepLines, and widowControl improve natural pagination but do not create hard breaks.
Tables and layout
For fixed columns in a Traditional Doc, prefer a borderless layout table. Real data tables must define column widths, header rows, merges, and borders explicitly.
const table = doc.insertTableFromData(
[
["Group", ""],
["Name", "Description"],
["A", "Long description"],
],
{ width: 602, columnWidths: [200.667, 401.333], headerRowCount: 2 },
);
if (!table) throw new Error("table insert failed");
table.mergeCells({ startRow: 0, endRow: 0, startColumn: 0, endColumn: 1 });
table.setHeaderRowCount(2);
table.setTableBorder({
preset: api.Enum.DocsTableBorderPreset.None,
color: "#FFFFFF",
width: 0,
});
Constrain cell-local paragraph edits with table.getCellContentRange(row, column) and confirm the target text. Do not search duplicate text globally and broadcast a mutation. The public Facade has no verified dynamic current-page field, table-cell padding mutation, or cell vertical-alignment mutation; report these gaps instead of faking them.
Native charts
Create detached chart information directly from doc, then insert it to obtain a live
FDocumentChart. Query FDocument.newChart, FDocument.insertChart, FDocument.getCharts,
FDocument.getChart, FDocumentChartBuilderOf, and DocsChartInsertAnchorKind before authoring.
const info = doc
.newChart(univerAPI.Enum.ChartTypeString.Column)
.setTitle({ text: "Quarterly Revenue" })
.setSource([
["Quarter", "Revenue"],
["Q1", 12],
["Q2", 18],
["Q3", 15],
])
.setCategoryField(0)
.setValueFields([1])
.setPosition({ kind: univerAPI.Enum.DocsChartInsertAnchorKind.BodyOffset, offset: 0 })
.setInline()
.setSize(480, 320)
.build();
const inserted = await doc.insertChart(info);
return { chartId: inserted.getId(), drawingId: inserted.getDrawingId(), info: inserted.getInfo() };
doc.getCharts() and doc.getChart(id) return live charts. Await
chart.setDataSource(values) for data changes. For a complete replacement, use
chart.toBuilder().build() and await chart.update(info). Remove it with await chart.remove()
and check the boolean. Await every asynchronous mutation before execution returns. Verify in a
fresh read-only execution with
doc.getCharts().map((item) => ({ id: item.getId(), drawingId: item.getDrawingId(), type: item.getType(), info: item.getInfo() })).
Inspect and verify
After each mutation:
- Call
univer_inspectfor the document overview and relevant paragraph/range when supported. - Use a fresh read-only
univer_executeto confirm full paragraph text/order, stable IDs, styles, lists/tasks, table dimensions, image identities, chart descriptions, document flavor, section breaks, headers, footers, and page setup required by the task. - Call
univer_screenshotwith the DocunitId, selected worktree or trunk, and an explicit workspaceoutputdirectory. Inspect every returned page PNG for wrapping, physical pagination, image placement, and layout failures. Logical inspection alone cannot prove these facts. - If
.docxdelivery is requested, calluniver_exportonly after structural readback succeeds. - Follow the
univerready/status handoff workflow.
compile-typst is not available in this plugin. Do not reproduce it with unrelated converters.