Справочник API

Sharp предоставляет богатый API для обработки изображений. На этой странице представлен подробный справочник всех доступных методов.

Конструктор

sharp(input, options?)

Создает новый экземпляр Sharp.

import sharp from 'sharp';

// Создание из файла
const image = sharp('input.jpg');

// Создание из Buffer
const image = sharp(buffer);

// Создание из Stream
const image = sharp(stream);

// Создание пустого изображения
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

Метаданные ввода

metadata()

Получает метаданные изображения.

const metadata = await sharp('input.jpg').metadata();
console.log(metadata);
// {
//   format: 'jpeg',
//   width: 1920,
//   height: 1080,
//   space: 'srgb',
//   channels: 3,
//   depth: 'uchar',
//   density: 72,
//   hasProfile: false,
//   hasAlpha: false
// }

stats()

Получает статистику изображения.

const stats = await sharp('input.jpg').stats();
console.log(stats);
// {
//   isOpaque: true,
//   dominant: { r: 128, g: 128, b: 128 }
// }

Опции вывода

toFile(filename, callback?)

Сохраняет обработанное изображение в файл.

await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

toBuffer(options?, callback?)

Выводит обработанное изображение как Buffer.

const buffer = await sharp('input.jpg')
  .resize(300, 200)
  .jpeg()
  .toBuffer();

toFormat(format, options?)

Устанавливает формат вывода.

// JPEG
await sharp('input.png')
  .jpeg({ quality: 80, progressive: true })
  .toFile('output.jpg');

// PNG
await sharp('input.jpg')
  .png({ compressionLevel: 9, adaptiveFiltering: true })
  .toFile('output.png');

// WebP
await sharp('input.jpg')
  .webp({ quality: 80, effort: 6 })
  .toFile('output.webp');

// AVIF
await sharp('input.jpg')
  .avif({ quality: 80, effort: 4 })
  .toFile('output.avif');

// TIFF
await sharp('input.jpg')
  .tiff({ quality: 80, compression: 'lzw' })
  .toFile('output.tiff');

Изменение изображения

resize(width?, height?, options?)

Изменяет размер изображения.

// Базовое изменение размера
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

// Сохранение соотношения сторон
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// Использование режима адаптации
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // Обрезка для соответствия
    position: 'center',  // Центрированная обрезка
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

// Использование ядра
await sharp('input.jpg')
  .resize(300, 200, {
    kernel: sharp.kernel.lanczos3
  })
  .toFile('output.jpg');

extract(region)

Обрезает область изображения.

await sharp('input.jpg')
  .extract({ left: 100, top: 100, width: 200, height: 200 })
  .toFile('cropped.jpg');

trim(threshold?)

Автоматически обрезает прозрачные или белые края.

await sharp('input.png')
  .trim()
  .toFile('trimmed.png');

Операции с изображениями

rotate(angle, options?)

Поворачивает изображение.

// Поворот на 90 градусов
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// Поворот с заполнением фона
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?)

Переворачивает изображение вертикально.

await sharp('input.jpg')
  .flip()
  .toFile('flipped.jpg');

flop(flop?)

Переворачивает изображение горизонтально.

await sharp('input.jpg')
  .flop()
  .toFile('flopped.jpg');

affine(matrix, options?)

Применяет аффинное преобразование.

