تحويل SVG إلى PNG في Node.JS

تحويل الرسومات المتجهية إلى صور نقطية هو طلب شائع عند إنشاء الصور المصغرة أو المعاينات أو ملفات PDF على الخادم. GroupDocs.Conversion Cloud SDK for Node.JS يوفر مكتبة قوية تتعامل مع تحويل SVG إلى PNG بالكامل في السحابة. في هذا الدليل ستشاهد مثالًا عمليًا كاملاً، وسير عمل cURL مطابق، ونصائح التكوين، وتوصيات أفضل الممارسات. في النهاية ستتمكن من دمج تحويل SVG إلى PNG على جانب الخادم في أي تطبيق Node.JS.

مثال كامل يعمل لتحويل SVG إلى PNG في Node.JS

يوضح هذا المثال كيفية تحويل ملف SVG مخزن في GroupDocs Cloud storage إلى صورة PNG باستخدام GroupDocs.Conversion Cloud SDK for Node.JS.

const { Configuration, ConvertApi, ConvertDocumentRequest, ConvertSettings, PngOptions, StorageApi, DownloadFileRequest } = require("@groupdocs/conversion-cloud");
const fs = require('fs');
const path = require('path');

// -----------------------------------------------------------------------------
// Configuration – replace with your own credentials
// -----------------------------------------------------------------------------
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

const convertApi = new ConvertApi(config);
const storageApi = new StorageApi(config);

// -----------------------------------------------------------------------------
// Define source SVG and target PNG locations inside GroupDocs Cloud storage
// -----------------------------------------------------------------------------
const inputSvgPath = "input/sample.svg";          // SVG stored in cloud storage
const outputPngPath = "output/sample.png";       // Desired PNG location

// -----------------------------------------------------------------------------
// PNG conversion options – set dimensions to control memory/CPU usage
// -----------------------------------------------------------------------------
const pngOptions = new PngOptions({
    width: 1024,               // Resize width (optional)
    height: 768,               // Resize height (optional)
    backgroundColor: "#FFFFFF" // Ensure opaque background
});

// -----------------------------------------------------------------------------
// Build conversion settings object
// -----------------------------------------------------------------------------
const convertSettings = new ConvertSettings({
    filePath: inputSvgPath,
    format: "png",
    outputPath: outputPngPath,
    options: pngOptions
});

const convertRequest = new ConvertDocumentRequest(convertSettings);

// -----------------------------------------------------------------------------
// Execute conversion, then download the PNG locally
// -----------------------------------------------------------------------------
convertApi.convertDocument(convertRequest)
    .then(convResult => {
        console.log("Conversion succeeded. Cloud file:", convResult.path);
        const downloadReq = new DownloadFileRequest({ path: convResult.path });
        return storageApi.downloadFile(downloadReq);
    })
    .then(fileBuffer => {
        const localFile = path.resolve(__dirname, "sample.png");
        fs.writeFileSync(localFile, fileBuffer);
        console.log("PNG downloaded to:", localFile);
    })
    .catch(err => {
        console.error("Error during SVG → PNG conversion:", err);
    })
    .finally(() => {
        // Clean up HTTP client resources if the SDK exposes a close method
        if (config && config.httpClient && typeof config.httpClient.close === "function") {
            config.httpClient.close();
        }
    });

ملاحظة: يوضح مثال الشيفرة هذا الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (input/sample.svg, output/sample.png, إلخ) لتتناسب مع مواقع ملفاتك الفعلية، وتحقق من أن جميع الاعتمادات المطلوبة مثبتة بشكل صحيح، واختبر بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

تحويل SVG إلى PNG عبر REST API باستخدام cURL

إذا كنت تفضل نهج REST النقي، يمكن إجراء نفس التحويل باستخدام أوامر cURL. تُظهر الخطوات أدناه كيفية الحصول على رمز الوصول، تحميل ملف SVG، بدء التحويل، وتنزيل ملف PNG.

المصادقة والحصول على رمز الوصول

curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{
           "client_id": "YOUR_CLIENT_ID",
           "client_secret": "YOUR_CLIENT_SECRET"
         }'

تحتوي الاستجابة على access_token الذي ستستخدمه في المكالمات اللاحقة.

تحميل ملف SVG المصدر

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=input/sample.svg" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/local/sample.svg"

