Web SDK

Изображения

Изображения помогают дополнить содержимое электронной таблицы, сделать его нагляднее, проиллюстрировать или выделить важную информацию.

В настоящее время поддерживаются плавающие изображения и изображения в ячейках.

Режим плагина

Установка

Shell
pnpm add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui

Использование

TypeScript
import { IImageIoService, LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDocsDrawingPlugin } from '@univerjs/docs-drawing'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIEnUS from '@univerjs/sheets-drawing-ui/locale/en-US'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs/sheets-drawing-ui/lib/index.css'import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DrawingUIEnUS,       SheetsDrawingUIEnUS,     ),  },})univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)

Если вы используете функцию совместной работы, добавьте настройку override:

TypeScript
univer.registerPlugin(UniverDrawingPlugin, {  override: [[IImageIoService, null]],   // allowImageSize: 20 * 1024 * 1024, // set the maximum allowed size of uploaded images to 20MB, optional})

Плагины и конфигурация

TypeScript
interface IUniverDrawingConfig {  /**   * The maximum allowed size of uploaded images in bytes.   * @default 5 * 1024 * 1024 (5MB)   */  allowImageSize?: number}

Поддержка мобильных устройств

Сначала настройте мобильный редактор. В коде инициализации режима плагинов на этой странице замените указанные настольные регистрации мобильными экспортами тех же пакетов до открытия документа. Сохраните модели, стили, локализации и импорты Facade; не регистрируйте оба варианта.

ПакетНастольная регистрацияМобильная регистрация
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/sheets-drawing-uiUniverSheetsDrawingUIPluginUniverSheetsDrawingMobileUIPlugin

Режим предустановки

Установка

Shell
pnpm add @univerjs/preset-sheets-drawing

Использование

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsDrawingEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),   ],})

Если вы используете функцию совместной работы, обязательно передайте параметр collaboration: true в UniverSheetsDrawingPreset:

TypeScript
UniverSheetsDrawingPreset({  collaboration: true, })

Предустановки и конфигурация

TypeScript
interface IUniverSheetsDrawingPresetConfig {  /**   * Whether use the collaboration feature.   * @default false   */  collaboration?: boolean  /**   * The maximum allowed size of uploaded images in bytes.   * @default 5 * 1024 * 1024 (5MB)   */  allowImageSize?: number}

Facade API

Полные определения типов Facade API доступны в справочнике Facade API.

Импорт

Примечание о режиме плагина

Импортировать пакет Facade вручную требуется только в режиме плагина. В режиме предустановки соответствующий пакет Facade уже включён, поэтому дополнительный импорт не нужен.

TypeScript
import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'

Добавление плавающего DOM-элемента

Метод FWorksheet.addFloatDomToPosition(layer) добавляет плавающий DOM-элемент в указанную позицию.

TSX
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()// You should register components at an appropriate time (e.g., when Univer is loaded)// This is a React component. For Vue3 components, the third parameter should be `{ framework: 'vue3' }`univerAPI.registerComponent(  'myFloatDom',  ({ data }) => (    <div style={{ width: '100%', height: '100%', background: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' }}>      popup content:      {' '}      {data?.label}    </div>  ),)// Add a floating DOM// If disposable is null, floating DOM addition failedconst disposable = fWorksheet.addFloatDomToPosition({  componentKey: 'myFloatDom',  initPosition: {    startX: 100,    endX: 300,    startY: 100,    endY: 200,  },  // Component data  data: {    label: 'hahah',  },})// 2 秒后移除浮动 DOMsetTimeout(() => {  disposable?.dispose()}, 2000)

Метод FWorksheet.addFloatDomToRange(range, layer, domLayout) добавляет плавающий DOM-элемент в указанный диапазон.

