@univerjs/drawing

Shared drawing models, commands, and services for Univer.

import { UniverDrawingPlugin } from '@univerjs/drawing'univer.registerPlugin(UniverDrawingPlugin, {})

Image opacity

The root entry exports normalizeImageOpacity(opacity: number | undefined): number. It clamps finite values to 0–1 and returns 1 for undefined or non-finite values. Use it when normalizing drawing data. The image Facade setters validate input and throw RangeError for invalid values instead.

IUniverDrawingConfig

import type { DependencyOverride } from '@univerjs/core'import type { IOleConfig } from '@univerjs/drawing'export interface IUniverDrawingConfig {  ole?: IOleConfig  override?: DependencyOverride  /**   * The maximum allowed size of uploaded images in bytes.   * @default 5 * 1024 * 1024 (5MB)   */  allowImageSize?: number}

OLE attachments

The model plugin preserves original attachment resources independently of preview images, including in headless snapshots. IOleConfig configures authorized attachment storage, temporary Office previews, conversion to independent online documents, and application links. Register the host drawing UI for attachment controls. See OLE integration and export options.

For custom snapshot storage, prepareOleSnapshot(snapshot, mode, targetUnitId?, io?) returns a prepared copy of Unit data or an Exchange JSON envelope. In 'json' mode it embeds original attachment bytes; persisted attachments need io.read. In 'unit' mode it requires a target Unit ID and IOleAttachmentIo, uploads the originals, and replaces embedded bytes with UUID attachment references. Conversion failures leave the input snapshot unchanged; uploads already completed are not rolled back.

readOleFile(file, io?, signal?) reads embedded or persisted bytes and verifies their size and SHA-256 hash. Preserve OLE_RESOURCE_NAME resources when saving snapshots, rather than retaining only drawing preview images.