تبدیل داده‌های Excel به CSV یک نیاز مکرر هنگام ساخت خطوط داده، ابزارهای گزارش‌گیری یا ویژگی‌های واردات/صادرات است. Aspose.BarCode Cloud SDK for Node.js کتابخانه‌ای قدرتمند فراهم می‌کند که تبدیل XLS به CSV را در Node.JS ساده و قابل اعتماد می‌سازد. این راهنما شما را از پیش‌نیازها، مراحل نصب، یک مثال کامل عملی و نکات بهترین شیوه‌ها عبور می‌دهد تا بتوانید با اطمینان این تبدیل را در برنامه خود ادغام کنید.

مثال کامل و عملی برای تبدیل XLS به CSV در Node.JS با استفاده از Aspose.BarCode

این مثال نشان می‌دهد که چگونه یک کتاب کار XLS را از ذخیره‌سازی ابری بخوانید، هر برگه کاری را به CSV تبدیل کنید و نتیجه را به‌صورت جریان به مشتری بازگردانید.

// Full working code for XLS to CSV conversion using Aspose.BarCode Cloud SDK

const { BarcodeApi, Configuration } = require('aspose-barcode-cloud');
const fs = require('fs');
const path = require('path');

// ==== Configuration ====
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    // Optional: set a custom base URL if you use a private cloud
    // baseUrl: "https://api.aspose.cloud"
});

const apiInstance = new BarcodeApi(config);

// ==== Input / Output Paths ====
const inputFile = "sample.xls";               // Path to your local XLS file
const outputFolder = "output";                // Cloud folder for CSV files

// ---- 1. Upload XLS to cloud storage ----
async function uploadFile() {
    const fileData = fs.readFileSync(inputFile);
    await apiInstance.uploadFile({ path: inputFile, file: fileData });
    console.log(`Uploaded ${inputFile} to cloud storage.`);
}

// ---- 2. Convert XLS to CSV ----
async function convertXlsToCsv() {
    // Conversion options
    const options = {
        storage: "Default",               // Use default storage
        outPath: outputFolder,            // Destination folder
        format: "CSV",                    // Target format
        // Optional: delimiter, encoding, etc.
        delimiter: ",",
        encoding: "UTF-8"
    };

// Call the conversion endpoint (hypothetical method)
    const response = await apiInstance.convertDocument({
        name: inputFile,
        format: "csv",
        options: options
    });

console.log(`Conversion started. Check ${outputFolder} for CSV files.`);
    return response;
}

// ---- 3. Download generated CSV files ----
async function downloadCsvFiles() {
    const files = await apiInstance.getFilesList({ path: outputFolder });
    for (const file of files.value) {
        if (file.name.endsWith(".csv")) {
            const csvData = await apiInstance.downloadFile({ path: `${outputFolder}/${file.name}` });
            const localPath = path.join(__dirname, "result", file.name);
            fs.mkdirSync(path.dirname(localPath), { recursive: true });
            fs.writeFileSync(localPath, csvData.body);
            console.log(`Downloaded ${file.name} to ${localPath}`);
        }
    }
}

// ==== Execution Flow ====
(async () => {
    try {
        await uploadFile();
        await convertXlsToCsv();
        await downloadCsvFiles();
        console.log("XLS to CSV conversion completed successfully.");
    } catch (error) {
        console.error("Error during conversion:", error);
    }
})();

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

تبدیل XLS به CSV از طریق Cloud API با cURL

شما می‌توانید همان تبدیل را بدون نوشتن کد با استفاده از cURL برای فراخوانی نقاط انتهایی REST انجام دهید. این جریان شامل احراز هویت، بارگذاری فایل، درخواست تبدیل و دانلود است.

# 1. Get an access token
curl -X POST "https://api.aspose.cloud/connect/token" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
     -H "Content-Type: application/x-www-form-urlencoded"
# Response contains "access_token"

# 2. Upload the XLS file
curl -X PUT "https://api.aspose.cloud/v3.0/barcode/storage/file/sample.xls" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "sample.xls"