تنفيذ تحويل SVG إلى PNG

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "filePath": "input/sample.svg",
           "format": "png",
           "outputPath": "output/sample.png",
           "options": {
               "width": 1024,
               "height": 768,
               "backgroundColor": "#FFFFFF"
           }
         }'

تُعيد الواجهة البرمجية (API) مسار ملف PNG الذي تم إنشاؤه حديثًا في التخزين السحابي.

تحميل ملف PNG الناتج

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download?path=output/sample.png" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o sample.png

تمنحك أوامر cURL هذه تحكمًا كاملاً في عملية التحويل دون كتابة أي شفرة. لمزيد من التفاصيل، راجع وثائق API الرسمية.

كيفية تحويل SVG إلى PNG في Node.JS

استيراد فئات SDK - يتم تحميل الفئات الأساسية مثل ConvertApi و ConvertSettings و PngOptions بواسطة تعليمة require("@groupdocs/conversion-cloud") (مرجع API).
```
const { ConvertApi, ConvertSettings, PngOptions } = require("@groupdocs/conversion-cloud");
```
تكوين المصادقة - كائن Configuration يحتوي على clientId و clientSecret الخاصين بك. يتم تمرير هذا الكائن إلى كل من ConvertApi و StorageApi لتفويض جميع المكالمات اللاحقة.
```
const config = new Configuration({ clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" });
```
تحديد مسارات الإدخال والإخراج - inputSvgPath يشير إلى ملف SVG في التخزين السحابي، بينما outputPngPath يحدد المكان الذي يجب حفظ ملف PNG فيه.
```
const inputSvgPath = "input/sample.svg";
const outputPngPath = "output/sample.png";
```
تعيين خيارات PNG - PngOptions يتيح لك التحكم في الأبعاد ولون الخلفية، وهو مفيد للرسومات المتجهة الكبيرة أو الشفافة (SVGs).
```
const pngOptions = new PngOptions({ width: 1024, height: 768, backgroundColor: "#FFFFFF" });
```
إنشاء إعدادات التحويل وتنفيذها - ConvertSettings يجمع مسار الملف، التنسيق المستهدف، موقع الإخراج، والخيارات. طريقة convertDocument تقوم بإجراء التحويل، والنتيجة تحتوي على مسار السحابة لملف PNG.

const convertSettings = new ConvertSettings({ filePath: inputSvgPath, format: "png", outputPath: outputPngPath, options: pngOptions });
const convertRequest = new ConvertDocumentRequest(convertSettings);
convertApi.convertDocument(convertRequest);

تنزيل PNG - بعد التحويل، StorageApi.downloadFile يسترجع البيانات الثنائية، والتي يمكنك كتابتها إلى نظام الملفات المحلي.

فهم كل خطوة يساعدك على تخصيص العملية، ومعالجة الأخطاء، وتكامل التحويل في سير عمل أكبر.

التثبيت والتهيئة GroupDocs.Conversion Cloud SDK for Node.JS

npm install groupdocs-conversion-cloud

يتطلب SDK Node.js 12 أو أحدث. بعد التثبيت، أنشئ كائن تكوين يحتوي على clientId و clientSecret (متاحين من حساب GroupDocs Cloud الخاص بك). راجع صفحة التحميل للحصول على أحدث إصدار من الحزمة.

const { Configuration } = require("@groupdocs/conversion-cloud");
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

تأكد من أن بيانات الاعتماد لديها إذن للوصول إلى خدمات التخزين والتحويل. بمجرد التكوين، يمكنك إنشاء كائنات ConvertApi و StorageApi كما هو موضح في مثال الشيفرة.

ضبط إعدادات تحويل PNG

تقدم فئة PngOptions عدة خصائص يمكنك تعديلها:

width / height - تعريف دقة الإخراج. القيم الأكبر تزيد الجودة ولكنها تستهلك المزيد من الذاكرة.
```
const pngOptions = new PngOptions({ width: 1920, height: 1080 });
```
backgroundColor - تعيين خلفية صلبة للرسومات SVG التي تحتوي على شفافية.
```
const pngOptions = new PngOptions({ backgroundColor: "#000000" });
```
compressionLevel - (إذا كان مدعومًا) اختر مستوى ضغط بين 0 (بدون ضغط) و 9 (أقصى ضغط) لتقليل حجم الملف.
```
const pngOptions = new PngOptions({ compressionLevel: 6 });
```

