Преобразование SVG в PNG в Node.JS

Преобразование векторной графики в растровые изображения часто требуется при создании миниатюр, превью или PDF на сервере. GroupDocs.Conversion Cloud SDK for Node.JS предоставляет надёжную библиотеку, которая полностью в облаке обрабатывает конвертацию SVG в PNG. В этом руководстве вы увидите полностью работающий пример, соответствующий cURL‑workflow, советы по настройке и рекомендации по лучшим практикам. К концу вы сможете интегрировать серверную конвертацию SVG в PNG в любое приложение Node.JS.

Полный рабочий пример конвертации SVG в PNG в Node.JS

В этом примере демонстрируется, как преобразовать файл SVG, хранящийся в хранилище GroupDocs Cloud, в изображение 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

1. Импорт классов SDK - Оператор require("@groupdocs/conversion-cloud") загружает необходимые классы, такие как ConvertApi, ConvertSettings и PngOptions (Ссылка на API).

const { ConvertApi, ConvertSettings, PngOptions } = require("@groupdocs/conversion-cloud");

2. Настройка аутентификации - Объект Configuration хранит ваш clientId и clientSecret. Этот объект передаётся как в ConvertApi, так и в StorageApi для авторизации всех последующих вызовов.

const config = new Configuration({ clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" });

3. Определите пути ввода и вывода - inputSvgPath указывает на SVG в облачном хранилище, а outputPngPath задает, где следует сохранить PNG.

const inputSvgPath = "input/sample.svg";
const outputPngPath = "output/sample.png";

4. Установить параметры PNG - PngOptions позволяет управлять размерами и цветом фона, что полезно для больших или прозрачных SVG.

   const pngOptions = new PngOptions({ width: 1024, height: 768, backgroundColor: "#FFFFFF" });
   

5. Создать параметры конвертации и выполнить - ConvertSettings объединяет путь к файлу, целевой формат, место вывода и параметры. Метод convertDocument выполняет конвертацию, а результат содержит облачный путь к PNG.

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

6. Download the 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 – Следите за своей квотой конвертации и корректно обрабатывайте ответы с ограничением скорости.

Заключение

GroupDocs.Conversion Cloud SDK for Node.JS делает серверную конвертацию SVG в PNG простой, масштабируемой и безопасной. Следуя полному примеру кода, эквивалентному cURL‑рабочему процессу и приведённым выше советам по конфигурации, вы сможете интегрировать высокопроизводительное преобразование изображений в любой бэкенд‑сервис. Не забудьте ознакомиться с вариантами лицензирования: для продакшн‑развёртываний требуется платная подписка, а временную лицензию для тестирования можно получить на странице временной лицензии. Начните конвертировать уже сегодня и предоставляйте пользователям чёткие 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, чтобы изучить дополнительные настройки, такие как уровень сжатия и глубина цвета.

Читать дальше

• Пошаговое руководство по конвертации HTML в DOCX в Node.JS
• Пошаговый пример конвертации CSV в PDF в Node.JS
• Конвертация PDF в DOCX в Node.JS