Изображения
Изображения помогают дополнить содержимое электронной таблицы, сделать его нагляднее, проиллюстрировать или выделить важную информацию.
В настоящее время поддерживаются плавающие изображения и изображения в ячейках.
Режим плагина
Установка
pnpm add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uinpm install @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uiyarn add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uibun add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-uiИспользование
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:
univer.registerPlugin(UniverDrawingPlugin, { override: [[IImageIoService, null]], // allowImageSize: 20 * 1024 * 1024, // set the maximum allowed size of uploaded images to 20MB, optional})Плагины и конфигурация
interface IUniverDrawingConfig { /** * The maximum allowed size of uploaded images in bytes. * @default 5 * 1024 * 1024 (5MB) */ allowImageSize?: number}Поддержка мобильных устройств
Сначала настройте мобильный редактор. В коде инициализации режима плагинов на этой странице замените указанные настольные регистрации мобильными экспортами тех же пакетов до открытия документа. Сохраните модели, стили, локализации и импорты Facade; не регистрируйте оба варианта.
| Пакет | Настольная регистрация | Мобильная регистрация |
|---|---|---|
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
Режим предустановки
Установка
pnpm add @univerjs/preset-sheets-drawingnpm install @univerjs/preset-sheets-drawingyarn add @univerjs/preset-sheets-drawingbun add @univerjs/preset-sheets-drawingИспользование
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:
UniverSheetsDrawingPreset({ collaboration: true, })Предустановки и конфигурация
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 уже включён, поэтому дополнительный импорт не нужен.
import '@univerjs/sheets-drawing/facade'import '@univerjs/sheets-drawing-ui/facade'Добавление плавающего DOM-элемента
Метод FWorksheet.addFloatDomToPosition(layer) добавляет плавающий DOM-элемент в указанную позицию.
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-элемент в указанный диапазон.
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-элемент в заголовок указанного столбца.
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 | Задаёт угол поворота изображения |
// 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).
// 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[].
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const images = fWorksheet.getImages()images.forEach((image) => { image.getId()})Получить плавающее изображение по идентификатору можно с помощью метода FWorksheet.getImageById(id).
Обновление плавающих изображений
Метод FWorksheet.updateImages(sheetImages) позволяет обновить положение, размер и другие параметры плавающих изображений.
// 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) удаляет плавающие изображения.
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet()const image = fWorksheet.getImages()[0]// Delete the first image of the sheetfWorksheet.deleteImages([image])Вставка изображений в ячейки
Метод FRange.insertCellImageAsync(file) вставляет изображения в ячейки.
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 для отрисовки и загрузки.
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(). Панель свойств также содержит настройку прозрачности.
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 фиксирует оба. Скрытие и показ строк или столбцов сохраняют привязки: изображение, следующее размеру диапазона, может временно сжаться и восстановиться при показе. Не перезаписывайте привязки временной геометрией скрытых строк.
Насколько полезно это руководство?