يتم تمرير هذه الخيارات عبر خاصية options في ConvertSettings. راجع مرجع API للحصول على القائمة الكاملة للإعدادات المتاحة.

أفضل الممارسات لتحويل SVG إلى PNG بكفاءة

تحقق من محتوى SVG - تأكد من أن ملف SVG لا يحتوي على سكريبتات خارجية أو حمولة خبيثة قبل التحميل. تقوم GroupDocs.Conversion بتنظيف الإدخال، لكن التحقق المسبق يضيف طبقة أمان إضافية.
إعادة استخدام كائن Configuration - أنشئ نسخة واحدة من Configuration وشاركها عبر عدة استدعاءات ConvertApi لتقليل الحمل الزائد.
تحديد أبعاد معقولة - حدِّد العرض والارتفاع إلى الحجم الذي تحتاجه فعليًا. الصور الكبيرة جدًا تزيد من زمن المعالجة واستهلاك الذاكرة.
تدفق الملفات الكبيرة - بالنسبة لملفات SVG الكبيرة جدًا، فكر في تدفق التنزيل بدلاً من تحميل كامل الذاكرة المؤقتة إلى الذاكرة.
مراقبة استخدام API - راقب حصتك من التحويل وتعامل مع ردود حدود المعدل (rate‑limit) بلطف.

الخلاصة

GroupDocs.Conversion Cloud SDK for Node.JS يجعل تحويل SVG إلى PNG على الخادم بسيطًا، قابلًا للتوسع، وآمنًا. باتباع مثال الكود الكامل، وسير عمل cURL المكافئ، ونصائح التكوين المذكورة أعلاه، يمكنك دمج تحويل الصور عالي الأداء في أي خدمة خلفية. تذكر مراجعة خيارات الترخيص؛ تتطلب عمليات النشر في الإنتاج اشتراكًا مدفوعًا، ويمكنك الحصول على ترخيص مؤقت للاختبار من صفحة temporary license page. ابدأ التحويل اليوم وقدم ملفات PNG واضحة لمستخدميك بثقة.

الأسئلة المتكررة

كيف أقوم بتحويل SVG إلى PNG في Node.JS باستخدام GroupDocs؟
استخدم GroupDocs.Conversion Cloud SDK for Node.JS. قم بتحميل SVG إلى التخزين السحابي، اضبط PngOptions، استدعِ convertDocument، وحمّل PNG. يوضح مثال الشيفرة الكامل في هذه المقالة كل خطوة.

هل يمكنني تحويل مجموعة من ملفات SVG دفعة واحدة؟
نعم. قم بالتكرار عبر قائمة مسارات SVG واستدعِ طلب التحويل نفسه لكل ملف. يعالج SDK كل طلب بشكل مستقل، مما يتيح لك تخزين جميع نتائج PNG في مجلد إخراج واحد.

ماذا ينبغي عليّ أن أفعل إذا فشل التحويل مع ظهور خطأ؟
تحقق من رسالة الخطأ التي تم إرجاعها في كتلة الـ catch. تشمل المشكلات الشائعة بيانات اعتماد غير صالحة، مسارات ملفات مفقودة، أو ميزات SVG غير مدعومة. راجع التوثيق الرسمي للحصول على رموز الأخطاء التفصيلية وخطوات استكشاف الأخطاء وإصلاحها.

أين يمكنني العثور على مزيد من المعلومات حول خيارات PNG؟
جميع الخصائص القابلة للتكوين مدرجة في مرجع API لـ PngOptions. زر مرجع API لاستكشاف إعدادات إضافية مثل مستوى الضغط وعمق اللون.

مثال كامل يعمل لتحويل SVG إلى PNG في Node.JS#

تحويل SVG إلى PNG عبر REST API باستخدام cURL#

المصادقة والحصول على رمز الوصول#

تحميل ملف SVG المصدر#

تنفيذ تحويل SVG إلى PNG#

تحميل ملف PNG الناتج#

كيفية تحويل SVG إلى PNG في Node.JS#

التثبيت والتهيئة GroupDocs.Conversion Cloud SDK for Node.JS#

ضبط إعدادات تحويل PNG#

أفضل الممارسات لتحويل SVG إلى PNG بكفاءة#

الخلاصة#

الأسئلة المتكررة#

اقرأ المزيد#