Converter gráficos vetoriais em imagens raster é uma necessidade frequente ao gerar miniaturas, pré‑visualizações ou PDFs no servidor. GroupDocs.Conversion Cloud SDK for Node.JS fornece uma biblioteca robusta que lida com a conversão de SVG para PNG totalmente na nuvem. Neste guia você verá um exemplo completo em funcionamento, um fluxo de trabalho cURL correspondente, dicas de configuração e recomendações de boas práticas. Ao final, você será capaz de integrar a conversão de SVG para PNG no lado do servidor em qualquer aplicação Node.JS.
Exemplo completo de funcionamento para conversão de SVG para PNG em Node.JS
Este exemplo demonstra como converter um arquivo SVG armazenado no armazenamento do GroupDocs Cloud para uma imagem PNG usando o 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();
}
});
Observação: Este exemplo de código demonstra a funcionalidade principal. Antes de usá-lo em seu projeto, certifique-se de atualizar os caminhos dos arquivos (
input/sample.svg,output/sample.png, etc.) para corresponder às suas localizações reais, verifique se todas as dependências necessárias estão corretamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter ajuda.
Conversão de SVG para PNG via API REST usando cURL
Se você preferir uma abordagem puramente REST, a mesma conversão pode ser realizada com comandos cURL. As etapas abaixo mostram como obter um token de acesso, enviar o SVG, iniciar a conversão e baixar o PNG.
Autenticar e Obter Token de Acesso
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"
}'
A resposta contém um access_token que você usará nas chamadas subsequentes.
Carregar o Arquivo SVG de Origem
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"
Executar a Conversão de SVG para 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"
}
}'
A API retorna o caminho do arquivo PNG recém‑criado no armazenamento em nuvem.
Baixe o Arquivo PNG Resultante
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download?path=output/sample.png" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o sample.png
Esses comandos cURL dão a você controle total sobre o processo de conversão sem escrever nenhum código. Para mais detalhes, veja a documentação oficial da API.
Como a Conversão de SVG para PNG no Node.JS Funciona
Importar classes do SDK - A instrução
require("@groupdocs/conversion-cloud")carrega classes essenciais comoConvertApi,ConvertSettingsePngOptions(referência da API).const { ConvertApi, ConvertSettings, PngOptions } = require("@groupdocs/conversion-cloud");Configurar Autenticação - Um objeto
Configurationcontém seuclientIdeclientSecret. Esse objeto é passado tanto paraConvertApiquanto paraStorageApipara autorizar todas as chamadas subsequentes.const config = new Configuration({ clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" });Definir caminhos de entrada e saída -
inputSvgPathaponta para o SVG no armazenamento em nuvem, enquantooutputPngPathespecifica onde o PNG deve ser salvo.
const inputSvgPath = "input/sample.svg";
const outputPngPath = "output/sample.png";
Definir opções PNG -
PngOptionspermite controlar as dimensões e a cor de fundo, o que é útil para SVGs grandes ou transparentes.const pngOptions = new PngOptions({ width: 1024, height: 768, backgroundColor: "#FFFFFF" });Criar Configurações de Conversão e Executar -
ConvertSettingsagrupa o caminho do arquivo, o formato de destino, o local de saída e as opções. O métodoconvertDocumentrealiza a conversão, e o resultado contém o caminho na nuvem do PNG.const convertSettings = new ConvertSettings({ filePath: inputSvgPath, format: "png", outputPath: outputPngPath, options: pngOptions }); const convertRequest = new ConvertDocumentRequest(convertSettings); convertApi.convertDocument(convertRequest);Baixe o PNG - Após a conversão,
StorageApi.downloadFilerecupera os dados binários, que você pode gravar no sistema de arquivos local.
Compreender cada etapa ajuda a personalizar o processo, lidar com erros e integrar a conversão em fluxos de trabalho maiores.
Instalando e Configurando GroupDocs.Conversion Cloud SDK for Node.JS
npm install groupdocs-conversion-cloud
O SDK requer Node.js 12 ou posterior. Após a instalação, crie um objeto de configuração com seu clientId e clientSecret (disponíveis na sua conta do GroupDocs Cloud). Consulte a página de download para a versão mais recente do pacote.
const { Configuration } = require("@groupdocs/conversion-cloud");
const config = new Configuration({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
});
Certifique‑se de que as credenciais tenham permissão para acessar os serviços de armazenamento e conversão. Depois de configurado, você pode instanciar ConvertApi e StorageApi como mostrado no exemplo de código.
Ajuste fino das configurações de conversão PNG
A classe PngOptions oferece várias propriedades que você pode ajustar:
- width / height - Defina a resolução de saída. Valores maiores aumentam a qualidade, mas consomem mais memória.
const pngOptions = new PngOptions({ width: 1920, height: 1080 }); - backgroundColor - Defina um fundo sólido para SVGs que contêm transparência.
const pngOptions = new PngOptions({ backgroundColor: "#000000" }); - compressionLevel - (Se suportado) Escolha um nível de compressão entre 0 (sem compressão) e 9 (compressão máxima) para reduzir o tamanho do arquivo.
const pngOptions = new PngOptions({ compressionLevel: 6 });
Essas opções são passadas através da propriedade options de ConvertSettings. Consulte a referência da API para a lista completa de configurações disponíveis.
Melhores práticas para conversão eficiente de SVG para PNG
- Validar o conteúdo SVG - Certifique‑se de que o SVG não contém scripts externos ou cargas maliciosas antes do upload. GroupDocs.Conversion sanitiza a entrada, mas a pré‑validação adiciona uma camada extra de segurança.
- Reutilizar o objeto de Configuração - Crie uma única instância
Configuratione compartilhe‑a entre várias chamadasConvertApipara reduzir a sobrecarga. - Definir dimensões razoáveis - Limite a largura e a altura ao tamanho realmente necessário. Imagens excessivamente grandes aumentam o tempo de processamento e o uso de memória.
- Transmitir arquivos grandes - Para SVGs muito grandes, considere transmitir o download em vez de carregar todo o buffer na memória.
- Monitorar o uso da API - Fique de olho na sua cota de conversão e trate as respostas de limite de taxa de forma elegante.
Conclusão
GroupDocs.Conversion Cloud SDK for Node.JS torna a conversão de SVG para PNG no lado do servidor simples, escalável e segura. Seguindo o exemplo de código completo, o fluxo de trabalho equivalente em cURL e as dicas de configuração acima, você pode integrar a conversão de imagens de alto desempenho em qualquer serviço de backend. Lembre‑se de revisar as opções de licenciamento; implantações em produção exigem uma assinatura paga, e você pode obter uma licença temporária para testes na página de licença temporária. Comece a converter hoje e entregue ativos PNG nítidos aos seus usuários com confiança.
Perguntas Frequentes
Como faço a conversão de SVG para PNG no Node.JS usando GroupDocs?
Use o GroupDocs.Conversion Cloud SDK for Node.JS. Upload o SVG para o armazenamento na nuvem, configure PngOptions, chame convertDocument e faça o download do PNG. O exemplo de código completo neste artigo mostra cada passo.
Posso converter em lote muitos arquivos SVG de uma vez?
Sim. Percorra uma lista de caminhos SVG e invoque a mesma solicitação de conversão para cada arquivo. O SDK processa cada solicitação de forma independente, permitindo que você armazene todos os resultados PNG em uma única pasta de saída.
O que devo fazer se a conversão falhar com um erro?
Verifique a mensagem de erro retornada no bloco catch. Problemas comuns incluem credenciais inválidas, caminhos de arquivo ausentes ou recursos SVG não suportados. Consulte a documentação oficial para códigos de erro detalhados e etapas de solução de problemas.
Onde posso encontrar mais informações sobre as opções PNG?
Todas as propriedades configuráveis estão listadas na referência da API para PngOptions. Visite a referência da API para explorar configurações adicionais, como nível de compressão e profundidade de cor.