await sharp('input.jpg')
  .affine([[1, 0.3], [0, 1]], { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('transformed.jpg');

Эффекты фильтров

blur(sigma?)

Применяет размытие по Гауссу.

await sharp('input.jpg')
  .blur(5)
  .toFile('blurred.jpg');

sharpen(sigma?, flat?, jagged?)

Применяет фильтр резкости.

await sharp('input.jpg')
  .sharpen()
  .toFile('sharpened.jpg');

// Пользовательские параметры резкости
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?)

Применяет медианный фильтр.

await sharp('input.jpg')
  .median(3)
  .toFile('median.jpg');

flatten(options?)

Объединяет прозрачный канал.

await sharp('input.png')
  .flatten({ background: { r: 255, g: 255, b: 255 } })
  .toFile('flattened.jpg');

Операции с цветом

grayscale(grayscale?)

Преобразует в оттенки серого.

await sharp('input.jpg')
  .grayscale()
  .toFile('grayscale.jpg');

negate(negate?)

Эффект негатива.

await sharp('input.jpg')
  .negate()
  .toFile('negated.jpg');

modulate(options?)

Настраивает яркость, насыщенность и оттенок.

await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // Яркость
    saturation: 0.8,    // Насыщенность
    hue: 90             // Оттенок
  })
  .toFile('modulated.jpg');

tint(rgb)

Применяет тонирование.

await sharp('input.jpg')
  .tint({ r: 255, g: 0, b: 0 })
  .toFile('tinted.jpg');

removeAlpha()

Удаляет прозрачный канал.

await sharp('input.png')
  .removeAlpha()
  .toFile('no-alpha.jpg');

ensureAlpha()

Обеспечивает наличие прозрачного канала.

await sharp('input.jpg')
  .ensureAlpha()
  .toFile('with-alpha.png');

Операции с каналами

bandbool(boolean)

Применяет булеву операцию к каналам.

await sharp('input.jpg')
  .bandbool('and')
  .toFile('bandbool.jpg');

joinChannel(channels)

Объединяет каналы.

await sharp('input.jpg')
  .joinChannel(['red.jpg', 'green.jpg', 'blue.jpg'])
  .toFile('joined.jpg');

extractChannel(channel)

Извлекает один канал.

await sharp('input.jpg')
  .extractChannel('red')
  .toFile('red-channel.jpg');

Глобальные свойства

sharp.versions

Получает информацию о версии.

console.log(sharp.versions);
// {
//   sharp: '0.32.0',
//   vips: '8.14.0'
// }

sharp.format

Получает поддерживаемые форматы.

console.log(sharp.format);
// {
//   jpeg: { id: 'jpeg', ... },
//   png: { id: 'png', ... },
//   webp: { id: 'webp', ... },
//   ...
// }

sharp.kernel

Получает доступные ядра.

console.log(sharp.kernel);
// {
//   nearest: 'nearest',
//   cubic: 'cubic',
//   mitchell: 'mitchell',
//   lanczos2: 'lanczos2',
//   lanczos3: 'lanczos3'
// }

Обработка ошибок

try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('Обработка изображения не удалась:', error);
}

Оптимизация производительности

Потоковая обработка

const pipeline = sharp()
  .resize(300, 200)
  .jpeg({ quality: 80 });

fs.createReadStream('large-input.jpg')
  .pipe(pipeline)
  .pipe(fs.createWriteStream('output.jpg'));

Параллельная обработка

const promises = images.map(image => 
  sharp(image)
    .resize(300, 200)
    .jpeg()
    .toBuffer()
);

const results = await Promise.all(promises);

Полный пример

import sharp from 'sharp';

async function processImage() {
  try {
    // Получение метаданных
    const metadata = await sharp('input.jpg').metadata();
    console.log('Исходный размер изображения:', metadata.width, 'x', metadata.height);

    // Создание нескольких версий
    const promises = [
      // Миниатюра
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // Средний размер
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

      // Большой размер
      sharp('input.jpg')
        .resize(1920, 1080, { fit: 'inside' })
        .jpeg({ quality: 85, progressive: true })
        .toFile('large.jpg'),

      // Версия в оттенках серого
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('Все изображения обработаны!');
  } catch (error) {
    console.error('Обработка не удалась:', error);
  }
}

processImage();

Следующие шаги

• Посетите страницу примеров для получения дополнительной информации
• Узнайте о оптимизации производительности
• Просмотрите журнал изменений для получения информации о последних функциях