dream-num/dsh-univer-office/univer-doc

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.

Model essentials

• A new Doc starts with one empty paragraph. Usually update it with setText or append with doc.appendParagraph(text).
• Paragraph editing methods live on doc: appendParagraph, insertParagraph, insertText, and deleteRange.
• Paragraph IDs are stable across multi-step edits; indexes drift as content changes.
• FDocumentParagraph supports getText, setText, appendText, setStyle, and getRange.
• Lists and task helpers include isListItem, isTask, and setTaskChecked.
• Native charts use the direct doc.newChart(), doc.insertChart(), doc.getCharts(), and

doc.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.

univer_import imports .docx as Traditional by default so page size, orientation, margins, and headers/footers survive export. Pass docType: "modern" only when the user asks for a pageless document or the source has no page layout worth keeping: modern rewrites page geometry to a fixed layout and the source page setup cannot be recovered.

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:

1. Call univer_inspect for the document overview and relevant paragraph/range when supported.
2. Use a fresh read-only univer_execute to 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.
3. Call univer_screenshot with the Doc unitId, selected worktree or trunk, and an explicit workspace output directory. Inspect every returned page PNG for wrapping, physical pagination, image placement, and layout failures. Logical inspection alone cannot prove these facts.
4. If .docx delivery is requested, call univer_export only after structural readback succeeds.
5. Follow the univer ready/status handoff workflow.

compile-typst is not available in this plugin. Do not reproduce it with unrelated converters.