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

次のステップ

• サンプルページ を確認して、より多くの使い方を学ぶ
• パフォーマンス最適化 のテクニックを学ぶ
• 更新ログ を確認して最新機能を確認する