PDF

Facade APIs for creating, reading, and editing Univer PDF units.

Import @univerjs-pro/pdfs/facade before using these APIs in plugin mode.

For setup and task-oriented examples, start with the Univer PDFs guide.

Before using the API

Register UniverPdfsPlugin and import @univerjs-pro/pdfs/facade after @univerjs/core/facade. Browser editing also needs UniverPdfsUIPlugin, its CSS, and the client license configuration. See installation.

PDF positions and sizes use PDF points, not CSS pixels. Page indexes and element indexes are zero-based. Use save() to persist accepted edits; getDocument() returns the source document and does not replace a complete snapshot. See the PDF data model.

Unit access

createPdf(data?: Partial<IPdfUnitData>, options?: ICreateUnitOptions): FPdfgetActivePdf(): FPdf | nullgetPdf(id: string): FPdf | nullgetPdfTableThemePresets(): ReadonlyArray<Readonly<IPdfTableThemePreset>>

createPdf() returns a new FPdf; omitting data creates a blank unit. Supply a complete snapshot to restore saved content. getActivePdf() and getPdf(id) return null if no matching PDF exists, so check the result before editing.

FPdf

getId(): stringgetName(): stringsave(): IPdfUnitDatagetDocument(): IPdfDocumentgetModel(): PdfDocumentModelinsertPage(index?: number): FPdfPagegetPages(): FPdfPage[]getPageById(id: string): FPdfPage | nullgetPageByIndex(index: number): FPdfPage | null

Page access and persistence

FPdfPage

FPdfPage resolves existing page elements and inserts editable text boxes, paragraphs, lists, tables, dividers, annotations, and images.

getId(): stringgetIndex(): numbergetData(): Readonly<IPdfPage>getElements(): FPdfPageElement[]getElementById(id: string): FPdfPageElement | nullgetTextBoxes(): FPdfTextBox[]getImages(): FPdfImage[]getParagraphs(): FPdfParagraph[]getLists(): FPdfList[]getTables(): FPdfTable[]getDividers(): FPdfDivider[]getAnnotations(): FPdfAnnotation[]getTextSpans(): FPdfTextSpan[]insertTextBox(options: IPdfTextBoxInsertOptions): FPdfTextBoxinsertParagraph(options: IPdfParagraphInsertOptions): FPdfParagraphinsertList(options: IPdfListInsertOptions): FPdfListinsertTable(options: IPdfTableInsertOptions): FPdfTableinsertDivider(options?: IPdfDividerInsertOptions): FPdfDividerinsertAnnotation(options: IPdfAnnotationInsertOptions): FPdfAnnotationnewImage(existing?: FPdfImage | string): FPdfImageBuilderinsertImage(info: IPdfImageBuilderInfo, index?: number): FPdfImageinsertImageAsync(source: string | IFBlobSource, options?: IPdfImageInsertOptions): Promise<FPdfImage>

Insertion parameters

Text boxes, paragraphs, lists, tables, dividers, annotations, and images share IPdfElementInsertOptions:

Text boxes and paragraphs

insertTextBox(options) returns FPdfTextBox; insertParagraph(options) returns FPdfParagraph.

Tables

insertTable(options) returns FPdfTable.

Images

insertImageAsync(source, options?) accepts a URL string or IFBlobSource and returns Promise<FPdfImage>. Await completion before saving the snapshot. Image options add imageSourceType, crop, and opacity (0 through 1, default 1) to the shared placement fields. See images.

Errors and lifetime

Mutations throw when the action is rejected. Invalid page insertion indexes throw RangeError. Catch errors at the application interaction boundary and present the failed operation to the user. Do not continue using page or element wrappers after their owning unit is disposed. Dispose the owning univer instance when unmounting the editor.

Page elements

Every FPdfPageElement supports identity, transform, visibility, locking, z-order, and removal. Specialized wrappers add content editing:

// FPdfPageElementgetId(): stringgetType(): PdfObjectTypegetData(): Readonly<PdfObject>getTransform(): IPdfFacadeTransformsetTransform(transform: IPdfFacadeTransform): thissetPosition(left: number, top: number): thissetSize(width: number, height: number): thissetRotation(rotation: number): thissetVisible(visible: boolean): thissetLocked(locked: boolean): thisbringToFront(): thissendToBack(): thisbringForward(): thissendBackward(): thisremove(): void

import '@univerjs-pro/pdfs/facade'const pdf = univerAPI.createPdf({ name: 'Project brief' })const page = pdf.insertPage()page.insertTextBox({ text: 'Hello PDF', left: 36, top: 36 }).setTextStyle({ fontSize: 18, fill: '#274690' })page.insertTable({  left: 36,  top: 90,  rowCount: 2,  columnCount: 2,  cellTexts: ['Metric', 'Value', 'Users', '42'],})const snapshot = pdf.save()// Store snapshot in your application; pass it to createPdf(snapshot) when restoring.

PDF facade enums include PdfAnnotationType, PdfListKind, PdfListPresetId, PdfTextAnchor, and PdfTableCellVerticalAlign through univerAPI.Enum.

For browser printing, see @univerjs-pro/pdfs-print.