Cordova/cordova plugin network information

توفر إضافة حالة الشبكة (cordova-plugin-network-information) تقديمًا لإصدار قديم من الواجهة البرمجية لمعلومات الشبكة، إذ توفر معلومات حول حالة الاتصال بشبكة الاتصال الخليوية (cellular) والشبكة اللاسلكي (wifi)، وتتحقق مما إذا كان الجهاز متصلًا بالإنترنت.

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

التثبيت

يمكن تثبيت هذه الإضافة عبر الأمر:

cordova plugin add cordova-plugin-network-information‎

المنصات المدعومة

• أندرويد
• Browser
• iOS
• ويندوز

Connection

يُوفر الكائن connection، الذي يمكن الحصول عليه عبر navigator.connection، معلوماتٍ حول الاتصال بشبكة الاتصال الخليوية (cellular) والشبكة اللاسلكي (wifi).

الخاصيات

• connection.type

الثوابت

• Connection.UNKNOWN
• Connection.ETHERNET
• Connection.WIFI
• Connection.CELL_2G
• Connection.CELL_3G
• Connection.CELL_4G
• Connection.CELL
• Connection.NONE

connection.type

توفر هذه الخاصية طريقة سريعة لتحديد حالة اتصال الجهاز بالشبكة، ونوع الاتصال.

ألق نظرة على المثال التالي:

function checkConnection() {
    var networkState = navigator.connection.type;
    var states = {};
    states[Connection.UNKNOWN]  = 'Unknown connection';
    states[Connection.ETHERNET] = 'Ethernet connection';
    states[Connection.WIFI]     = 'WiFi connection';
    states[Connection.CELL_2G]  = 'Cell 2G connection';
    states[Connection.CELL_3G]  = 'Cell 3G connection';
    states[Connection.CELL_4G]  = 'Cell 4G connection';
    states[Connection.CELL]     = 'Cell generic connection';
    states[Connection.NONE]     = 'No network connection';
    alert('Connection type: ' + states[networkState]);
}
checkConnection();‎

التغييرات في الواجهة البرمجية

حتى الإصدار 2.3.0 من كوردوفا، كان المطورون يصلون إلى الكائن Connection عبر التعبير navigator.network.connection، وبعد ذلك تم تغييره إلى navigator.connection ليتطابق مع مواصفات W3C. لكنه لا يزال متوفرًا بشكله القديم، غير أنّه أصبح مٌهملًا الآن، وسيُزال في الإصدارات القادمة.

ملاحظات خاصة بمنصة iOS

• يتعذر على منصات iOS دون الإصدار السابع اكتشافَ نوع الاتصال بالشبكة الخليوية.
• تُعيّن الخاصية navigator.connection.type إلى القيمة Connection.CELL لجميع البيانات الخليوية.

ملاحظات خاصة بمنصة ويندوز

• عند تشغيل التطبيق على محاكي Windows Phone 8.1، فستكون الخاصية navigator.connection.type مساوية دائمًا للقيمة Connection.ETHERNET.

ملاحظات خاصة بالمتصفحات (Browsers)

• لا يمكن للمتصفح اكتشاف نوع الاتصال بالشبكة. إذ تُضبط الخاصية navigator.connection.type دائمًا إلى القيمة Connection.UNKNOWN عند الاتصال بالإنترنت.

أحداث متعلقة بالشبكة

offline

يُطلق هذا الحدث عند انقطاع اتصال التطبيق (offline)، وعندما لا يكون الجهاز متصلًا بالإنترنت.

document.addEventListener("offline", yourCallbackFunction, false);‎

يُطلق الحدث offline عندما يفقد جهازٌ مُتصلٌ اتصالَهُ بالشبكة، بحيث يتعذر على التطبيق الوصول إلى الإنترنت. يعتمد هذا الحدث على نفس معلومات الواجهة البرمجية للكائن Connection، ويُطلق عندما تصبح قيمة الخاصية connection.type مساوية للقيمة NONE.

عادةً، يجب أن تستخدم التطبيقات التابعَ document.addEventListener لإرفاق مُنصتٍ للأحداث (event listener) بمجرد إطلاق الحدث deviceready.

إليك المثال التالي:

document.addEventListener("offline", onOffline, false);
function onOffline() {
    // offline معالجة الحدث 
}‎

ملاحظات خاصة بمنصة iOS

أثناء بدء التشغيل الأولي، يستغرق أول حدثٍ offline (إن كان مُطبّقا) ثانيةً واحدةً على الأقل قبل إطلاقه.

online

يُطلق هذا الحدث عندما يصبح أحد التطبيقات متصلًا بالإنترنت، وعند توصيل الجهاز بالإنترنت.

document.addEventListener("online", yourCallbackFunction, false);‎

