La conversión de gráficos vectoriales a imágenes raster es un requisito frecuente al generar miniaturas, vistas previas o PDFs en el servidor. GroupDocs.Conversion Cloud SDK for Node.JS ofrece una biblioteca robusta que maneja la conversión de SVG a PNG completamente en la nube. En esta guía verás un ejemplo completo y funcional, un flujo de trabajo cURL correspondiente, consejos de configuración y recomendaciones de buenas prácticas. Al final, podrás integrar la conversión de SVG a PNG del lado del servidor en cualquier aplicación Node.JS.
Ejemplo completo de funcionamiento para la conversión de SVG a PNG en Node.JS
Este ejemplo muestra cómo convertir un archivo SVG almacenado en GroupDocs Cloud storage a una imagen PNG usando el 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();
}
});
Nota: Este ejemplo de código muestra la funcionalidad principal. Antes de usarlo en su proyecto, asegúrese de actualizar las rutas de los archivos (
input/sample.svg,output/sample.png, etc.) para que coincidan con sus ubicaciones reales, verifique que todas las dependencias requeridas estén correctamente instaladas y realice pruebas exhaustivas en su entorno de desarrollo. Si encuentra algún problema, consulte la documentación oficial o póngase en contacto con el equipo de soporte para obtener ayuda.
Conversión de SVG a PNG mediante API REST usando cURL
Si prefiere un enfoque puramente REST, la misma conversión se puede realizar con comandos cURL. Los pasos a continuación muestran cómo obtener un token de acceso, cargar el SVG, iniciar la conversión y descargar el PNG.
Autenticar y obtener token de acceso
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"
}'
La respuesta contiene un access_token que usarás en llamadas posteriores.
Cargar el archivo SVG de origen
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"
Ejecutar la conversión de SVG a 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"
}
}'
La API devuelve la ruta del archivo PNG recién creado en el almacenamiento en la nube.
Descargar el archivo 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
Estos comandos cURL le brindan un control total sobre el proceso de conversión sin escribir código. Para obtener más detalles, consulte la documentación oficial de la API.
Cómo funciona la conversión de SVG a PNG en Node.JS
Importar clases del SDK - La instrucción
require("@groupdocs/conversion-cloud")carga clases esenciales comoConvertApi,ConvertSettingsyPngOptions(referencia de API).const { ConvertApi, ConvertSettings, PngOptions } = require("@groupdocs/conversion-cloud");Configurar autenticación - Un objeto
Configurationcontiene suclientIdyclientSecret. Este objeto se pasa tanto aConvertApicomo aStorageApipara autorizar todas las llamadas posteriores.const config = new Configuration({ clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" });Definir rutas de entrada y salida -
inputSvgPathapunta al SVG en el almacenamiento en la nube, mientras queoutputPngPathespecifica dónde se debe guardar el PNG.
const inputSvgPath = "input/sample.svg";
const outputPngPath = "output/sample.png";
Establecer opciones PNG -
PngOptionsle permite controlar las dimensiones y el color de fondo, lo que es útil para SVG grandes o transparentes.const pngOptions = new PngOptions({ width: 1024, height: 768, backgroundColor: "#FFFFFF" });Crear configuraciones de conversión y ejecutar -
ConvertSettingsagrupa la ruta del archivo, el formato de destino, la ubicación de salida y las opciones. El métodoconvertDocumentrealiza la conversión y el resultado contiene la ruta en la nube del PNG.const convertSettings = new ConvertSettings({ filePath: inputSvgPath, format: "png", outputPath: outputPngPath, options: pngOptions }); const convertRequest = new ConvertDocumentRequest(convertSettings); convertApi.convertDocument(convertRequest);Descargar el PNG - Después de la conversión,
StorageApi.downloadFilerecupera los datos binarios, que puedes escribir en el sistema de archivos local.
Comprender cada paso le ayuda a personalizar el proceso, manejar errores e integrar la conversión en flujos de trabajo más amplios.
Instalación y Configuración GroupDocs.Conversion Cloud SDK for Node.JS
npm install groupdocs-conversion-cloud
El SDK requiere Node.js 12 o posterior. Después de la instalación, cree un objeto de configuración con su clientId y clientSecret (disponibles en su cuenta de GroupDocs Cloud). Consulte la página de descarga para obtener la última versión del paquete.
const { Configuration } = require("@groupdocs/conversion-cloud");
const config = new Configuration({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
});
Asegúrese de que las credenciales tengan permiso para acceder a los servicios de almacenamiento y conversión. Una vez configurado, puede instanciar ConvertApi y StorageApi como se muestra en el ejemplo de código.
Ajuste fino de la configuración de conversión PNG
La clase PngOptions ofrece varias propiedades que puedes ajustar:
- width / height - Define la resolución de salida. Valores mayores aumentan la calidad pero consumen más memoria.
const pngOptions = new PngOptions({ width: 1920, height: 1080 }); - backgroundColor - Establece un fondo sólido para los SVG que contienen transparencia.
const pngOptions = new PngOptions({ backgroundColor: "#000000" }); - compressionLevel - (Si es compatible) Elige un nivel de compresión entre 0 (sin compresión) y 9 (compresión máxima) para reducir el tamaño del archivo.
const pngOptions = new PngOptions({ compressionLevel: 6 });
Estas opciones se pasan a través de la propiedad options de ConvertSettings. Consulte la referencia de API para obtener la lista completa de configuraciones disponibles.
Mejores prácticas para una conversión eficiente de SVG a PNG
- Validar contenido SVG - Asegúrese de que el SVG no contenga scripts externos ni cargas útiles maliciosas antes de subirlo. GroupDocs.Conversion sanitiza la entrada, pero la pre‑validación agrega una capa adicional de seguridad.
- Reutilizar el objeto de configuración - Cree una única instancia de
Configurationy compártala entre múltiples llamadas aConvertApipara reducir la sobrecarga. - Establecer dimensiones razonables - Limite el ancho y la altura al tamaño que realmente necesita. Las imágenes demasiado grandes aumentan el tiempo de procesamiento y el uso de memoria.
- Transmitir archivos grandes - Para SVGs muy grandes, considere transmitir la descarga en lugar de cargar todo el búfer en memoria.
- Monitorear el uso de la API - Vigile su cuota de conversión y maneje las respuestas de limitación de velocidad de forma adecuada.
Conclusión
GroupDocs.Conversion Cloud SDK for Node.JS hace que la conversión de SVG a PNG del lado del servidor sea sencilla, escalable y segura. Siguiendo el ejemplo de código completo, el flujo de trabajo equivalente en cURL y los consejos de configuración anteriores, puedes integrar la conversión de imágenes de alto rendimiento en cualquier servicio backend. Recuerda revisar las opciones de licencia; los despliegues en producción requieren una suscripción paga, y puedes obtener una licencia temporal para pruebas desde la página de licencia temporal. Comienza a convertir hoy y entrega activos PNG nítidos a tus usuarios con confianza.
Preguntas frecuentes
¿Cómo realizo la conversión de SVG a PNG en Node.JS usando GroupDocs?
Utilice el SDK de GroupDocs.Conversion Cloud para Node.JS. Cargue el SVG en el almacenamiento en la nube, configure PngOptions, llame a convertDocument y descargue el PNG. El ejemplo de código completo en este artículo muestra cada paso.
¿Puedo convertir en lote muchos archivos SVG a la vez?
Sí. Itera sobre una lista de rutas SVG y llama a la misma solicitud de conversión para cada archivo. El SDK procesa cada solicitud de forma independiente, lo que te permite almacenar todos los resultados PNG en una única carpeta de salida.
¿Qué debo hacer si la conversión falla con un error?
Verifique el mensaje de error devuelto en el bloque catch. Los problemas comunes incluyen credenciales inválidas, rutas de archivo faltantes o características SVG no compatibles. Consulte la documentación oficial para obtener códigos de error detallados y pasos de solución de problemas.
¿Dónde puedo encontrar más información sobre las opciones PNG?
Todas las propiedades configurables se enumeran en la referencia de API para PngOptions. Visite la referencia de API para explorar configuraciones adicionales como el nivel de compresión y la profundidad de color.