تبدیل 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 - دستور require("@groupdocs/conversion-cloud") کلاس‌های اساسی مانند ConvertApi، ConvertSettings و PngOptions را بارگذاری می‌کند (مرجع 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 به شما امکان می‌دهد ابعاد و رنگ پس‌زمینه را کنترل کنید، که برای SVGهای بزرگ یا شفاف مفید است.
```
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 - (در صورت پشتیبانی) یک سطح فشرده‌سازی بین ۰ (بدون فشرده‌سازی) و ۹ (حداکثر فشرده‌سازی) انتخاب کنید تا حجم فایل کاهش یابد.
```
const pngOptions = new PngOptions({ compressionLevel: 6 });
```

این گزینه‌ها از طریق ویژگی options در ConvertSettings عبور می‌کنند. برای فهرست کامل تنظیمات موجود به مرجع API مراجعه کنید.

بهترین روش‌ها برای تبدیل مؤثر SVG به PNG

اعتبارسنجی محتوای SVG - اطمینان حاصل کنید که SVG حاوی اسکریپت‌های خارجی یا بارهای مخرب قبل از بارگذاری نیست. GroupDocs.Conversion ورودی را پاک‌سازی می‌کند، اما اعتبارسنجی پیش‌ازبارگذاری لایه امنیتی اضافی اضافه می‌کند.
استفاده مجدد از شیء Configuration - یک نمونهٔ Configuration واحد ایجاد کنید و آن را بین چندین فراخوانی ConvertApi به اشتراک بگذارید تا بار کاری کاهش یابد.
تنظیم ابعاد معقول - عرض و ارتفاع را به اندازه‌ای که واقعاً نیاز دارید محدود کنید. تصاویر بزرگ‌نمایی‌شده زمان پردازش و مصرف حافظه را افزایش می‌دهند.
استریم فایل‌های بزرگ - برای SVGهای بسیار بزرگ، به جای بارگذاری تمام بافر در حافظه، استریم دانلود را در نظر بگیرید.
نظارت بر استفاده از API - به سهمیهٔ تبدیل خود نظارت کنید و پاسخ‌های محدودیت نرخ را به‌صورت ملایم مدیریت کنید.

نتیجه‌گیری

GroupDocs.Conversion Cloud SDK for Node.JS سرور‑ساید تبدیل SVG به PNG را به‌صورت ساده، مقیاس‌پذیر و ایمن می‌کند. با دنبال کردن مثال کامل کد، جریان کاری معادل cURL، و نکات پیکربندی بالا، می‌توانید تبدیل تصویر با عملکرد بالا را در هر سرویس بک‌اند یکپارچه کنید. به یاد داشته باشید که گزینه‌های مجوزدهی را بررسی کنید؛ استقرارهای تولیدی نیاز به اشتراک پرداختی دارند، و می‌توانید یک مجوز موقت برای تست از صفحه مجوز موقت دریافت کنید. امروز شروع به تبدیل کنید و دارایی‌های PNG واضح را با اطمینان به کاربران خود ارائه دهید.

سوالات متداول

چگونه می‌توانم تبدیل SVG به PNG را در Node.JS با استفاده از GroupDocs انجام دهم؟
از GroupDocs.Conversion Cloud SDK برای 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#

نتیجه‌گیری#

سوالات متداول#

بیشتر بخوانید#