TSX
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()// Register a range loading componentfunction RangeLoading() {  const divStyle = {    width: '100%',    height: '100%',    backgroundColor: '#fff',    border: '1px solid #ccc',    boxSizing: 'border-box' as const,    display: 'flex',    justifyContent: 'center',    alignItems: 'center',    textAlign: 'center' as const,    transformOrigin: 'top left',  }  return (    <div style={divStyle}>      Loading...    </div>  )}univerAPI.registerComponent('RangeLoading', RangeLoading)// Add the range loading component covering the range A1:C3const fRange = fWorksheet.getRange('A1:C3')const disposable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading')// Remove the floating DOM after 2 secondssetTimeout(() => {  disposable?.dispose()}, 2000)// another example-------------------// Register a float button componentfunction FloatButton() {  const divStyle = {    width: '100px',    height: '30px',    backgroundColor: '#fff',    border: '1px solid #ccc',    boxSizing: 'border-box' as const,    display: 'flex',    justifyContent: 'center',    alignItems: 'center',    textAlign: 'center' as const,    cursor: 'pointer',  }  const clickHandler = () => {    console.warn('click')  }  return (    <div style={divStyle} onClick={clickHandler}>      FloatButton    </div>  )}univerAPI.registerComponent('FloatButton', FloatButton)// Add the float button to the range A5:C7, position is start from A5 cell, and width is 100px, height is 30px, margin is 100% of range width and heightconst fRange2 = fWorksheet.getRange('A5:C7')const disposable2 = fWorksheet.addFloatDomToRange(  fRange2,  {    componentKey: 'FloatButton',  },  {    width: 100,    height: 30,    marginX: '100%', // margin percent to range width, or pixel    marginY: '100%',  },  'myFloatButton',)

Метод FWorksheet.addFloatDomToColumnHeader(column, layer, domPos) добавляет плавающий DOM-элемент в заголовок указанного столбца.

TSX
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()// Register a float button componentfunction FloatButton() {  const divStyle = {    width: '100px',    height: '30px',    backgroundColor: '#fff',    border: '1px solid #ccc',    boxSizing: 'border-box' as const,    display: 'flex',    justifyContent: 'center',    alignItems: 'center',    textAlign: 'center' as const,    cursor: 'pointer',  }  const clickHandler = () => {    console.warn('click')  }  return (    <div style={divStyle} onClick={clickHandler}>      FloatButton    </div>  )}univerAPI.registerComponent('FloatButton', FloatButton)// Add the float button to the column D header, position is right align, width is 100px, height is 30px, margin is 0const disposable = fWorksheet.addFloatDomToColumnHeader(  3,  {    componentKey: 'FloatButton',    allowTransform: false,  },  {    width: 100,    height: 30,    marginX: 0,    marginY: 0,    horizonOffsetAlign: 'right',  },  'myFloatButton',)// Remove the float button after 2 secondssetTimeout(() => {  disposable?.dispose()}, 2000)

Вставка плавающих изображений

Метод FWorksheet.newOverGridImage() создаёт построитель плавающего изображения и возвращает экземпляр FOverGridImageBuilder. С помощью цепочки вызовов он формирует объект ISheetImage для вставки плавающего изображения.

Некоторые методы FOverGridImageBuilder:

МетодОписание
buildAsyncСоздаёт изображение и возвращает объект ISheetImage
setSourceЗадаёт источник изображения
setColumnЗадаёт положение изображения по горизонтали
setRowЗадаёт положение изображения по вертикали
setColumnOffsetЗадаёт смещение изображения по горизонтали
setRowOffsetЗадаёт смещение изображения по вертикали
setWidthЗадаёт ширину изображения
setHeightЗадаёт высоту изображения
setAnchorTypeЗадаёт тип привязки изображения, определяющий, меняются ли его положение и размер вместе с ячейкой
setCropTopЗадаёт область обрезки по верхнему краю, чтобы показать нужную часть изображения
setCropLeftЗадаёт область обрезки по левому краю, чтобы показать нужную часть изображения
setCropBottomЗадаёт область обрезки по нижнему краю, чтобы показать нужную часть изображения
setCropRightЗадаёт область обрезки по правому краю, чтобы показать нужную часть изображения
setRotateЗадаёт угол поворота изображения
TypeScript
// create a new image builder and set image source.// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300pxconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setWidth(500)  .setHeight(300)  .buildAsync()fWorksheet.insertImages([image])

