---
title: "Блок «Изображение» — загрузка, вставка, сжатие"
description: "Загрузка, вставка и ссылки на изображения с изменением размера, подписями, сжатием на клиенте и лимитом размера."
source: https://blokeditor.com/ru/docs/image/
lastmod: 2026-09-07
---

Фреймворк JavaScript

Блочные инструменты Изображение

# Изображение: загрузка, подписи и размеры

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

### Импорт

TypeScript

```
import { Image } from '@bloklabs/core/tools';
```

### Конфигурация

| Опция | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `uploader` | `ImageUploader` | `undefined` | Загрузчик от потребителя с необязательными методами `uploadByFile(file, ctx)` и `uploadByUrl(url, ctx)`, каждый из которых возвращает `{ url, fileName? }`. Если он не задан, изображения откатываются на локальный blob URL (uploadByFile) или на вставленный URL (uploadByUrl). |
| `types` | `string[]` | `['image/*']` | Список разрешённых MIME-типов. Записи могут быть точными (`image/png`) или групповыми (`image/*`). По умолчанию разрешён любой тип изображения. |
| `maxSize` | `MaxSizeConfig` | `30 MiB` | Максимальный размер загрузки. Число ограничивает все типы (в байтах); объект задаёт ограничение для каждого MIME-типа, где `'*'` — запасное значение. Передайте Infinity, чтобы снять ограничение. |
| `sources` | `'upload' | 'url' | 'both'` | `'both'` | Ограничивает способы добавления изображения — только загрузка файла, только URL или оба варианта. |
| `convertGifToVideo` | `boolean` | `true` | Автоматически преобразовывать анимированные GIF при вставке в зацикленный блок видео WebM. Работает, только если зарегистрирован инструмент видео — без него GIF остаются блоками изображения. Установите false, чтобы GIF всегда оставались блоками изображения. |
| `captionPlaceholder` | `string` | `"Write a caption…"` | Плейсхолдер, который показывается в поле подписи. |
| `compress` | `boolean | ImageCompressionConfig` | `true` | Перекодирует загружаемые изображения до того, как они попадут в загрузчик. Включено по умолчанию в намеренно безопасном режиме: тот же формат, качество 0.92, исходные размеры, и результат используется, только если экономит не менее 10% — иначе загружаются исходные байты без изменений. Передайте объект, чтобы получить файл поменьше: `format` (`'original'` | `'jpeg'` | `'webp'` | `'avif'` | `'auto'`), `fallbackFormat` (формат, который пробуется, если браузер не умеет закодировать `format`, прежде чем откатиться на исходный формат — например, `{ format: 'avif', fallbackFormat: 'webp' }` загружает AVIF там, где браузер умеет его создавать, и WebP во всех остальных случаях), `quality` (0–1), `maxWidth` / `maxHeight`, `minSize` (пропускать файлы меньше этого размера, по умолчанию 100 KiB), `minSavings` (по умолчанию 0.1) или `transform(file)`, чтобы подключить собственный кодировщик. Установите `false`, чтобы загружать ровно исходные байты. Сжатие никогда не ломает загрузку — если оно не помогает, используется оригинал. |
| `reloadAttempts` | `number` | `5` | Сколько раз отрисованное изображение молча перезапрашивает свой `src` после ошибки загрузки, прежде чем показать состояние «изображение не загружено». Установите 0, чтобы отключить автоповтор. |

### Формат данных

TypeScript

```
interface ImageData {
  url: string;             // Image source URL — http(s) or blob:
  caption?: string;        // Plain-text caption
  width?: number;          // Width as percent of container, 10–100 (default 100)
  alignment?: 'left' | 'center' | 'right';
  size?: 'sm' | 'md' | 'lg' | 'full'; // Discrete size preset; overrides width when set
  frame?: 'none' | 'border' | 'shadow'; // Decorative frame treatment (default 'none')
  rounded?: boolean;       // Rounded corners (default true)
  captionVisible?: boolean; // Caption visible in the rendered state (default true)
  crop?: ImageCrop;        // Non-destructive crop rectangle
  alt?: string;            // Alt text for screen readers
  fileName?: string;       // Original filename, when known
  naturalWidth?: number;   // Intrinsic pixel width of the source (cached)
  naturalHeight?: number;  // Intrinsic pixel height of the source (cached)
}
```

JSON

```
{
  "id": "img001",
  "type": "image",
  "data": {
    "url": "https://example.com/image.png",
    "caption": "A cat",
    "alt": "A cat",
    "alignment": "center"
  }
}
```

### Пример использования

TypeScript

```
import { Blok } from '@bloklabs/core';
import { Image } from '@bloklabs/core/tools';

const editor = new Blok({
  holder: 'editor',
  tools: {
    image: {
      class: Image,
      config: {
        uploader: {
          async uploadByFile(file) {
            const url = await myUpload(file);
            return { url, fileName: file.name };
          },
        },
      },
    },
  },
});
```