تبدیل داده‌های CSV به گزارش‌های براق PDF یک نیاز مکرر برای داشبوردها، فاکتورها و آرشیوهای داده‌ای است.

GroupDocs.Conversion Cloud SDK for Node.js یک API ساده ارائه می‌دهد که تبدیل CSV به PDF را در Node.JS با دقت بالا انجام می‌دهد.

در این آموزش، شما SDK را تنظیم می‌کنید، پیاده‌سازی گام‌به‌گام را مرور می‌کنید و نکات عملکردی و توصیه‌های بهترین روش‌ها را بررسی می‌کنید تا تبدیل را به‌صورت یکپارچه در برنامه‌های سمت‑سرور خود ادغام کنید.

مراحل تبدیل CSV به PDF در Node.JS

  1. راه‌اندازی کلاینت API تبدیل: یک نمونه از ConversionApi را با شناسه مشتری و رمز عبور خود ایجاد کنید. این شیء احراز هویت و امضای درخواست را مدیریت می‌کند.
    const { ConversionApi } = require('groupdocs-conversion-cloud');
const apiInstance = new ConversionApi({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET' });
  2. بارگذاری فایل منبع CSV: از متد UploadFile برای ارسال CSV به فضای ذخیره‌سازی ابری استفاده کنید. این متد شناسه فایلی را برمی‌گرداند که در فراخوانی‌های بعدی استفاده می‌شود.
    const uploadResult = await apiInstance.uploadFile({ file: './data/input.csv' });
const sourceFileId = uploadResult.id;
  3. تعریف گزینه‌های تبدیل به PDF: PdfConvertOptions را برای تنظیم اندازه صفحه، جهت‌گیری و جاسازی فونت پیکربندی کنید.
    const pdfOptions = { 
    pageSize: 'A4', 
    orientation: 'Portrait', 
    embedFonts: true 
};
  4. اجرای تبدیل: با فراخوانی convert شناسه فایل منبع، فرمت هدف "PDF" و شیء گزینه‌ها را ارسال کنید.
    const convertResult = await apiInstance.convert({
    fileId: sourceFileId,
    outputFormat: 'PDF',
    options: pdfOptions
});
const pdfFileId = convertResult.id;
  5. بارگیری PDF حاصل: PDF را با استفاده از downloadFile دریافت کنید و به صورت محلی ذخیره کنید.
    const pdfStream = await apiInstance.downloadFile({ fileId: pdfFileId });
const fs = require('fs');
const writeStream = fs.createWriteStream('./output/result.pdf');
pdfStream.pipe(writeStream);

نمونه تبدیل CSV به PDF - مثال کامل کد

مثال زیر تمام مراحل را در یک اسکریپت قابل اجرا ترکیب می‌کند.

// Complete CSV to PDF conversion using GroupDocs.Conversion Cloud SDK for Node.js
const fs = require('fs');
const { ConversionApi } = require('groupdocs-conversion-cloud');

// Configure API client
const api = new ConversionApi({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET'
});

async function convertCsvToPdf() {
    try {
        // 1. Upload CSV file
        const upload = await api.uploadFile({ file: './data/input.csv' });
        const sourceId = upload.id;

// 2. Set PDF conversion options
        const pdfOptions = {
            pageSize: 'A4',
            orientation: 'Portrait',
            embedFonts: true
        };

// 3. Convert to PDF
        const conversion = await api.convert({
            fileId: sourceId,
            outputFormat: 'PDF',
            options: pdfOptions
        });
        const pdfId = conversion.id;

// 4. Download PDF
        const pdfStream = await api.downloadFile({ fileId: pdfId });
        const outputPath = './output/result.pdf';
        const writeStream = fs.createWriteStream(outputPath);
        pdfStream.pipe(writeStream);

writeStream.on('finish', () => {
            console.log(`PDF saved to ${outputPath}`);
        });
    } catch (error) {
        console.error('Conversion failed:', error);
    }
}

convertCsvToPdf();

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل (./data/input.csv, ./output/result.pdf) را به‌گونه‌ای به‌روزرسانی کنید که با مکان‌های واقعی فایل‌های شما مطابقت داشته باشد، اطمینان حاصل کنید تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک با تیم پشتیبانی تماس بگیرید.

تبدیل CSV به PDF از راه دور از طریق REST API با استفاده از cURL

API ابری را می‌توان با دستورات ساده cURL نیز دسترسی یافت. مقادیر جایگزین را با اعتبارنامه‌ها و نام‌های فایل خود جایگزین کنید.

  1. دریافت توکن دسترسی
    curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
  2. بارگذاری فایل CSV
    curl -X POST "https://api.groupdocs.cloud/v1.0/storage/file" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@./data/input.csv"
  3. درخواست تبدیل CSV به PDF
    curl -X POST "https://api.groupdocs.cloud/v1.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileId":"UPLOADED_FILE_ID",
           "outputFormat":"PDF",
           "options":{"pageSize":"A4","orientation":"Portrait","embedFonts":true}
         }'
  4. دانلود PDF تبدیل‌شده
    curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file/OUTPUT_FILE_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o result.pdf

برای دریافت فهرست کامل نقاط انتهایی و پارامترها، به مستندات رسمی API مراجعه کنید.

نصب و راه‌اندازی در Node.js

  1. نصب SDK
    npm install groupdocs-conversion-cloud
  2. دانلود آخرین بسته (اختیاری) از صفحهٔ release page.
  3. پیکربندی اعتبارنامه‌های خود - clientId و clientSecret را به‌صورت ایمن ذخیره کنید، برای مثال در متغیرهای محیطی.
  4. اعمال یک لایسنس موقت برای اهداف تست با استفاده از URL ارائه‌شده در صفحهٔ temporary license page. استقرارهای تولیدی به یک لایسنس خریداری‌شده نیاز دارند.

مثال تبدیل CSV به PDF در Node.JS با GroupDocs.Conversion

این بخش جریان کاری کلی تبدیل یک سند CSV به گزارش PDF را با استفاده از سرویس ابری توضیح می‌دهد. API مدیریت فایل، تجزیه فرمت و رندر چیدمان را انتزاع می‌کند و به شما امکان می‌دهد بر منطق کسب‌وکار تمرکز کنید. با ارسال CSV به عنوان فایل منبع و تعیین PDF به عنوان فرمت هدف، سرویس یک PDF آماده‑به‑استفاده برمی‌گرداند که ساختارهای جدول، استایل‌گذاری سلول و کاراکترهای یونیکد را حفظ می‌کند.

ویژگی‌های GroupDocs.Conversion که برای این کار مهم هستند

  • تشخیص خودکار جدول - موتور جداکننده‌های CSV را شناسایی می‌کند و بدون نیاز به کد اضافی جداول را می‌سازد.
  • رندر PDF با کیفیت بالا - از گرافیک‌های برداری، جاسازی فونت و چیدمان دقیق صفحه پشتیبانی می‌کند.
  • پردازش مقیاس‌پذیر ابری - فایل‌های بزرگ و درخواست‌های همزمان را بدون محدودیت منابع محلی مدیریت می‌کند.
  • پشتیبانی گسترده از فرمت‌ها - فراتر از CSV و PDF، همان API می‌تواند Excel، HTML، و بسیاری فرمت‌های دیگر را تبدیل کند و توسعه‌های آینده را ساده می‌سازد.

پیکربندی گزینه‌های تبدیل برای خروجی PDF

می‌توانید با تنظیم شی PdfConvertOptions، تولید PDF را به‌دقت تنظیم کنید:

گزینهتوضیحمقدار مثال
pageSizeابعاد صفحه هدف (A4، Letter، و غیره)"A4"
orientationجهت صفحه - عمودی یا افقی"Portrait"
embedFontsجاسازی فونت‌های استفاده‌شده در PDF برای قابلیت حملtrue
marginTopحاشیه بالایی به پوینت20
marginBottomحاشیه پایینی به پوینت20
marginLeftحاشیه چپ به پوینت15
marginRightحاشیه راست به پوینت15

این گزینه‌ها را قبل از فراخوانی متد convert تنظیم کنید تا سند نهایی سفارشی شود.

بهینه‌سازی عملکرد تبدیل در Node.JS

می‌توان عملکرد را با استفاده از تماس‌های ناهمزمان و بارگذاری/بارگیری‌های جریان‌دار بهبود داد. جدول زیر اجرای همزمان در مقابل ناهمزمان را برای یک فایل CSV 5 MB مقایسه می‌کند.

حالتزمان متوسط (میلی‌ثانیه)مصرف CPU (%)حافظه (مگابایت)
همزمان82045120
ناهمزمان5403085

نکات برای سرعت بهینه

  • از await همراه با متدهای async SDK استفاده کنید تا از مسدود شدن حلقه رویداد جلوگیری شود.
  • فشرده‌سازی gzip را در درخواست‌های HTTP فعال کنید (SDK این کار را به‌صورت خودکار انجام می‌دهد).
  • اگر نیاز به پیش‌پردازش داده‌ها قبل از تبدیل دارید، فایل‌های CSV بزرگ را به‌صورت بخش‑بخش پردازش کنید.

بهترین روش‌ها برای تبدیل CSV به PDF در Node.JS

  • اعتبارسنجی ورودی - اطمینان حاصل کنید که CSV قبل از بارگذاری، از جداکننده‌ها و رمزگذاری مورد انتظار پیروی می‌کند.
  • حفظ اعتبارنامه‌ها - clientId و clientSecret را از کنترل نسخه خارج نگه دارید؛ از متغیرهای محیطی یا مدیران راز استفاده کنید.
  • مدیریت خطاها به‌صورت ملایم - فراخوانی‌های API را در بلوک‌های try/catch بپیچید و جزئیات خطا را از پاسخ SDK لاگ کنید.
  • استفاده از استریمینگ - برای فایل‌های بسیار بزرگ، بارگذاری و دانلود را به صورت استریم کنید تا مصرف حافظه به حداقل برسد.
  • آزمون با داده‌های واقعی - نتایج تبدیل را با نمونه‌های نماینده CSV بررسی کنید، به‌ویژه هنگام کار با کاراکترهای خاص یا فیلدهای چندخطی.

نتیجه‌گیری

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

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

  • چگونه می‌توانم مثال تبدیل CSV به PDF را در Node.JS پیاده‌سازی کنم؟
    از کلاس ConversionApi استفاده کنید، CSV خود را بارگذاری کنید، PdfConvertOptions را تنظیم کنید، متد convert را فراخوانی کنید و PDF را دانلود کنید. قطعه کد کامل بالا جریان کامل را نشان می‌دهد.
  • مشکلات رایج هنگام تبدیل فایل‌های CSV بزرگ چیست؟
    کاهش حافظه و خطاهای زمان‌سنجی معمول هستند. بارگذاری فایل را به صورت جریان (stream) انجام دهید، زمان‌سنجی درخواست را افزایش دهید و محدودیت‌های نرخ API را همان‌طور که در مستندات SDK توضیح داده شده است، نظارت کنید.
  • آیا می‌توانم چیدمان PDF را فراتر از تنظیمات پیش‌فرض سفارشی کنم؟
    بله، شیء PdfConvertOptions به شما امکان تنظیم اندازه صفحه، حاشیه‌ها، جهت‌گیری و جاسازی فونت را می‌دهد. برای لیست کامل گزینه‌ها به API reference مراجعه کنید.
  • آیا راهی برای تبدیل دسته‌ای چندین فایل CSV در یک درخواست وجود دارد؟
    SDK یک فایل را در هر درخواست پردازش می‌کند، اما می‌توانید بر روی مجموعه‌ای از فایل‌ها حلقه بزنید و تبدیل‌ها را به صورت موازی با استفاده از Promise.all برای پردازش دسته‌ای کارآمد اجرا کنید.

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