# 3. Request XLS to CSV conversion
curl -X POST "https://api.aspose.cloud/v3.0/barcode/convert/sample.xls?format=csv&outPath=output" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 4. Download the generated CSV file
curl -X GET "https://api.aspose.cloud/v3.0/barcode/storage/file/output/sample.csv" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -o "sample.csv"

برای جزئیات بیشتر دربارهٔ پارامترهای درخواست، به مستندات رسمی API مراجعه کنید.

نحوه تبدیل XLS به CSV در Node.JS

  1. راه‌اندازی پیکربندی - یک شیء Configuration شامل اعتبارهای کلاینت شما و URL پایه اختیاری است. این شیء به نمونه BarcodeApi منتقل می‌شود. 
    const config = new Configuration({ clientId, clientSecret });
const apiInstance = new BarcodeApi(config);
  2. بارگذاری فایل - متد uploadFile فایل XLS محلی را به فضای ذخیره‌سازی ابری Aspose.BarCode جریان می‌دهد و آن را برای تبدیل در دسترس می‌کند. 
    await apiInstance.uploadFile({ path: inputFile, file: fileData });
  3. درخواست تبدیل - convertDocument (فرضی) درخواست را با نام فایل منبع، فرمت هدف (csv) و گزینه‌های تبدیل مانند جداکننده و رمزگذاری ارسال می‌کند. سرویس هر ورق کاری را پردازش کرده و فایل‌های CSV مربوطه را ایجاد می‌کند. 
    const response = await apiInstance.convertDocument({ name: inputFile, format: "csv", options });
  4. دریافت نتیجه - پس از تبدیل، getFilesList فایل‌های CSV تولید شده را در پوشه خروجی فهرست می‌کند. سپس هر فایل با downloadFile دانلود و به‌صورت محلی ذخیره می‌شود. 
    const files = await apiInstance.getFilesList({ path: outputFolder });
const csvData = await apiInstance.downloadFile({ path: csvPath });
  5. مدیریت خطا - هر خطای API در بلوک catch گرفته می‌شود، جایی که می‌توانید جزئیات را لاگ کنید یا منطق retry را پیاده‌سازی کنید. برای دریافت فهرست کامل کدهای خطا، به مرجع API مراجعه کنید.

آماده‌سازی محیط - پیش‌نیازها و تنظیمات

قبل از شروع، اطمینان حاصل کنید که پیش‌نیازهای زیر برآورده شده‌اند:

  • Node.js 14 یا بالاتر نصب شده بر روی ماشین توسعه شما.
  • یک حساب Aspose Cloud با اعتبارنامه‌های معتبر مشتری (Client ID و Client Secret).
  • دسترسی به اینترنت برای فراخوانی‌های API.

نصب کتابخانه از طریق npm و لینک صفحه دانلود برای مرجع:

npm install aspose-barcode-cloud
# Download package details: https://releases.aspose.cloud/barcode/nodejs/

پس از نصب، یک فایل پیکربندی (به عنوان مثال، config.json) ایجاد کنید تا اعتبارنامه‌های خود را به‌صورت ایمن ذخیره کنید.

پارامترهای تبدیل: گزینه‌ها و تنظیمات

API تبدیل چندین پارامتر اختیاری را می‌پذیرد که به شما امکان تنظیم دقیق خروجی را می‌دهد:

  • delimiter - یک کاراکتر برای جدا کردن فیلدها انتخاب کنید (پیش‌فرض ,). 
    options.delimiter = "\t"; // Tab‑delimited CSV
  • encoding - رمزگذاری کاراکترها برای فایل CSV را تعریف کنید (مثلاً UTF-8، ISO-8859-1). 
    options.encoding = "UTF-8";
  • outPath - یک پوشهٔ ابری را که فایل‌های CSV در آن ذخیره می‌شوند، مشخص کنید. 
    options.outPath = "converted";
  • storage - نام ذخیره‌سازی را در صورتی که از سرویس ذخیره‌سازی سفارشی استفاده می‌کنید، انتخاب کنید. 
    options.storage = "MyCustomStorage";

