Sharp لجافا سكريبت (Node.js): دليل شامل مع أمثلة

مقدمة: ما هي مكتبة Sharp ولماذا تحتاجها؟

Sharp هي مكتبة عالية الأداء لمعالجة الصور، مكتوبة بلغة C++ وتوفر واجهة برمجة تطبيقات (API) سهلة الاستخدام لـ Node.js. تتيح لك تحويل الصور من صيغ JPEG و PNG و WebP و AVIF و TIFF و GIF إلى صيغ أخرى، وتغيير حجمها، وقصها، وتدويرها، وإضافة تأثيرات، وغير ذلك الكثير.

الميزة الرئيسية لـ Sharp هي السرعة. تستخدم المكتبة مكتبات libvips الأصلية، مما يجعلها أسرع بعدة مرات من البدائل (مثل Jimp أو gm). وهي مثالية من أجل:

• خوادم الويب وواجهات API — معالجة ديناميكية للصور الرمزية، والمعاينات، وتحسين الصور قبل التحميل.
• المعالجة المجمعة — تحويل آلاف الصور إلى الصيغة والحجم المطلوبين.
• إنشاء الصور المصغرة والمعارض — توليد سريع للصور المصغرة (thumbnails).
• تحسين حجم الصور — ضغط بدون فقدان الجودة (أو مع فقدان متحكم به).

تعمل Sharp مع المخازن المؤقتة (buffers) والتيارات (streams) والملفات، مما يجعلها مرنة للتكامل مع أي تطبيق Node.js.

التثبيت

يتم تثبيت Sharp عبر npm. تتطلب المكتبة إصدار Node.js 12.13.0 أو أعلى (يُوصى باستخدام 14+).

npm install sharp

إذا كنت تستخدم yarn:

yarn add sharp

ملاحظة مهمة: تقوم Sharp بترجمة الوحدات الأصلية أثناء التثبيت. إذا واجهت أخطاء، تأكد من تثبيت build-essential (على Linux) أو Xcode Command Line Tools (على macOS). بالنسبة لنظام Windows، عادةً ما تكون Visual Studio Build Tools كافية.

بعد التثبيت، قم باستيراد المكتبة إلى مشروعك:

const sharp = require('sharp');

بداية سريعة

لنكتب نصًا برمجيًا بسيطًا يقوم بتحميل صورة، وتصغيرها إلى عرض 300 بكسل (مع الحفاظ على الأبعاد)، وحفظها بصيغة WebP.

const sharp = require('sharp');
const path = require('path');

async function quickStart() {
    try {
        await sharp('input.jpg')
            .resize(300) // العرض 300px، الارتفاع سيتم ضبطه تلقائيًا
            .webp({ quality: 80 }) // تحويل إلى WebP بجودة 80%
            .toFile('output.webp');
        
        console.log('تمت معالجة الصورة بنجاح!');
    } catch (error) {
        console.error('خطأ:', error);
    }
}

quickStart();

يوضح هذا المثال التسلسل (chaining) للدوال، وهو أساس العمل مع Sharp. كل دالة تُرجع نسخة جديدة من Sharp، مما يسمح بتطبيق التحويلات بشكل متتابع.

الدوال والأساليب الأساسية

فيما يلي 10 دوال رئيسية في Sharp مع شرح مفصل، والمعاملات، وأمثلة عملية.

1. resize() — تغيير حجم الصورة

الوظيفة: تغيير عرض و/أو ارتفاع الصورة. يمكنها قص الصورة أو تكييفها داخل إطار محدد.

المعاملات:

• width (رقم، اختياري) — العرض الجديد بالبكسل.
• height (رقم، اختياري) — الارتفاع الجديد بالبكسل.
• options (كائن، اختياري):
  • fit (نص) — وضع التكييف: 'cover' (ملء الإطار مع قص الزائد)، 'contain' (تكييف الصورة كاملة)، 'fill' (تمديد الصورة)، 'inside' (تصغير لتناسب الإطار)، 'outside' (تكبير لتجاوز الإطار). القيمة الافتراضية هي 'cover'.
  • position (نص) — موضع القص: 'center', 'top', 'left', 'right', 'bottom' وغيرها.
  • withoutEnlargement (قيمة منطقية) — منع تكبير الصورة.

مثال:

// تصغير إلى 200x200 مع القص من المنتصف
await sharp('input.jpg')
    .resize(200, 200, { fit: 'cover', position: 'center' })