Изображение также можно вставить методом FWorksheet.insertImage(url, column, row, offsetX, offsetY).

TypeScript
// Insert an image to the sheet, position is F6, offset is 10pxconst fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5, 10, 10)

Получение плавающих изображений

Метод FWorksheet.getImages() возвращает все плавающие изображения листа в виде массива экземпляров FOverGridImage[].

TypeScript
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const images = fWorksheet.getImages()images.forEach((image) => {  image.getId()})

Получить плавающее изображение по идентификатору можно с помощью метода FWorksheet.getImageById(id).

Обновление плавающих изображений

Метод FWorksheet.updateImages(sheetImages) позволяет обновить положение, размер и другие параметры плавающих изображений.

TypeScript
// create a new image builder and set image source.// then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300pxconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const image = await fWorksheet.newOverGridImage()  .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL)  .setColumn(5)  .setRow(5)  .setWidth(500)  .setHeight(300)  .buildAsync()fWorksheet.insertImages([image])// update the image width to 100px and height to 50px after 4 secondssetTimeout(async () => {  const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder()  const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync()  fWorksheet.updateImages([newImage])}, 4000)

Удаление плавающих изображений

Метод FWorksheet.deleteImages(sheetImages) удаляет плавающие изображения.

TypeScript
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const image = fWorksheet.getImages()[0]// Delete the first image of the sheetfWorksheet.deleteImages([image])

Вставка изображений в ячейки

Метод FRange.insertCellImageAsync(file) вставляет изображения в ячейки.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Insert an image into the cell A10const fRange = fWorksheet.getRange('A10')const result = await fRange.insertCellImageAsync('https://avatars.githubusercontent.com/u/61444807?s=48&v=4')

Фоновое изображение листа

Лист поддерживает одно изображение, повторяемое под ячейками. Оно хранится в IWorksheetData.backgroundImage отдельно от плавающих изображений и изображений ячеек. Пресет Drawing включает функцию. В режиме плагинов нужны @univerjs/sheets-drawing, его Facade и Drawing UI для отрисовки и загрузки.

TypeScript
import '@univerjs/sheets-drawing/facade'const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()if (!sheet) throw new Error('No active worksheet')sheet.setBackgroundImage('https://example.com/background.png')console.log(sheet.getBackgroundImage())sheet.deleteBackgroundImage()

setBackgroundImage() по умолчанию использует ImageSourceType.URL и заменяет фон, а deleteBackgroundImage() удаляет его. Команды поддерживают отмену и повтор. UI использует настроенный сервис изображений. Фон отображается на экране и не печатается.

Непрозрачность изображений

Плавающие изображения поддерживают общую непрозрачность. setOpacity() принимает конечное число от 0 (прозрачное) до 1 (непрозрачное); значение по умолчанию — 1. Недопустимое значение вызывает RangeError. Настройте его в FOverGridImageBuilder перед созданием или в существующем FOverGridImage. Оба объекта предоставляют getOpacity(). Панель свойств также содержит настройку прозрачности.

TypeScript
const sheet = univerAPI.getActiveWorkbook()?.getActiveSheet()const image = sheet?.getImages()[0]if (image) {  image.setOpacity(0.5)  console.log(image.getOpacity())}

Размер и привязка изображений

При вставке через встроенный выбор файла сохраняются пропорции, а размер при необходимости уменьшается до 500 × 500 пикселей. Маленькие изображения не увеличиваются. Это размер отображения, отдельно от ограничения байтов allowImageSize. Через Facade можно задать размеры самостоятельно.

SheetDrawingAnchorType.Position перемещает изображение с ячейками без изменения размера, Both следует положению и размеру диапазона, None фиксирует оба. Скрытие и показ строк или столбцов сохраняют привязки: изображение, следующее размеру диапазона, может временно сжаться и восстановиться при показе. Не перезаписывайте привязки временной геометрией скрытых строк.

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.