Images

Les images permettent d’enrichir le contenu des feuilles de calcul, d’améliorer leur présentation visuelle et d’illustrer ou de mettre en évidence des informations importantes.

Deux types d’images sont actuellement pris en charge : les images flottantes et les images dans les cellules.

Mode plugin

Installation

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

Utilisation

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)

Si vous utilisez la fonctionnalité de Collaboration, vous devez ajouter la configuration override :

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

Plugins et configuration

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

Prise en charge mobile

Configurez d’abord l’éditeur mobile. Dans l’initialisation en mode plugin de cette page, remplacez les inscriptions de bureau ci-dessous par les exports mobiles des mêmes paquets avant d’ouvrir un document. Conservez modèles, styles, traductions et imports Facade ; n’enregistrez pas les deux variantes.

PaquetInscription de bureauInscription mobile
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/sheets-drawing-uiUniverSheetsDrawingUIPluginUniverSheetsDrawingMobileUIPlugin

Mode prédéfini

Installation

Shell
pnpm add @univerjs/preset-sheets-drawing

Utilisation

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(),   ],})

Si vous utilisez la fonctionnalité de Collaboration, veillez à transmettre l’option collaboration: true à UniverSheetsDrawingPreset :

TypeScript
UniverSheetsDrawingPreset({  collaboration: true, })

Préréglages et configuration

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}

API Facade

Les définitions de types complètes de l’API Facade sont disponibles dans la FacadeAPI.

Importation

Remarque sur le mode plugin

Seul le mode plugin nécessite d’importer manuellement le package Facade. Le mode prédéfini inclut déjà le package Facade correspondant : aucun import supplémentaire n’est nécessaire.

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

Ajouter un élément DOM flottant

La méthode FWorksheet.addFloatDomToPosition(layer) permet d’ajouter un élément DOM flottant à un emplacement précis.

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)

La méthode FWorksheet.addFloatDomToRange(range, layer, domLayout) permet d’ajouter un élément DOM flottant à une plage précise.

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',)

La méthode FWorksheet.addFloatDomToColumnHeader(column, layer, domPos) permet d’ajouter un élément DOM flottant à l’en-tête d’une colonne précise.

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)

Insérer des images flottantes

FWorksheet.newOverGridImage() crée un générateur d’image flottante, renvoie une instance de FOverGridImageBuilder et produit, au moyen d’appels chaînés, un objet ISheetImage permettant d’insérer des images flottantes.

Voici quelques méthodes de FOverGridImageBuilder :

MéthodeDescription
buildAsyncGénère l’image et renvoie un objet ISheetImage.
setSourceDéfinit la source de l’image.
setColumnDéfinit la position horizontale de l’image.
setRowDéfinit la position verticale de l’image.
setColumnOffsetDéfinit le décalage horizontal de l’image.
setRowOffsetDéfinit le décalage vertical de l’image.
setWidthDéfinit la largeur de l’image.
setHeightDéfinit la hauteur de l’image.
setAnchorTypeDéfinit le type d’ancrage de l’image, c’est-à-dire si sa position et sa taille évoluent avec la cellule.
setCropTopDéfinit le bord supérieur de la zone de recadrage afin d’afficher la partie souhaitée de l’image.
setCropLeftDéfinit le bord gauche de la zone de recadrage afin d’afficher la partie souhaitée de l’image.
setCropBottomDéfinit le bord inférieur de la zone de recadrage afin d’afficher la partie souhaitée de l’image.
setCropRightDéfinit le bord droit de la zone de recadrage afin d’afficher la partie souhaitée de l’image.
setRotateDéfinit l’angle de rotation de l’image.
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])

Vous pouvez également insérer une image avec la méthode 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)

Récupérer les images flottantes

La méthode FWorksheet.getImages() récupère toutes les images flottantes de la feuille de calcul et renvoie un tableau d’instances FOverGridImage[].

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

Vous pouvez également récupérer une image flottante à partir de son identifiant avec la méthode FWorksheet.getImageById(id).

Mettre à jour les images flottantes

La méthode FWorksheet.updateImages(sheetImages) permet notamment de modifier la position et la taille des images flottantes.

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)

Supprimer des images flottantes

La méthode FWorksheet.deleteImages(sheetImages) permet de supprimer des images flottantes.

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

Insérer des images dans des cellules

La méthode FRange.insertCellImageAsync(file) permet d’insérer des images dans des cellules.

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')

Image de fond de feuille

Une feuille peut afficher une image répétée derrière les cellules. Elle est stockée dans IWorksheetData.backgroundImage, indépendamment des images flottantes ou de cellule. Le preset Drawing inclut cette fonction. En mode plugin, utilisez @univerjs/sheets-drawing, sa Facade et l’UI Drawing pour le rendu et le téléversement.

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() utilise ImageSourceType.URL par défaut et remplace le fond ; deleteBackgroundImage() le retire. Ces commandes prennent en charge annuler/rétablir. L’UI utilise le service d’images configuré. Le fond est une décoration à l’écran, exclue de l’impression.

Opacité des images

Les images flottantes acceptent une opacité globale. setOpacity() prend un nombre fini entre 0 (transparent) et 1 (opaque), avec 1 par défaut ; une valeur invalide déclenche RangeError. Utilisez FOverGridImageBuilder avant la création ou un FOverGridImage existant. Les deux exposent getOpacity(). Le panneau des propriétés propose aussi un réglage de transparence.

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

Taille et ancrage des images

Les images insérées par le sélecteur intégré conservent leur ratio et sont réduites si nécessaire pour tenir dans 500 × 500 pixels, sans agrandir les petites images. Cette taille d’affichage est distincte de la limite d’octets allowImageSize. Le Facade permet de choisir les dimensions.

SheetDrawingAnchorType.Position suit le déplacement des cellules sans changer de taille, Both suit le déplacement et la taille de la plage, et None fixe les deux. Masquer puis afficher lignes ou colonnes préserve les ancres : une image liée à la taille de la plage peut se réduire temporairement et retrouver sa géométrie ensuite. Ne remplacez pas les ancres par cette géométrie temporaire.

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.