@univerjs-pro/docs-reference

Document reference commands and Facade APIs for Univer Pro. Register this plugin for traditional-document footnote and endnote creation, deletion and settings. It has no browser UI and can be used with the Docs runtime on Node.js.

Package Overview

| Package | UMD global | CSS | Locales | Facade entry | | --- | --- | :---: | :---: | :---: | | @univerjs-pro/docs-reference | UniverProDocsReference | No | No | Yes |

Installation

pnpm add @univerjs-pro/docs-reference
# or
npm install @univerjs-pro/docs-reference

Keep all @univerjs/* and @univerjs-pro/* packages on the same version.

Usage

Keep all Univer packages on the same version and configure UniverLicensePlugin with your application license.

import { UniverDocsReferencePlugin } from '@univerjs-pro/docs-reference';
import '@univerjs-pro/docs-reference/facade';

univer.registerPlugin(UniverDocsReferencePlugin);

const document = univerAPI.getActiveDocument();
const id = document?.insertFootnote(5, {
    body: { dataStream: 'Source details\r\n', paragraphs: [{ startIndex: 14 }] },
});
if (id) {
    document.getTextRange(0, 6, id).setText('Citation');
}
document?.setFootnoteSettings({ numberFormat: 'decimal', restart: 'eachSect' });

getFootnotes() returns detached note data in reference order. deleteFootnote(id) removes both the reference and content. getFootnoteSettings(sectionId?) reads explicit settings; setFootnoteSettings(settings, sectionId?) replaces them, and null restores inheritance.

Data and editing

References use stable IDs and the core document note segments. Commands use the existing rich-text editing mutation, permissions, undo/redo and collaboration channels. No additional collaboration mutation or resource is required. Text offsets are UTF-16 offsets in the document body, including structural tokens.

Footnotes and endnotes are available only in traditional documents. Modern-mode DOCX import removes references and note content before calculating text offsets. Note bodies support paragraphs, inline images and ordinary tables; document and section settings control numbering, placement and columns. Separator, continuation separator and continuation notice bodies belong to document settings.

Install @univerjs-pro/docs-reference-ui for the References ribbon, settings and navigation.

Endnotes use insertEndnote(offset, content?), getEndnotes(), and deleteEndnote(id). Their content is edited with the same segment text-range APIs as footnotes. setEndnoteSettings({ position: 'docEnd', numberFormat: 'lowerRoman' }) configures document defaults; pass a section ID to configure sectEnd placement or numbering restart for that section. getEndnoteSettings(sectionId?) reads explicit settings and passing null to the setter restores inheritance. Footnotes and endnotes count independently.

Snapshots store both kinds in notes: Record<string, IDocumentNote>, identified by stable noteId and a type of footnote or endnote. Document defaults live in noteSettings.footnote and noteSettings.endnote; section overrides live in sectionBreaks[].noteProperties. References, content and settings use the existing rich-text mutation and undo/collaboration path. All collaborating clients must understand the new snapshot fields and ENDNOTE range type.

Integration Notes

• Keep all @univerjs/* and @univerjs-pro/* packages on the same version.
• Import @univerjs-pro/docs-reference/facade when using the package through Univer Facade APIs.

Resources

• Documentation
• NPM package