مرجع واجهة برمجة التطبيقات

يوفر Sharp واجهة برمجة تطبيقات غنية لمعالجة الصور. توفر هذه الصفحة مرجعًا مفصلًا لجميع الطرق المتاحة.

المنشئ

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

الخطوات التالية

• عرض صفحة الأمثلة لمعرفة المزيد من الاستخدامات
• تعلم تقنيات تحسين الأداء
• عرض سجل التحديثات لمعرفة أحدث الميزات