مقارنة ملفات Word برمجيًا هي حاجة متكررة للخدمات الخلفية التي تحتاج إلى اكتشاف التغييرات، إنشاء تقارير مراجعة، أو فرض سياسات المستندات. GroupDocs.Comparison Cloud SDK for Node.js يوفر واجهة برمجة تطبيقات قوية تبسط هذه المهمة لتطبيقات Node.js. في هذا الدليل ستتعلم كيفية إعداد SDK، تشغيل مقارنة كاملة بين ملفين DOCX، استخدام أوامر cURL المكافئة، فهم كل جزء من التنفيذ، واتباع توصيات أفضل الممارسات للحفاظ على موثوقية وأمان الحل الخاص بك.

مثال كامل للكود: مقارنة مستندات Word في Node.JS

المثال التالي يوضح سير عمل كامل من البداية إلى النهاية لمقارنة مستندين Word باستخدام GroupDocs.Comparison Cloud SDK for Node.js.

const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

// ==== Authentication =========================================================
const clientId = "YOUR_CLIENT_ID";
const clientSecret = "YOUR_CLIENT_SECRET";

const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

// ==== File definitions =======================================================
const sourceFileName = "document1.docx";
const targetFileName = "document2.docx";
const resultFileName = "comparison_result.docx";

const sourceFilePath = path.resolve(__dirname, sourceFileName);
const targetFilePath = path.resolve(__dirname, targetFileName);

// ==== Main async function ====================================================
(async () => {
    try {
        // ---- Upload source document -----------------------------------------
        const sourceData = fs.readFileSync(sourceFilePath);
        const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: sourceFileName,
            file: sourceData
        });
        await storageApi.uploadFile(uploadSourceReq);

// ---- Upload target document -----------------------------------------
        const targetData = fs.readFileSync(targetFilePath);
        const uploadTargetReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: targetFileName,
            file: targetData
        });
        await storageApi.uploadFile(uploadTargetReq);

// ---- Prepare comparison options --------------------------------------
        const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
            sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
            targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
            outputPath: resultFileName,
            // optional: you can set settings like generateSummaryPage, showDeletedContent, etc.
        });

const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
            compareOptions: compareOptions
        });

// ---- Execute comparison -----------------------------------------------
        const compareResult = await compareApi.compareDocument(compareRequest);
        console.log("Comparison completed. Result stored at:", compareResult.path);

// ---- (Optional) Clean up uploaded files --------------------------------
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));
        // Note: result file remains in storage; you can download it if needed.
    } catch (error) {
        console.error("Error during comparison:", error);
    }
})();

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

إجراء مقارنة المستندات باستخدام cURL وREST API

إذا كنت تفضل نهجًا غير معتمد على اللغة، يمكنك تحقيق النتيجة نفسها باستخدام طلبات HTTP العادية. أدناه أوامر cURL الأساسية.

  1. المصادقة والحصول على رمز الوصول
    استبدل YOUR_CLIENT_ID و YOUR_CLIENT_SECRET ببيانات الاعتماد الخاصة بك.
curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. تحميل ملف DOCX المصدر
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document1.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document1.docx"
  1. تحميل ملف DOCX المستهدف
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document2.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document2.docx"
  1. تنفيذ عملية المقارنة
curl -X POST "https://api.groupdocs.cloud/v2.0/comparison/compare" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFile": { "filePath": "document1.docx" },
           "targetFiles": [{ "filePath": "document2.docx" }],
           "outputPath": "comparison_result.docx"
         }'
  1. تحميل ملف المقارنة الناتج
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/comparison_result.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o comparison_result.docx

لمزيد من التفاصيل حول حمولة الطلبات وتنسيقات الاستجابة، راجع وثائق API الرسمية.

فهم مقارنة مستندات Word في كود Node.JS

فيما يلي تفصيل خطوة بخطوة للمثال الكامل:

  1. استيراد SDK ووحدات Node.js
const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

توفر مساحة الأسماء GroupDocsComparisonCloud الوصول إلى جميع فئات API.

  1. إنشاء تكوين باستخدام بيانات اعتماد العميل
const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);

هذا الكائن يُصادق على كل استدعاء API لاحق.

  1. إنشاء كائنات CompareApi و StorageApi
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

CompareApi يتعامل مع المقارنة، بينما StorageApi يدير تحميلات الملفات وحذفها. راجع مرجع API للحصول على تفاصيل الطرق.

  1. تحميل ملفات DOCX المصدر والهدف
const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
    path: sourceFileName,
    file: sourceData
});
await storageApi.uploadFile(uploadSourceReq);

يتم تكرار النمط نفسه لملف الهدف.

  1. تكوين CompareOptions وتشغيل المقارنة
