# Images

- Human documentation: [https://docs.univer.ai/fr-FR/guides/sheets/features/images](https://docs.univer.ai/fr-FR/guides/sheets/features/images)

- Agent Markdown: [https://docs.univer.ai/fr-FR/guides/sheets/features/images.md](https://docs.univer.ai/fr-FR/guides/sheets/features/images.md)

- Requested language: `fr-FR`

- Content language: `fr-FR`

- Documentation version: `1.2.0`

- Source: [sheets/features/images.fr-FR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/images.fr-FR.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-drawing",
      "locale": "@univerjs/preset-sheets-drawing/locales/en-US",
      "style": "@univerjs/preset-sheets-drawing/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/drawing"
    },
    {
      "client": "@univerjs/drawing-ui",
      "locale": "@univerjs/drawing-ui/locale/en-US",
      "style": "@univerjs/drawing-ui/lib/index.css"
    },
    {
      "client": "@univerjs/sheets-drawing"
    },
    {
      "client": "@univerjs/sheets-drawing-ui",
      "facade": "@univerjs/sheets-drawing-ui/facade",
      "locale": "@univerjs/sheets-drawing-ui/locale/en-US",
      "style": "@univerjs/sheets-drawing-ui/lib/index.css"
    }
  ],
  "server": false
}
```

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.

> Interactive example: [Open the playground](/playground/sheets/images)

## Mode plugin

### Installation

#### npm

```bash
npm install @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### pnpm

```bash
pnpm add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### yarn

```bash
yarn add @univerjs/docs-drawing @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui
```

#### bun

```bash
bun 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' // [!code ++]
import { UniverDrawingPlugin } from '@univerjs/drawing' // [!code ++]
import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui' // [!code ++]
import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US' // [!code ++]
import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing' // [!code ++]
import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui' // [!code ++]
import SheetsDrawingUIEnUS from '@univerjs/sheets-drawing-ui/locale/en-US' // [!code ++]
import '@univerjs/drawing-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-drawing-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-drawing/facade' // [!code ++]
import '@univerjs/sheets-drawing-ui/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      DrawingUIEnUS, // [!code ++]
      SheetsDrawingUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverDrawingUIPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsDrawingUIPlugin) // [!code ++]
```

Si vous utilisez la fonctionnalité de [Collaboration](https://docs.univer.ai/fr-FR/guides/docs/features/collaboration.md), vous devez ajouter la configuration `override` :

```typescript
univer.registerPlugin(UniverDrawingPlugin, {
  override: [[IImageIoService, null]], // [!code ++]
  // 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](https://docs.univer.ai/fr-FR/guides/sheets/getting-started/installation.md#mobile-support). 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.

| Paquet                        | Inscription de bureau         | Inscription mobile                  |
| ----------------------------- | ----------------------------- | ----------------------------------- |
| `@univerjs/drawing-ui`        | `UniverDrawingUIPlugin`       | `UniverDrawingMobileUIPlugin`       |
| `@univerjs/sheets-drawing-ui` | `UniverSheetsDrawingUIPlugin` | `UniverSheetsDrawingMobileUIPlugin` |

## Mode prédéfini

### Installation

#### npm

```bash
npm install @univerjs/preset-sheets-drawing
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing
```

#### bun

```bash
bun 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' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
  ],
})
```

Si vous utilisez la fonctionnalité de [Collaboration](https://docs.univer.ai/fr-FR/guides/sheets/features/collaboration.md), veillez à transmettre l’option `collaboration: true` à `UniverSheetsDrawingPreset` :

```typescript
UniverSheetsDrawingPreset({
  collaboration: true, // [!code ++]
})
```

### 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](https://docs.univer.ai/fr-FR/reference/facade.md).

### Importation

> [!INFO: 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 failed
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'myFloatDom',
  initPosition: {
    startX: 100,
    endX: 300,
    startY: 100,
    endY: 200,
  },

  // Component data
  data: {
    label: 'hahah',
  },
})

// 2 秒后移除浮动 DOM
setTimeout(() => {
  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 component
function 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:C3
const fRange = fWorksheet.getRange('A1:C3')
const disposable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading')

// Remove the floating DOM after 2 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)

// another example-------------------
// Register a float button component
function 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 height
const 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 component
function 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 0
const 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 seconds
setTimeout(() => {
  disposable?.dispose()
}, 2000)
```

### Insérer des images flottantes

[`FWorksheet.newOverGridImage()`](https://docs.univer.ai/fr-FR/reference/facade/worksheet.md#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`](https://docs.univer.ai/fr-FR/reference/facade/over-grid-image-builder.md) :

| Méthode         | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| buildAsync      | Génère l’image et renvoie un objet `ISheetImage`.                                                        |
| setSource       | Définit la source de l’image.                                                                            |
| setColumn       | Définit la position horizontale de l’image.                                                              |
| setRow          | Définit la position verticale de l’image.                                                                |
| setColumnOffset | Définit le décalage horizontal de l’image.                                                               |
| setRowOffset    | Définit le décalage vertical de l’image.                                                                 |
| setWidth        | Définit la largeur de l’image.                                                                           |
| setHeight       | Définit la hauteur de l’image.                                                                           |
| setAnchorType   | Définit le type d’ancrage de l’image, c’est-à-dire si sa position et sa taille évoluent avec la cellule. |
| setCropTop      | Définit le bord supérieur de la zone de recadrage afin d’afficher la partie souhaitée de l’image.        |
| setCropLeft     | Définit le bord gauche de la zone de recadrage afin d’afficher la partie souhaitée de l’image.           |
| setCropBottom   | Définit le bord inférieur de la zone de recadrage afin d’afficher la partie souhaitée de l’image.        |
| setCropRight    | Définit le bord droit de la zone de recadrage afin d’afficher la partie souhaitée de l’image.            |
| setRotate       | Dé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 300px
const 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 10px
const 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[]`](https://docs.univer.ai/fr-FR/reference/facade/chart.md).

```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 300px
const 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 seconds
setTimeout(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 sheet
fWorksheet.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 A10
const 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.

```ts
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.

```ts
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.