Фреймворк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, чтобы снять ограничение.
`onUploadError`	`UploadErrorHandler`	`undefined`	Вызывается, когда загрузка не удалась. Получает `{ code, tool, message, file?, url?, size?, maxSize?, cause }`. Ничего не вернули: блок показывает своё сообщение. Вернули строку: блок показывает её. Вернули `false`: блок возвращается в пустое состояние без ошибки, и вы можете показать свой тост. Если ваш uploader отклонил промис, придёт код `UPLOAD_FAILED`. Исходная ошибка лежит в `cause`.
`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`, `fallbackFormat`, `quality`, `maxWidth` / `maxHeight`, `minSize`, `minSavings` и `transform(file)`. `format` принимает `'original'` \| `'jpeg'` \| `'webp'` \| `'avif'` \| `'auto'`. `fallbackFormat` это формат, который пробуется, если браузер не умеет закодировать `format`, прежде чем откатиться на исходный формат. Так, `{ format: 'avif', fallbackFormat: 'webp' }` загружает AVIF там, где браузер умеет его создавать, и WebP во всех остальных случаях. `quality` идёт от 0 до 1. `minSize` пропускает файлы меньше этого размера, по умолчанию 100 KiB. `minSavings` по умолчанию 0.1. `transform(file)` подключает собственный кодировщик. Установите `false`, чтобы загружать ровно исходные байты. Сжатие никогда не ломает загрузку. Если оно не помогает, используется оригинал.
`reloadAttempts`	`number`	`5`	Сколько раз отрисованное изображение молча перезапрашивает свой `src` после ошибки загрузки, прежде чем показать состояние «изображение не загружено». Установите 0, чтобы отключить автоповтор.
`filters`	`Array<ImageFilterPreset \| ImageFilterDefinition>`	`every built-in`	Фильтры, которые предлагает вкладка «Фильтры» редактора изображений, по порядку. «Оригинал» всегда идёт первым. Строка выбирает встроенный фильтр, например `'vivid'`, `'noir'` или `'film'`. Всего их 23. Объект `{ name, title, css }` добавляет собственный фильтр. `name` сохраняется в `filter`, `title` это подпись, а `css` это значение CSS-свойства filter. Сохраняются только `brightness`, `contrast`, `saturate`, `grayscale`, `sepia`, `invert` и `hue-rotate`. Имя встроенного фильтра переопределяет этот фильтр. `[]` скрывает вкладку «Фильтры». Встроенный фильтр, которого нет в списке, всё равно отображается на изображениях, где он уже применён. Сохранённое имя, которое редактор не знает, отображается без фильтра и сохраняется как есть.

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

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, in the turned image's box
  rotation?: 0 | 90 | 180 | 270; // Clockwise quarter turn (omitted for 0)
  flipX?: boolean;         // Mirrored left to right, before rotation
  straighten?: number;     // Fine turn in degrees, -45 to 45, after rotation
  filter?: ImageFilterPreset | string; // A built-in look or a host filter name (omitted for 'none')
  filterStrength?: number; // How strongly filter applies, 0 to 100 (omitted for 100)
  adjust?: { brightness?: number; contrast?: number; saturation?: number }; // Each -100 to 100
  markup?: ImageMarkup[];  // Drawings, shapes and text over the image, back to front
  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)
  variants?: { url: string; mimeType: string }[]; // Other formats, best first
}

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 };
          },
        },
      },
    },
  },
});