يُطلق الحدث online عندما يتصل جهاز غير متصلٍ بالشبكة للسماح بوصول تطبيقٍ ما إلى الإنترنت. ويعتمد على نفس معلومات الواجهة البرمجية للكائن Connection، ويُطلَق عندما تتغير قيمة الخاصية connection.type من NONE إلى أي قيمة أخرى.

في العادة، يجب أن تستخدم التطبيقاتُ التابعَ document.addEventListener لإرفاق منصتٍ بحدثٍ بمجرد إطلاق الحدث deviceready.

إليك مثال سريع عن ذلك:

document.addEventListener("online", onOnline, false);
function onOnline() {
    // online معالجة الحدث 
}‎

ملاحظات خاصة بمنصة iOS

أثناء بدء التشغيل الأولي، يستغرق الحدث online الأول (إن وُجد) ثانية واحدةً على الأقل قبل إطلاقه، وتكون قيمة الخاصية connection.type قبل ذلك مساوية للقيمة UNKNOWN.

مثال توضيحي

تعرض الشيفرات البرمجية الموجودة في هذا القسم أمثلةً لتغيير سلوك التطبيق باستخدام الحدثين online و offline وحالات الاتصال بالشبكة.

سنبدأ بإنشاء الكائن FileEntry الجديد (data.txt) لاستخدامه لجمع البيانات. استدع الدالة التالية في معالج الحدث deviceready.

ملاحظة: يتطلب هذا المثال تثبيت إضافة الملفات.

var dataFileEntry;
function createSomeData() {
    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
        console.log('file system open: ' + fs.name);
        // انشاء ملف جديد، أو فتح ملف موجود
        fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {
          dataFileEntry = fileEntry;
        }, onErrorCreateFile);
    }, onErrorLoadFs);
}‎

بعد ذلك، أضف مُنصتَين (listeners) للحدثين online و offline في معالج الحدث deviceready.

document.addEventListener("offline", onOffline, false);
document.addEventListener("online", onOnline, false);‎

ستعالج دالة التطبيق onOnline الحدث online. في معالج الحدث، تحقَّق من الحالة الراهنة للشبكة. تعامل مع كل أنواع الاتصال باستثناء النوع Connection.NONE. وحاول تحميل ملف إن حصلت على اتصال.

function onOnline() {
    // online معالجة الحدث
    var networkState = navigator.connection.type;
    if (networkState !== Connection.NONE) {
        if (dataFileEntry) {
            tryToUploadFile();
        }
    }
    display('Connection type: ' + networkState);
}‎

الشيفرة السابقة ستستدعي دالة التطبيق tryToUploadFile عند إطلاق الحدث online.

إن فشل استدعاء التابع upload الخاص بالكائن FileTransfer، فاستدع دالة التطبيق offlineWrite لحفظ البيانات الحالية في مكان ما.

ملاحظة: يتطلب هذا المثال تثبيت الإضافة FileTransfer.

function tryToUploadFile() {
    // يحتوي على عنوان صالح يُشير إلى ملف نصي على الجهاز fileURL نفترض أن المتغير
    var fileURL = getDataFileEntry().toURL();
    var success = function (r) {
        console.log("Response = " + r.response);
        display("Uploaded. Response: " + r.response);
    }
    var fail = function (error) {
        console.log("An error has occurred: Code = " + error.code);
        offlineWrite("Failed to upload: some offline data");
    }
    var options = new FileUploadOptions();
    options.fileKey = "file";
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
    options.mimeType = "text/plain";
    var ft = new FileTransfer();
    // Content-Security-Policy تأكد من إضافة نطاق عنوان الخادم إلى الوسم
    // index.html في الملف
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};‎

إليك شيفرة الدالة offlineWrite:

ملاحظة: يتطلب هذا المثال إضافة الملفات.

function offlineWrite(offlineData) {
    // FileEntry لأجل FileWriter انشاء كائن
    dataFileEntry.createWriter(function (fileWriter) {
        fileWriter.onwriteend = function () {
            console.log("Successful file write...");
            display(offlineData);
        };
        fileWriter.onerror = function (e) {
            console.log("Failed file write: " + e.toString());
        };
        fileWriter.write(offlineData);
    });
}‎

عند وقوع الحدث offline، افعل شيئًا ما، مثل تنبيه المستخدم. في هذا المثال، سنعرض رسالة عبر دالة سطر الأوامر log.

function onOffline() {
    // offline معالجة الحدث
    console.log("lost connection");
}‎

 انظر أيضًا

• إضافة الأحداث
• إضافة الوصول إلى الملفات
• دليل تطوير الإضافات في كوردوفا

مصادر

• صفحة cordova-plugin-network-information في توثيق كوردوفا الرسمي.