تحويل بيانات 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);
    }
})();

ملاحظة: هذا المثال يوضح الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (sample.xls, output)، والتحقق من تثبيت جميع الاعتمادات المطلوبة بشكل صحيح، واختبارها بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

تحويل XLS إلى CSV عبر واجهة برمجة التطبيقات السحابية باستخدام 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، حيث يمكنك تسجيل التفاصيل أو تنفيذ منطق إعادة المحاولة. للحصول على قائمة كاملة بأكواد الأخطاء، راجع مرجع 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) لتخزين بيانات الاعتماد الخاصة بك بأمان.

معلمات التحويل: الخيارات والإعدادات

تقبل واجهة برمجة تطبيقات التحويل عدة معلمات اختيارية تسمح لك بضبط الإخراج بدقة.

  • 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 بكفاءة

  • تدفق الملفات الكبيرة - تمكين وضع التدفق لمعالجة الصفوف على دفعات وتجنب استهلاك الذاكرة العالي.
  • استخدام مجلد مؤقت - كتابة ملفات CSV الوسيطة إلى مجلد سحابي مخصص وتنظيفه بعد التنزيل.
  • تحديد فاصل مناسب - إذا كانت بياناتك تحتوي على فواصل، استبدلها بفاصل تبويب أو عمود (pipe) لتجنب عدم محاذاة الأعمدة.
  • التحقق بعد التنزيل - فحص أول بضعة صفوف من ملف CSV للتأكد من الترميز الصحيح واستخدام الفاصل قبل المتابعة في المعالجة.

الخاتمة

تحويل XLS إلى CSV في Node.JS يصبح بسيطًا عندما تستفيد من قدرات Aspose.BarCode Cloud SDK for Node.js. يغطي هذا الدليل كل شيء من إعداد البيئة ومثال عملي كامل إلى خيارات التكوين وأفضل الممارسات الموجهة للأداء. تذكر تأمين بيانات اعتماد العميل الخاصة بك، واختيار البث للدفاتر الكبيرة، وتنظيف الملفات المؤقتة للحفاظ على نظافة التخزين السحابي. بالنسبة للنشر في بيئة الإنتاج ستحتاج إلى ترخيص مدفوع؛ يمكنك مراجعة الأسعار على صفحة المنتج والحصول على ترخيص تجريبي مؤقت من صفحة الترخيص المؤقت.

الأسئلة المتكررة

كيف يتعامل تحويل XLS إلى CSV في Node.JS مع أوراق العمل المتعددة؟
تقوم المكتبة بمعالجة كل ورقة عمل بالتتابع، وتوليد ملف CSV منفصل لكل ورقة. يمكنك دمجها لاحقًا إذا كان ملف CSV واحد مطلوبًا. راجع Aspose.BarCode Cloud SDK for Node.js للاستخدام التفصيلي.

هل يمكنني بث ملفات XLS الكبيرة إلى CSV دون تحميل المصنف بالكامل في الذاكرة؟
نعم. من خلال تمكين خيار البث في معلمات التحويل، تقوم الواجهة البرمجية بقراءة الصفوف على دفعات قابلة للإدارة، مما يحافظ على انخفاض استهلاك الذاكرة وارتفاع الأداء.

ما الترخيص المطلوب لاستخدام Aspose.BarCode Cloud SDK for Node.js في بيئة الإنتاج؟
يتطلب الاستخدام في الإنتاج ترخيصًا تجاريًا. يتم سرد خيارات الشراء في صفحة أسعار المنتج، ويمكنك طلب ترخيص تقييم مؤقت من صفحة الترخيص المؤقت.

هل من الممكن تخصيص الفاصل في CSV أثناء التحويل؟
بالطبع. قم بتعيين خيار delimiter في معلمات التحويل إلى أي حرف تحتاجه، مثل علامة التبويب (\t) أو الأنبوب (|). هذا يضمن أن ملف CSV الناتج يطابق توقعات معالجة البيانات اللاحقة الخاصة بك.

اقرأ المزيد