برای دریافت فهرست کامل گزینه‌های پشتیبانی‌شده، به مرجع API مراجعه کنید.

نکات عملی برای تبدیل مؤثر XLS به CSV

  • پخش فایل‌های بزرگ - حالت پخش (streaming) را فعال کنید تا ردیف‌ها را به صورت بخش‌های کوچک پردازش کنید و از مصرف زیاد حافظه جلوگیری شود.
  • از پوشه موقت استفاده کنید - فایل‌های CSV میانی را در یک پوشه اختصاصی در ابر بنویسید و پس از دانلود آن را پاک کنید.
  • یک جداکننده مناسب تنظیم کنید - اگر داده‌های شما شامل کاما هستند، به جداکننده تب یا لوله (pipe) تغییر دهید تا از عدم هم‌ترازی ستون‌ها جلوگیری شود.
  • پس از دانلود اعتبارسنجی کنید - چند ردیف اول CSV را بررسی کنید تا از صحت رمزگذاری و استفاده از جداکننده اطمینان حاصل کنید قبل از پردازش‌های بعدی.

نتیجه‌گیری

XLS به CSV در Node.JS زمانی که از قابلیت‌های Aspose.BarCode Cloud SDK for Node.js استفاده کنید، ساده می‌شود. این راهنما همه چیز را از تنظیم محیط و یک مثال کامل کاری تا گزینه‌های پیکربندی و بهترین شیوه‌های مبتنی بر عملکرد پوشش داد. به یاد داشته باشید که اعتبارنامه‌های کلاینت خود را ایمن کنید، برای کتاب‌کارهای بزرگ از استریمینگ استفاده کنید و فایل‌های موقت را پاک کنید تا فضای ذخیره‌سازی ابری شما منظم بماند. برای استقرارهای تولیدی به یک لایسنس پرداختی نیاز خواهید داشت؛ می‌توانید قیمت‌گذاری را در صفحه محصول بررسی کنید و یک لایسنس ارزیابی موقت از صفحه لایسنس موقت دریافت کنید.

FAQs

چگونه تبدیل XLS به CSV در Node.JS چندین برگه کاری را مدیریت می‌کند؟
کتابخانه هر برگه کاری را به‌صورت متوالی پردازش می‌کند و برای هر برگه یک فایل CSV جداگانه تولید می‌نماید. در صورت نیاز به یک فایل CSV واحد می‌توانید پس از آن آن‌ها را ترکیب کنید. برای استفادهٔ دقیق به Aspose.BarCode Cloud SDK for Node.js مراجعه کنید.

آیا می‌توانم فایل‌های بزرگ XLS را به CSV استریم کنم بدون اینکه کل کتاب کار را در حافظه بارگذاری کنم؟
بله. با فعال‌سازی گزینه استریم در پارامترهای تبدیل، API ردیف‌ها را به‌صورت بخش‌های قابل مدیریت می‌خواند، که مصرف حافظه را کم و عملکرد را بالا نگه می‌دارد.

استفاده از Aspose.BarCode Cloud SDK برای Node.js در محیط تولید چه مجوزی لازم است؟
برای استفاده در تولید، یک مجوز تجاری لازم است. گزینه‌های خرید در صفحه قیمت‌گذاری محصول فهرست شده‌اند و می‌توانید یک مجوز ارزیابی موقت را از صفحه مجوز موقت درخواست کنید.

آیا می‌توان در حین تبدیل، جداکننده CSV را سفارشی کرد؟
به‌طور قطع. گزینه delimiter را در پارامترهای تبدیل به هر کاراکتری که نیاز دارید، مانند تب (\t) یا لوله (|) تنظیم کنید. این اطمینان می‌دهد که CSV تولید شده با انتظارات پردازش بعدی شما مطابقت داشته باشد.

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