const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
    sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
    targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
    outputPath: resultFileName,
});
const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
    compareOptions: compareOptions
});
const compareResult = await compareApi.compareDocument(compareRequest);

CompareOptions يتيح لك ضبط العملية بدقة (مثلاً، إنشاء صفحة ملخص). يحتوي كائن النتيجة على المسار إلى مستند المقارنة المُنشأ.

  1. تنظيف الملفات المؤقتة (اختياري)
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));

إزالة الملفات الأصلية التي تم تحميلها يحافظ على تنظيم التخزين.

المتطلبات الأولية والإعداد لـ GroupDocs.Comparison

  1. إصدار Node.js - تأكد من أنك تستخدم Node 14 أو أحدث.
  2. الحصول على بيانات الاعتماد للعميل - سجّل في بوابة GroupDocs Cloud للحصول على clientId و clientSecret.
  3. تثبيت SDK
npm install groupdocs-comparison-cloud
  1. (اختياري) تنزيل مشروع العينة - يمكنك استنساخ المستودع من صفحة GitHub.
  2. تكوين بيئتك - اضبط بيانات الاعتماد كمتغيرات بيئية أو استبدل القيم النائبة في الشيفرة.

للحصول على قائمة كاملة بالملفات الثنائية القابلة للتنزيل، راجع صفحة التحميل.

أفضل الممارسات لمقارنة مستندات Word بكفاءة

  • تحقق من صحة ملفات الإدخال - تحقق من حجم الملف وتنسيقه قبل الرفع لتجنب استدعاءات API غير الضرورية.
  • إعادة استخدام جلسات التخزين - حمّل الملفات مرة واحدة وأعد استخدام مساراتها لمقارنات متعددة لتقليل زمن الاستجابة.
  • تمكين صفحة الملخص فقط عند الحاجة - إنشاء صفحة ملخص يضيف وقت معالجة؛ عطلها للقيام بفحوصات اختلاف بسيطة.
  • معالجة المستندات الكبيرة بشكل غير متزامن - بالنسبة لملفات DOCX التي يزيد حجمها عن 10 ميغابايت، فكر في استعلام حالة المهمة بدلاً من الانتظار بشكل متزامن.
  • تأمين بيانات الاعتماد - احفظ clientId و clientSecret في متغيرات البيئة أو مدير الأسرار؛ لا تقم أبداً بكتابة قيمها مباشرة في الشيفرة.

الخاتمة

مقارنة مستندات Word في Node.JS تصبح بسيطة مع GroupDocs.Comparison Cloud SDK for Node.js. باتباع خطوات التثبيت، واستخدام مثال الكود المقدم، واختيارياً الاستفادة من REST API باستخدام cURL، يمكنك دمج مقارنة المستندات القوية في أي خدمة خلفية. تذكر تأمين بيانات الاعتماد الخاصة بك، وتنظيف الملفات المؤقتة، وضبط خيارات المقارنة للأداء. بالنسبة للنشر في بيئات الإنتاج ستحتاج إلى نسخة مرخصة؛ تفاصيل الأسعار متاحة على صفحة المنتج، ويمكنك الحصول على ترخيص مؤقت للتقييم من صفحة الترخيص المؤقت. ابدأ التجربة اليوم وامنح تطبيقات Node.js الخاصة بك قدرات موثوقة لاختلاف المستندات.

FAQs

  • كيف يمكنني مقارنة مستندات Word في Node.JS دون كتابة كود؟
    يمكنك استخدام العملية نفسها عبر استدعاءات REST. توضح أمثلة cURL في هذه المقالة التسلسل الدقيق: المصادقة، تحميل الملفات، استدعاء نقطة النهاية للمقارنة، وتنزيل النتيجة.

  • ما هي صيغ الملفات المدعومة للمقارنة؟
    يدعم SDK صيغ DOCX، DOC، ODT، RTF، وTXT من بين أخرى. جميع أسماء الصيغ غير حساسة لحالة الأحرف، ولكنها موثقة بأحرف كبيرة (مثال: DOCX) في مرجع API.

  • هل يمكنني مقارنة أكثر من مستندين في آن واحد؟
    نعم. يمكن أن تحتوي مصفوفة targetFiles في CompareOptions على عدة كائنات FileInfo، مما يتيح لك مقارنة ملف المصدر مع عدة أهداف في طلب واحد.

  • هل هناك طريقة لتخصيص النمط البصري لنتيجة المقارنة؟
    يوفر SDK إعدادات مثل showDeletedContent و showInsertedContent و generateSummaryPage. اضبط هذه الخصائص في CompareOptions للتحكم في كيفية تمييز التغييرات. راجع الوثائق الرسمية للحصول على القائمة الكاملة للخيارات.

Read More