Referência da API

Sharp fornece uma API rica para processar imagens. Esta página fornece referência detalhada para todos os métodos disponíveis.

Construtor

sharp(input, options?)

Cria uma nova instância Sharp.

import sharp from 'sharp';

// Criar a partir de arquivo
const image = sharp('input.jpg');

// Criar a partir de Buffer
const image = sharp(buffer);

// Criar a partir de Stream
const image = sharp(stream);

// Criar imagem em branco
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

Metadados de Entrada

metadata()

Obtém informações de metadados da imagem.

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

Obtém informações estatísticas da imagem.

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

Opções de Saída

toFile(filename, callback?)

Salva a imagem processada em arquivo.

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

toBuffer(options?, callback?)

Saída da imagem processada como Buffer.

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

toFormat(format, options?)

Define o formato de saída.

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

Ajuste de Imagem

resize(width?, height?, options?)

Redimensiona a imagem.

// Redimensionamento básico
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

// Manter proporção
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// Usar modo de ajuste
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // Cortar para ajustar
    position: 'center',  // Cortar centralizado
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

// Usar kernel
await sharp('input.jpg')
  .resize(300, 200, {
    kernel: sharp.kernel.lanczos3
  })
  .toFile('output.jpg');

extract(region)

Corta região da imagem.

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

trim(threshold?)

Corta automaticamente bordas transparentes ou brancas.

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

Operações de Imagem

rotate(angle, options?)

Rotaciona a imagem.

// Rotacionar 90 graus
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// Rotacionar e preencher fundo
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?)

Inverte a imagem verticalmente.

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

flop(flop?)

Inverte a imagem horizontalmente.

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

affine(matrix, options?)

Aplica transformação afim.

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

Efeitos de Filtro

blur(sigma?)

Aplica desfoque gaussiano.

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

sharpen(sigma?, flat?, jagged?)

Aplica filtro de nitidez.

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

// Parâmetros de nitidez personalizados
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?)

Aplica filtro mediano.

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

flatten(options?)

Mescla canal de transparência.

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

Operações de Cor

grayscale(grayscale?)

Converte para imagem em escala de cinza.

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

negate(negate?)

Efeito negativo.

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

modulate(options?)

Ajusta brilho, saturação e matiz.

await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // Brilho
    saturation: 0.8,    // Saturação
    hue: 90             // Matiz
  })
  .toFile('modulated.jpg');

tint(rgb)

Aplica matiz.

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

removeAlpha()

Remove canal de transparência.

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

ensureAlpha()

Garante que há canal de transparência.

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

Operações de Canal

bandbool(boolean)

Aplica operação booleana aos canais.

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

joinChannel(channels)

Combina canais.

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

extractChannel(channel)

Extrai canal único.

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

Propriedades Globais

sharp.versions

Obtém informações de versão.

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

sharp.format

Obtém formatos suportados.

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

sharp.kernel

Obtém kernels disponíveis.

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

Tratamento de Erros

try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('Processamento de imagem falhou:', error);
}

Otimização de Performance

Processamento em Stream

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

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

Processamento Concorrente

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

const results = await Promise.all(promises);

Exemplo Completo

import sharp from 'sharp';

async function processImage() {
  try {
    // Obter metadados
    const metadata = await sharp('input.jpg').metadata();
    console.log('Dimensões da imagem original:', metadata.width, 'x', metadata.height);

    // Criar múltiplas versões
    const promises = [
      // Miniatura
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // Tamanho médio
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

      // Tamanho grande
      sharp('input.jpg')
        .resize(1920, 1080, { fit: 'inside' })
        .jpeg({ quality: 85, progressive: true })
        .toFile('large.jpg'),

      // Versão em escala de cinza
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('Processamento de imagem concluído!');
  } catch (error) {
    console.error('Processamento falhou:', error);
  }
}

processImage();

Próximos Passos

• Ver página de exemplos para mais usos
• Aprender técnicas de otimização de performance
• Ver changelog para recursos mais recentes